1  # Depends build
  2  
  3  This is a system of building and caching dependencies necessary for building
  4  Bitcoin Core. It supports cross-compilation. For more details see [description.md](description.md),
  5  as well as [packages.md](packages.md) for how to add packages.
  6  
  7  ## Usage
  8  
  9  ### Ubuntu & Debian
 10  
 11      apt install cmake curl make patch
 12  
 13  Skip the following packages if you don't intend to use the GUI and will build with [`NO_QT=1`](#dependency-options):
 14  
 15      apt install bison g++ ninja-build pkgconf python3 xz-utils
 16  
 17  To build dependencies for the current arch+OS:
 18  
 19      make
 20  
 21  ### macOS
 22  
 23  Install Xcode Command Line Tools and Homebrew Package Manager,
 24  see [build-osx.md](../doc/build-osx.md).
 25  
 26      brew install cmake make ninja
 27  
 28  To build dependencies for the current arch+OS:
 29  
 30      gmake
 31  
 32  ### FreeBSD
 33  
 34      pkg install bash cmake curl gmake
 35  
 36  Skip the following packages if you don't intend to use the GUI and will build with [`NO_QT=1`](#dependency-options):
 37  
 38      pkg install bison ninja pkgconf python3
 39  
 40  To build dependencies for the current arch+OS:
 41  
 42      gmake
 43  
 44  ### NetBSD
 45  
 46      pkgin install bash cmake curl gmake perl
 47  
 48  To build dependencies for the current arch+OS:
 49  
 50      gmake
 51  
 52  ### OpenBSD
 53  
 54      pkg_add bash cmake curl gmake gtar
 55  
 56  To build dependencies for the current arch+OS:
 57  
 58      gmake
 59  
 60  ### Alpine
 61  
 62      apk add bash build-base cmake curl make patch
 63  
 64  Skip the following packages if you don't intend to use the GUI and will build with [`NO_QT=1`](#dependency-options):
 65  
 66      apk add bison linux-headers samurai pkgconf python3
 67  
 68  To build dependencies for the current arch+OS:
 69  
 70      make
 71  
 72  ## Configuring Bitcoin Core
 73  
 74  **When configuring Bitcoin Core, CMake by default will ignore the depends output.** In
 75  order for it to pick up libraries, tools, and settings from the depends build,
 76  you must specify the toolchain file.
 77  In the above example for Ubuntu, a file named `depends/x86_64-pc-linux-gnu/toolchain.cmake` will be
 78  created. To use it during configuring Bitcoin Core:
 79  
 80      cmake -B build --toolchain depends/x86_64-pc-linux-gnu/toolchain.cmake
 81  
 82  ## Dependency Options
 83  
 84  The following can be set when running make: `make FOO=bar`
 85  
 86  - `SOURCES_PATH`: Downloaded sources will be placed here
 87  - `BASE_CACHE`: Built packages will be placed here
 88  - `SDK_PATH`: Path where SDKs can be found (used by macOS)
 89  - `FALLBACK_DOWNLOAD_PATH`: If a source file can't be fetched, try here before giving up
 90  - `C_STANDARD`: Set the C standard version used. Defaults to `c11`.
 91  - `CXX_STANDARD`: Set the C++ standard version used. Defaults to `c++20`.
 92  - `NO_BOOST`: Don't download/build/cache Boost
 93  - `NO_LIBEVENT`: Don't download/build/cache Libevent
 94  - `NO_QT`: Don't download/build/cache Qt and its dependencies
 95  - `NO_QR`: Don't download/build/cache packages needed for enabling qrencode
 96  - `NO_ZMQ`: Don't download/build/cache packages needed for enabling ZeroMQ
 97  - `NO_WALLET`: Don't download/build/cache libs needed to enable the wallet (SQLite)
 98  - `NO_USDT`: Don't download/build/cache packages needed for enabling USDT tracepoints
 99  - `NO_IPC`: Don't build Cap’n Proto and libmultiprocess packages. Default on Windows.
