diff options
Diffstat (limited to 'doc/building.rst')
| -rw-r--r-- | doc/building.rst | 456 |
1 files changed, 456 insertions, 0 deletions
diff --git a/doc/building.rst b/doc/building.rst new file mode 100644 index 000000000..cc6f0af5d --- /dev/null +++ b/doc/building.rst @@ -0,0 +1,456 @@ + +Building The Library +================================= + +This document describes how to build Botan on Unix/POSIX and MS +Windows systems. The POSIX oriented descriptions should apply to most +common Unix systems (including MacOS X), along with POSIX-ish systems +like BeOS, QNX, and Plan 9. Currently, systems other than Windows and +POSIX (such as VMS, MacOS 9, OS/390, OS/400, ...) are not supported by +the build system, primarily due to lack of access. Please contact the +maintainer if you would like to build Botan on such a system. + +Botan's build is controlled by configure.py, which is a `Python +<http://www.python.org>`_ script. Python 2.5 or later is required. + +For the impatient, this works for most systems:: + + $ ./configure.py [--prefix=/some/directory] + $ make + $ make check + $ make install + +Or using ``nmake``, if you're compiling on Windows with Visual C++. On +platforms that do not understand the '#!' convention for beginning +script files, or that have Python installed in an unusual spot, you +might need to prefix the ``configure.py`` command with ``python`` or +``/path/to/python``:: + + $ python ./configure.py [arguments] + +Configuring the Build +--------------------------------- + +The first step is to run ``configure.py``, which is a Python script +that creates various directories, config files, and a Makefile for +building everything. The script requires at least Python 2.5; any +later version of Python 2.x should also work. Python 3.1 will also +work but requires an extra step; see :ref:`configure_with_python3` for +details. + +The script will attempt to guess what kind of system you are trying to +compile for (and will print messages telling you what it guessed). +You can override this process by passing the options ``--cc``, +``--os``, and ``--cpu``. + +You can pass basically anything reasonable with ``--cpu``: the script +knows about a large number of different architectures, their +sub-models, and common aliases for them. You should only select the +64-bit version of a CPU (such as "sparc64" or "mips64") if your +operating system knows how to handle 64-bit object code - a 32-bit +kernel on a 64-bit CPU will generally not like 64-bit code. + +By default the script tries to figure out what will work on your +system, and use that. It will print a display at the end showing which +algorithms have and have not been enabled. For instance on one system +we might see lines like:: + + INFO: Skipping, by request only - bzip2 gnump openssl qt_mutex zlib + INFO: Skipping, incompatible CPU - aes_intel aes_ssse3 asm_x86_64 mp_asm64 mp_x86_64 sha1_x86_64 + INFO: Skipping, incompatible OS - beos_stats cryptoapi_rng win32_crit_section win32_stats + INFO: Skipping, incompatible compiler - mp_msvc64 mp_x86_32_msvc + +The ones that are skipped because they are 'by request only' have to +be explicitly asked for, because they rely on third party libraries +which your system might not have or that you might not want the +resulting binary to depend on. For instance to enable zlib support, +add ``--with-zlib`` to your invocation of ``configure.py``. + +You can control which algorithms and modules are built using the +options ``--enable-modules=MODS`` and ``--disable-modules=MODS``, for +instance ``--enable-modules=zlib`` and ``--disable-modules=rc5,idea``. +Modules not listed on the command line will simply be loaded if needed +or if configured to load by default. If you use ``--no-autoload``, +only the most core modules will be included; you can then explicitly +enable things that you want to use with ``--enable-modules``. This is +useful for creating a minimal build targeting to a specific +application, especially in conjunction with the amalgamation option; +see :ref:`amalgamation`. + +For instance:: + + $ ./configure.py --no-autoload --enable-modules=rsa,ecdsa,eme1,emsa1,emsa4 + +will set up a build that only includes RSA, ECDSA, and some padding +modes, along with their dependencies. A small subset of core features, +including AES, SHA-2, HMAC, and the multiple precision integer +library, are always loaded. + +The script tries to guess what kind of makefile to generate, and it +almost always guesses correctly (basically, Visual C++ uses NMAKE with +Windows commands, and everything else uses Unix make with POSIX +commands). Just in case, you can override it with +``--make-style=somestyle``. The styles Botan currently knows about are +'unix' (normal Unix makefiles), and 'nmake', the make variant commonly +used by Windows compilers. To add a new variant (eg, a build script +for VMS), you will need to create a new template file in +``src/build-data/makefile``. + +On Unix +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The basic build procedure on Unix and Unix-like systems is:: + + $ ./configure.py [--enable-modules=<list>] [--cc=CC] + $ make + # You may need to set your LD_LIBRARY_PATH or equivalent for ./check to run + $ make check # optional, but a good idea + $ make install + +On Unix systems the script will default to using GCC; use +``--cc`` if you want something else. For instance use +``--cc=icc`` for Intel C++ and ``--cc=clang`` for Clang. + +The ``make install`` target has a default directory in which it +will install Botan (typically ``/usr/local``). You can override +this by using the ``--prefix`` argument to +``configure.py``, like so: + +``./configure.py --prefix=/opt <other arguments>`` + +On some systems shared libraries might not be immediately visible to +the runtime linker. For example, on Linux you may have to edit +``/etc/ld.so.conf`` and run ``ldconfig`` (as root) in +order for new shared libraries to be picked up by the linker. An +alternative is to set your ``LD_LIBRARY_PATH`` shell variable +to include the directory that the Botan libraries were installed into. + +On Mac OS X +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In general the Unix instructions above should apply, however OS X does +not support ``LD_LIBRARY_PATH``. Thomas Keller suggests instead +running ``install_name_tool`` between building and running the +self-test program:: + + $ VERSION=1.10.0 # or whatever the current version is + $ install_name_tool -change $(otool -X -D libbotan-$VERSION.dylib) \ + $PWD/libbotan-$VERSION.dylib check + +Building Universal Binaries +&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&& + +To build a universal binary for OS X, some simple modifications are +required. First, create a CPU type for the target universalbinary, +one that doesn't specify any special handlers. This is done by +creating an empty file in src/build-data/arch:: + + $ touch src/build-data/arch/universalbinary.txt + +and then adding a special target for it in gcc, by adding the line:: + + universalbinary -> "-force_cpusubtype_ALL -mmacosx-version-min=10.4 -arch i386 -arch ppc" + +in the section marked `<mach_abi_linking>` in +`src/build-data/cc/gcc.txt`. Then configure with:: + + $ ./configure.py --cpu=universalbinary [other options here] + + +On MS Windows +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you don't want to deal with building botan on Windows, check the +website; commonly prebuilt Windows binaries with installers are +available, especially for stable versions. + +You need to have a copy of Python installed, and have both Python and +your chosen compiler in your path. Open a command shell (or the SDK +shell), and run:: + + > python configure.py --cc=msvc (or --cc=gcc for MinGW) [--cpu=CPU] + > nmake + > nmake check # optional, but recommended + > nmake install + +For Win95 pre OSR2, the ``cryptoapi_rng`` module will not work, +because CryptoAPI didn't exist. And all versions of NT4 lack the +ToolHelp32 interface, which is how ``win32_stats`` does its slow +polls, so a version of the library built with that module will not +load under NT4. Later versions of Windows support both methods, so +this shouldn't be much of an issue anymore. + +By default the install target will be ``C:\botan``; you can modify +this with the ``--prefix`` option. + +When building your applications, all you have to do is tell the +compiler to look for both include files and library files in +``C:\botan``, and it will find both. Or you can move them to a +place where they will be in the default compiler search paths (consult +your documentation and/or local expert for details). + +Other Build-Related Tasks +---------------------------------------- + +.. _building_docs: + +Building The Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are two documentation options available, Sphinx and Doxygen. +Sphinx will be used if ``sphinx-build`` is detected in the PATH, or if +``--with-sphinx`` is used at configure time. Doxygen is only enabled +if ``--with-doxygen`` is used. Both are generated by the makefile +target ``docs``. + + +.. _amalgamation: + +The Amalgamation Build +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can also configure Botan to be built using only a single source +file; this is quite convenient if you plan to embed the library into +another application. To do so, run ``configure.py`` with whatever +arguments you would ordinarily use, along with the option +``--gen-amalgamation``. This will create two (rather large) files, +``botan_all.h`` and ``botan_all.cpp``. + +Whenever you would have included a botan header, you can then include +``botan_all.h``, and include ``botan_all.cpp`` along with the rest of +the source files in your build. If you want to be able to easily +switch between amalgamated and non-amalgamated versions (for instance +to take advantage of prepackaged versions of botan on operating +systems that support it), you can instead ignore ``botan_all.h`` and +use the headers from ``build/include`` as normal. + +You can also build the library as normal but using the amalgamation +instead of the individual source files using ``--via-amalgamation``. +This is essentially a very simple form of link time optimization; +because the entire library source is visible to the compiler, it has +more opportunities for interprocedural optimizations. + +Modules Relying on Third Party Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are a fairly large number of modules included with Botan. Some +of these are extremely useful, while others are only necessary in very +unusual circumstances. Most are loaded (or not) automatically as +necessary, but some require external libraries are thus must be +enabled at build time; these include: + + - ``--with-bzip2`` enables the filters providing bzip2 compression + and decompression. Requires the bzip2 development libraries to be + installed. + + - ``--with-zlib`` enables the filters providing zlib compression + and decompression. Requires the zlib development libraries to be + installed. + + - ``--with-gnump`` adds an alternative engine for public key + cryptography that uses the GNU MP library. GNU MP 4.1 or later is + required. + + - ``--with-openssl`` adds an engine that uses OpenSSL for some public + key operations and ciphers/hashes. OpenSSL 0.9.7 or later is + required. Note that OpenSSL's versions are not always faster than + the versions built into botan. + +Multiple Builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It may be useful to run multiple builds with different +configurations. Specify ``--build-dir=<dir>`` to set up a build +environment in a different directory. + +.. _configure_with_python3: + +Configuring the Build With Python 3.1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The versions of Python beginning with 3 are (intentionally) +incompatible with the (currently more common) 2.x series. If you want +to use Python 3.1 to set up the build, you'll have to use the +``2to3`` program (included in the Python distribution) on the +script; this will convert the script to the Python 3.x dialect:: + + $ python ./configure.py + File "configure.py", line 860 + except KeyError, e: + ^ + SyntaxError: invalid syntax + $ # incompatible python version, let's fix it + $ 2to3 -w configure.py + [...] + RefactoringTool: Files that were modified: + RefactoringTool: configure.py + $ python ./configure.py + [...] + +Setting Distribution Info +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The build allows you to set some information about what distribution +this build of the library comes from. It is particularly relevant to +people packaging the library for wider distribution, to signify what +distribution this build is from. Applications can test this value by +checking the string value of the macro ``BOTAN_DISTRIBUTION_INFO``. It +can be set using the ``--distribution-info`` flag to ``configure.py``, +and otherwise defaults to "unspecified". For instance, a `Gentoo +<http://www.gentoo.org>`_ ebuild might set it with +``--distribution-info="Gentoo ${PVR}"`` where ``${PVR}`` is an ebuild +variable automatically set to a combination of the library and ebuild +versions. + +Local Configuration Settings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You may want to do something peculiar with the configuration; to +support this there is a flag to ``configure.py`` called +``--with-local-config=<file>``. The contents of the file are +inserted into ``build/build.h`` which is (indirectly) included +into every Botan header and source file. + +Configuration Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are some configuration parameters which you may want to tweak +before building the library. These can be found in ``config.h``. This +file is overwritten every time the configure script is run (and does +not exist until after you run the script for the first time). + +Also included in ``build/build.h`` are macros which let applications +check which features are included in the current version of the +library. All of them begin with ``BOTAN_HAS_``. For example, if +``BOTAN_HAS_BLOWFISH`` is defined, then an application can include +``<botan/blowfish.h>`` and use the Blowfish class. + +``BOTAN_MP_WORD_BITS``: This macro controls the size of the words used +for calculations with the MPI implementation in Botan. You can choose +8, 16, 32, or 64. Normally this defaults to either 32 or 64, depending +on the processor. Unless you are building for a 8 or 16-bit CPU, this +isn't worth messing with. + +``BOTAN_DEFAULT_BUFFER_SIZE``: This constant is used as the size of +buffers throughout Botan. The default should be fine for most +purposes, reduce if you are very concerned about runtime memory usage. + +Building Applications +---------------------------------------- + +Unix +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Botan usually links in several different system libraries (such as +``librt`` and ``libz``), depending on which modules are +configured at compile time. In many environments, particularly ones +using static libraries, an application has to link against the same +libraries as Botan for the linking step to succeed. But how does it +figure out what libraries it *is* linked against? + +The answer is to ask the ``botan-config`` script. This +basically solves the same problem all the other ``*-config`` +scripts solve, and in basically the same manner. + +There are 4 options: + +``--prefix[=DIR]``: If no argument, print the prefix where Botan +is installed (such as ``/opt`` or ``/usr/local``). If an +argument is specified, other options given with the same command will +execute as if Botan as actually installed at ``DIR`` and not +where it really is; or at least where ``botan-config`` thinks +it really is. I should mention that it + +``--version``: Print the Botan version number. + +``--cflags``: Print options that should be passed to the compiler +whenever a C++ file is compiled. Typically this is used for setting +include paths. + +``--libs``: Print options for which libraries to link to (this includes +``-lbotan``). + +Your ``Makefile`` can run ``botan-config`` and get the +options necessary for getting your application to compile and link, +regardless of whatever crazy libraries Botan might be linked against. + +Botan also by default installs a file for ``pkg-config``, +namespaced by the major and minor versions. So it can be used, +for instance, as:: + + $ pkg-config botan-1.10 --modversion + 1.10.0 + $ pkg-config botan-1.10 --cflags + -I/usr/local/include + $ pkg-config botan-1.10 --libs + -L/usr/local/lib -lbotan -lm -lbz2 -lpthread -lrt + +MS Windows +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +No special help exists for building applications on Windows. However, +given that typically Windows software is distributed as binaries, this +is less of a problem - only the developer needs to worry about it. As +long as they can remember where they installed Botan, they just have +to set the appropriate flags in their Makefile/project file. + +Language Wrappers +---------------------------------------- + +Building the Python wrappers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Python wrappers for Botan use Boost.Python, so you must have Boost +installed. To build the wrappers, pass the flag +``--with-boost-python`` to ``configure.py``. This will create a second +makefile, ``Makefile.python``, with instructions for building the +Python module. After building the library, execute:: + + $ make -f Makefile.python + +to build the module. Currently only Unix systems are supported, and +the Makefile assumes that the version of Python you want to build +against is the same one you used to run ``configure.py``. + +To install the module, use the ``install`` target. + +See :doc:`Python Bindings <python>` for more information about the +binding. + +Building the Perl XS wrappers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build the Perl XS wrappers, change your directory to +``src/wrap/perl-xs`` and run ``perl Makefile.PL``, then run +``make`` to build the module and ``make test`` to run the test +suite:: + + $ perl Makefile.PL + Checking if your kit is complete... + Looks good + Writing Makefile for Botan + $ make + cp Botan.pm blib/lib/Botan.pm + AutoSplitting blib/lib/Botan.pm (blib/lib/auto/Botan) + /usr/bin/perl5.8.8 /usr/lib64/perl5/5.8.8/ExtUtils/xsubpp [...] + g++ -c -Wno-write-strings -fexceptions -g [...] + Running Mkbootstrap for Botan () + chmod 644 Botan.bs + rm -f blib/arch/auto/Botan/Botan.so + g++ -shared Botan.o -o blib/arch/auto/Botan/Botan.so \ + -lbotan -lbz2 -lpthread -lrt -lz \ + + chmod 755 blib/arch/auto/Botan/Botan.so + cp Botan.bs blib/arch/auto/Botan/Botan.bs + chmod 644 blib/arch/auto/Botan/Botan.bs + Manifying blib/man3/Botan.3pm + $ make test + PERL_DL_NONLAZY=1 /usr/bin/perl5.8.8 [...] + t/base64......ok + t/filt........ok + t/hex.........ok + t/oid.........ok + t/pipe........ok + t/x509cert....ok + All tests successful. + Files=6, Tests=83, 0 wallclock secs ( 0.08 cusr + 0.02 csys = 0.10 CPU) |