mirror of
https://github.com/ethereum/go-ethereum.git
synced 2026-08-20 10:52:25 +00:00
move cross compile doc to into build category
This commit is contained in:
Felix Lange
parent
50dd37fb13
commit
f3c47a421d
1 changed files with 59 additions and 60 deletions
|
|
@ -1,21 +1,21 @@
|
|||
---
|
||||
title: Cross-compiling Ethereum
|
||||
title: Cross-Compiling Geth
|
||||
---
|
||||
**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.
|
||||
**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.**
|
||||
|
||||
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.
|
||||
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:
|
||||
|
||||
|
|
@ -24,28 +24,27 @@ The currently supported target platforms are:
|
|||
- 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.
|
||||
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.
|
||||
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.
|
||||
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:
|
||||
|
||||
|
|
@ -70,8 +69,8 @@ compile itself and verifying that all cross compilations succeeded or not.
|
|||
|
||||
## Building Ethereum
|
||||
|
||||
Cross compiling Ethereum is analogous to the above example, but an additional
|
||||
flags is required to satisfy the dependencies:
|
||||
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
|
||||
|
||||
|
|
@ -92,38 +91,38 @@ Injecting the GNU Arithmetic Library dependency and selecting `geth` would be:
|
|||
-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).
|
||||
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.
|
||||
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`):
|
||||
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:
|
||||
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.
|
||||
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/* \
|
||||
|
|
@ -131,20 +130,20 @@ To limit the build targets or compile to a different Android platform, use the
|
|||
|
||||
### 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:
|
||||
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:
|
||||
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`)
|
||||
|
|
@ -163,5 +162,5 @@ 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.
|
||||
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 a new issue