diff --git a/docs/_developers/Cross-compiling-Ethereum.md b/docs/_install-and-build/cross-compile.md similarity index 59% rename from docs/_developers/Cross-compiling-Ethereum.md rename to docs/_install-and-build/cross-compile.md index 9cb8852f44..6fcd561d6d 100644 --- a/docs/_developers/Cross-compiling-Ethereum.md +++ b/docs/_install-and-build/cross-compile.md @@ -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--` 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--` 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-`: Cross compiles supported architectures of a particular OS (e.g. `linux`) @@ -163,5 +162,5 @@ 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. \ No newline at end of file +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.