diff options
Diffstat (limited to 'doc/building.tex')
| -rw-r--r-- | doc/building.tex | 95 |
1 files changed, 52 insertions, 43 deletions
diff --git a/doc/building.tex b/doc/building.tex index 5d9b0b171..91d3ded42 100644 --- a/doc/building.tex +++ b/doc/building.tex @@ -13,7 +13,7 @@ \title{\textbf{Botan Build Guide}} \author{Jack Lloyd \\ \texttt{[email protected]}} -\date{2009-10-09} +\date{2010-06-10} \newcommand{\filename}[1]{\texttt{#1}} \newcommand{\module}[1]{\texttt{#1}} @@ -42,13 +42,16 @@ 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.4 or later is required. +script. Python 2.4 or later is required (but 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} @@ -63,7 +66,10 @@ spot, you might need to prefix the \texttt{configure.py} command with 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.4; any -later version of Python 2.x should also work. +later version of Python 2.x should also work. If you want to use +Python 3.1, first run the program \texttt{2to3} (included in the +Python distribution) on the script; this will convert the script to +the Python 3.x dialect. 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). @@ -95,11 +101,15 @@ 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=blowfish,md5,rsa,zlib --disable-modules=arc4,cmac|''. -Modules not listed on the command line will simply be loaded if needed -or if configured to load by default. +options \verb|--enable-modules=MODS| and +\verb|--disable-modules=MODS|, for instance +\verb|--enable-modules=blowfish,md5,rsa,zlib| and +\verb|--disable-modules=arc4,cmac|. 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 @@ -123,8 +133,9 @@ The basic build procedure on Unix and Unix-like systems is: $ make install \end{verbatim} -This will probably default to using GCC, depending on what can be -found within your PATH. +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 @@ -142,29 +153,31 @@ to include the directory that the Botan libraries were installed into. \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 Python installed, and have both Python and Visual C++ in your path. +If you don't want to deal with building botan on Windows, check the +website; commonly prebuild Windows binaries with installers are +available, especially for stable versions. + +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 Python installed, and have both +Python and Visual C++ in your path. \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 systems (98/ME/2000/XP) support both methods, so -this shouldn't be much of an issue. +load under NT4. Later versions of Windows support both methods, so +this shouldn't be much of an issue anymore. -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|build\include\botan| -directory, which was constructed when you built the library, into the -same directory. +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 @@ -208,12 +221,6 @@ perfectly fine. 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. -\macro{BOTAN\_GZIP\_OS\_CODE}: The OS code is included in the Gzip header when -compressing. The default is 255, which means 'Unknown'. You can look in RFC -1952 for the full list; the most common are Windows (0) and Unix (3). There is -also a Macintosh (7), but it probably makes more sense to use the Unix code on -OS X. - \subsection{Multiple Builds} It may be useful to run multiple builds with different @@ -239,20 +246,22 @@ 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.} + \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 \verb|--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 \verb|--with-zlib|} - \item \mod{zlib}{Enables an application to perform zlib compression and - decompression using the library. Available on any system that has - 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 \verb|--with-gnump|} - \item \mod{gnump}{An engine that uses GNU MP to speed up PK operations. - GNU MP 4.1 or later is required.} + \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.} To enable, use option \verb|--with-openssl|} - \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.} \end{list} \section{Building Applications} @@ -297,11 +306,11 @@ namespaced by the major and minor versions. So it can be used, for instance, as \begin{verbatim} -$ pkg-config botan-1.8 --modversion -1.8.0 -$ pkg-config botan-1.8 --cflags +$ pkg-config botan-1.9 --modversion +1.9.8 +$ pkg-config botan-1.9 --cflags -I/usr/local/include -$ pkg-config botan-1.8 --libs +$ pkg-config botan-1.9 --libs -L/usr/local/lib -lbotan -lm -lbz2 -lpthread -lrt \end{verbatim} @@ -320,7 +329,7 @@ to set the appropriate flags in their Makefile/project file. The Python wrappers for Botan use Boost.Python, so you must have Boost installed. To build the wrappers, add the flag -\verb|--use-boost-python| +\verb|--with-boost-python| to \verb|configure.py|. This will create a second makefile, \verb|Makefile.python|, with instructions for building the Python |