diff options
Diffstat (limited to 'doc/build-windows.md')
-rw-r--r-- | doc/build-windows.md | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/doc/build-windows.md b/doc/build-windows.md new file mode 100644 index 0000000000..c415595e43 --- /dev/null +++ b/doc/build-windows.md @@ -0,0 +1,159 @@ +WINDOWS BUILD NOTES +==================== + +Below are some notes on how to build Bitcoin Core for Windows. + +Most developers use cross-compilation from Ubuntu to build executables for +Windows. This is also used to build the release binaries. + +Building on Ubuntu Trusty 14.04 is recommended. +At the time of writing the Windows Subsystem for Linux installs Ubuntu Xenial 16.04. The default cross +compiler package for Ubuntu Xenial does not produce working executables for some of the bitcoin applications. +It is possible to build on Ubuntu Xenial by installing the cross compiler packages from +Ubuntu Zesty, see the steps below. +Building on Ubuntu Zesty 17.04 up to 17.10 has been verified to work. + +While there are potentially a number of ways to build on Windows (for example using msys / mingw-w64), +using the Windows Subsystem For Linux is the most straightforward. If you are building with +another method, please contribute the instructions here for others who are running versions +of Windows that are not compatible with the Windows Subsystem for Linux. + +Compiling with Windows Subsystem For Linux +------------------------------------------- + +With Windows 10, Microsoft has released a new feature named the [Windows +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 +environment. Within this environment you can cross compile for Windows without +the need for a separate Linux VM or server. + +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](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide). + +For Windows 10 systems with the Fall Creators Update applied (version >= 16215.0) use the Windows Store +to install Ubuntu. Search for "Linux" in the Windows Store and install the free "Ubuntu" application. +Full instructions are available on the above link. + +To get the bash shell, you must first activate the feature in Windows. + +1. Turn on Developer Mode + * Open Settings -> Update and Security -> For developers + * Select the Developer Mode radio button + * Restart if necessary +2. Enable the Windows Subsystem for Linux feature + * From Start, search for "Turn Windows features on or off" (type 'turn') + * Select Windows Subsystem for Linux (beta) + * Click OK + * Restart if necessary +3. Complete Installation + * Open a cmd prompt and type "bash" + * Accept the license + * 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 +with the "Cross-compilation" section. Compiling the 64-bit version is +recommended but it is possible to compile the 32-bit version. + +Cross-compilation +------------------- + +These steps can be performed on, for example, an Ubuntu VM. The depends system +will also work on other Linux distributions, however the commands for +installing the toolchain will be different. + +First, install the general dependencies: + + sudo apt install build-essential libtool autotools-dev automake pkg-config bsdmainutils curl git + +A host toolchain (`build-essential`) is necessary because some dependency +packages (such as `protobuf`) need to build host utilities that are used in the +build process. + +See also: [dependencies.md](dependencies.md). + +## Building for 64-bit Windows + +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. + +Common steps to install mingw32 cross compiler tool chain: + + 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 zesty 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 Zesty 17.04 <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: + + PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var + cd depends + make HOST=x86_64-w64-mingw32 + cd .. + ./autogen.sh # not required when building from tarball + CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/ + make + +## Building for 32-bit Windows + +To build executables for Windows 32-bit, install the following dependencies: + + sudo apt install g++-mingw-w64-i686 mingw-w64-i686-dev + +For Ubuntu Xenial 16.04, Ubuntu Zesty 17.04 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. + +Then build using: + + PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var + cd depends + make HOST=i686-w64-mingw32 + cd .. + ./autogen.sh # not required when building from tarball + CONFIG_SITE=$PWD/depends/i686-w64-mingw32/share/config.site ./configure --prefix=/ + make + +## Depends system + +For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. + +Installation +------------- + +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 +as they appear in the release `.zip` archive. This can be done in the following +way. This will install to `c:\workspace\bitcoin`, for example: + + make install DESTDIR=/mnt/c/workspace/bitcoin + +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 distribution solves the issue, however, this is not +an officially supported approach and it's only recommended if you are prepared to reinstall WSL/Ubutntu 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). |