mirror of
https://github.com/ipfs/kubo.git
synced 2025-06-26 15:42:21 +08:00
Merge pull request #4691 from djdv/docs/windows
Change Windows build documentation
This commit is contained in:
Whyrusleeping
239
docs/windows.md
239
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.
|
||||
|
||||
|
||||
## Install Go
|
||||
|
||||
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.
|
||||
|
||||
## Download go-ipfs and fix Git authentication
|
||||
|
||||
Use the following command to download go-ipfs source code:
|
||||
|
||||
```
|
||||
go get -u github.com/ipfs/go-ipfs
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
git config --global credential.helper wincred
|
||||
```
|
||||
`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
|
||||
|
||||
## 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.
|
||||
|
||||
Now there are two ways to download, install the dependencies and to
|
||||
build go-ipfs:
|
||||
**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)
|
||||
|
||||
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.
|
||||
**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)
|
||||
|
||||
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.
|
||||
## 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
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Manual Way: download and install dependencies
|
||||
|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|
|
||||
|
||||
The following commands should download or update go-ipfs dependencies
|
||||
and then install them:
|
||||
To build again after making changes to the source, run:
|
||||
```
|
||||
SET PATH=%PATH%;\msys64\usr\bin
|
||||
cd %GOPATH%\src\github.com\ipfs\go-ipfs
|
||||
make install
|
||||
```
|
||||
|
||||
**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:
|
||||
```
|
||||
SETX PATH %PATH%
|
||||
```
|
||||
|
||||
## 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.
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
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:
|
||||
```
|
||||
SET PATH=%PATH%;\cygwin64\bin
|
||||
cd %GOPATH%\src\github.com\ipfs\go-ipfs
|
||||
make install
|
||||
```
|
||||
|
||||
**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:
|
||||
```
|
||||
SETX PATH %PATH%
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
### `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:
|
||||
|
||||
```
|
||||
go get -u github.com/whyrusleeping/gx
|
||||
go get -u github.com/whyrusleeping/gx-go
|
||||
```
|
||||
|
||||
### `go-ipfs`
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## Manual Way: build go-ipfs
|
||||
|
||||
To actually build go-ipfs, first go to the cmd/ipfs directory:
|
||||
|
||||
```
|
||||
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`
|
||||
|
||||
Then get the current Git commit:
|
||||
|
||||
Finally, we'll build and test `ipfs` itself.
|
||||
```
|
||||
git rev-parse --short HEAD
|
||||
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.
|
||||
|
||||
It will output a small number of hex characters that you must pass to
|
||||
the actual build command (replace XXXXXXX with these characters):
|
||||
## 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`
|
||||
|
||||
```
|
||||
go install -ldflags="-X "github.com/ipfs/go-ipfs/repo/config".CurrentCommit=XXXXXXX"
|
||||
```
|
||||
- **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.
|
||||
|
||||
After that ipfs should have been built and should be available in
|
||||
"%GOPATH%\bin".
|
||||
|
||||
You can check that the ipfs you built has the right version using:
|
||||
|
||||
```
|
||||
ipfs version --commit
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
cd $GOPATH/src/github.com/ipfs/go-ipfs
|
||||
make install
|
||||
```
|
||||
|
||||
After that ipfs should have been built and should be available in
|
||||
"%GOPATH%\bin".
|
||||
|
||||
You can check that the ipfs you built has the right version using:
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user