| 1 | # Building on Windows |
| 2 |  |
| 3 | |
| 4 | If you just want to install kubo, please download it from https://dist.ipfs.tech/#kubo. This document explains how to build it from source. |
| 5 | |
| 6 | ## Install Go |
| 7 | `kubo` is built on Golang and thus depends on it for all building methods. |
| 8 | https://golang.org/doc/install |
| 9 | The `GOPATH` environment variable must be set as well. |
| 10 | https://golang.org/doc/code.html#GOPATH |
| 11 | |
| 12 | ## Choose the way you want to proceed |
| 13 | `kubo` utilizes `make` to automate builds and run tests, but can be built without it using only `git` and `go`. |
| 14 | No matter which method you choose, if you encounter issues, please see the [Troubleshooting](#troubleshooting) section. |
| 15 | |
| 16 | **Using `make`:** |
| 17 | MSYS2 and Cygwin provide the Unix tools we need to build `kubo`. You may use either, but if you don't already have one installed, we recommend MSYS2. |
| 18 | [MSYS2→](#msys2) |
| 19 | [Cygwin→](#cygwin) |
| 20 | |
| 21 | **Using build tools manually:** |
| 22 | This section assumes you have a working version of `go` and `git` already setup. You may want to build this way if your environment restricts installing additional software, or if you're integrating IPFS into your own build system. |
| 23 | [Minimal→](#minimal) |
| 24 | |
| 25 | ## MSYS2 |
| 26 | 1. Install msys2 (http://www.msys2.org) |
| 27 | 2. Run the following inside a normal `cmd` prompt (Not the MSYS2 prompt, we only need MSYS2's tools). |
| 28 | An explanation of this block is below. |
| 29 | ``` |
| 30 | SET PATH=%PATH%;\msys64\usr\bin |
| 31 | pacman --noconfirm -S git make unzip |
| 32 | go get -u github.com/ipfs/kubo |
| 33 | cd %GOPATH%\src\github.com\ipfs\kubo |
| 34 | make install |
| 35 | %GOPATH%\bin\ipfs.exe version --all |
| 36 | ``` |
| 37 | |
| 38 | If there were no errors, the final command should output version information similar to "`ipfs version 0.4.14-dev-XXXXXXX`" where "XXXXXXX" should match the current short-hash of the `kubo` repo. You can retrieve said hash via this command: `git rev-parse --short HEAD`. |
| 39 | If `ipfs.exe` executes and the version string matches, then building was successful. |
| 40 | |
| 41 | |Command|Explanation| |
| 42 | | ---: | :--- | |
| 43 | |`SET PATH=%PATH%;\msys64\usr\bin` |Add msys2's tools to our [`PATH`](https://ss64.com/nt/path.html); Defaults to: (\msys64\usr\bin)| |
| 44 | |`pacman --noconfirm -S git make unzip` |Install `kubo` build dependencies| |
| 45 | |`go get -u github.com/ipfs/kubo` |Fetch / Update `kubo` source| |
| 46 | |`cd %GOPATH%\src\github.com\ipfs\kubo` |Change to `kubo` source directory| |
| 47 | |`make install` |Build and install to `%GOPATH%\bin\ipfs.exe`| |
| 48 | |`%GOPATH%\bin\ipfs.exe version --all` |Test the built binary| |
| 49 | |
| 50 | To build again after making changes to the source, run: |
| 51 | ``` |
| 52 | SET PATH=%PATH%;\msys64\usr\bin |
| 53 | cd %GOPATH%\src\github.com\ipfs\kubo |
| 54 | make install |
| 55 | ``` |
| 56 | |
| 57 | **Tip:** To avoid setting `PATH` every time (`SET PATH=%PATH%;\msys64\usr\bin`), you can lock it in permanently using `setx` after it's been set once: |
| 58 | ``` |
| 59 | SETX PATH %PATH% |
| 60 | ``` |
| 61 | |
| 62 | ## Cygwin |
| 63 | 1. Install Cygwin (https://www.cygwin.com) |
| 64 | 2. During the install, select the following packages. (If you already have Cygwin installed, run the setup file again to install additional packages.) A fresh install should look something like [this reference image](https://ipfs.io/ipfs/QmaYFSQa4iHDafcebiKjm1WwuKhosoXr45HPpfaeMbCRpb/cygwin%20-%20install.png). |
| 65 | - devel packages |
| 66 | - `git` |
| 67 | - `make` |
| 68 | - archive packages |
| 69 | - `unzip` |
| 70 | - net packages |
| 71 | - `curl` |
| 72 | 3. Run the following inside a normal `cmd` prompt (Not the Cygwin prompt, we only need Cygwin's tools) |
| 73 | An explanation of this block is below. |
| 74 | ``` |
| 75 | SET PATH=%PATH%;\cygwin64\bin |
| 76 | mkdir %GOPATH%\src\github.com\ipfs |
| 77 | cd %GOPATH%\src\github.com\ipfs |
| 78 | git clone https://github.com/ipfs/kubo.git |
| 79 | cd %GOPATH%\src\github.com\ipfs\kubo |
| 80 | make install |
| 81 | %GOPATH%\bin\ipfs.exe version --all |
| 82 | ``` |
| 83 | |
| 84 | If there were no errors, the final command should output version information similar to "`ipfs version 0.4.14-dev-XXXXXXX`" where "XXXXXXX" should match the current short-hash of the `kubo` repo. You can retrieve said hash via this command: `git rev-parse --short HEAD`. |
| 85 | If `ipfs.exe` executes and the version string matches, then building was successful. |
| 86 | |
| 87 | |Command|Explanation| |
| 88 | | ---: | :--- | |
| 89 | |`SET PATH=%PATH%;\cygwin64\bin` |Add Cygwin's tools to our [`PATH`](https://ss64.com/nt/path.html); Defaults to: (\cygwin64\bin)| |
| 90 | |`mkdir %GOPATH%\src\github.com\ipfs`<br/>`cd %GOPATH%\src\github.com\ipfs`<br/>`git clone https://github.com/ipfs/kubo.git` |Fetch / Update `kubo` source| |
| 91 | |`cd %GOPATH%\src\github.com\ipfs\kubo` |Change to `kubo` source directory| |
| 92 | |`make install` |Build and install to `%GOPATH%\bin\ipfs.exe`| |
| 93 | |`%GOPATH%\bin\ipfs.exe version --all` |Test the built binary| |
| 94 | |
| 95 | To build again after making changes to the source, run: |
| 96 | ``` |
| 97 | SET PATH=%PATH%;\cygwin64\bin |
| 98 | cd %GOPATH%\src\github.com\ipfs\kubo |
| 99 | make install |
| 100 | ``` |
| 101 | |
| 102 | **Tip:** To avoid setting `PATH` every time (`SET PATH=%PATH%;\cygwin64\bin`), you can lock it in permanently using `setx` after it's been set once: |
| 103 | ``` |
| 104 | SETX PATH %PATH% |
| 105 | ``` |
| 106 | |
| 107 | ## Minimal |
| 108 | |
| 109 | While it's possible to build `kubo` with `go` alone, we'll be using `git` to fetch the source. |
| 110 | |
| 111 | You can use whichever version of `git` you wish but we recommend the Windows builds at <https://git-scm.com>. `git` must be in your [`PATH`](https://ss64.com/nt/path.html) for `go get` to recognize and use it. |
| 112 | |
| 113 | ### kubo |
| 114 | |
| 115 | Clone and change directory to the source code, if you haven't already: |
| 116 | |
| 117 | CMD: |
| 118 | ```bat |
| 119 | git clone https://github.com/ipfs/kubo %GOPATH%/src/github.com/ipfs/kubo |
| 120 | cd %GOPATH%/src/github.com/ipfs/kubo/cmd/ipfs |
| 121 | ``` |
| 122 | |
| 123 | PowerShell: |
| 124 | ```powershell |
| 125 | git clone https://github.com/ipfs/kubo $env:GOPATH/src/github.com/ipfs/kubo |
| 126 | cd $env:GOPATH/src/github.com/ipfs/kubo/cmd/ipfs |
| 127 | ``` |
| 128 | |
| 129 | We need the `git` commit hash to be included in our build so that in the extremely rare event a bug is found, we have a reference point later for tracking it. We'll ask `git` for it and store it in a variable. The syntax for the next command is different depending on whether you're using the interactive command line or writing a batch file. Use the one that applies to you. |
| 130 | - interactive: `FOR /F %V IN ('git rev-parse --short HEAD') do set SHA=%V` |
| 131 | - interpreter: `FOR /F %%V IN ('git rev-parse --short HEAD') do set SHA=%%V` |
| 132 | |
| 133 | Finally, we'll build and test `ipfs` itself. |
| 134 | |
| 135 | CMD: |
| 136 | ```bat |
| 137 | go install -ldflags="-X "github.com/ipfs/kubo".CurrentCommit=%SHA%" |
| 138 | %GOPATH%\bin\ipfs.exe version --all |
| 139 | ``` |
| 140 | |
| 141 | PowerShell: |
| 142 | ```powershell |
| 143 | go install -ldflags="-X "github.com/ipfs/kubo".CurrentCommit=$env:SHA" |
| 144 | cp ./ipfs.exe $env:GOPATH/bin/ipfs.exe -force |
| 145 | . $env:GOPATH/bin/ipfs.exe version --all |
| 146 | ``` |
| 147 | You can check that the ipfs output versions match with `go version` and `git rev-parse --short HEAD`. |
| 148 | If `ipfs.exe` executes and everything matches, then building was successful. |
| 149 | |
| 150 | ## Troubleshooting |
| 151 | - **Git auth** |
| 152 | If you get authentication problems with Git, you might want to take a look at https://help.github.com/articles/caching-your-github-password-in-git/ and use the suggested solution: |
| 153 | `git config --global credential.helper wincred` |
| 154 | |
| 155 | - **Anything else** |
| 156 | Please search [https://discuss.ipfs.tech](https://discuss.ipfs.tech/search?q=windows%20category%3A13) for any additional issues you may encounter. If you can't find any existing resolution, feel free to post a question asking for help. |
| 157 | |
| 158 | If you encounter a bug with `kubo` itself (not related to building) please use the [issue tracker](https://github.com/ipfs/kubo/issues) to report it. |