-
-
Notifications
You must be signed in to change notification settings - Fork 3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4691 from djdv/docs/windows
Change Windows build documentation
- Loading branch information
Showing
1 changed file
with
107 additions
and
102 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,142 +1,147 @@ | ||
| # Building on Windows | ||
|
|
||
| ## Install Git For Windows | ||
|
|
||
| As Git is used by the Go language to download dependencies, you need | ||
| to install Git, for example from http://git-scm.com/. | ||
|
|
||
| You also must make sure that the directory that contains the Git For | ||
| Windows binary is in the Path environment variable. Note that Git For | ||
| Windows has a 'git' binary in a 'Git\bin' directory and another one in | ||
| a 'Git\cmd' directory. You should only put the 'Git\cmd' directory in | ||
| the Path environment variable. | ||
|  | ||
|
|
||
| ## Install Go | ||
| `go-ipfs` is built on Golang and thus depends on it for all building methods. | ||
| https://golang.org/doc/install | ||
| The `GOPATH` environment variable must be set as well. | ||
| https://golang.org/doc/code.html#GOPATH | ||
|
|
||
| Please install the Go language as explained on | ||
| https://golang.org/doc/install. | ||
|
|
||
| To properly install Go, you will need to set some environment | ||
| variables. We recommend you to set them globally using the Control | ||
| Panel, as explained in the documentation above, so that these | ||
| environment variables are automatically available in all the possible | ||
| environments that you might want to use like Git Bash, Windows's cmd, | ||
| Cygwin's terminal, Windows' PowerShell and so on. | ||
|
|
||
| You must make sure that the GOROOT environment variable is set and | ||
| that the %GOROOT%/bin directory is in the Path environment variable. | ||
|
|
||
| The GOPATH environment variable should also be set to a directory that | ||
| you have created, and the %GOPATH/bin directory should also be in the | ||
| Path environment variable. | ||
| ## Choose the way you want to proceed | ||
| `go-ipfs` utilizes `make` to automate builds and run tests, but can be built without it using only `git` and `go`. | ||
| No matter which method you choose, if you encounter issues, please see the [Troubleshooting](#troubleshooting) section. | ||
|
|
||
| ## Download go-ipfs and fix Git authentication | ||
| **Using `make`:** | ||
| MSYS2 and Cygwin provide the Unix tools we need to build `go-ipfs`. You may use either, but if you don't already have one installed, we recommend MSYS2. | ||
| [MSYS2→](#msys2) | ||
| [Cygwin→](#cygwin) | ||
|
|
||
| Use the following command to download go-ipfs source code: | ||
| **Using build tools manually:** | ||
| 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. | ||
| [Minimal→](#minimal) | ||
|
|
||
| ## MSYS2 | ||
| 1. Install msys2 (http://www.msys2.org) | ||
| 2. Run the following inside a normal `cmd` prompt (Not the MSYS2 prompt, we only need MSYS2's tools). | ||
| An explanation of this block is below. | ||
| ``` | ||
| SET PATH=%PATH%;\msys64\usr\bin | ||
| pacman --noconfirm -S git make unzip | ||
| go get -u github.com/ipfs/go-ipfs | ||
| cd %GOPATH%\src\github.com\ipfs\go-ipfs | ||
| make install | ||
| %GOPATH%\bin\ipfs.exe version --all | ||
| ``` | ||
|
|
||
| The above command uses Git to download go-ipfs from its GitHub | ||
| repository. 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: | ||
| 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 `go-ipfs` repo. You can retrieve said hash via this command: `git rev-parse --short HEAD`. | ||
| If `ipfs.exe` executes and the version string matches, then building was successful. | ||
|
|
||
| |Command|Explanation| | ||
| | ---: | :--- | | ||
| |`SET PATH=%PATH%;\msys64\usr\bin` |Add msys2's tools to our [`PATH`](https://ss64.com/nt/path.html); Defaults to: (\msys64\usr\bin)| | ||
| |`pacman --noconfirm -S git make unzip` |Install `go-ipfs` build dependencies| | ||
| |`go get -u github.com/ipfs/go-ipfs` |Fetch / Update `go-ipfs` source| | ||
| |`cd %GOPATH%\src\github.com\ipfs\go-ipfs` |Change to `go-ipfs` source directory| | ||
| |`make install` |Build and install to `%GOPATH%\bin\ipfs.exe`| | ||
| |`%GOPATH%\bin\ipfs.exe version --all` |Test the built binary| | ||
|
|
||
| To build again after making changes to the source, run: | ||
| ``` | ||
| git config --global credential.helper wincred | ||
| SET PATH=%PATH%;\msys64\usr\bin | ||
| cd %GOPATH%\src\github.com\ipfs\go-ipfs | ||
| make install | ||
| ``` | ||
|
|
||
| ## Choose the way you want to proceed | ||
|
|
||
| Now there are two ways to download, install the dependencies and to | ||
| build go-ipfs: | ||
|
|
||
| 1) There is the "Manual Way", where you don't need to install anymore | ||
| software except the dependencies, but you have a number of commands to | ||
| type. | ||
|
|
||
| 2) There is a way by installing 'make' through Cygwin and using it to | ||
| do nearly everything. We call this way the "Cygwin Way". It may take | ||
| much more time, because installing Cygwin can take a lot of time, but | ||
| after that it might be easier as many procedures are just a 'make' | ||
| command away. | ||
|
|
||
| So use the next steps below that start with "Manual Way" if that's the | ||
| way you want, otherwise scroll down a bit and use the "Cygwin Way" | ||
| steps below. | ||
|
|
||
| ## Manual Way: download and install dependencies | ||
|
|
||
| The following commands should download or update go-ipfs dependencies | ||
| and then install them: | ||
|
|
||
| **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: | ||
| ``` | ||
| go get -u github.com/whyrusleeping/gx | ||
| go get -u github.com/whyrusleeping/gx-go | ||
| cd %GOPATH%/src/github.com/ipfs/go-ipfs | ||
| gx --verbose install --global | ||
| SETX PATH %PATH% | ||
| ``` | ||
|
|
||
| ## Manual Way: build go-ipfs | ||
|
|
||
| To actually build go-ipfs, first go to the cmd/ipfs directory: | ||
|
|
||
| ## Cygwin | ||
| 1. Install Cygwin (https://www.cygwin.com) | ||
| 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). | ||
| - devel packages | ||
| - `git` | ||
| - `make` | ||
| - archive packages | ||
| - `unzip` | ||
| - net packages | ||
| - `curl` | ||
| 3. Run the following inside a normal `cmd` prompt (Not the Cygwin prompt, we only need Cygwin's tools) | ||
| An explanation of this block is below. | ||
| ``` | ||
| cd cmd\ipfs | ||
| SET PATH=%PATH%;\cygwin64\bin | ||
| mkdir %GOPATH%\src\github.com\ipfs | ||
| cd %GOPATH%\src\github.com\ipfs | ||
| git clone https://github.com/ipfs/go-ipfs.git | ||
| cd %GOPATH%\src\github.com\ipfs\go-ipfs | ||
| make install | ||
| %GOPATH%\bin\ipfs.exe version --all | ||
| ``` | ||
|
|
||
| Then get the current Git commit: | ||
| 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 `go-ipfs` repo. You can retrieve said hash via this command: `git rev-parse --short HEAD`. | ||
| If `ipfs.exe` executes and the version string matches, then building was successful. | ||
|
|
||
| |Command|Explanation| | ||
| | ---: | :--- | | ||
| |`SET PATH=%PATH%;\cygwin64\bin` |Add Cygwin's tools to our [`PATH`](https://ss64.com/nt/path.html); Defaults to: (\cygwin64\bin)| | ||
| |`mkdir %GOPATH%\src\github.com\ipfs`<br/>`cd %GOPATH%\src\github.com\ipfs`<br/>`git clone https://github.com/ipfs/go-ipfs.git` |Fetch / Update `go-ipfs` source| | ||
| |`cd %GOPATH%\src\github.com\ipfs\go-ipfs` |Change to `go-ipfs` source directory| | ||
| |`make install` |Build and install to `%GOPATH%\bin\ipfs.exe`| | ||
| |`%GOPATH%\bin\ipfs.exe version --all` |Test the built binary| | ||
|
|
||
| To build again after making changes to the source, run: | ||
| ``` | ||
| git rev-parse --short HEAD | ||
| SET PATH=%PATH%;\cygwin64\bin | ||
| cd %GOPATH%\src\github.com\ipfs\go-ipfs | ||
| make install | ||
| ``` | ||
|
|
||
| It will output a small number of hex characters that you must pass to | ||
| the actual build command (replace XXXXXXX with these characters): | ||
|
|
||
| **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: | ||
| ``` | ||
| go install -ldflags="-X "github.com/ipfs/go-ipfs/repo/config".CurrentCommit=XXXXXXX" | ||
| SETX PATH %PATH% | ||
| ``` | ||
|
|
||
| After that ipfs should have been built and should be available in | ||
| "%GOPATH%\bin". | ||
| ## Minimal | ||
| While it's possible to build `go-ipfs` with `go` alone, we'll be using `git` and `gx` for practical source management. | ||
| 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. | ||
|
|
||
| You can check that the ipfs you built has the right version using: | ||
| ### `gx` | ||
| You may install prebuilt binaries for [`gx`](https://dist.ipfs.io/#gx) & [`gx-go`](https://dist.ipfs.io/#gx-go) if they're available for your platform. | ||
| Alternatively, you can build them from source and install them to `%GOPATH%\bin` by running the following: | ||
|
|
||
| ``` | ||
| ipfs version --commit | ||
| go get -u github.com/whyrusleeping/gx | ||
| go get -u github.com/whyrusleeping/gx-go | ||
| ``` | ||
|
|
||
| It should output something like "ipfs version 0.4.0-dev-XXXXXXX" where | ||
| XXXXXXX is the current commit that you passed to the build command. | ||
|
|
||
| ## Cygwin way: install Cygwin | ||
|
|
||
| Install Cygwin as explained in the Cygwin documentation: | ||
| ### `go-ipfs` | ||
|
|
||
| http://cygwin.com/install.html | ||
|
|
||
| By default Cygwin will not install 'make', so you should click on the | ||
| "Devel" category during the Cygwin installation process and then check | ||
| the 'make' package. | ||
|
|
||
| ## Cygwin way: build go-ipfs | ||
|
|
||
| To build go-ipfs using Cygwin you just need to open a Cygwin Terminal | ||
| and then type the following commands: | ||
| ``` | ||
| SET PATH=%PATH%;%GOPATH%\bin | ||
| go get -u -d github.com/ipfs/go-ipfs | ||
| cd %GOPATH%/src/github.com/ipfs/go-ipfs | ||
| gx --verbose install --global | ||
| cd cmd\ipfs | ||
| ``` | ||
| 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. | ||
| - interactive: `FOR /F %V IN ('git rev-parse --short HEAD') do set SHA=%V` | ||
| - interpreter: `FOR /F %%V IN ('git rev-parse --short HEAD') do set SHA=%%V` | ||
|
|
||
| Finally, we'll build and test `ipfs` itself. | ||
| ``` | ||
| cd $GOPATH/src/github.com/ipfs/go-ipfs | ||
| make install | ||
| go install -ldflags="-X "github.com/ipfs/go-ipfs/repo/config".CurrentCommit=%SHA%" | ||
| %GOPATH%\bin\ipfs.exe version --all | ||
| ``` | ||
| You can check that the ipfs output versions match with `go version` and `git rev-parse --short HEAD`. | ||
| If `ipfs.exe` executes and everything matches, then building was successful. | ||
|
|
||
| After that ipfs should have been built and should be available in | ||
| "%GOPATH%\bin". | ||
| ## Troubleshooting | ||
| - **Git auth** | ||
| 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: | ||
| `git config --global credential.helper wincred` | ||
|
|
||
| You can check that the ipfs you built has the right version using: | ||
| - **Anything else** | ||
| Please search [https://discuss.ipfs.io](https://discuss.ipfs.io/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. | ||
|
|
||
| ``` | ||
| ipfs version --commit | ||
| ``` | ||
| If you encounter a bug with `go-ipfs` itself (not related to building) please use the [issue tracker](https://github.com/ipfs/go-ipfs/issues) to report it. |