docs/building.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
   7 <title>libtorrent manual</title>
   8 <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
   9 <link rel="stylesheet" href="style.css" type="text/css" />
  10 </head>
  11 <body>
  12 <div class="document" id="libtorrent-manual">
  13 <h1 class="title">libtorrent manual</h1>
  14 <table class="docinfo" frame="void" rules="none">
  15 <col class="docinfo-name" />
  16 <col class="docinfo-content" />
  17 <tbody valign="top">
  18 <tr><th class="docinfo-name">Author:</th>
  19 <td>Arvid Norberg, <a class="last reference" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
  20 </tbody>
  21 </table>
  22 <div class="contents topic" id="table-of-contents">
  23 <p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
  24 <ul class="simple">
  25 <li><a class="reference" href="#downloading-and-building" id="id9" name="id9">downloading and building</a><ul>
  26 <li><a class="reference" href="#building-from-svn" id="id10" name="id10">building from svn</a></li>
  27 <li><a class="reference" href="#building-with-bbv2" id="id11" name="id11">building with BBv2</a></li>
  28 <li><a class="reference" href="#building-with-autotools" id="id12" name="id12">building with autotools</a></li>
  29 <li><a class="reference" href="#building-with-other-build-systems" id="id13" name="id13">building with other build systems</a></li>
  30 <li><a class="reference" href="#build-configurations" id="id14" name="id14">build configurations</a></li>
  31 <li><a class="reference" href="#building-openssl-for-windows" id="id15" name="id15">building openssl for windows</a></li>
  32 </ul>
  33 </li>
  34 </ul>
  35 </div>
  36 <div class="section">
  37 <h1><a id="downloading-and-building" name="downloading-and-building">downloading and building</a></h1>
  38 <p>To acquire the latest version of libtorrent, you'll have to grab it from SVN.
  39 You'll find instructions on how to do this <a class="reference" href="http://sourceforge.net/svn/?group_id=79942">here</a> (see subversion access).</p>
  40 <p>The build systems supported &quot;out of the box&quot; in libtorrent are boost-build v2
  41 (BBv2) and autotools (for unix-like systems). If you still can't build after
  42 following these instructions, you can usually get help in the <tt class="docutils literal"><span class="pre">#libtorrent</span></tt>
  43 IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
  44 <p>Community contributed build tutorials can be found on the <a class="reference" href="http://code.rasterbar.com/libtorrent/wiki/Building">wiki</a>.</p>
  45 <div class="section">
  46 <h2><a id="building-from-svn" name="building-from-svn">building from svn</a></h2>
  47 <p>To build libtorrent from svn you need to check out the libtorrent sources from
  48 sourceforge and also check out the asio sources from its sourceforge cvs.
  49 If you downloaded a release tarball, you can skip this section.</p>
  50 <p>To prepare the directory structure for building, follow these steps:</p>
  51 <ul class="simple">
  52 <li>Check out libtorrent (<a class="reference" href="http://sourceforge.net/svn/?group_id=79942">instructions</a>).</li>
  53 <li>Check out asio (<a class="reference" href="http://sourceforge.net/cvs/?group_id=122478">instructions</a>).</li>
  54 <li>Copy the <tt class="docutils literal"><span class="pre">asio/include/asio/</span></tt> directory into the <tt class="docutils literal"><span class="pre">libtorrent/include/libtorrent/</span></tt>
  55 directory. Alternatively you can make a symbolic link.</li>
  56 <li>Copy <tt class="docutils literal"><span class="pre">asio/include/asio.hpp</span></tt> into <tt class="docutils literal"><span class="pre">libtorrent/include/libtorrent</span></tt>.</li>
  57 </ul>
  58 <p>Now the libtorrent directory is ready for building. Follow the steps in one
  59 of the following sections depending on which build system you prefer to use.</p>
  60 </div>
  61 <div class="section">
  62 <h2><a id="building-with-bbv2" name="building-with-bbv2">building with BBv2</a></h2>
  63 <p>The primary reason to use boost-build is that it will automatically build the
  64 dependent boost libraries with the correct compiler settings, in order to
  65 ensure that the build targets are link compatible (see <a class="reference" href="http://boost.org/more/separate_compilation.html">boost guidelines</a>
  66 for some details on this issue).</p>
  67 <p>Since BBv2 will build the boost libraries for you, you need the full boost
  68 source package. Having boost installed via some package system is usually not
  69 enough (and even if it is enough, the necessary environment variables are
  70 usually not set by the package installer).</p>
  71 <p>If you want to build against an installed copy of boost, you can skip directly
  72 to step 3 (assuming you also have boost build installed).</p>
  73 <div class="section">
  74 <h3><a id="step-1-download-boost" name="step-1-download-boost">Step 1: Download boost</a></h3>
  75 <p>You'll find boost <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041&amp;release_id=619445">here</a>.</p>
  76 <p>Extract the archive to some directory where you want it. For the sake of this
  77 guide, let's assume you extract the package to <tt class="docutils literal"><span class="pre">c:\boost_1_34_0</span></tt> (I'm using
  78 a windows path in this example since if you're on linux/unix you're more likely
  79 to use the autotools). You'll need at least version 1.34 of the boost library
  80 in order to build libtorrent.</p>
  81 </div>
  82 <div class="section">
  83 <h3><a id="step-2-setup-bbv2" name="step-2-setup-bbv2">Step 2: Setup BBv2</a></h3>
  84 <p>First you need to build <tt class="docutils literal"><span class="pre">bjam</span></tt>. You do this by opening a terminal (In
  85 windows, run <tt class="docutils literal"><span class="pre">cmd</span></tt>). Change directory to
  86 <tt class="docutils literal"><span class="pre">c:\boost_1_34_0\tools\jam\src</span></tt>. Then run the script called
  87 <tt class="docutils literal"><span class="pre">build.bat</span></tt> or <tt class="docutils literal"><span class="pre">build.sh</span></tt> on a unix system. This will build <tt class="docutils literal"><span class="pre">bjam</span></tt> and
  88 place it in a directory starting with <tt class="docutils literal"><span class="pre">bin.</span></tt> and then have the name of your
  89 platform. Copy the <tt class="docutils literal"><span class="pre">bjam.exe</span></tt> (or <tt class="docutils literal"><span class="pre">bjam</span></tt> on a unix system) to a place
  90 that's in you shell's <tt class="docutils literal"><span class="pre">PATH</span></tt>. On linux systems a place commonly used may be
  91 <tt class="docutils literal"><span class="pre">/usr/local/bin</span></tt> or on windows <tt class="docutils literal"><span class="pre">c:\windows</span></tt> (you can also add directories
  92 to the search paths by modifying the environment variable called <tt class="docutils literal"><span class="pre">PATH</span></tt>).</p>
  93 <p>Now you have <tt class="docutils literal"><span class="pre">bjam</span></tt> installed. <tt class="docutils literal"><span class="pre">bjam</span></tt> can be considered an interpreter
  94 that the boost-build system is implemented on. So boost-build uses <tt class="docutils literal"><span class="pre">bjam</span></tt>.
  95 So, to complete the installation you need to make two more things. You need to
  96 set the environment variable <tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt>. This is the path that tells
  97 <tt class="docutils literal"><span class="pre">bjam</span></tt> where it can find boost-build, your configuration file and all the
  98 toolsets (descriptions used by boost-build to know how to use different
  99 compilers on different platforms). Assuming the boost install path above, set
 100 it to <tt class="docutils literal"><span class="pre">c:\boost_1_34_0\tools\build\v2</span></tt>.</p>
 101 <p>To set an environment variable in windows, type for example:</p>
 102 <pre class="literal-block">
 103 set BOOST_BUILD_PATH=c:\boost_1_34_0\tools\build\v2
 104 </pre>
 105 <p>In a terminal window.</p>
 106 <p>The last thing to do to complete the setup of BBv2 is to modify your
 107 <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file. It is located in <tt class="docutils literal"><span class="pre">c:\boost_1_34_0\tools\build\v2</span></tt>.
 108 Depending on your platform and which compiler you're using, you should add a
 109 line for each compiler and compiler version you have installed on your system
 110 that you want to be able to use with BBv2. For example, if you're using
 111 Microsoft Visual Studio 7.1 (2003), just add a line:</p>
 112 <pre class="literal-block">
 113 using msvc : 7.1 ;
 114 </pre>
 115 <p>If you use GCC, add the line:</p>
 116 <pre class="literal-block">
 117 using gcc ;
 118 </pre>
 119 <p>If you have more than one version of GCC installed, you can add the
 120 commandline used to invoke g++ after the version number, like this:</p>
 121 <pre class="literal-block">
 122 using gcc : 3.3 : g++-3.3 ;
 123 using gcc : 4.0 : g++-4.0 ;
 124 </pre>
 125 <p>Another toolset worth mentioning is the <tt class="docutils literal"><span class="pre">darwin</span></tt> toolset (For MacOS X).
 126 From Tiger (10.4) MacOS X comes with both GCC 3.3 and GCC 4.0. Then you can
 127 use the following toolsets:</p>
 128 <pre class="literal-block">
 129 using darwin : 3.3 : g++-3.3 ;
 130 using darwin : 4.0 : g++-4.0 ;
 131 </pre>
 132 <p>Note that the spaces around the semi-colons and colons are important!</p>
 133 <p>Also see the <a class="reference" href="http://www.boost.org/doc/html/bbv2/installation.html">official installation instructions</a>.</p>
 134 </div>
 135 <div class="section">
 136 <h3><a id="step-3-building-libtorrent" name="step-3-building-libtorrent">Step 3: Building libtorrent</a></h3>
 137 <p>When building libtorrent, the <tt class="docutils literal"><span class="pre">Jamfile</span></tt> expects the environment variable
 138 <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> to be set to the boost installation directory. It uses this to
 139 find the boost libraries it depends on, so they can be built and their headers
 140 files found. So, set this to <tt class="docutils literal"><span class="pre">c:\boost_1_34_0</span></tt>. You only need this if you're
 141 building against a source distribution of boost.</p>
 142 <p>Then the only thing left is simply to invoke <tt class="docutils literal"><span class="pre">bjam</span></tt>. If you want to specify
 143 a specific toolset to use (compiler) you can just add that to the commandline.
 144 For example:</p>
 145 <pre class="literal-block">
 146 bjam msvc-7.1 boost=source
 147 bjam gcc-3.3 boost=source
 148 bjam darwin-4.0 boost=source
 149 </pre>
 150 <p>If you're building against a system installed boost, specify <tt class="docutils literal"><span class="pre">boost=system</span></tt>.</p>
 151 <p>To build different versions you can also just add the name of the build
 152 variant. Some default build variants in BBv2 are <tt class="docutils literal"><span class="pre">release</span></tt>, <tt class="docutils literal"><span class="pre">debug</span></tt>,
 153 <tt class="docutils literal"><span class="pre">profile</span></tt>.</p>
 154 <p>You can build libtorrent as a dll too, by typing <tt class="docutils literal"><span class="pre">link=shared</span></tt>, or
 155 <tt class="docutils literal"><span class="pre">link=static</span></tt> to build a static library.</p>
 156 <p>If you want to explicitly say how to link against the runtime library, you
 157 can set the <tt class="docutils literal"><span class="pre">runtime-link</span></tt> feature on the commandline, either to <tt class="docutils literal"><span class="pre">shared</span></tt>
 158 or <tt class="docutils literal"><span class="pre">static</span></tt>. Most operating systems will only allow linking shared against
 159 the runtime, but on windows you can do both. Example:</p>
 160 <pre class="literal-block">
 161 bjam msvc-7.1 link=static runtime-link=static boost=source
 162 </pre>
 163 <div class="warning">
 164 <p class="first admonition-title">Warning</p>
 165 <p class="last">If you link statically to the runtime library, you cannot build libtorrent
 166 as a shared library (DLL), since you will get separate heaps in the library
 167 and in the client application. It will result in crashes and possibly link
 168 errors.</p>
 169 </div>
 170 <div class="warning">
 171 <p class="first admonition-title">Warning</p>
 172 <p class="last">With boost-build V2 (Milestone 11), the darwin toolset uses the <tt class="docutils literal"><span class="pre">-s</span></tt> linker
 173 option to strip debug symbols. This option is buggy in Apple's GCC, and
 174 will make the executable crash on startup. On Mac OS X, instead build
 175 your release executables with the <tt class="docutils literal"><span class="pre">debug-symbols=on</span></tt> option, and
 176 later strip your executable with <tt class="docutils literal"><span class="pre">strip</span></tt>.</p>
 177 </div>
 178 <div class="warning">
 179 <p class="first admonition-title">Warning</p>
 180 <p class="last">Some linux systems requires linking against <tt class="docutils literal"><span class="pre">librt</span></tt> in order to access
 181 the POSIX clock functions. If you get an error complaining about a missing
 182 symbol <tt class="docutils literal"><span class="pre">clock_gettime</span></tt>, you have to give <tt class="docutils literal"><span class="pre">need-librt=yes</span></tt> on the
 183 bjam command line. This will make libtorrent link against <tt class="docutils literal"><span class="pre">librt</span></tt>.</p>
 184 </div>
 185 <p>The build targets are put in a directory called bin, and under it they are
 186 sorted in directories depending on the toolset and build variant used.</p>
 187 <p>To build the examples, just change directory to the examples directory and
 188 invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> from there. To build and run the tests, go to the test
 189 directory and run <tt class="docutils literal"><span class="pre">bjam</span></tt>.</p>
 190 <p>Note that if you're building on windows using the <tt class="docutils literal"><span class="pre">msvc</span></tt> toolset, you cannot run it
 191 from a cygwin terminal, you'll have to run it from a <tt class="docutils literal"><span class="pre">cmd</span></tt> terminal. The same goes for
 192 cygwin, if you're building with gcc in cygwin you'll have to run it from a cygwin terminal.
 193 Also, make sure the paths are correct in the different environments. In cygwin, the paths
 194 (<tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt> and <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt>) should be in the typical unix-format (e.g.
 195 <tt class="docutils literal"><span class="pre">/cygdrive/c/boost_1_34_0</span></tt>). In the windows environment, they should have the typical
 196 windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_34_0</span></tt>).</p>
 197 <p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> will define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> when it's building a release build.
 198 For more build configuration flags see <a class="reference" href="#build-configurations">Build configurations</a>.</p>
 199 <p>Build features:</p>
 200 <table border="1" class="docutils">
 201 <colgroup>
 202 <col width="33%" />
 203 <col width="67%" />
 204 </colgroup>
 205 <thead valign="bottom">
 206 <tr><th class="head">boost build feature</th>
 207 <th class="head">values</th>
 208 </tr>
 209 </thead>
 210 <tbody valign="top">
 211 <tr><td><tt class="docutils literal"><span class="pre">boost</span></tt></td>
 212 <td><ul class="first last simple">
 213 <li><tt class="docutils literal"><span class="pre">system</span></tt> - default. Tells the Jamfile that
 214 boost is installed and should be linked against
 215 the system libraries.</li>
 216 <li><tt class="docutils literal"><span class="pre">source</span></tt> - Specifies that boost is to be built
 217 from source. The environment variable
 218 <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> must be defined to point to the
 219 boost directory.</li>
 220 </ul>
 221 </td>
 222 </tr>
 223 <tr><td><tt class="docutils literal"><span class="pre">boost-link</span></tt></td>
 224 <td><ul class="first last simple">
 225 <li><tt class="docutils literal"><span class="pre">static</span></tt> - links statically against the boost
 226 libraries.</li>
 227 <li><tt class="docutils literal"><span class="pre">shared</span></tt> - links dynamically against the boost
 228 libraries.</li>
 229 </ul>
 230 </td>
 231 </tr>
 232 <tr><td><tt class="docutils literal"><span class="pre">logging</span></tt></td>
 233 <td><ul class="first last simple">
 234 <li><tt class="docutils literal"><span class="pre">none</span></tt> - no logging.</li>
 235 <li><tt class="docutils literal"><span class="pre">default</span></tt> - basic session logging.</li>
 236 <li><tt class="docutils literal"><span class="pre">verbose</span></tt> - verbose peer wire logging.</li>
 237 <li><tt class="docutils literal"><span class="pre">errors</span></tt> - like verbose, but limited to errors.</li>
 238 </ul>
 239 </td>
 240 </tr>
 241 <tr><td><tt class="docutils literal"><span class="pre">dht-support</span></tt></td>
 242 <td><ul class="first last simple">
 243 <li><tt class="docutils literal"><span class="pre">on</span></tt> - build with support for tracker less
 244 torrents and DHT support.</li>
 245 <li><tt class="docutils literal"><span class="pre">logging</span></tt> - build with DHT support and verbose
 246 logging of the DHT protocol traffic.</li>
 247 <li><tt class="docutils literal"><span class="pre">off</span></tt> - build without DHT support.</li>
 248 </ul>
 249 </td>
 250 </tr>
 251 <tr><td><tt class="docutils literal"><span class="pre">need-librt</span></tt></td>
 252 <td><ul class="first last simple">
 253 <li><tt class="docutils literal"><span class="pre">no</span></tt> - this platform does not need to link
 254 against librt to have POSIX time functions.</li>
 255 <li><tt class="docutils literal"><span class="pre">yes</span></tt> - specify this if your linux system
 256 requires you to link against librt.a. This is
 257 typically the case on x86 64 bit systems.</li>
 258 </ul>
 259 </td>
 260 </tr>
 261 <tr><td><tt class="docutils literal"><span class="pre">zlib</span></tt></td>
 262 <td><ul class="first last simple">
 263 <li><tt class="docutils literal"><span class="pre">system</span></tt> - links against the zlib supplied
 264 with your operating system.</li>
 265 <li><tt class="docutils literal"><span class="pre">shipped</span></tt> - links against the zlib bundled
 266 with the libtorrent package.</li>
 267 </ul>
 268 </td>
 269 </tr>
 270 <tr><td><tt class="docutils literal"><span class="pre">geoip</span></tt></td>
 271 <td><ul class="first last simple">
 272 <li><tt class="docutils literal"><span class="pre">off</span></tt> - geo ip lookups disabled</li>
 273 <li><tt class="docutils literal"><span class="pre">static</span></tt> - <a class="reference" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup code linked
 274 in statically. Note that this code is under
 275 LGPL license.</li>
 276 <li><tt class="docutils literal"><span class="pre">shared</span></tt> - The <a class="reference" href="http://www.maxmind.com/app/api">MaxMind</a> geo ip lookup library
 277 is expected to be installed on the system and
 278 it will be used.</li>
 279 </ul>
 280 </td>
 281 </tr>
 282 <tr><td><tt class="docutils literal"><span class="pre">upnp-logging</span></tt></td>
 283 <td><ul class="first last simple">
 284 <li><tt class="docutils literal"><span class="pre">off</span></tt> - default. Does not log UPnP traffic.</li>
 285 <li><tt class="docutils literal"><span class="pre">on</span></tt> - creates &quot;upnp.log&quot; with the messages
 286 sent to and received from UPnP devices.</li>
 287 </ul>
 288 </td>
 289 </tr>
 290 <tr><td><tt class="docutils literal"><span class="pre">openssl</span></tt></td>
 291 <td><ul class="first last simple">
 292 <li><tt class="docutils literal"><span class="pre">pe</span></tt> - turns on support for encrypted
 293 connections. requires openssl (libcrypto)</li>
 294 <li><tt class="docutils literal"><span class="pre">sha-1</span></tt> - openssl will be used instead of the
 295 public domain SHA-1 implementation shipped with
 296 libtorrent. <tt class="docutils literal"><span class="pre">libcrypto.a</span></tt> will be required for
 297 linking. Encryption support is still turned off.</li>
 298 <li><tt class="docutils literal"><span class="pre">off</span></tt> - turns off support for encrypted
 299 connections. openssl is not linked in. The
 300 shipped public domain SHA-1 implementation is
 301 used.</li>
 302 </ul>
 303 </td>
 304 </tr>
 305 <tr><td><tt class="docutils literal"><span class="pre">pool-allocators</span></tt></td>
 306 <td><ul class="first last simple">
 307 <li><tt class="docutils literal"><span class="pre">on</span></tt> - default, uses pool allocators for send
 308 buffers.</li>
 309 <li><tt class="docutils literal"><span class="pre">off</span></tt> - uses <tt class="docutils literal"><span class="pre">malloc()</span></tt> and <tt class="docutils literal"><span class="pre">free()</span></tt>
 310 instead. Might be useful to debug buffer issues
 311 with tools like electric fence or libgmalloc.</li>
 312 </ul>
 313 </td>
 314 </tr>
 315 <tr><td><tt class="docutils literal"><span class="pre">link</span></tt></td>
 316 <td><ul class="first last simple">
 317 <li><tt class="docutils literal"><span class="pre">static</span></tt> - builds libtorrent as a static
 318 library (.a / .lib)</li>
 319 <li><tt class="docutils literal"><span class="pre">shared</span></tt> - builds libtorrent as a shared
 320 library (.so / .dll).</li>
 321 </ul>
 322 </td>
 323 </tr>
 324 <tr><td><tt class="docutils literal"><span class="pre">runtime-link</span></tt></td>
 325 <td><ul class="first last simple">
 326 <li><tt class="docutils literal"><span class="pre">static</span></tt> - links statically against the
 327 run-time library (if available on your
 328 platform).</li>
 329 <li><tt class="docutils literal"><span class="pre">shared</span></tt> - link dynamically against the
 330 run-time library (default).</li>
 331 </ul>
 332 </td>
 333 </tr>
 334 <tr><td><tt class="docutils literal"><span class="pre">variant</span></tt></td>
 335 <td><ul class="first last simple">
 336 <li><tt class="docutils literal"><span class="pre">debug</span></tt> - builds libtorrent with debug
 337 information and invariant checks.</li>
 338 <li><tt class="docutils literal"><span class="pre">release</span></tt> - builds libtorrent in release mode
 339 without invariant checks and with optimization.</li>
 340 <li><tt class="docutils literal"><span class="pre">profile</span></tt> - builds libtorrent with profile
 341 information.</li>
 342 </ul>
 343 </td>
 344 </tr>
 345 <tr><td><tt class="docutils literal"><span class="pre">character-set</span></tt></td>
 346 <td><p class="first">This setting will only have an affect on windows.
 347 Other platforms are expected to support UTF-8.</p>
 348 <ul class="last simple">
 349 <li><tt class="docutils literal"><span class="pre">unicode</span></tt> - The unicode version of the win32
 350 API is used. This is default.</li>
 351 <li><tt class="docutils literal"><span class="pre">ansi</span></tt> - The ansi version of the win32 API is
 352 used.</li>
 353 </ul>
 354 </td>
 355 </tr>
 356 <tr><td><tt class="docutils literal"><span class="pre">invariant-checks</span></tt></td>
 357 <td><p class="first">This setting only affects debug builds (where
 358 <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> is not defined). It defaults to <tt class="docutils literal"><span class="pre">on</span></tt>.</p>
 359 <ul class="last simple">
 360 <li><tt class="docutils literal"><span class="pre">on</span></tt> - internal invariant checks are enabled.</li>
 361 <li><tt class="docutils literal"><span class="pre">off</span></tt> - internal invariant checks are
 362 disabled. The resulting executable will run
 363 faster than a regular debug build.</li>
 364 <li><tt class="docutils literal"><span class="pre">full</span></tt> - turns on extra expensive invariant
 365 checks.</li>
 366 </ul>
 367 </td>
 368 </tr>
 369 <tr><td><tt class="docutils literal"><span class="pre">debug-symbols</span></tt></td>
 370 <td><ul class="first last simple">
 371 <li><tt class="docutils literal"><span class="pre">on</span></tt> - default for debug builds. This setting
 372 is useful for building release builds with
 373 symbols.</li>
 374 <li><tt class="docutils literal"><span class="pre">off</span></tt> - default for release builds.</li>
 375 </ul>
 376 </td>
 377 </tr>
 378 <tr><td><tt class="docutils literal"><span class="pre">deprecated-functions</span></tt></td>
 379 <td><ul class="first last simple">
 380 <li><tt class="docutils literal"><span class="pre">on</span></tt> - default. Includes deprecated functions
 381 of the API (might produce warnings during build
 382 when deprecated functions are used).</li>
 383 <li><tt class="docutils literal"><span class="pre">off</span></tt> - excludes deprecated functions from the
 384 API. Generates build errors when deprecated
 385 functions are used.</li>
 386 </ul>
 387 </td>
 388 </tr>
 389 </tbody>
 390 </table>
 391 <p>The <tt class="docutils literal"><span class="pre">variant</span></tt> feature is <em>implicit</em>, which means you don't need to specify
 392 the name of the feature, just the value.</p>
 393 <p>The logs created when building vlog or log mode are put in a directory called
 394 <tt class="docutils literal"><span class="pre">libtorrent_logs</span></tt> in the current working directory.</p>
 395 <p>When building the example client on windows, you need to build with
 396 <tt class="docutils literal"><span class="pre">link=static</span></tt> otherwise you may get unresolved external symbols for some
 397 boost.program-options symbols.</p>
 398 <p>For more information, see the <a class="reference" href="http://www.boost.org/tools/build/v2/index.html">Boost build v2 documentation</a>, or more
 399 specifically <a class="reference" href="http://www.boost.org/doc/html/bbv2/reference.html#bbv2.advanced.builtins.features">the section on builtin features</a>.</p>
 400 </div>
 401 </div>
 402 <div class="section">
 403 <h2><a id="building-with-autotools" name="building-with-autotools">building with autotools</a></h2>
 404 <p>First of all, you need to install <tt class="docutils literal"><span class="pre">automake</span></tt> and <tt class="docutils literal"><span class="pre">autoconf</span></tt>. Many
 405 unix/linux systems comes with these preinstalled.</p>
 406 <p>The prerequisites for building libtorrent are boost.thread, boost.date_time
 407 and boost.filesystem. Those are the <em>compiled</em> boost libraries needed. The
 408 headers-only libraries needed include (but is not necessarily limited to)
 409 boost.bind, boost.ref, boost.multi_index, boost.optional, boost.lexical_cast,
 410 boost.integer, boost.iterator, boost.tuple, boost.array, boost.function,
 411 boost.smart_ptr, boost.preprocessor, boost.static_assert.</p>
 412 <p>If you want to build the <tt class="docutils literal"><span class="pre">client_test</span></tt> example, you'll also need boost.regex
 413 and boost.program_options.</p>
 414 <div class="section">
 415 <h3><a id="step-1-generating-the-build-system" name="step-1-generating-the-build-system">Step 1: Generating the build system</a></h3>
 416 <p>No build system is present if libtorrent is checked out from CVS - it
 417 needs to be generated first. If you're building from a released tarball,
 418 you may skip directly to <a class="reference" href="#step-2-running-configure">Step 2: Running configure</a>.</p>
 419 <p>Execute the following commands, in the given order, to generate
 420 the build system:</p>
 421 <pre class="literal-block">
 422 aclocal -I m4
 423 autoheader
 424 libtoolize --copy --force
 425 automake --add-missing --copy --gnu
 426 autoconf
 427 </pre>
 428 <p>On darwin/OSX you have to run <tt class="docutils literal"><span class="pre">glibtoolize</span></tt> instead of <tt class="docutils literal"><span class="pre">libtoolize</span></tt>.</p>
 429 </div>
 430 <div class="section">
 431 <h3><a id="step-2-running-configure" name="step-2-running-configure">Step 2: Running configure</a></h3>
 432 <p>In your shell, change directory to the libtorrent directory and run
 433 <tt class="docutils literal"><span class="pre">./configure</span></tt>. This will look for libraries and C++ features that libtorrent
 434 is dependent on. If something is missing or can't be found it will print an
 435 error telling you what failed.</p>
 436 <p>The most likely problem you may encounter is that the configure script won't
 437 find the boost libraries. Make sure you have boost installed on your system.
 438 The easiest way to install boost is usually to use the preferred package
 439 system on your platform. Usually libraries and headers are installed in
 440 standard directories where the compiler will find them, but sometimes that
 441 may not be the case. For example when installing boost on darwin using
 442 darwinports (the package system based on BSD ports) all libraries are
 443 installed to <tt class="docutils literal"><span class="pre">/opt/local/lib</span></tt> and headers are installed to
 444 <tt class="docutils literal"><span class="pre">/opt/local/include</span></tt>. By default the compiler will not look in these
 445 directories. You have to set the enviornment variables <tt class="docutils literal"><span class="pre">LDFLAGS</span></tt> and
 446 <tt class="docutils literal"><span class="pre">CXXFLAGS</span></tt> in order to make the compiler find those libs. In this example
 447 you'd set them like this:</p>
 448 <pre class="literal-block">
 449 export LDFLAGS=-L/opt/local/lib
 450 export CXXFLAGS=-I/opt/local/include
 451 </pre>
 452 <p>It was observed on FreeBSD (release 6.0) that one needs to add '-lpthread' to
 453 LDFLAGS, as Boost::Thread detection will fail without it, even if
 454 Boost::Thread is installed.</p>
 455 <p>If you need to set these variables, it may be a good idea to add those lines
 456 to your <tt class="docutils literal"><span class="pre">~/.profile</span></tt> or <tt class="docutils literal"><span class="pre">~/.tcshrc</span></tt> depending on your shell.</p>
 457 <p>If the boost libraries are named with a suffix on your platform, you may use
 458 the <tt class="docutils literal"><span class="pre">--with-boost-thread=</span></tt> option to specify the suffix used for the thread
 459 library in this case. For more information about these options, run:</p>
 460 <pre class="literal-block">
 461 ./configure --help
 462 </pre>
 463 <p>On gentoo the boost libraries that are built with multi-threading support have
 464 the suffix <tt class="docutils literal"><span class="pre">mt</span></tt>.</p>
 465 <p>You know that the boost libraries were found if you see the following output
 466 from the configure script:</p>
 467 <pre class="literal-block">
 468 checking whether the Boost::DateTime library is available... yes
 469 checking for main in -lboost_date_time... yes
 470 checking whether the Boost::Filesystem library is available... yes
 471 checking for main in -lboost_filesystem... yes
 472 checking whether the Boost::Thread library is available... yes
 473 checking for main in -lboost_thread... yes
 474 </pre>
 475 <p>Another possible source of problems may be if the path to your libtorrent
 476 directory contains spaces. Make sure you either rename the directories with
 477 spaces in their names to remove the spaces or move the libtorrent directory.</p>
 478 </div>
 479 <div class="section">
 480 <h3><a id="creating-a-debug-build" name="creating-a-debug-build">Creating a debug build</a></h3>
 481 <p>To tell configure to build a debug version (with debug info, asserts
 482 and invariant checks enabled), you have to run the configure script
 483 with the following option:</p>
 484 <pre class="literal-block">
 485 ./configure --enable-debug=yes
 486 </pre>
 487 </div>
 488 <div class="section">
 489 <h3><a id="creating-a-release-build" name="creating-a-release-build">Creating a release build</a></h3>
 490 <p>To tell the configure to build a release version (without debug info,
 491 asserts and invariant checks), you have to run the configure script
 492 with the following option:</p>
 493 <pre class="literal-block">
 494 ./configure --enable-debug=no
 495 </pre>
 496 <p>The above option make use of -DNDEBUG, which is used throughout libtorrent.</p>
 497 </div>
 498 <div class="section">
 499 <h3><a id="id8" name="id8">Step 3: Building libtorrent</a></h3>
 500 <p>Once the configure script is run successfully, you just type <tt class="docutils literal"><span class="pre">make</span></tt> and
 501 libtorrent, the examples and the tests will be built.</p>
 502 <p>When libtorrent is built it may be a good idea to run the tests, you do this
 503 by running <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt>.</p>
 504 <p>If you want to build a release version (without debug info, asserts and
 505 invariant checks), you have to rerun the configure script and rebuild, like this:</p>
 506 <pre class="literal-block">
 507 ./configure --disable-debug
 508 make clean
 509 make
 510 </pre>
 511 </div>
 512 </div>
 513 <div class="section">
 514 <h2><a id="building-with-other-build-systems" name="building-with-other-build-systems">building with other build systems</a></h2>
 515 <p>If you're making your own project file, note that there are two versions of
 516 the file abstraction. There's one <tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which relies on windows
 517 file API that supports files larger than 2 Gigabytes. This does not work in
 518 vc6 for some reason, possibly because it may require windows NT and above.
 519 The other file, <tt class="docutils literal"><span class="pre">file.cpp</span></tt> is the default implementation that simply relies
 520 on the standard low level io routines (<tt class="docutils literal"><span class="pre">read()</span></tt>, <tt class="docutils literal"><span class="pre">write()</span></tt>, <tt class="docutils literal"><span class="pre">open()</span></tt>
 521 etc.), this implementation doesn't do anything special to support unicode
 522 filenames, so if your target is Windows 2000 and up, you may want to use
 523 <tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which supports unicode filenames.</p>
 524 <p>If you're building in MS Visual Studio, you may have to set the compiler
 525 options &quot;force conformance in for loop scope&quot;, &quot;treat wchar_t as built-in
 526 type&quot; and &quot;Enable Run-Time Type Info&quot; to Yes. For a detailed description
 527 on how to build libtorrent with VS, see <a class="reference" href="http://code.rasterbar.com/libtorrent/wiki/Building">the wiki</a>.</p>
 528 </div>
 529 <div class="section">
 530 <h2><a id="build-configurations" name="build-configurations">build configurations</a></h2>
 531 <p>By default libtorrent is built In debug mode, and will have pretty expensive
 532 invariant checks and asserts built into it. If you want to disable such checks
 533 (you want to do that in a release build) you can see the table below for which
 534 defines you can use to control the build.</p>
 535 <table border="1" class="docutils">
 536 <colgroup>
 537 <col width="45%" />
 538 <col width="55%" />
 539 </colgroup>
 540 <thead valign="bottom">
 541 <tr><th class="head">macro</th>
 542 <th class="head">description</th>
 543 </tr>
 544 </thead>
 545 <tbody valign="top">
 546 <tr><td><tt class="docutils literal"><span class="pre">NDEBUG</span></tt></td>
 547 <td>If you define this macro, all asserts,
 548 invariant checks and general debug code will be
 549 removed. Since there is quite a lot of code in
 550 in header files in libtorrent, it may be
 551 important to define the symbol consistently
 552 across compilation units, including the clients
 553 files. Potential problems is different
 554 compilation units having different views of
 555 structs and class layouts and sizes.</td>
 556 </tr>
 557 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_LOGGING</span></tt></td>
 558 <td>This macro will enable logging of the session
 559 events, such as tracker announces and incoming
 560 connections (as well as blocked connections).</td>
 561 </tr>
 562 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_GEO_IP</span></tt></td>
 563 <td>This is defined by default by the Jamfile. It
 564 disables the GeoIP features, and avoids linking
 565 against LGPL:ed code.</td>
 566 </tr>
 567 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt></td>
 568 <td>If you define this macro, every peer connection
 569 will log its traffic to a log file as well as
 570 the session log.</td>
 571 </tr>
 572 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_STORAGE_DEBUG</span></tt></td>
 573 <td>This will enable extra expensive invariant
 574 checks in the storage, including logging of
 575 piece sorting.</td>
 576 </tr>
 577 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_UPNP_LOGGING</span></tt></td>
 578 <td>Generates a &quot;upnp.log&quot; file with the UPnP
 579 traffic. This is very useful when debugging
 580 support for various UPnP routers.
 581 support for various UPnP routers.</td>
 582 </tr>
 583 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISK_STATS</span></tt></td>
 584 <td>This will create a log of all disk activity
 585 which later can parsed and graphed using
 586 <tt class="docutils literal"><span class="pre">parse_disk_log.py</span></tt>.</td>
 587 </tr>
 588 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_STATS</span></tt></td>
 589 <td>This will generate a log with transfer rates,
 590 downloading torrents, seeding torrents, peers,
 591 connecting peers and disk buffers in use. The
 592 log can be parsed and graphed with
 593 <tt class="docutils literal"><span class="pre">parse_session_stats.py</span></tt>.</td>
 594 </tr>
 595 <tr><td><tt class="docutils literal"><span class="pre">UNICODE</span></tt></td>
 596 <td>If building on windows this will make sure the
 597 UTF-8 strings in pathnames are converted into
 598 UTF-16 before they are passed to the file
 599 operations.</td>
 600 </tr>
 601 <tr><td><tt class="docutils literal"><span class="pre">LITTLE_ENDIAN</span></tt></td>
 602 <td>This will use the little endian version of the
 603 sha-1 code. If defined on a big-endian system
 604 the sha-1 hashes will be incorrect and fail.
 605 If it is not defined and <tt class="docutils literal"><span class="pre">__BIG_ENDIAN__</span></tt>
 606 isn't defined either (it is defined by Apple's
 607 GCC) both little-endian and big-endian versions
 608 will be built and the correct code will be
 609 chosen at run-time.</td>
 610 </tr>
 611 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_POOL_ALLOCATOR</span></tt></td>
 612 <td>Disables use of <tt class="docutils literal"><span class="pre">boost::pool&lt;&gt;</span></tt>.</td>
 613 </tr>
 614 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_LINKING_SHARED</span></tt></td>
 615 <td>If this is defined when including the
 616 libtorrent headers, the classes and functions
 617 will be tagged with <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt>
 618 on msvc and default visibility on GCC 4 and
 619 later. Set this in your project if you're
 620 linking against libtorrent as a shared library.
 621 (This is set by the Jamfile when
 622 <tt class="docutils literal"><span class="pre">link=shared</span></tt> is set).</td>
 623 </tr>
 624 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_BUILDING_SHARED</span></tt></td>
 625 <td>If this is defined, the functions and classes
 626 in libtorrent are marked with
 627 <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> on msvc, or with
 628 default visibility on GCC 4 and later. This
 629 should be defined when building libtorrent as
 630 a shared library. (This is set by the Jamfile
 631 when <tt class="docutils literal"><span class="pre">link=shared</span></tt> is set).</td>
 632 </tr>
 633 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt></td>
 634 <td>If this is defined, the support for trackerless
 635 torrents will be disabled.</td>
 636 </tr>
 637 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DHT_VERBOSE_LOGGING</span></tt></td>
 638 <td>This will enable verbose logging of the DHT
 639 protocol traffic.</td>
 640 </tr>
 641 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_ENCRYPTION</span></tt></td>
 642 <td>This will disable any encryption support and
 643 the openssl dependency that comes with it.
 644 Encryption support is the peer connection
 645 encrypted supported by clients such as
 646 uTorrent, Azureus and KTorrent.</td>
 647 </tr>
 648 <tr><td><tt class="docutils literal"><span class="pre">_UNICODE</span></tt></td>
 649 <td>On windows, this will cause the file IO
 650 use wide character API, to properly support
 651 non-ansi characters.</td>
 652 </tr>
 653 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_RESOLVE_COUNTRIES</span></tt></td>
 654 <td>Defining this will disable the ability to
 655 resolve countries of origin for peer IPs.</td>
 656 </tr>
 657 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_INVARIANT_CHECKS</span></tt></td>
 658 <td>This will disable internal invariant checks in
 659 libtorrent. The invariant checks can sometime
 660 be quite expensive, they typically don't scale
 661 very well. This option can be used to still
 662 build in debug mode, with asserts enabled, but
 663 make the resulting executable faster.</td>
 664 </tr>
 665 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_EXPENSIVE_INVARIANT_CHECKS</span></tt></td>
 666 <td>This will enable extra expensive invariant
 667 checks. Useful for finding particular bugs
 668 or for running before releases.</td>
 669 </tr>
 670 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_NO_DEPRECATE</span></tt></td>
 671 <td>This will exclude all deprecated functions from
 672 the header files and cpp files.</td>
 673 </tr>
 674 </tbody>
 675 </table>
 676 <p>If you experience that libtorrent uses unreasonable amounts of cpu, it will
 677 definitely help to define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt>, since it will remove the invariant checks
 678 within the library.</p>
 679 </div>
 680 <div class="section">
 681 <h2><a id="building-openssl-for-windows" name="building-openssl-for-windows">building openssl for windows</a></h2>
 682 <p>To build openssl for windows with Visual Studio 7.1 (2003) execute the following commands
 683 in a command shell:</p>
 684 <pre class="literal-block">
 685 perl Configure VC-WIN32 --prefix=&quot;c:/openssl
 686 call ms\do_nasm
 687 call &quot;C:\Program Files\Microsoft Visual Studio .NET 2003\vc7\bin\vcvars32.bat&quot;
 688 nmake -f ms\nt.mak
 689 copy inc32\openssl &quot;C:\Program Files\Microsoft Visual Studio .NET 2003\vc7\include\&quot;
 690 copy out32\libeay32.lib &quot;C:\Program Files\Microsoft Visual Studio .NET 2003\vc7\lib&quot;
 691 copy out32\ssleay32.lib &quot;C:\Program Files\Microsoft Visual Studio .NET 2003\vc7\lib&quot;
 692 </pre>
 693 <p>This will also install the headers and library files in the visual studio directories to
 694 be picked up by libtorrent.</p>
 695 </div>
 696 </div>
 697 </div>
 698 </body>
 699 </html>