|
| 1 | +# Building the Podman client and client installer on Windows |
| 2 | + |
| 3 | +The following describes the process for building the Podman client on Windows. |
| 4 | + |
| 5 | +## OS requirements |
| 6 | + |
| 7 | +Windows OS can behave very differently depending on how it was configured. This documentation assumes that one is using |
| 8 | +a [Windows 11 development machine](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/) or a |
| 9 | +configuration close to this one. The Podman Windows client installer bundles several tools, which are unnecessary for Podman builds, but this |
| 10 | +set of packages is well aligned with GitHub's `windows-latest` offerings. Some of the tools will still be missing from |
| 11 | +this distribution and will have to be manually added after this installation completes. |
| 12 | + |
| 13 | +## Install Pandoc |
| 14 | + |
| 15 | +Pandoc could be installed from https://pandoc.org/installing.html When performing the Pandoc installation one, has to choose the option |
| 16 | +"Install for all users" (to put the binaries into "Program Files" directory). |
| 17 | + |
| 18 | +## Install WiX Toolset v3 (is preinstalled in Github runner) |
| 19 | +The latest release of the WiX Toolset can be obtained from https://wixtoolset.org/docs/wix3/. Installing it into a clean VM might require |
| 20 | +an additional installation of .NET Framework 3.5 in advance |
| 21 | +([instructions for adding .NET Framework 3.5 via enabling the Windows feature](https://learn.microsoft.com/en-us/dotnet/framework/install/dotnet-35-windows#enable-the-net-framework-35-in-control-panel)) |
| 22 | + |
| 23 | +## Install msys2 |
| 24 | + |
| 25 | +Podman requires brew -- a collection of Unix like build tools and libraries adapted for Windows. More details and |
| 26 | +installation instructions are available from their [home page](https://www.msys2.org/). There are also premade GitHub |
| 27 | +actions for this tool that are available. |
| 28 | + |
| 29 | +## Install build dependencies |
| 30 | + |
| 31 | +Podman requires some software from msys2 to be able to build. This can be done using msys2 shell. One can start it |
| 32 | +from the Start menu. This documentation covers only usage of MSYS2 UCRT64 shell (msys2 shells come preconfigured for |
| 33 | +different [environments](https://www.msys2.org/docs/environments/)). |
| 34 | + |
| 35 | +``` |
| 36 | +$ pacman -S git make zip mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-go mingw-w64-ucrt-x86_64-python |
| 37 | +``` |
| 38 | + |
| 39 | +The Pandoc tool installed in a prior step is specific, that is the installer doesn't add the tool to any PATH environment |
| 40 | +variable known to msys2, so, it has to be linked explicitly to work. |
| 41 | + |
| 42 | +``` |
| 43 | +$ mkdir -p /usr/local/bin |
| 44 | +$ ln -sf "/c/Program Files/Pandoc/pandoc.exe" "/usr/local/bin/pandoc.exe" |
| 45 | +``` |
| 46 | + |
| 47 | +## Restart shell (important) |
| 48 | + |
| 49 | +One needs to restart the [msys2](https://www.msys2.org/) shell after dependency installation before proceeding with the build. |
| 50 | + |
| 51 | +## Obtain Podman source code |
| 52 | + |
| 53 | +One can obtain the latest source code for Podman from its [GitHub](https://github.com/containers/podman) repository. |
| 54 | + |
| 55 | +``` |
| 56 | +$ git clone https://github.com/containers/podman.git go/src/github.com/containers/podman |
| 57 | +``` |
| 58 | + |
| 59 | +## Build client |
| 60 | + |
| 61 | +After completing the preparatory steps of obtaining the Podman source code and installing its dependencies, the client |
| 62 | +can now be built. |
| 63 | + |
| 64 | +``` |
| 65 | +$ cd go/src/github.com/containers/podman |
| 66 | +$ make clean podman-remote-release-windows_amd64.zip |
| 67 | +``` |
| 68 | + |
| 69 | +The complete distribution will be packaged to the `podman-remote-release-windows_amd64.zip` file. It is possible to |
| 70 | +unzip it and replace files in the default Podman installation with the built ones to use the custom build. |
| 71 | + |
| 72 | +### Build client only (for faster feedback loop) |
| 73 | + |
| 74 | +Building Podman by following this documentation can take a fair amount of time and effort. Packaging the installer adds even more overhead. If |
| 75 | +the only needed artifact is the Podman binary itself, it is possible to build only it with this command: |
| 76 | + |
| 77 | +``` |
| 78 | +$ make podman-remote |
| 79 | +``` |
| 80 | + |
| 81 | +The binary will be located in `bin/windows/`. It could be used as drop in replacement for the installed version of |
| 82 | +Podman. |
| 83 | + |
| 84 | +It is also possible to cross-build for other platforms by providing GOOS and GOARCH environment variables. |
| 85 | + |
| 86 | +## Build client installer |
| 87 | + |
| 88 | +As Windows requires more effort in comparison to Unix systems for installation procedures, it is sometimes |
| 89 | +easier to pack the changes into a ready-to-use installer. To create the installer, the full client distribution in ZIP |
| 90 | +format has to be built beforehand. |
| 91 | + |
| 92 | +``` |
| 93 | +$ export BUILD_PODMAN_VERSION=$(test/version/version | sed 's/-.*//') |
| 94 | +$ mkdir -p contrib/win-installer/current |
| 95 | +$ cp podman-remote-release-windows_amd64.zip contrib/win-installer/current/ |
| 96 | +$ cd contrib/win-installer |
| 97 | +$ powershell -ExecutionPolicy Bypass -File build.ps1 $BUILD_PODMAN_VERSION dev current |
| 98 | +``` |
| 99 | + |
| 100 | +The installer will be located in the `contrib/win-installer` folder (relative to checkout root) and will have a name |
| 101 | +like `podman-4.5.0-dev-setup.exe`. This could be installed in a similar manner as the official Podman for Windows installers |
| 102 | +(when installing unsigned binaries is allowed on the host). |
| 103 | + |
| 104 | +## Using the client |
| 105 | + |
| 106 | +To learn how to use the Podman client, refer to its |
| 107 | +[tutorial](https://github.com/containers/podman/blob/main/docs/tutorials/remote_client.md). |
0 commit comments