diff options
Diffstat (limited to 'doc/building.tex')
| -rw-r--r-- | doc/building.tex | 444 |
1 files changed, 0 insertions, 444 deletions
diff --git a/doc/building.tex b/doc/building.tex deleted file mode 100644 index 7164f74eb..000000000 --- a/doc/building.tex +++ /dev/null @@ -1,444 +0,0 @@ -\documentclass{article} - -\setlength{\textwidth}{6.5in} -\setlength{\textheight}{9in} - -\setlength{\headheight}{0in} -\setlength{\topmargin}{0in} -\setlength{\headsep}{0in} - -\setlength{\oddsidemargin}{0in} -\setlength{\evensidemargin}{0in} - -\title{\textbf{Botan Build Guide}} -\author{Jack Lloyd \\ - \texttt{[email protected]}} -\date{2010-06-10} - -\newcommand{\filename}[1]{\texttt{#1}} -\newcommand{\module}[1]{\texttt{#1}} - -\newcommand{\type}[1]{\texttt{#1}} -\newcommand{\function}[1]{\textbf{#1}} -\newcommand{\macro}[1]{\texttt{#1}} - -\begin{document} - -\maketitle - -\tableofcontents - -\parskip=5pt -\pagebreak - -\section{Introduction} - -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 -script. Python 2.5 or later is required. If you want to use the -(incompatible) Python 3, you must first run the \texttt{2to3} script -on it. - -\section{For the Impatient} - -\begin{verbatim} -$ ./configure.py [--prefix=/some/directory] -$ make -$ make check -$ make install -\end{verbatim} - -Or using \verb|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 \texttt{configure.py} command with -\texttt{python} or \texttt{/path/to/python}. - -\section{Building the Library} - -The first step is to run \filename{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 the section ``Using Python 3.1'', -later in this document. - -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 \verb|--cc|, -\verb|--os|, and \verb|--cpu|. - -You can pass basically anything reasonable with \verb|--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: - -\begin{verbatim} - INFO: Skipping mod because CPU incompatible - asm_amd64 mp_amd64 mp_asm64 sha1_amd64 - INFO: Skipping mod because OS incompatible - cryptoapi_rng win32_stats - INFO: Skipping mod because compiler incompatible - mp_ia32_msvc - INFO: Skipping mod because loaded on request only - bzip2 gnump openssl qt_mutex zlib -\end{verbatim} - -The ones that are 'loaded on request only' have to be explicitly asked -for, because they rely on third party libraries which your system -might not have. For instance to enable zlib support, add -\verb|--with-zlib| to your invocation of \verb|configure.py|. - -You can control which algorithms and modules are built using the -options \verb|--enable-modules=MODS| and -\verb|--disable-modules=MODS|, for instance -\verb|--enable-modules=zlib| and \verb|--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 \verb|--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 targetted to a specific application. - -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 -\verb|--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 -\filename{src/build-data/makefile}. - -\subsection{POSIX / Unix} - -The basic build procedure on Unix and Unix-like systems is: - -\begin{verbatim} - $ ./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 -\end{verbatim} - -On Unix systems the script will default to using GCC; use -\texttt{--cc} if you want something else. For instance use -\texttt{--cc=icc} for Intel C++ and \texttt{--cc=clang} for Clang. - -The \verb|make install| target has a default directory in which it -will install Botan (typically \verb|/usr/local|). You can override -this by using the \texttt{--prefix} argument to -\filename{configure.py}, like so: - -\verb|./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 -\filename{/etc/ld.so.conf} and run \texttt{ldconfig} (as root) in -order for new shared libraries to be picked up by the linker. An -alternative is to set your \texttt{LD\_LIBRARY\_PATH} shell variable -to include the directory that the Botan libraries were installed into. - -\subsection{Mac OS X} - -In general the Unix instructions above should apply, however OS X does -not support \texttt{LD\_LIBRARY\_PATH}. Thomas Keller suggests instead -running \verb|install_name_tool| between building and running the -self-test program: - -\begin{verbatim} - $ VERSION=1.9.10 - $ install_name_tool -change $(otool -X -D libbotan-$VERSION.dylib) \ - $PWD/libbotan-$VERSION.dylib check -\end{verbatim} - -\subsection{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: - -\begin{verbatim} - > python configure.py --cc=msvc (or --cc=gcc for MinGW) [--cpu=CPU] - > nmake - > nmake check # optional, but recommended - > nmake install -\end{verbatim} - -For Win95 pre OSR2, the \verb|cryptoapi_rng| module will not work, -because CryptoAPI didn't exist. And all versions of NT4 lack the -ToolHelp32 interface, which is how \verb|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:\textbackslash botan'; you -can modify this with the \texttt{--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 -\verb|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). - -\section{Trickier Things} - -\subsection{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: - -\newcommand{\mod}[2]{\textbf{#1}: #2} - -\begin{list}{$\cdot$} - \item \mod{bzip2}{Enables an application to perform bzip2 - compression and decompression using the library. Available on any - system that has bzip2. To enable, use option \texttt{--with-bzip2}} - - \item \mod{zlib}{Enables an application to perform zlib compression - and decompression using the library. Available on any system that - has zlib. To enable, use option \texttt{--with-zlib}} - - \item \mod{gnump}{An engine that uses GNU MP to speed up PK - operations. GNU MP 4.1 or later is required. To enable, use - option \texttt{--with-gnump}} - - \item \mod{openssl}{An engine that uses OpenSSL to speed up public - key operations and some ciphers/hashes. OpenSSL 0.9.7 or later is - required. Note that, unlike GNU MP, OpenSSL's versions are not - always faster than the versions built into botan. To enable, use - option \texttt{--with-openssl}} - -\end{list} - -\subsection{Amalgamation} - -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 \filename{configure.py} with -whatever arguments you would ordinarily use, along with the option -\texttt{--gen-amalgamation}. This will create two (rather large) -files, \filename{botan\_all.h} and \filename{botan\_all.cpp}. - -Whenever you would have included a botan header, you can then include -\filename{botan\_all.h}, and include \filename{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 -\filename{botan\_all.h} and use the headers from -\filename{build/include} as normal. - -\subsection{Multiple Builds} - -It may be useful to run multiple builds with different -configurations. Specify \verb|--build-dir=<dir>| to set up a build -environment in a different directory. - -\subsection{Using Python 3.1} - -The versions of Python begininning 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 -\texttt{2to3} program (included in the Python distribution) on the -script; this will convert the script to the Python 3.x dialect: - -\begin{verbatim} - $ 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 -[...] -\end{verbatim} - -\subsection{Local Configuration} - -You may want to do something peculiar with the configuration; to -support this there is a flag to \filename{configure.py} called -\texttt{--with-local-config=<file>}. The contents of the file are -inserted into \filename{build/build.h} which is (indirectly) included -into every Botan header and source file. - -\subsection{Configuration Parameters} - -There are some configuration parameters which you may want to tweak -before building the library. These can be found in -\filename{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 \filename{build/build.h} are macros which are defined -if one or more extensions are available. All of them begin with -\verb|BOTAN_HAS_|. For example, if \verb|BOTAN_HAS_COMPRESSOR_BZIP2| -is defined, then an application using Botan can include -\filename{<botan/bzip2.h>} and use the Bzip2 filters. - -\macro{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, with 32 being the default. You can use 8, -16, or 32 bit words on any CPU, but the value should be set to the -same size as the CPU's registers for best performance. You can only -use 64-bit words if an assembly module (such as \module{mp\_ia32} or -\module{mp\_asm64}) is used. If the appropriate module is available, -64 bits are used, otherwise this is set to 32. Unless you are building -for a 8 or 16-bit CPU, this isn't worth messing with. - -\macro{BOTAN\_VECTOR\_OVER\_ALLOCATE}: The memory container -\type{SecureVector} will over-allocate requests by this amount (in -elements). In several areas of the library, we grow a vector fairly often. By -over-allocating by a small amount, we don't have to do allocations as often -(which is good, because the allocators can be quite slow). If you \emph{really} -want to reduce memory usage, set it to 0. Otherwise, the default should be -perfectly fine. - -\macro{BOTAN\_DEFAULT\_BUFFER\_SIZE}: This constant is used as the size of -buffers throughout Botan. A good rule of thumb would be to use the page size of -your machine. The default should be fine for most, if not all, purposes. - -\section{Building Applications} - -\subsection{Unix} - -Botan usually links in several different system libraries (such as -\texttt{librt} and \texttt{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 \emph{is} linked against? - -The answer is to ask the \filename{botan-config} script. This -basically solves the same problem all the other \filename{*-config} -scripts solve, and in basically the same manner. - -There are 4 options: - -\texttt{--prefix[=DIR]}: If no argument, print the prefix where Botan -is installed (such as \filename{/opt} or \filename{/usr/local}). If an -argument is specified, other options given with the same command will -execute as if Botan as actually installed at \filename{DIR} and not -where it really is; or at least where \filename{botan-config} thinks -it really is. I should mention that it - -\texttt{--version}: Print the Botan version number. - -\texttt{--cflags}: Print options that should be passed to the compiler -whenever a C++ file is compiled. Typically this is used for setting -include paths. - -\texttt{--libs}: Print options for which libraries to link to (this includes -\texttt{-lbotan}). - -Your \filename{Makefile} can run \filename{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 \texttt{pkg-config}, -namespaced by the major and minor versions. So it can be used, -for instance, as - -\begin{verbatim} -$ pkg-config botan-1.9 --modversion -1.9.8 -$ pkg-config botan-1.9 --cflags --I/usr/local/include -$ pkg-config botan-1.9 --libs --L/usr/local/lib -lbotan -lm -lbz2 -lpthread -lrt -\end{verbatim} - -\subsection{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. - -\section{Language Wrappers} - -\subsection{Building the Python wrappers} - -The Python wrappers for Botan use Boost.Python, so you must have Boost -installed. To build the wrappers, add the flag - -\verb|--with-boost-python| - -to \verb|configure.py|. This will create a second makefile, -\verb|Makefile.python|, with instructions for building the Python -module. After building the library, execute - -\begin{verbatim} -$ make -f Makefile.python -\end{verbatim} - -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 \verb|configure.py|. - -To install the module, use the \verb|install| target. - -Examples of using the Python module can be seen in \filename{doc/python} - -\subsection{Building the Perl XS wrappers} - -To build the Perl XS wrappers, change your directory to -\filename{src/wrap/perl-xs} and run \verb|perl Makefile.PL|, then run -\verb|make| to build the module and \verb|make test| to run the test -suite. - -\begin{verbatim} -$ 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) -\end{verbatim} - -\end{document} |