1Building Bitcoin Core with Visual Studio
2========================================
3
4Introduction
5---------------------
6Solution and project files to build the Bitcoin Core applications `msbuild` or Visual Studio can be found in the `build_msvc` directory. The build has been tested with Visual Studio 2019 (building with earlier versions of Visual Studio should not be expected to work).
7
8Building with Visual Studio is an alternative to the Linux based [cross-compiler build](https://github.com/bitcoin/bitcoin/blob/master/doc/build-windows.md).
9
10Quick Start
11---------------------
12The minimal steps required to build Bitcoin Core with the msbuild toolchain are below. More detailed instructions are contained in the following sections.
13
14```
15cd build_msvc
16py -3 msvc-autogen.py
17msbuild /m bitcoin.sln /p:Platform=x64 /p:Configuration=Release /t:build
18```
19
20Dependencies
21---------------------
22A number of [open source libraries](https://github.com/bitcoin/bitcoin/blob/master/doc/dependencies.md) are required in order to be able to build Bitcoin Core.
23
24Options for installing the dependencies in a Visual Studio compatible manner are:
25
26- Use Microsoft's [vcpkg](https://docs.microsoft.com/en-us/cpp/vcpkg) to download the source packages and build locally. This is the recommended approach.
27- Download the source code, build each dependency, add the required include paths, link libraries and binary tools to the Visual Studio project files.
28- Use [nuget](https://www.nuget.org/) packages with the understanding that any binary files have been compiled by an untrusted third party.
29
30The [external dependencies](https://github.com/bitcoin/bitcoin/blob/master/doc/dependencies.md) required for building are listed in the `build_msvc/vcpkg.json` file. To ensure `msbuild` project files automatically install the `vcpkg` dependencies use:
31
32```
33vcpkg integrate install
34```
35
36Qt
37---------------------
38In order to build Bitcoin Core a static build of Qt is required. The runtime library version (e.g. v142) and platform type (x86 or x64) must also match.
39
40Some prebuilt x64 versions of Qt can be downloaded from [here](https://github.com/sipsorcery/qt_win_binary/releases). Please be aware these downloads are NOT officially sanctioned by Bitcoin Core and are provided for developer convenience only. They should NOT be used for builds that will be used in a production environment or with real funds.
41
42To determine which Qt prebuilt version to download open the `.appveyor.yml` file and note the `QT_DOWNLOAD_URL`. When extracting the zip file the destination path must be set to `C:\`. This is due to the way that Qt includes, libraries and tools use internal paths.
43
44To build Bitcoin Core without Qt unload or disable the `bitcoin-qt`, `libbitcoin_qt` and `test_bitcoin-qt` projects.
45
46Building
47---------------------
48The instructions below use `vcpkg` to install the dependencies.
49
50- Install [`vcpkg`](https://github.com/Microsoft/vcpkg).
51
52- Use Python to generate `*.vcxproj` from Makefile
53
54```
55PS >py -3 msvc-autogen.py
56```
57
58- An optional step is to adjust the settings in the `build_msvc` directory and the `common.init.vcxproj` file. This project file contains settings that are common to all projects such as the runtime library version and target Windows SDK version. The Qt directories can also be set.
59
60- To build from the command line with the Visual Studio 2019 toolchain use:
61
62```
63msbuild /m bitcoin.sln /p:Platform=x64 /p:Configuration=Release /t:build
64```
65
66- Alternatively, open the `build_msvc/bitcoin.sln` file in Visual Studio 2019.
67
68AppVeyor
69---------------------
70The .appveyor.yml in the root directory is suitable to perform builds on [AppVeyor](https://www.appveyor.com/) Continuous Integration servers. The simplest way to perform an AppVeyor build is to fork Bitcoin Core and then configure a new AppVeyor Project pointing to the forked repository.
71
72For safety reasons the Bitcoin Core .appveyor.yml file has the artifact options disabled. The build will be performed but no executable files will be available. To enable artifacts on a forked repository uncomment the lines shown below:
73
74```
75    #- 7z a bitcoin-%APPVEYOR_BUILD_VERSION%.zip %APPVEYOR_BUILD_FOLDER%\build_msvc\%platform%\%configuration%\*.exe
76    #- path: bitcoin-%APPVEYOR_BUILD_VERSION%.zip
77```
78
79Security
80---------------------
81[Base address randomization](https://docs.microsoft.com/en-us/cpp/build/reference/dynamicbase-use-address-space-layout-randomization?view=msvc-160) is used to make Bitcoin Core more secure. When building Bitcoin using the `build_msvc` process base address randomization can be disabled by editing `common.init.vcproj` to change `RandomizedBaseAddress` from `true` to `false` and then rebuilding the project.
82
83To check if `bitcoind` has `RandomizedBaseAddress` enabled or disabled run
84
85```
86.\dumpbin.exe /headers src/bitcoind.exe
87```
88
89If is it enabled then in the output `Dynamic base` will be listed in the `DLL characteristics` under `OPTIONAL HEADER VALUES` as shown below
90
91```
92            8160 DLL characteristics
93                   High Entropy Virtual Addresses
94                   Dynamic base
95                   NX compatible
96                   Terminal Server Aware
97```
98
99This may not disable all stack randomization as versions of windows employ additional stack randomization protections. These protections must be turned off in the OS configuration.