1.. _building: 2 3Building The Library 4================================= 5 6This document describes how to build Botan on Unix/POSIX and Windows 7systems. The POSIX oriented descriptions should apply to most 8common Unix systems (including OS X), along with POSIX-ish systems 9like BeOS, QNX, and Plan 9. Currently, systems other than Windows and 10POSIX (such as VMS, MacOS 9, OS/390, OS/400, ...) are not supported by 11the build system, primarily due to lack of access. Please contact the 12maintainer if you would like to build Botan on such a system. 13 14Botan's build is controlled by configure.py, which is a `Python 15<https://www.python.org>`_ script. Python 2.6 or later is required. 16 17.. highlight:: none 18 19For the impatient, this works for most systems:: 20 21 $ ./configure.py [--prefix=/some/directory] 22 $ make 23 $ make install 24 25Or using ``nmake``, if you're compiling on Windows with Visual C++. On 26platforms that do not understand the '#!' convention for beginning 27script files, or that have Python installed in an unusual spot, you 28might need to prefix the ``configure.py`` command with ``python`` or 29``/path/to/python``:: 30 31 $ python ./configure.py [arguments] 32 33Configuring the Build 34--------------------------------- 35 36The first step is to run ``configure.py``, which is a Python script 37that creates various directories, config files, and a Makefile for 38building everything. This script should run under a vanilla install of 39Python 2.6, 2.7, or 3.x. 40 41The script will attempt to guess what kind of system you are trying to 42compile for (and will print messages telling you what it guessed). 43You can override this process by passing the options ``--cc``, 44``--os``, and ``--cpu``. 45 46You can pass basically anything reasonable with ``--cpu``: the script 47knows about a large number of different architectures, their 48sub-models, and common aliases for them. You should only select the 4964-bit version of a CPU (such as "sparc64" or "mips64") if your 50operating system knows how to handle 64-bit object code - a 32-bit 51kernel on a 64-bit CPU will generally not like 64-bit code. 52 53By default the script tries to figure out what will work on your 54system, and use that. It will print a display at the end showing which 55algorithms have and have not been enabled. For instance on one system 56we might see lines like:: 57 58 INFO: Skipping (dependency failure): certstor_sqlite3 sessions_sqlite3 59 INFO: Skipping (incompatible CPU): aes_power8 60 INFO: Skipping (incompatible OS): darwin_secrandom getentropy win32_stats 61 INFO: Skipping (incompatible compiler): aes_armv8 pmull sha1_armv8 sha2_32_armv8 62 INFO: Skipping (no enabled compression schemes): compression 63 INFO: Skipping (requires external dependency): boost bzip2 lzma openssl sqlite3 tpm zlib 64 65The ones that are skipped because they are require an external 66dependency have to be explicitly asked for, because they rely on third 67party libraries which your system might not have or that you might not 68want the resulting binary to depend on. For instance to enable zlib 69support, add ``--with-zlib`` to your invocation of ``configure.py``. 70All available modules can be listed with ``--list-modules``. 71 72You can control which algorithms and modules are built using the 73options ``--enable-modules=MODS`` and ``--disable-modules=MODS``, for 74instance ``--enable-modules=zlib`` and ``--disable-modules=xtea,idea``. 75Modules not listed on the command line will simply be loaded if needed 76or if configured to load by default. If you use ``--minimized-build``, 77only the most core modules will be included; you can then explicitly 78enable things that you want to use with ``--enable-modules``. This is 79useful for creating a minimal build targeting to a specific 80application, especially in conjunction with the amalgamation option; 81see :ref:`amalgamation` and :ref:`minimized_builds`. 82 83For instance:: 84 85 $ ./configure.py --minimized-build --enable-modules=rsa,eme_oaep,emsa_pssr 86 87will set up a build that only includes RSA, OAEP, PSS along with any 88required dependencies. Note that a minimized build does not by default 89include any random number generator, which is needed for example to 90generate keys, nonces and IVs. See :doc:`api_ref/rng` on which random number 91generators are available. 92 93Cross Compiling 94--------------------- 95 96Cross compiling refers to building software on one type of host (say Linux 97x86-64) but creating a binary for some other type (say MinGW x86-32). This is 98completely supported by the build system. To extend the example, we must tell 99`configure.py` to use the MinGW tools:: 100 101 $ ./configure.py --os=mingw --cpu=x86_32 --cc-bin=i686-w64-mingw32-g++ --ar-command=i686-w64-mingw32-ar 102 ... 103 $ make 104 ... 105 $ file botan.exe 106 botan.exe: PE32 executable (console) Intel 80386, for MS Windows 107 108.. note:: 109 For whatever reason, some distributions of MinGW lack support for 110 threading or mutexes in the C++ standard library. You can work around 111 this by disabling thread support using ``--without-os-feature=threads`` 112 113You can also specify the alternate tools by setting the `CXX` and `AR` 114environment variables (instead of the `--cc-bin` and `--ar-command` options), as 115is commonly done with autoconf builds. 116 117On Unix 118---------------- 119 120The basic build procedure on Unix and Unix-like systems is:: 121 122 $ ./configure.py [--enable-modules=<list>] [--cc=CC] 123 $ make 124 $ make check 125 126If the tests look OK, install:: 127 128 $ make install 129 130On Unix systems the script will default to using GCC; use ``--cc`` if 131you want something else. For instance use ``--cc=icc`` for Intel C++ 132and ``--cc=clang`` for Clang. 133 134The ``make install`` target has a default directory in which it will 135install Botan (typically ``/usr/local``). You can override this by 136using the ``--prefix`` argument to ``configure.py``, like so:: 137 138 $ ./configure.py --prefix=/opt <other arguments> 139 140On some systems shared libraries might not be immediately visible to 141the runtime linker. For example, on Linux you may have to edit 142``/etc/ld.so.conf`` and run ``ldconfig`` (as root) in order for new 143shared libraries to be picked up by the linker. An alternative is to 144set your ``LD_LIBRARY_PATH`` shell variable to include the directory 145that the Botan libraries were installed into. 146 147On macOS 148-------------- 149 150A build on macOS works much like that on any other Unix-like system. 151 152To build a universal binary for macOS, you need to set some additional 153build flags. Do this with the `configure.py` flag `--cc-abi-flags`:: 154 155 --cc-abi-flags="-force_cpusubtype_ALL -mmacosx-version-min=10.4 -arch i386 -arch ppc" 156 157On Windows 158-------------- 159 160.. note:: 161 162 The earliest versions of Windows supported are Windows 7 and Windows 2008 R2 163 164You need to have a copy of Python installed, and have both Python and 165your chosen compiler in your path. Open a command shell (or the SDK 166shell), and run:: 167 168 $ python configure.py --cc=msvc --os=windows 169 $ nmake 170 $ nmake check 171 $ nmake install 172 173Botan supports the nmake replacement `Jom <https://wiki.qt.io/Jom>`_ 174which enables you to run multiple build jobs in parallel. 175 176For MinGW, use:: 177 178 $ python configure.py --cc=gcc --os=mingw 179 $ make 180 181By default the install target will be ``C:\botan``; you can modify 182this with the ``--prefix`` option. 183 184When building your applications, all you have to do is tell the 185compiler to look for both include files and library files in 186``C:\botan``, and it will find both. Or you can move them to a 187place where they will be in the default compiler search paths (consult 188your documentation and/or local expert for details). 189 190 191For iOS using XCode 192------------------------- 193 194For iOS, you typically build for 3 architectures: armv7 (32 bit, older 195iOS devices), armv8-a (64 bit, recent iOS devices) and x86_64 for 196the iPhone simulator. You can build for these 3 architectures and then 197create a universal binary containing code for all of these 198architectures, so you can link to Botan for the simulator as well as 199for an iOS device. 200 201To cross compile for armv7, configure and make with:: 202 203 $ ./configure.py --os=ios --prefix="iphone-32" --cpu=armv7 --cc=clang \ 204 --cc-abi-flags="-arch armv7" 205 $ xcrun --sdk iphoneos make install 206 207To cross compile for armv8-a, configure and make with:: 208 209 $ ./configure.py --os=ios --prefix="iphone-64" --cpu=armv8-a --cc=clang \ 210 --cc-abi-flags="-arch arm64" 211 $ xcrun --sdk iphoneos make install 212 213To compile for the iPhone Simulator, configure and make with:: 214 215 $ ./configure.py --os=ios --prefix="iphone-simulator" --cpu=x86_64 --cc=clang \ 216 --cc-abi-flags="-arch x86_64" 217 $ xcrun --sdk iphonesimulator make install 218 219Now create the universal binary and confirm the library is compiled 220for all three architectures:: 221 222 $ xcrun --sdk iphoneos lipo -create -output libbotan-2.a \ 223 iphone-32/lib/libbotan-2.a \ 224 iphone-64/lib/libbotan-2.a \ 225 iphone-simulator/lib/libbotan-2.a 226 $ xcrun --sdk iphoneos lipo -info libbotan-2.a 227 Architectures in the fat file: libbotan-2.a are: armv7 x86_64 armv64 228 229The resulting static library can be linked to your app in Xcode. 230 231For Android 232--------------------- 233 234Modern versions of Android NDK use Clang and support C++11. Simply 235configure using the appropriate NDK compiler:: 236 237 $ export CXX=/opt/android-ndk/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android28-clang++ 238 $ ./configure.py --os=android --cc=clang --cpu=arm64 239 240Docker 241^^^^^^^^^^^ 242 243To build android version, there is the possibility to use 244the docker way:: 245 246 sudo ANDROID_SDK_VER=21 ANDROID_ARCH=arm64 src/scripts/docker-android.sh 247 248This will produce the docker-builds/android folder containing 249each architecture compiled. 250 251Emscripten (WebAssembly) 252--------------------------- 253 254To build for WebAssembly using Emscripten, try:: 255 256 CXX=em++ ./configure.py --cc=clang --cpu=llvm --os=emscripten 257 make 258 259This will produce bitcode files ``botan-test.bc`` and ``botan.bc`` 260along with a static archive ``libbotan-2.a`` which can linked with 261other modules. To convert the tests into a WASM file which can be 262executed on a browser, use:: 263 264 em++ -s ALLOW_MEMORY_GROWTH=1 -s DISABLE_EXCEPTION_CATCHING=0 -s WASM=1 \ 265 --preload-file src/tests/data botan-test.bc -o botan-test.html 266 267Supporting Older Distros 268-------------------------- 269 270Some "stable" distributions, notably RHEL/CentOS, ship very obsolete 271versions of binutils, which do not support more recent CPU instructions. 272As a result when building you may receive errors like:: 273 274 Error: no such instruction: `sha256rnds2 %xmm0,%xmm4,%xmm3' 275 276Depending on how old your binutils is, you may need to disable BMI2, 277AVX2, SHA-NI, and/or RDSEED. These can be disabled by passing the 278flags ``--disable-bmi2``, ``--disable-avx2``, ``--disable-sha-ni``, 279and ``--disable-rdseed`` to ``configure.py``. 280 281Other Build-Related Tasks 282---------------------------------------- 283 284.. _building_docs: 285 286Building The Documentation 287^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 288 289There are two documentation options available, Sphinx and Doxygen. 290Sphinx will be used if ``sphinx-build`` is detected in the PATH, or if 291``--with-sphinx`` is used at configure time. Doxygen is only enabled 292if ``--with-doxygen`` is used. Both are generated by the makefile 293target ``docs``. 294 295 296.. _amalgamation: 297 298The Amalgamation Build 299^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 300 301You can also configure Botan to be built using only a single source file; this 302is quite convenient if you plan to embed the library into another application. 303 304To generate the amalgamation, run ``configure.py`` with whatever options you 305would ordinarily use, along with the option ``--amalgamation``. This will create 306two (rather large) files, ``botan_all.h`` and ``botan_all.cpp``. 307 308.. note:: 309 310 The library will as usual be configured to target some specific operating 311 system and CPU architecture. You can use the CPU target "generic" if you need 312 to target multiple CPU architectures, but this has the effect of disabling 313 *all* CPU specific features such as SIMD, AES instruction sets, or inline 314 assembly. If you need to ship amalgamations for multiple targets, it would be 315 better to create different amalgamation files for each individual target. 316 317Whenever you would have included a botan header, you can then include 318``botan_all.h``, and include ``botan_all.cpp`` along with the rest of the source 319files in your build. If you want to be able to easily switch between amalgamated 320and non-amalgamated versions (for instance to take advantage of prepackaged 321versions of botan on operating systems that support it), you can instead ignore 322``botan_all.h`` and use the headers from ``build/include`` as normal. 323 324You can also build the library using Botan's build system (as normal) but 325utilizing the amalgamation instead of the individual source files by running 326something like ``./configure.py --amalgamation && make``. This is essentially a 327very simple form of link time optimization; because the entire library source is 328visible to the compiler, it has more opportunities for interprocedural 329optimizations. Additionally (assuming you are not making use of a compiler 330cache such as ``ccache`` or ``sccache``) amalgamation builds usually have 331significantly shorter compile times for full rebuilds. 332 333Modules Relying on Third Party Libraries 334^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 335 336Currently ``configure.py`` cannot detect if external libraries are 337available, so using them is controlled explicitly at build time 338by the user using 339 340 - ``--with-bzip2`` enables the filters providing bzip2 compression and 341 decompression. Requires the bzip2 development libraries to be installed. 342 343 - ``--with-zlib`` enables the filters providing zlib compression and 344 decompression. Requires the zlib development libraries to be installed. 345 346 - ``--with-lzma`` enables the filters providing lzma compression and 347 decompression. Requires the lzma development libraries to be installed. 348 349 - ``--with-sqlite3`` enables using sqlite3 databases in various contexts 350 (TLS session cache, PSK database, etc). 351 352 - ``--with-openssl`` adds an engine that uses OpenSSL for some ciphers, hashes, 353 and public key operations. OpenSSL 1.0.2 or later is supported. LibreSSL can 354 also be used. 355 356 - ``--with-tpm`` adds support for using TPM hardware via the TrouSerS library. 357 358 - ``--with-boost`` enables using some Boost libraries. In particular 359 Boost.Filesystem is used for a few operations (but on most platforms, a 360 native API equivalent is available), and Boost.Asio is used to provide a few 361 extra TLS related command line utilities. 362 363Multiple Builds 364^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 365 366It may be useful to run multiple builds with different configurations. 367Specify ``--with-build-dir=<dir>`` to set up a build environment in a 368different directory. 369 370Setting Distribution Info 371^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 372 373The build allows you to set some information about what distribution 374this build of the library comes from. It is particularly relevant to 375people packaging the library for wider distribution, to signify what 376distribution this build is from. Applications can test this value by 377checking the string value of the macro ``BOTAN_DISTRIBUTION_INFO``. It 378can be set using the ``--distribution-info`` flag to ``configure.py``, 379and otherwise defaults to "unspecified". For instance, a `Gentoo 380<https://www.gentoo.org>`_ ebuild might set it with 381``--distribution-info="Gentoo ${PVR}"`` where ``${PVR}`` is an ebuild 382variable automatically set to a combination of the library and ebuild 383versions. 384 385Local Configuration Settings 386^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 387 388You may want to do something peculiar with the configuration; to 389support this there is a flag to ``configure.py`` called 390``--with-local-config=<file>``. The contents of the file are 391inserted into ``build/build.h`` which is (indirectly) included 392into every Botan header and source file. 393 394Enabling or Disabling Use of Certain OS Features 395^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 396 397Botan uses compile-time flags to enable or disable use of certain operating 398specific functions. You can also override these at build time if desired. 399 400The default feature flags are given in the files in ``src/build-data/os`` in the 401``target_features`` block. For example Linux defines flags like ``proc_fs``, 402``getauxval``, and ``sockets``. The ``configure.py`` option 403``--list-os-features`` will display all the feature flags for all operating 404system targets. 405 406To disable a default-enabled flag, use ``--without-os-feature=feat1,feat2,...`` 407 408To enable a flag that isn't otherwise enabled, use ``--with-os-feature=feat``. 409For example, modern Linux systems support the ``getentropy`` call, but it is not 410enabled by default because many older systems lack it. However if you know you 411will only deploy to recently updated systems you can use 412``--with-os-feature=getentropy`` to enable it. 413 414A special case if dynamic loading, which applications for certain environments 415will want to disable. There is no specific feature flag for this, but 416``--disable-modules=dyn_load`` will prevent it from being used. 417 418.. note:: Disabling ``dyn_load`` module will also disable the PKCS #11 419 wrapper, which relies on dynamic loading. 420 421Configuration Parameters 422^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 423 424There are some configuration parameters which you may want to tweak 425before building the library. These can be found in ``build.h``. This 426file is overwritten every time the configure script is run (and does 427not exist until after you run the script for the first time). 428 429Also included in ``build/build.h`` are macros which let applications 430check which features are included in the current version of the 431library. All of them begin with ``BOTAN_HAS_``. For example, if 432``BOTAN_HAS_RSA`` is defined, then an application knows that this 433version of the library has RSA available. 434 435``BOTAN_MP_WORD_BITS``: This macro controls the size of the words used for 436calculations with the MPI implementation in Botan. It must be set to either 32 437or 64 bits. The default is chosen based on the target processor. There is 438normally no reason to change this. 439 440``BOTAN_DEFAULT_BUFFER_SIZE``: This constant is used as the size of 441buffers throughout Botan. The default should be fine for most 442purposes, reduce if you are very concerned about runtime memory usage. 443 444Building Applications 445---------------------------------------- 446 447Unix 448^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 449 450Botan usually links in several different system libraries (such as 451``librt`` or ``libz``), depending on which modules are configured at 452compile time. In many environments, particularly ones using static 453libraries, an application has to link against the same libraries as 454Botan for the linking step to succeed. But how does it figure out what 455libraries it *is* linked against? 456 457The answer is to ask the ``botan`` command line tool using 458the ``config`` and ``version`` commands. 459 460``botan version``: Print the Botan version number. 461 462``botan config prefix``: If no argument, print the prefix where Botan is 463installed (such as ``/opt`` or ``/usr/local``). 464 465``botan config cflags``: Print options that should be passed to the 466compiler whenever a C++ file is compiled. Typically this is used for 467setting include paths. 468 469``botan config libs``: Print options for which libraries to link to 470(this will include a reference to the botan library itself). 471 472Your ``Makefile`` can run ``botan config`` and get the options 473necessary for getting your application to compile and link, regardless 474of whatever crazy libraries Botan might be linked against. 475 476Windows 477^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 478 479No special help exists for building applications on Windows. However, 480given that typically Windows software is distributed as binaries, this 481is less of a problem - only the developer needs to worry about it. As 482long as they can remember where they installed Botan, they just have 483to set the appropriate flags in their Makefile/project file. 484 485Language Wrappers 486---------------------------------------- 487 488Building the Python wrappers 489^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 490 491The Python wrappers for Botan use ctypes and the C89 API so no special 492build step is required, just import botan2.py 493 494See :doc:`Python Bindings <api_ref/python>` for more information about 495the Python bindings. 496 497.. _minimized_builds: 498 499Minimized Builds 500-------------------- 501 502Many developers wish to configure a minimized build which contains only the 503specific features their application will use. In general this is straighforward: 504use ``--minimized-build`` plus ``--enable-modules=`` to enable the specific modules 505you wish to use. Any such configurations should build and pass the tests; if you 506encounter a case where it doesn't please file an issue. 507 508The only trick is knowing which features you want to enable. The most common 509difficulty comes with entropy sources. By default, none are enabled, which means 510if you attempt to use ``AutoSeeded_RNG``, it will fail. The easiest resolution 511is to also enable ``system_rng`` which can act as either an entropy source or 512used directly as the RNG. 513 514If you are building for x86, ARM, or POWER, it can be beneficial to enable 515hardware support for the relevant instruction sets with modules such as 516``aes_ni`` and ``clmul`` for x86, or ``aes_armv8``, ``pmull``, and 517``sha2_32_armv8`` on ARMv8. SIMD optimizations such as ``chacha_avx2`` also can 518provide substantial performance improvements. 519 520.. note:: 521 In a future release, hardware specific modules will be enabled by default if 522 the underlying "base" module is enabled. 523 524If you are building a TLS application, you may (or may not) want to include 525``tls_cbc`` which enables support for CBC ciphersuites. If ``tls_cbc`` is 526disabled, then it will not be possible to negotiate TLS v1.0/v1.1. In general 527this should be considered a feature; only enable this if you need backward 528compatability with obsolete clients or servers. 529 530For TLS another useful feature which is not enabled by default is the 531ChaCha20Poly1305 ciphersuites. To enable these, add ``chacha20poly1305``. 532 533 534Configure Script Options 535--------------------------- 536 537``--cpu=CPU`` 538^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 539 540Set the target CPU architecture. If not used, the arch of the current 541system is detected (using Python's platform module) and used. 542 543``--os=OS`` 544^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 545 546Set the target operating system. 547 548``--cc=COMPILER`` 549^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 550 551Set the desired build compiler 552 553``--cc-min-version=MAJOR.MINOR`` 554^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 555 556Set the minimal version of the target 557compiler. Use --cc-min-version=0.0 to support all compiler 558versions. Default is auto detection. 559 560``--cc-bin=BINARY`` 561^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 562 563Set path to compiler binary 564 565If not provided, the value of the ``CXX`` environment variable is used if set. 566 567``--cc-abi-flags=FLAGS`` 568^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 569 570Set ABI flags, which for the purposes of this option mean options 571which should be passed to both the compiler and linker. 572 573``--cxxflags=FLAGS`` 574^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 575 576Override all compiler flags. This is equivalent to setting ``CXXFLAGS`` 577in the environment. 578 579``--extra-cxxflags=FLAGS`` 580^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 581 582Set extra compiler flags, which are appended to the default set. This 583is useful if you want to set just one or two additional options but 584leave the normal logic for selecting flags alone. 585 586``--ldflags=FLAGS`` 587^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 588 589Set flags to pass to the linker. This is equivalent to setting ``LDFLAGS`` 590 591``--ar-command=AR`` 592^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 593 594Set the path to the tool to use to create static archives (``ar``). 595This is normally only used for cross-compilation. 596 597If not provided, the value of the ``AR`` environment variable is used if set. 598 599``--ar-options=AR_OPTIONS`` 600^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 601 602Specify the options to pass to ``ar``. 603 604If not provided, the value of the ``AR_OPTIONS`` environment variable is used if set. 605 606``--msvc-runtime=RT`` 607^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 608 609Specify the MSVC runtime to use (MT, MD, MTd, or MDd). If not specified, 610picks either MD or MDd depending on if debug mode is set. 611 612``--with-endian=ORDER`` 613^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 614 615The parameter should be either "little" or "big". If not used then if 616the target architecture has a default, that is used. Otherwise left 617unspecified, which causes less optimal codepaths to be used but will 618work on either little or big endian. 619 620``--with-os-features=FEAT`` 621^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 622 623Specify an OS feature to enable. See ``src/build-data/os`` and 624``doc/os.rst`` for more information. 625 626``--without-os-features=FEAT`` 627^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 628 629Specify an OS feature to disable. 630 631``--disable-sse2`` 632^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 633 634Disable use of SSE2 intrinsics 635 636``--disable-ssse3`` 637^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 638 639Disable use of SSSE3 intrinsics 640 641``--disable-sse4.1`` 642^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 643 644Disable use of SSE4.1 intrinsics 645 646``--disable-sse4.2`` 647^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 648 649Disable use of SSE4.2 intrinsics 650 651``--disable-avx2`` 652^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 653 654Disable use of AVX2 intrinsics 655 656``--disable-bmi2`` 657^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 658 659Disable use of BMI2 intrinsics 660 661``--disable-rdrand`` 662^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 663 664Disable use of RDRAND intrinsics 665 666``--disable-rdseed`` 667^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 668 669Disable use of RDSEED intrinsics 670 671``--disable-aes-ni`` 672^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 673 674Disable use of AES-NI intrinsics 675 676``--disable-sha-ni`` 677^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 678 679Disable use of SHA-NI intrinsics 680 681``--disable-altivec`` 682^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 683 684Disable use of AltiVec intrinsics 685 686``--disable-neon`` 687^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 688 689Disable use of NEON intrinsics 690 691``--disable-armv8crypto`` 692^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 693 694Disable use of ARMv8 Crypto intrinsics 695 696``--disable-powercrypto`` 697^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 698 699Disable use of POWER Crypto intrinsics 700 701``--with-debug-info`` 702^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 703 704Include debug symbols. 705 706``--with-sanitizers`` 707^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 708 709Enable some default set of sanitizer checks. What exactly is enabled 710depends on the compiler. 711 712``--enable-sanitizers=SAN`` 713^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 714 715Enable specific sanitizers. See ``src/build-data/cc`` for more information. 716 717``--without-stack-protector`` 718^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 719 720Disable stack smashing protections. **not recommended** 721 722``--with-coverage`` 723^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 724 725Add coverage info and disable optimizations 726 727``--with-coverage-info`` 728^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 729 730Add coverage info, but leave optimizations alone 731 732``--disable-shared-library`` 733^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 734 735Disable building a shared library 736 737``--disable-static-library`` 738^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 739 740Disable building static library 741 742``--optimize-for-size`` 743^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 744 745Optimize for code size. 746 747``--no-optimizations`` 748^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 749 750Disable all optimizations for debugging. 751 752``--debug-mode`` 753^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 754 755Enable debug info and disable optimizations 756 757``--amalgamation`` 758^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 759 760Use amalgamation to build 761 762``--system-cert-bundle=PATH`` 763^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 764 765Set a path to a file containing one or more trusted CA certificates in 766PEM format. If not given, some default locations are checked. 767 768``--with-build-dir=DIR`` 769^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 770 771Setup the build in a specified directory instead of ``./build`` 772 773``--with-external-includedir=DIR`` 774^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 775 776Search for includes in this directory. Provide this parameter multiple times to 777define multiple additional include directories. 778 779``--with-external-libdir=DIR`` 780^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 781 782Add DIR to the link path. Provide this parameter multiple times to define 783multiple additional library link directories. 784 785``--define-build-macro`` 786^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 787 788Set a compile-time pre-processor definition (i.e. add a -D... to the compiler 789invocations). Provide this parameter multiple times to add multiple compile-time 790definitions. Both KEY=VALUE and KEY (without specific value) are supported. 791 792``--with-sysroot-dir=DIR`` 793^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 794 795Use specified dir for system root while cross-compiling 796 797``--with-openmp`` 798^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 799 800Enable use of OpenMP 801 802``--link-method=METHOD`` 803^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 804 805During build setup a directory linking to each header file is created. 806Choose how the links are performed (options are "symlink", "hardlink", 807or "copy"). 808 809``--with-local-config=FILE`` 810^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 811 812Include the contents of FILE into the generated build.h 813 814``--distribution-info=STRING`` 815^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 816 817Set distribution specific version information 818 819``--maintainer-mode`` 820^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 821 822A build configuration used by library developers, which enables extra 823warnings and turns most warnings into errors. 824 825.. warning:: 826 827 When this option is used, all relevant warnings available in the 828 most recent release of GCC/Clang are enabled, so it may fail to 829 build if your compiler is not sufficiently recent. In addition 830 there may be non-default configurations or unusual platforms which 831 cause warnings which are converted to errors. Patches addressing 832 such warnings are welcome, but otherwise no support is available 833 when using this option. 834 835``--werror-mode`` 836^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 837 838Turns most warnings into errors. 839 840``--no-install-python-module`` 841^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 842 843Skip installing Python module. 844 845``--with-python-versions=N.M`` 846^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 847 848Where to install botan2.py. By default this is chosen to be the 849version of Python that is running ``configure.py``. 850 851``--with-valgrind`` 852^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 853 854Use valgrind API to perform additional checks. Not needed by end users. 855 856``--unsafe-fuzzer-mode`` 857^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 858 859Disable essential checks for testing. **UNSAFE FOR PRODUCTION** 860 861``--build-fuzzers=TYPE`` 862^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 863 864Select which interface the fuzzer uses. Options are "afl", 865"libfuzzer", "klee", or "test". The "test" mode builds fuzzers that 866read one input from stdin and then exit. 867 868``--with-fuzzer-lib=LIB`` 869^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 870 871Specify an additional library that fuzzer binaries must link with. 872 873``--build-targets=BUILD_TARGETS`` 874^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 875 876Build only the specific targets and tools 877(``static``, ``shared``, ``cli``, ``tests``, ``bogo_shim``). 878 879``--boost-library-name`` 880^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 881 882Provide an alternative name for a boost library. Depending on the platform and 883boost's build configuration these library names differ significantly (see `Boost docs 884<https://www.boost.org/doc/libs/1_70_0/more/getting_started/unix-variants.html#library-naming>`_). 885The provided library name must be suitable as identifier in a linker parameter, 886e.g on unix: ``boost_system`` or windows: ``libboost_regex-vc71-x86-1_70``. 887 888``--without-documentation`` 889^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 890 891Skip building/installing documentation 892 893``--with-sphinx`` 894^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 895 896Use Sphinx to generate the handbook 897 898``--with-pdf`` 899^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 900 901Use Sphinx to generate PDF doc 902 903``--with-rst2man`` 904^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 905 906Use rst2man to generate a man page for the CLI 907 908``--with-doxygen`` 909^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 910 911Use Doxygen to generate API reference 912 913``--module-policy=POL`` 914^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 915 916The option ``--module-policy=POL`` enables modules required by and 917disables modules prohibited by a text policy in ``src/build-data/policy``. 918Additional modules can be enabled if not prohibited by the policy. 919Currently available policies include ``bsi``, ``nist`` and ``modern``:: 920 921 $ ./configure.py --module-policy=bsi --enable-modules=tls,xts 922 923``--enable-modules=MODS`` 924^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 925 926Enable some specific modules 927 928``--disable-modules=MODS`` 929^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 930 931Disable some specific modules 932 933``--minimized-build`` 934^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 935 936Start with the bare minimum. This is mostly useful in conjuction with 937``--enable-modules`` to get a build that has just the features a 938particular application requires. 939 940``--with-boost`` 941^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 942 943Use Boost.Asio for networking support. This primarily affects the 944command line utils. 945 946``--with-bzip2`` 947^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 948 949Enable bzip2 compression 950 951``--with-lzma`` 952^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 953 954Enable lzma compression 955 956``--with-zlib`` 957^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 958 959Enable using zlib compression 960 961``--with-openssl`` 962^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 963 964Enable using OpenSSL for certain operations 965 966``--with-commoncrypto`` 967^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 968 969Enable using CommonCrypto for certain operations 970 971``--with-sqlite3`` 972^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 973 974Enable using sqlite3 for data storage 975 976``--with-tpm`` 977^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 978 979Enable support for TPM 980 981``--program-suffix=SUFFIX`` 982^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 983 984A string to append to all program binaries. 985 986``--library-suffix=SUFFIX`` 987^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 988 989A string to append to all library names. 990 991``--prefix=DIR`` 992^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 993 994Set the install prefix. 995 996``--docdir=DIR`` 997^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 998 999Set the documentation installation dir. 1000 1001``--bindir=DIR`` 1002^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1003 1004Set the binary installation dir. 1005 1006``--libdir=DIR`` 1007^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1008 1009Set the library installation dir. 1010 1011``--mandir=DIR`` 1012^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1013 1014Set the man page installation dir. 1015 1016``--includedir=DIR`` 1017^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1018 1019Set the include file installation dir. 1020