Changeset View
Changeset View
Standalone View
Standalone View
doc/build-windows.md
WINDOWS BUILD NOTES | WINDOWS BUILD NOTES | ||||
==================== | ==================== | ||||
Below are some notes on how to build Bitcoin ABC for Windows. | Below are some notes on how to build Bitcoin ABC for Windows. | ||||
Most developers use cross-compilation from Ubuntu to build executables for | The options known to work for building Bitcoin ABC on Windows are: | ||||
Windows. This is also used to build the release binaries. | |||||
While there are potentially a number of ways to build on Windows (for example using msys / mingw-w64), | * On Linux using the [Mingw-w64](https://mingw-w64.org/doku.php) cross compiler tool chain. Ubuntu Trusty 14.04 is recommended | ||||
using the Windows Subsystem For Linux is the most straightforward. If you are building with | and is the platform used to build the Bitcoin ABC Windows release binaries. | ||||
another method, please contribute the instructions here for others who are running versions | * On Windows using [Windows | ||||
of Windows that are not compatible with the Windows Subsystem for Linux. | Subsystem for Linux (WSL)](https://msdn.microsoft.com/commandline/wsl/about) and the Mingw-w64 cross compiler tool chain. | ||||
Compiling with Windows Subsystem For Linux | Other options which may work but which have not been extensively tested are (please contribute instructions): | ||||
------------------------------------------- | |||||
* On Windows using a POSIX compatibility layer application such as [cygwin](http://www.cygwin.com/) or [msys2](http://www.msys2.org/). | |||||
* On Windows using a native compiler tool chain such as [Visual Studio](https://www.visualstudio.com). | |||||
Installing Windows Subsystem for Linux | |||||
--------------------------------------- | |||||
With Windows 10, Microsoft has released a new feature named the [Windows | With Windows 10, Microsoft has released a new feature named the [Windows | ||||
Subsystem for Linux](https://msdn.microsoft.com/commandline/wsl/about). This | Subsystem for Linux (WSL)](https://msdn.microsoft.com/commandline/wsl/about). This | ||||
feature allows you to run a bash shell directly on Windows in an Ubuntu-based | feature allows you to run a bash shell directly on Windows in an Ubuntu-based | ||||
environment. Within this environment you can cross compile for Windows without | environment. Within this environment you can cross compile for Windows without | ||||
the need for a separate Linux VM or server. | the need for a separate Linux VM or server. Note that while WSL can be installed with | ||||
other Linux variants, such as OpenSUSE, the following instructions have only been | |||||
tested with Ubuntu. | |||||
This feature is not supported in versions of Windows prior to Windows 10 or on | This feature is not supported in versions of Windows prior to Windows 10 or on | ||||
Windows Server SKUs. In addition, it is available [only for 64-bit versions of | Windows Server SKUs. In addition, it is available [only for 64-bit versions of | ||||
Windows](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide). | Windows](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide). | ||||
To get the bash shell, you must first activate the feature in Windows. | Full instructions to install WSL are available on the above link. | ||||
To install WSL on Windows 10 with Fall Creators Update installed (version >= 16215.0) do the following: | |||||
1. Turn on Developer Mode | 1. Enable the Windows Subsystem for Linux feature | ||||
* Open Settings -> Update and Security -> For developers | * Open the Windows Features dialog (`OptionalFeatures.exe`) | ||||
* Select the Developer Mode radio button | * Enable 'Windows Subsystem for Linux' | ||||
* Restart if necessary | * Click 'OK' and restart if necessary | ||||
2. Enable the Windows Subsystem for Linux feature | 2. Install Ubuntu | ||||
* From Start, search for "Turn Windows features on or off" (type 'turn') | * Open Microsoft Store and search for Ubuntu or use [this link](https://www.microsoft.com/store/productId/9NBLGGH4MSV6) | ||||
* Select Windows Subsystem for Linux (beta) | * Click Install | ||||
* Click OK | |||||
* Restart if necessary | |||||
3. Complete Installation | 3. Complete Installation | ||||
* Open a cmd prompt and type "bash" | * Open a cmd prompt and type "Ubuntu" | ||||
* Accept the license | |||||
* Create a new UNIX user account (this is a separate account from your Windows account) | * Create a new UNIX user account (this is a separate account from your Windows account) | ||||
After the bash shell is active, you can follow the instructions below, starting | After the bash shell is active, you can follow the instructions below, starting | ||||
with the "Cross-compilation" section. Compiling the 64-bit version is | with the "Cross-compilation" section. Compiling the 64-bit version is | ||||
recommended but it is possible to compile the 32-bit version. | recommended but it is possible to compile the 32-bit version. | ||||
Cross-compilation | Cross-compilation for Ubuntu and Windows Subsystem for Linux | ||||
------------------- | ------------------------------------------------------------ | ||||
At the time of writing the Windows Subsystem for Linux installs Ubuntu Xenial 16.04. The Mingw-w64 package | |||||
for Ubuntu Xenial does not produce working executables for some of the Bitcoin ABC applications. | |||||
It is possible to build on Ubuntu Xenial by installing the cross compiler packages from Ubuntu Artful, see the steps below. | |||||
Building on Ubuntu Artful 17.10 has been verified to work. | |||||
These steps can be performed on, for example, an Ubuntu VM. The depends system | The steps below can be performed on Ubuntu (including in a VM) or WSL. The depends system | ||||
will also work on other Linux distributions, however the commands for | will also work on other Linux distributions, however the commands for | ||||
installing the toolchain will be different. | installing the toolchain will be different. | ||||
First, install the general dependencies: | First, install the general dependencies: | ||||
sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils curl | sudo apt update | ||||
sudo apt upgrade | |||||
sudo apt install build-essential libtool autotools-dev automake pkg-config bsdmainutils curl git | |||||
A host toolchain (`build-essential`) is necessary because some dependency | A host toolchain (`build-essential`) is necessary because some dependency | ||||
packages (such as `protobuf`) need to build host utilities that are used in the | packages (such as `protobuf`) need to build host utilities that are used in the | ||||
build process. | build process. | ||||
See also: [dependencies.md](dependencies.md). | |||||
## Building for 64-bit Windows | ## Building for 64-bit Windows | ||||
To build executables for Windows 64-bit, install the following dependencies: | The first step is to install the mingw-w64 cross-compilation tool chain. Due to different Ubuntu | ||||
packages for each distribution and problems with the Xenial packages the steps for each are different. | |||||
sudo apt-get install g++-mingw-w64-x86-64 mingw-w64-x86-64-dev | Common steps to install mingw32 cross compiler tool chain: | ||||
Then build using: | sudo apt install g++-mingw-w64-x86-64 | ||||
Ubuntu Trusty 14.04: | |||||
No further steps required | |||||
Ubuntu Xenial 16.04 and Windows Subsystem for Linux <sup>[1](#footnote1),[2](#footnote2)</sup>: | |||||
sudo apt install software-properties-common | |||||
sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu artful universe" | |||||
sudo apt update | |||||
sudo apt upgrade | |||||
sudo update-alternatives --config x86_64-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. | |||||
Ubuntu Artful 17.10 <sup>[2](#footnote2)</sup>: | |||||
sudo update-alternatives --config x86_64-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. | |||||
Once the tool chain is installed the build steps are common: | |||||
Note that for WSL the Bitcoin ABC source path MUST be somewhere in the default mount file system, for | |||||
example /usr/src/bitcoin-abc, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. | |||||
This means you cannot use a directory that located directly on the host Windows file system to perform the build. | |||||
Acquire the source in the usual way: | |||||
git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git | |||||
Once the source code is ready the build steps are below. | |||||
PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var | |||||
cd depends | cd depends | ||||
make HOST=x86_64-w64-mingw32 | make HOST=x86_64-w64-mingw32 | ||||
cd .. | cd .. | ||||
./autogen.sh # not required when building from tarball | ./autogen.sh # not required when building from tarball | ||||
CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/ | CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/ | ||||
make | make | ||||
## Building for 32-bit Windows | ## Building for 32-bit Windows | ||||
To build executables for Windows 32-bit, install the following dependencies: | To build executables for Windows 32-bit, install the following dependencies: | ||||
sudo apt-get install g++-mingw-w64-i686 mingw-w64-i686-dev | sudo apt install g++-mingw-w64-i686 mingw-w64-i686-dev | ||||
For Ubuntu Xenial 16.04, Ubuntu Artful 17.10 and Windows Subsystem for Linux <sup>[2](#footnote2)</sup>: | |||||
sudo update-alternatives --config i686-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. | |||||
Note that for WSL the Bitcoin ABC source path MUST be somewhere in the default mount file system, for | |||||
example /usr/src/bitcoin-abc, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. | |||||
This means you cannot use a directory that located directly on the host Windows file system to perform the build. | |||||
Acquire the source in the usual way: | |||||
git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git | |||||
Then build using: | Then build using: | ||||
PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var | |||||
cd depends | cd depends | ||||
make HOST=i686-w64-mingw32 | make HOST=i686-w64-mingw32 | ||||
cd .. | cd .. | ||||
./autogen.sh # not required when building from tarball | ./autogen.sh # not required when building from tarball | ||||
CONFIG_SITE=$PWD/depends/i686-w64-mingw32/share/config.site ./configure --prefix=/ | CONFIG_SITE=$PWD/depends/i686-w64-mingw32/share/config.site ./configure --prefix=/ | ||||
make | make | ||||
## Depends system | ## Depends system | ||||
For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. | For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. | ||||
Installation | Installation | ||||
------------- | ------------- | ||||
After building using the Windows subsystem it can be useful to copy the compiled | After building using the Windows subsystem it can be useful to copy the compiled | ||||
executables to a directory on the windows drive in the same directory structure | executables to a directory on the windows drive in the same directory structure | ||||
as they appear in the release `.zip` archive. This can be done in the following | as they appear in the release `.zip` archive. This can be done in the following | ||||
way. This will install to `c:\workspace\bitcoin-abc`, for example: | way. This will install to `c:\workspace\bitcoin-abc`, for example: | ||||
make install DESTDIR=/mnt/c/workspace/bitcoin-abc | make install DESTDIR=/mnt/c/workspace/bitcoin-abc | ||||
Footnotes | |||||
--------- | |||||
<a name="footnote1">1</a>: There is currently a bug in the 64 bit Mingw-w64 cross compiler packaged for WSL/Ubuntu Xenial 16.04 that | |||||
causes two of the bitcoin executables to crash shortly after start up. The bug is related to the | |||||
-fstack-protector-all g++ compiler flag which is used to mitigate buffer overflows. | |||||
Installing the Mingw-w64 packages from the Ubuntu 17.10 distribution solves the issue, however, this is not | |||||
an officially supported approach and it's only recommended if you are prepared to reinstall WSL/Ubuntu should | |||||
something break. | |||||
<a name="footnote2">2</a>: Starting from Ubuntu Xenial 16.04 both the 32 and 64 bit Mingw-w64 packages install two different | |||||
compiler options to allow a choice between either posix or win32 threads. The default option is win32 threads which is the more | |||||
efficient since it will result in binary code that links directly with the Windows kernel32.lib. Unfortunately, the headers | |||||
required to support win32 threads conflict with some of the classes in the C++11 standard library in particular std::mutex. | |||||
It's not possible to build the bitcoin code using the win32 version of the Mingw-w64 cross compilers (at least not without | |||||
modifying headers in the bitcoin source code). |