diff --git a/docs/_install-and-build/cross-compile.md b/docs/_install-and-build/cross-compile.md deleted file mode 100644 index 55af4e6652..0000000000 --- a/docs/_install-and-build/cross-compile.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Cross-Compiling Geth -sort_key: C ---- - -**Note: All of these and much more have been merged into the project Makefile. You can -cross build via `make geth--` without needing to know any of these details -from below.** - -Developers usually have a preferred platform that they feel most comfortable working in, -with all the necessary tools, libraries and environments set up for an optimal workflow. -However, there's often need to build for either a different CPU architecture, or an -entirely different operating system; but maintaining a development environment for each -and switching between the them quickly becomes unwieldy. - -Here we present a very simple way to cross compile Ethereum to various operating systems -and architectures using a minimal set of prerequisites and a completely containerized -approach, guaranteeing that your development environment remains clean even after the -complex requirements and mechanisms of a cross compilation. - -The currently supported target platforms are: - - - ARMv7 Android and iOS - - 32 bit, 64 bit and ARMv5 Linux - - 32 bit and 64 bit Mac OSX - - 32 bit and 64 bit Windows - -Please note, that cross compilation does not replace a release build. Although resulting -binaries can usually run perfectly on the desired platform, compiling on a native system -with the specialized tools provided by the official vendor can often result in more a -finely optimized code. - -## Cross compilation environment - -Although the `go-ethereum` project is written in Go, it does include a bit of C code -shared between all implementations to ensure that all perform equally well, including a -dependency to the GNU Multiple Precision Arithmetic Library. Because of these, Go cannot -by itself compile to a different platform than the host. To overcome this limitation, we -will use [`xgo`](https://github.com/karalabe/xgo), a Go cross compiler package based on -Docker containers that has been architected specifically to allow both embedded C snippets -as well as simpler external C dependencies during compilation. - -The `xgo` project has two simple dependencies: Docker (to ensure that the build -environment is completely contained) and Go. On most platforms these should be available -from the official package repositories. For manually installing them, please consult their -install guides at [Docker](https://docs.docker.com/installation/) and -[Go](https://golang.org/doc/install) respectively. This guide assumes that these two -dependencies are met. - -To install and/or update xgo, simply type: - - $ go get -u github.com/karalabe/xgo - -You can test whether `xgo` is functioning correctly by requesting it to cross -compile itself and verifying that all cross compilations succeeded or not. - - $ xgo github.com/karalabe/xgo - ... - - $ ls -al - -rwxr-xr-x 1 root root 2792436 Sep 14 16:45 xgo-android-21-arm - -rwxr-xr-x 1 root root 2353212 Sep 14 16:45 xgo-darwin-386 - -rwxr-xr-x 1 root root 2906128 Sep 14 16:45 xgo-darwin-amd64 - -rwxr-xr-x 1 root root 2388288 Sep 14 16:45 xgo-linux-386 - -rwxr-xr-x 1 root root 2960560 Sep 14 16:45 xgo-linux-amd64 - -rwxr-xr-x 1 root root 2437864 Sep 14 16:45 xgo-linux-arm - -rwxr-xr-x 1 root root 2551808 Sep 14 16:45 xgo-windows-386.exe - -rwxr-xr-x 1 root root 3130368 Sep 14 16:45 xgo-windows-amd64.exe - - -## Building Ethereum - -Cross compiling Ethereum is analogous to the above example, but an additional flags is -required to satisfy the dependencies: - - - `--deps` is used to inject arbitrary C dependency packages and pre-build them - -Injecting the GNU Arithmetic Library dependency and selecting `geth` would be: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - github.com/ethereum/go-ethereum/cmd/geth - ... - - $ ls -al - -rwxr-xr-x 1 root root 23213372 Sep 14 17:59 geth-android-21-arm - -rwxr-xr-x 1 root root 14373980 Sep 14 17:59 geth-darwin-386 - -rwxr-xr-x 1 root root 17373676 Sep 14 17:59 geth-darwin-amd64 - -rwxr-xr-x 1 root root 21098910 Sep 14 17:59 geth-linux-386 - -rwxr-xr-x 1 root root 25049693 Sep 14 17:59 geth-linux-amd64 - -rwxr-xr-x 1 root root 20578535 Sep 14 17:59 geth-linux-arm - -rwxr-xr-x 1 root root 16351260 Sep 14 17:59 geth-windows-386.exe - -rwxr-xr-x 1 root root 19418071 Sep 14 17:59 geth-windows-amd64.exe - - -As the cross compiler needs to build all the dependencies as well as the main project -itself for each platform, it may take a while for the build to complete (approximately 3-4 -minutes on a Core i7 3770K machine). - -### Fine tuning the build - -By default Go, and inherently `xgo`, checks out and tries to build the master branch of a -source repository. However, more often than not, you'll probably want to build a different -branch from possibly an entirely different remote repository. These can be controlled via -the `--remote` and `--branch` flags. - -To build the `develop` branch of the official `go-ethereum` repository instead of the -default `master` branch, you just need to specify it as an additional command line flag -(`--branch`): - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --branch=develop \ - github.com/ethereum/go-ethereum/cmd/geth - -Additionally, during development you will most probably want to not only build a custom -branch, but also one originating from your own fork of the repository instead of the -upstream one. This can be done via the `--remote` flag: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --remote=https://github.com/karalabe/go-ethereum \ - --branch=rpi-staging \ - github.com/ethereum/go-ethereum/cmd/geth - -By default `xgo` builds binaries for all supported platforms and architectures, with -Android binaries defaulting to the highest released Android NDK platform. To limit the -build targets or compile to a different Android platform, use the `--targets` CLI -parameter. - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - --targets=android-16/arm,windows/* \ - github.com/ethereum/go-ethereum/cmd/geth - -### Building locally - -If you would like to cross compile your local development version, simply specify a local -path (starting with `.` or `/`), and `xgo` will use all local code from `GOPATH`, only -downloading missing dependencies. In such a case of course, the `--branch`, `--remote` and -`--pkg` arguments are no-op: - - $ xgo --deps=https://gmplib.org/download/gmp/gmp-6.0.0a.tar.bz2 \ - ./cmd/geth - -## Using the Makefile - -Having understood the gist of `xgo` based cross compilation, you do not need to actually -memorize and maintain these commands, as they have been incorporated into the official -[Makefile](https://github.com/ethereum/go-ethereum/blob/master/Makefile) and can be -invoked with a trivial `make` request: - - * `make geth-cross`: Cross compiles to every supported OS and architecture - * `make geth-`: Cross compiles supported architectures of a particular OS (e.g. `linux`) - * `make geth--`: Cross compiles to a specific OS/architecture (e.g. `linux`, `arm`) - -We advise using the `make` based commands opposed to manually invoking `xgo` as we do -maintain the Makefile actively whereas we cannot guarantee that this document will be -always readily updated to latest advancements. - -### Tuning the cross builds - -A few of the `xgo` build options have also been surfaced directly into the Makefile to -allow fine tuning builds to work around either upstream Go issues, or to enable some -fancier mechanics. - - - `make ... GO=`: Use a specific Go runtime (e.g. `1.5.1`, `1.5-develop`, `develop`) - - `make ... MODE=`: Build a specific target type (e.g. `exe`, `c-archive`). - -Please note that these are not yet fully finalized, so they may or may not change in the -future as our code and the Go runtime features change.