100  - `DEBUG`: Disable some optimizations and enable more runtime checking
101  - `HOST_ID_SALT`: Optional salt to use when generating host package ids
102  - `BUILD_ID_SALT`: Optional salt to use when generating build package ids
103  - `LOG`: Use file-based logging for individual packages. During a package build its log file
104    resides in the `depends` directory, and the log file is printed out automatically in case
105    of build error. After successful build log files are moved along with package archives
106  - `LTO`: Enable options needed for LTO. Does not add `-flto` related options to *FLAGS.
107  
108  If some packages are not built, for example `make NO_WALLET=1`, the appropriate CMake cache
109  variables will be set when generating the Bitcoin Core buildsystem. In this case, `-DENABLE_WALLET=OFF`.
110  
111  ## Compiler Configuration
112  
113  `CC` and `CXX` control target compilers. `build_CC` and `build_CXX` control
114  compilers for native build tools (e.g. `native_capnp`, `native_qt`), which
115  default to `gcc`/`g++` on Linux and `clang`/`clang++` on macOS/FreeBSD/OpenBSD
116  (see `./depends/builders/*.mk`).
117  
118  On a system where the default build compiler is not available (e.g. Linux
119  without gcc/g++), you could use the following to build all packages using clang:
120  
121      make -C depends build_CC=clang build_CXX=clang++ CC=clang CXX=clang++
122  
123  ## Cross compilation
124  
125  To build for another arch/OS:
126  
127      make HOST=host-platform-triplet
128  
129  For example:
130  
131      make HOST=x86_64-w64-mingw32 -j4
132  
133  Common `host-platform-triplet`s for cross compilation are:
134  
135  - `i686-pc-linux-gnu` for Linux x86 32 bit
136  - `x86_64-pc-linux-gnu` for Linux x86 64 bit
137  - `x86_64-w64-mingw32` for Windows using MSVCRT
138  - `x86_64-w64-mingw32ucrt` for Windows using UCRT
139  - `x86_64-apple-darwin` for Intel macOS
140  - `arm64-apple-darwin` for ARM macOS
141  - `arm-linux-gnueabihf` for Linux ARM 32 bit
142  - `aarch64-linux-gnu` for Linux ARM 64 bit
143  - `powerpc64-linux-gnu` for Linux POWER 64 bit (big endian)
144  - `powerpc64le-linux-gnu` for Linux POWER 64 bit (little endian)
145  - `riscv32-linux-gnu` for Linux RISC-V 32 bit
146  - `riscv64-linux-gnu` for Linux RISC-V 64 bit
147  - `s390x-linux-gnu` for Linux S390X
148  
149  The paths are automatically configured and no other options are needed.
150  
151  #### For macOS cross compilation
152  
153      apt install clang lld llvm zip
154  
155  Clang 18 or later is required. You must also obtain the macOS SDK before
156  proceeding with a cross-compile. Under the depends directory, create a
157  subdirectory named `SDKs`. Then, place the extracted SDK under this new directory.
158  For more information, see [SDK Extraction](../contrib/macdeploy/README.md#sdk-extraction).
159  
160  #### For Windows cross compilation using MSVCRT
161  
162      apt install g++-mingw-w64-x86-64-posix
163  
164  #### For Windows cross compilation using UCRT
165  
166      apt install g++-mingw-w64-ucrt64
167  
168  #### For linux (including i386, ARM) cross compilation
169  
170  Common linux dependencies:
171  
172      sudo apt-get install g++-multilib binutils
173  
174  For linux ARM cross compilation:
175  
176      sudo apt-get install g++-arm-linux-gnueabihf binutils-arm-linux-gnueabihf
177  
178  For linux AARCH64 cross compilation:
179  
180      sudo apt-get install g++-aarch64-linux-gnu binutils-aarch64-linux-gnu
181  
182  For linux POWER 64-bit cross compilation (there are no packages for 32-bit):
183  
184      sudo apt-get install g++-powerpc64-linux-gnu binutils-powerpc64-linux-gnu g++-powerpc64le-linux-gnu binutils-powerpc64le-linux-gnu
185  
186  For linux RISC-V 64-bit cross compilation (there are no packages for 32-bit):
187  
188      sudo apt-get install g++-riscv64-linux-gnu binutils-riscv64-linux-gnu
189  
190  For linux S390X cross compilation:
191  
192      sudo apt-get install g++-s390x-linux-gnu binutils-s390x-linux-gnu
193  
194  ### Additional targets
195  
196      download: run 'make download' to fetch all sources without building them
197      download-osx: run 'make download-osx' to fetch all sources needed for macOS builds
198      download-win: run 'make download-win' to fetch all sources needed for win builds
199      download-linux: run 'make download-linux' to fetch all sources needed for linux builds