Joseph Cook
GitHub
parent
fa6793df1b
commit
bfba3a30a5
|
|
@ -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-<os>-<platform>` 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-<os>`: Cross compiles supported architectures of a particular OS (e.g. `linux`)
|
||||
* `make geth-<os>-<arch>`: 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=<go>`: Use a specific Go runtime (e.g. `1.5.1`, `1.5-develop`, `develop`)
|
||||
- `make ... MODE=<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.
|
||||
Loading…
Reference in New Issue