From bb47b63971eb312ed77c86025f5e4e6eaab0f38a Mon Sep 17 00:00:00 2001 From: Dominic Della Valle Date: Mon, 12 Feb 2018 20:37:26 -0500 Subject: [PATCH] Change Windows build documentation License: MIT Signed-off-by: Dominic Della Valle --- docs/windows.md | 209 +++++++++++++++++++++++++----------------------- 1 file changed, 107 insertions(+), 102 deletions(-) diff --git a/docs/windows.md b/docs/windows.md index 588fe269416..c5819395591 100644 --- a/docs/windows.md +++ b/docs/windows.md @@ -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. +![](https://ipfs.io/ipfs/QmccXW7JSZMVXidSc7tHsU6aktuaiV923q4yBGHUsdymYo/build.gif) ## 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`
`cd %GOPATH%\src\github.com\ipfs`
`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 . `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.