github.com/containers/podman/v5@v5.1.0-rc1/build_windows.md (about) 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 ## Building and running 24 25 ### Install git and go 26 27 To build Podman, the [git](https://gitforwindows.org/) and [go](https://go.dev) tools are required. In case they are not yet installed, 28 open a Windows Terminal and run the following command (it assumes that [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) is installed): 29 30 ``` 31 winget install -e GoLang.Go Git.Git 32 ``` 33 34 :information_source: A terminal restart is advised for the `PATH` to be reloaded. This can also be manually changed by configuring the `PATH`: 35 36 ``` 37 $env:Path += ";C:\Program Files\Go\bin\;C:\Program Files\Git\cmd\" 38 ``` 39 40 ### Enable Hyper-V (optional) 41 42 Podman on Windows can run on the [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/) or 43 on [Hyper-V](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). 44 45 Hyper-V is built into Windows Enterprise, Pro, or Education (not Home) as an optional feature. It is available on Windows 10 and 11 only 46 and [has some particular requirements in terms of CPU and memory](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v#check-requirements). 47 To enable it on a supported system, enter the following command: 48 49 ``` 50 Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All 51 ``` 52 53 After running this command a restart of the Windows machine is required. 54 55 :information_source: The VM provider used by podman (Hyper-V or WSL) can be configured in the file 56 `%APPDATA%/containers/containers.conf`. [More on that later](#configure-podman). 57 58 ### Get the source code 59 60 Open a Windows Terminal and run the following command: 61 62 ``` 63 git config --global core.autocrlf false 64 ``` 65 66 This configures git so that it does **not** automatically convert LF to CRLF. Files are expected to use the Unix LF rather 67 Windows CRLF in the Podman git repository. 68 69 Then run the command to clone the Podman git repository: 70 71 ``` 72 git clone https://github.com/containers/podman 73 ``` 74 75 This will create the folder `podman` in the current directory and clone the Podman git repository into it. 76 77 ### Build the podman client for windows 78 79 The Podman client for Windows can be built with the PowerShell script [winmake.ps1](https://github.com/containers/podman/blob/main/winmake.ps1). 80 81 The ExecutionPolicy is set to `Restricted` on Windows computers by default: running scripts is not allowed. 82 The ExecutionPolicy on the machine can be determined with this command: 83 84 ``` 85 Get-ExecutionPolicy 86 ``` 87 88 If the command returns `Restricted`, the ExecutionPolicy should be changed to `RemoteSigned`: 89 90 ``` 91 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 92 ``` 93 94 This policy allows the execution of local PowerShell scripts, such as `winmake.ps1`, for the current user: 95 96 ``` 97 # Get in the podman git repository directory 98 cd podman 99 100 # Build podman.exe 101 .\winmake.ps1 podman-remote 102 103 # Download gvproxy.exe and win-sshproxy.exe 104 # that are needed to execute the podman client 105 .\winmake.ps1 win-gvproxy 106 ``` 107 108 :information_source: To verify that the build was completed successfully, check the content of the .\bin\windows` folder. 109 Upon successful completion three executables should be shown: 110 111 ``` 112 ls .\bin\windows\ 113 114 115 Directory: C:\Users\mario\Git\podman\bin\windows 116 117 118 Mode LastWriteTime Length Name 119 ---- ------------- ------ ---- 120 -a---- 2/29/2024 12:10 PM 10946048 gvproxy.exe 121 -a---- 2/27/2024 11:59 AM 45408256 podman.exe 122 -a---- 2/29/2024 12:10 PM 4089856 win-sshproxy.exe 123 ``` 124 125 ### Configure podman 126 127 Create a containers.conf file: 128 129 ``` 130 mkdir $env:APPDATA\containers\ 131 New-Item -ItemType File $env:APPDATA\containers\containers.conf 132 notepad $env:APPDATA\containers\containers.conf 133 ``` 134 135 and add the following lines in it: 136 137 ```toml 138 [machine] 139 # Specify the provider 140 # Values can be "hyperv" or "wsl" 141 provider="hyperv" 142 [engine] 143 # Specify the path of the helper binaries. 144 # NOTE: path should use slashes instead of anti-slashes 145 helper_binaries_dir=["C:/Users/mario/git/podman/bin/windows"] 146 ``` 147 148 Create a policy.json file: 149 150 ``` 151 New-Item -ItemType File $env:APPDATA\containers\policy.json 152 notepad $env:APPDATA\containers\policy.json 153 ```` 154 155 and add the following lines in it: 156 157 ```json 158 { 159 "default": [ 160 { 161 "type": "insecureAcceptAnything" 162 } 163 ], 164 "transports": { 165 "docker-daemon": { 166 "": [{ "type": "insecureAcceptAnything" }] 167 } 168 } 169 } 170 ``` 171 172 ### Create and start a podman machine 173 174 Run a terminal **as an administrator** and execute the following commands to create a Podman machine: 175 176 ``` 177 .\bin\windows\podman.exe machine init 178 ``` 179 180 When `machine init` completes run `machine start`: 181 182 ``` 183 .\bin\windows\podman.exe machine start 184 ``` 185 186 ### Run a container using podman 187 188 The locally built Podman client for Windows can now be used to run containers: 189 190 ``` 191 .\bin\windows\podman.exe run hello-world 192 ``` 193 194 :information_source: Unlike the previous machine commands, this one doesn't require administrative privileges. 195 196 ## Building the Podman client and installer with MSYS2 197 198 ### Install msys2 199 200 Podman requires brew -- a collection of Unix like build tools and libraries adapted for Windows. More details and 201 installation instructions are available from their [home page](https://www.msys2.org/). There are also premade GitHub 202 actions for this tool that are available. 203 204 ### Install build dependencies 205 206 Podman requires some software from msys2 to be able to build. This can be done using msys2 shell. One can start it 207 from the Start menu. This documentation covers only usage of MSYS2 UCRT64 shell (msys2 shells come preconfigured for 208 different [environments](https://www.msys2.org/docs/environments/)). 209 210 ``` 211 $ pacman -S git make zip mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-go mingw-w64-ucrt-x86_64-python 212 ``` 213 214 The Pandoc tool installed in a prior step is specific, that is the installer doesn't add the tool to any PATH environment 215 variable known to msys2, so, it has to be linked explicitly to work. 216 217 ``` 218 $ mkdir -p /usr/local/bin 219 $ ln -sf "/c/Program Files/Pandoc/pandoc.exe" "/usr/local/bin/pandoc.exe" 220 ``` 221 222 ### Restart shell (important) 223 224 One needs to restart the [msys2](https://www.msys2.org/) shell after dependency installation before proceeding with the build. 225 226 ### Obtain Podman source code 227 228 One can obtain the latest source code for Podman from its [GitHub](https://github.com/containers/podman) repository. 229 230 ``` 231 $ git clone https://github.com/containers/podman.git go/src/github.com/containers/podman 232 ``` 233 234 ### Build client 235 236 After completing the preparatory steps of obtaining the Podman source code and installing its dependencies, the client 237 can now be built. 238 239 ``` 240 $ cd go/src/github.com/containers/podman 241 $ make clean podman-remote-release-windows_amd64.zip 242 ``` 243 244 The complete distribution will be packaged to the `podman-remote-release-windows_amd64.zip` file. It is possible to 245 unzip it and replace files in the default Podman installation with the built ones to use the custom build. 246 247 #### Build client only (for faster feedback loop) 248 249 Building Podman by following this documentation can take a fair amount of time and effort. Packaging the installer adds even more overhead. If 250 the only needed artifact is the Podman binary itself, it is possible to build only it with this command: 251 252 ``` 253 $ make podman-remote 254 ``` 255 256 The binary will be located in `bin/windows/`. It could be used as drop in replacement for the installed version of 257 Podman. 258 259 It is also possible to cross-build for other platforms by providing GOOS and GOARCH environment variables. 260 261 ### Build client installer 262 263 As Windows requires more effort in comparison to Unix systems for installation procedures, it is sometimes 264 easier to pack the changes into a ready-to-use installer. To create the installer, the full client distribution in ZIP 265 format has to be built beforehand. 266 267 ``` 268 $ export BUILD_PODMAN_VERSION=$(test/version/version | sed 's/-.*//') 269 $ mkdir -p contrib/win-installer/current 270 $ cp podman-remote-release-windows_amd64.zip contrib/win-installer/current/ 271 $ cd contrib/win-installer 272 $ powershell -ExecutionPolicy Bypass -File build.ps1 $BUILD_PODMAN_VERSION dev current 273 ``` 274 275 The installer will be located in the `contrib/win-installer` folder (relative to checkout root) and will have a name 276 like `podman-4.5.0-dev-setup.exe`. This could be installed in a similar manner as the official Podman for Windows installers 277 (when installing unsigned binaries is allowed on the host). 278 279 ## Using the client 280 281 To learn how to use the Podman client, refer to its 282 [tutorial](https://github.com/containers/podman/blob/main/docs/tutorials/remote_client.md).