aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorAaron Clauson <aaron.clauson@gmail.com>2017-10-15 22:51:53 +1100
committerAaron Clauson <aaron.clauson@gmail.com>2017-10-15 22:51:53 +1100
commite0fc4a73563189a1d60a222cf89c4f624d2d8e80 (patch)
treef2d3a4692a1f0232c69e2bfed6726b540db641f2 /doc
parent6ab0e4cf49549640b903bf5fce0e6035b8116397 (diff)
Updated Windows build doc for WSL/Xenial workarounds.
Diffstat (limited to 'doc')
-rw-r--r--doc/build-windows.md70
1 files changed, 53 insertions, 17 deletions
diff --git a/doc/build-windows.md b/doc/build-windows.md
index 0d96af26a2..90bf53d9d0 100644
--- a/doc/build-windows.md
+++ b/doc/build-windows.md
@@ -4,11 +4,14 @@ 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. Cross-compilation is also used to build the release binaries.
+Windows. This is also used to build the release binaries.
-Currently only building on Ubuntu Trusty 14.04 or Ubuntu Zesty 17.04 or later is supported.
-Building on Ubuntu Xenial 16.04 is known to be broken, see extensive discussion in issue [8732](https://github.com/bitcoin/bitcoin/issues/8732).
-While it may be possible to do so with work arounds, it's potentially dangerous and not recommended.
+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
@@ -19,7 +22,7 @@ Compiling with Windows Subsystem For Linux
-------------------------------------------
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
environment. Within this environment you can cross compile for Windows without
the need for a separate Linux VM or server.
@@ -57,7 +60,7 @@ installing the toolchain will be different.
First, install the general dependencies:
- sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils curl
+ 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
@@ -65,20 +68,32 @@ build process.
See also: [dependencies.md](dependencies.md).
-If you're building on Ubuntu 17.04 or later, run these two commands, selecting the 'posix' variant for both,
-to work around issues with mingw-w64. See issue [8732](https://github.com/bitcoin/bitcoin/issues/8732) for more information.
-```
-sudo update-alternatives --config x86_64-w64-mingw32-g++
-sudo update-alternatives --config x86_64-w64-mingw32-gcc
-```
-
## 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 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
@@ -92,7 +107,11 @@ Then build using:
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 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:
@@ -117,3 +136,20 @@ 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).