\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{Botan Build Guide}
\author{Jack Lloyd (lloyd@randombit.net)}
\date{November 19, 2003}

\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 today, along with POSIX-ish systems like BeOS, QNX, and Plan 9.
Currently, systems other than Windows and POSIX (for example, VMS, MacOS 9, and
OS/390) 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.

\section{Building the Library}

The first step is to run \filename{configure.pl}, which is a Perl script that
creates various directories, config files, and a Makefile for building
everything. It is run as \verb|./configure.pl CC-OS-CPU <extra args>|. The
script requires at least Perl 5.005, and preferably 5.6 or higher.

The tuple CC-OS-CPU specifies what system Botan is being built for, in terms of
the C++ compiler, the operating system, and the CPU model. For example, to use
GNU C++ on a FreeBSD box that has an Alpha EV6 CPU, one would use
``gcc-freebsd-alphaev6'', and for Visual C++ on Windows with a Pentium II,
``msvc-windows-pentium2''. To get the list of values for \verb|CC|, \verb|OS|,
and \verb|CPU| that \filename{configure.pl} supports, run it with the
``\verb|--help|'' option.

You can put basically anything reasonable for CPU: the script knows about a
large number of different architectures, their sub-models, and common aliases
for them. The script does not display all the possibilities in it's help
message because there are simply too many entries (if you're curious about what
exactly is available, you can look at the \verb|%ARCH|, \verb|%ARCH_ALIAS|, and
\verb|%SUBMODEL_ALIAS| hashes at the start of the script). You should only
select the 64-bit version of a CPU (like ``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. For example,
gcc-solaris-sparc64 will not work unless you're running a 64-bit Solaris kernel
(for 32-bit Solaris running on an UltraSPARC system, you want
gcc-solaris-sparc32-v9). You may or may not have to install 64-bit versions of
libc and related system libraries as well.

The script also knows about the various extension modules available. You can
enable one or more with the option ``\verb|--modules=MOD|'', where \verb|MOD|
is some name that identifies the extension (or a comma separated list of
them). Modules provide additional capabilities which require the use of non
portable APIs. You should enable any extensions which makes sense for your
system.

Not all OSes or CPUs have specific support in \filename{configure.pl}. If the
CPU architecture of your system isn't supported by \filename{configure.pl}, use
'generic'. This setting disables machine-specific optimization
flags. Similarly, setting OS to 'generic' disables things which depend greatly
on OS support (specifically, shared libraries).

However, it's impossible to guess which options to give to a system compiler.
Thus, if you want to compile Botan with a compiler which
\filename{configure.pl} does not support, the script will have to be updated.
Preferably, mail the man pages (or similar documentation) for the C and C++
compilers and the system linker to the author, or download the Botan-config
package from the Botan web site, and do it yourself. Modifying
\filename{configure.pl} on it's own is useless aside from one-off hacks,
because the script is auto-generated by \emph{another} Perl script, which reads
a little mini-language that tells it all about the systems in question.

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 POSIX 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.

\pagebreak

\subsection{POSIX / Unix}

The basic build procedure on Unix and Unix-like systems is:

\begin{verbatim}
   $ ./configure.pl CC-OS-CPU --module-set=[unix|beos] --modules=<other mods>
   $ make
   $ make check # optional, but a good idea
   $ make install
\end{verbatim}

The 'unix' module set should work on most POSIX/Unix systems out there
(including MacOS X), while the 'beos' module is specific to BeOS. While the two
sets share a number of modules, some normal Unix ones don't work on BeOS (in
particular, BeOS doesn't have a working \function{mmap} function), and BeOS has
a few extras just for it.

Other important modules you might want to include are \module{comp\_zlib}
(which wraps \texttt{zlib} for use in the library), and, if your hardware
supports it, \module{mp\_asm64}. That module is only usable on 64-bit systems,
and provides a 20-300\% increase in the performance of public key algorithms
when used. There is another module, \module{mp\_gmp}, which uses GNU MP for
certain low-level operations, and also provides very substantial speedups. You
can use both at once without any problems.

The \verb|make install| target has a default directory in which it will install
Botan (on everything that's a real Unix, it's \verb|/usr/local|). You can
override this by using the \texttt{--prefix} argument to
\filename{configure.pl}, like so:

\verb|./configure.pl --prefix=/opt <other arguments>|

On Unix, the makefile has to decide who should own the files once they are
installed. By default, it uses \texttt{root:root}, but on some systems (for
example, MacOS X), there is no \texttt{root} group. Also, if you don't have
root access on the system you will want them to be installed owned by something
other than root (like yourself). You can override the defaults at install time
by setting the \texttt{OWNER} and \texttt{GROUP} variables from the command
line.

\verb|make OWNER=lloyd GROUP=users install|

\subsection{MS Windows}

The situation is not much different here. We'll assume you're using Visual C++
(for Cygwin, the Unix instructions are probably more relevant). You need to
have a copy of Perl installed, and have both Perl and Visual C++ in your path.

\begin{verbatim}
   > perl configure.pl msvc-windows-<CPU> [--module-set=win32]
   > nmake
   > nmake check # optional, but recommended
\end{verbatim}

The additional argument \verb|--module-set=win32| is optional, but highly
recommended. This will include a set of modules for doing useful things on
Windows systems, particularly gathering entropy for the PRNG. In the future,
support for high resolution timers, mutexes, and maybe even secure memory
allocation will also be made available by this flag.

For Win95 pre OSR2, the \verb|es_capi| module will not work, because CryptoAPI
didn't exist. All versions of NT4 lack the ToolHelp32 interface, which is how
\verb|es_win32| does it's slow polls, so a version of the library built with
that module will not load under NT4. Later systems (98/ME/2000/XP) support both
methods, so this shouldn't be much of an issue.

If you have zlib or libbz2 installed, you can also use the \module{comp\_zlib}
or \module{comp\_bzip2} modules. The \module{mp\_gmp} module should also work,
if you have GNU MP installed. Most of the other modules rely on libraries or
system calls not available on Windows, or an inline assembler format not
supported by Visual C++.

Unfortunately, there currently isn't an install script usable on
Windows. Basically all you have to do is copy the newly created
\filename{libbotan.lib} to someplace where you can find it later (say,
\verb|C:\Botan\|). Then copy the entire \verb|include\botan| directory, which
was constructed when you built the library, into the same directory.

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.

\pagebreak

\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{config.h} are macros which are defined if one or
more extensions are available. All of them begin with \verb|BOTAN_EXT_|. For
example, if \verb|BOTAN_EXT_COMPRESSOR_BZIP2| is defined, then an application
using Botan can include \filename{<botan/bzip2.h>} and use the Bzip2 filters.

\macro{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 the \module{mp\_asm64} module is
used; this offers vastly improved performance of public key algorithms on
certain 64-bit CPUs (it will set this to 64 automatically when used).

Note that \macro{MP\_WORD\_BITS} is a macro that \emph{doesn't} start with the
typical \macro{BOTAN\_} prefix (mostly for historical reasons).

\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.

\pagebreak

\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. At some point in the future, a transition to
\filename{pkg-config} will be made (as it's less work, and has more features),
but right now it doesn't exist on most Unix systems, which a plain Bourne shell
script will run fine on anything.

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.

\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.

\end{document}
