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.5: 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="id8" name="id8">downloading and building</a><ul>
  26 <li><a class="reference" href="#building-from-svn" id="id9" name="id9">building from svn</a></li>
  27 <li><a class="reference" href="#building-with-bbv2" id="id10" name="id10">building with BBv2</a></li>
  28 <li><a class="reference" href="#building-with-autotools" id="id11" name="id11">building with autotools</a></li>
  29 <li><a class="reference" href="#building-with-other-build-systems" id="id12" name="id12">building with other build systems</a></li>
  30 <li><a class="reference" href="#build-configurations" id="id13" name="id13">build configurations</a></li>
  31 </ul>
  32 </li>
  33 </ul>
  34 </div>
  35 <div class="section">
  36 <h1><a id="downloading-and-building" name="downloading-and-building">downloading and building</a></h1>
  37 <p>To acquire the latest version of libtorrent, you'll have to grab it from SVN.
  38 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>
  39 <p>The build systems supported &quot;out of the box&quot; in libtorrent are boost-build v2
  40 (BBv2) and autotools (for unix-like systems). If you still can't build after
  41 following these instructions, you can usually get help in the <tt class="docutils literal"><span class="pre">#libtorrent</span></tt>
  42 IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
  43 <p>Community contributed build tutorials can be found on the <a class="reference" href="http://code.rasterbar.com/libtorrent/wiki/Building">wiki</a>.</p>
  44 <div class="section">
  45 <h2><a id="building-from-svn" name="building-from-svn">building from svn</a></h2>
  46 <p>To build libtorrent from svn you need to check out the libtorrent sources from
  47 sourceforge and also check out the asio sources from its sourceforge cvs.
  48 If you downloaded a release tarball, you can skip this section.</p>
  49 <p>To prepare the directory structure for building, follow these steps:</p>
  50 <ul class="simple">
  51 <li>Check out libtorrent (<a class="reference" href="http://sourceforge.net/svn/?group_id=79942">instructions</a>).</li>
  52 <li>Check out asio (<a class="reference" href="http://sourceforge.net/cvs/?group_id=122478">instructions</a>).</li>
  53 <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>
  54 directory. Alternatively you can make a symbolic link.</li>
  55 <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>
  56 </ul>
  57 <p>Now the libtorrent directory is ready for building. Follow the steps in one
  58 of the following sections depending on which build system you prefer to use.</p>
  59 </div>
  60 <div class="section">
  61 <h2><a id="building-with-bbv2" name="building-with-bbv2">building with BBv2</a></h2>
  62 <p>The primary reason to use boost-build is that it will automatically build the
  63 dependent boost libraries with the correct compiler settings, in order to
  64 ensure that the build targets are link compatible (see <a class="reference" href="http://boost.org/more/separate_compilation.html">boost guidelines</a>
  65 for some details on this issue).</p>
  66 <p>Since BBv2 will build the boost libraries for you, you need the full boost
  67 source package. Having boost installed via some package system is usually not
  68 enough (and even if it is enough, the necessary environment variables are
  69 usually not set by the package installer).</p>
  70 <div class="section">
  71 <h3><a id="step-1-download-boost" name="step-1-download-boost">Step 1: Download boost</a></h3>
  72 <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=376197">here</a>.</p>
  73 <p>Extract the archive to some directory where you want it. For the sake of this
  74 guide, let's assume you extract the package to <tt class="docutils literal"><span class="pre">c:\boost_1_33_1</span></tt> (I'm using
  75 a windows path in this example since if you're on linux/unix you're more likely
  76 to use the autotools). You'll need at least version 1.33.1 of the boost library
  77 in order to build libtorrent.</p>
  78 </div>
  79 <div class="section">
  80 <h3><a id="step-2-setup-bbv2" name="step-2-setup-bbv2">Step 2: Setup BBv2</a></h3>
  81 <p>First you need to build <tt class="docutils literal"><span class="pre">bjam</span></tt>. You do this by opening a terminal (In
  82 windows, run <tt class="docutils literal"><span class="pre">cmd</span></tt>). Change directory to
  83 <tt class="docutils literal"><span class="pre">c:\boost_1_33_1\tools\build\jam_src</span></tt>. Then run the script called
  84 <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
  85 place it in a directory starting with <tt class="docutils literal"><span class="pre">bin.</span></tt> and then have the name of your
  86 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
  87 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
  88 <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
  89 to the search paths by modifying the environment variable called <tt class="docutils literal"><span class="pre">PATH</span></tt>).</p>
  90 <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
  91 that the boost-build system is implemented on. So boost-build uses <tt class="docutils literal"><span class="pre">bjam</span></tt>.
  92 So, to complete the installation you need to make two more things. You need to
  93 set the environment variable <tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt>. This is the path that tells
  94 <tt class="docutils literal"><span class="pre">bjam</span></tt> where it can find boost-build, your configuration file and all the
  95 toolsets (descriptions used by boost-build to know how to use different
  96 compilers on different platforms). Assuming the boost install path above, set
  97 it to <tt class="docutils literal"><span class="pre">c:\boost_1_33_1\tools\build\v2</span></tt>.</p>
  98 <p>To set an environment variable in windows, type for example:</p>
  99 <pre class="literal-block">
 100 set BOOST_BUILD_PATH=c:\boost_1_33_1\tools\build\v2
 101 </pre>
 102 <p>In a terminal window.</p>
 103 <p>The last thing to do to complete the setup of BBv2 is to modify your
 104 <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_33_1\tools\build\v2</span></tt>.
 105 Depending on your platform and which compiler you're using, you should add a
 106 line for each compiler and compiler version you have installed on your system
 107 that you want to be able to use with BBv2. For example, if you're using
 108 Microsoft Visual Studio 7.1 (2003), just add a line:</p>
 109 <pre class="literal-block">
 110 using msvc : 7.1 ;
 111 </pre>
 112 <p>If you use GCC, add the line:</p>
 113 <pre class="literal-block">
 114 using gcc ;
 115 </pre>
 116 <p>If you have more than one version of GCC installed, you can add the
 117 commandline used to invoke g++ after the version number, like this:</p>
 118 <pre class="literal-block">
 119 using gcc : 3.3 : g++-3.3 ;
 120 using gcc : 4.0 : g++-4.0 ;
 121 </pre>
 122 <p>Another toolset worth mentioning is the <tt class="docutils literal"><span class="pre">darwin</span></tt> toolset (For MacOS X).
 123 From Tiger (10.4) MacOS X comes with both GCC 3.3 and GCC 4.0. Then you can
 124 use the following toolsets:</p>
 125 <pre class="literal-block">
 126 using darwin : 3.3 : g++-3.3 ;
 127 using darwin : 4.0 : g++-4.0 ;
 128 </pre>
 129 <p>Note that the spaces around the semi-colons and colons are important!</p>
 130 <p>Also see the <a class="reference" href="http://www.boost.org/doc/html/bbv2/installation.html">official installation instructions</a>.</p>
 131 </div>
 132 <div class="section">
 133 <h3><a id="step-3-building-libtorrent" name="step-3-building-libtorrent">Step 3: Building libtorrent</a></h3>
 134 <p>When building libtorrent, the <tt class="docutils literal"><span class="pre">Jamfile</span></tt> expects the environment variable
 135 <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> to be set to the boost installation directory. It uses this to
 136 find the boost libraries it depends on, so they can be built and their headers
 137 files found. So, set this to <tt class="docutils literal"><span class="pre">c:\boost_1_33_1</span></tt>.</p>
 138 <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
 139 a specific toolset to use (compiler) you can just add that to the commandline.
 140 For example:</p>
 141 <pre class="literal-block">
 142 bjam msvc-7.1 link=static
 143 bjam gcc-3.3 link=static
 144 bjam darwin-4.0 link=static
 145 </pre>
 146 <p>To build different versions you can also just add the name of the build
 147 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>,
 148 <tt class="docutils literal"><span class="pre">profile</span></tt>.</p>
 149 <p>You can build libtorrent as a dll too, by typing <tt class="docutils literal"><span class="pre">link=shared</span></tt>, or
 150 <tt class="docutils literal"><span class="pre">link=static</span></tt> to build a static library. <tt class="docutils literal"><span class="pre">link=shared</span></tt> is the default.</p>
 151 <p>If you want to explicitly say how to link against the runtime library, you
 152 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>
 153 or <tt class="docutils literal"><span class="pre">static</span></tt>. Most operating systems will only allow linking shared against
 154 the runtime, but on windows you can do both. Example:</p>
 155 <pre class="literal-block">
 156 bjam msvc-7.1 link=static runtime-link=static
 157 </pre>
 158 <div class="warning">
 159 <p class="first admonition-title">Warning</p>
 160 <p class="last">If you link statically to the runtime library, you cannot build libtorrent
 161 as a shared library (DLL), since you will get separate heaps in the library
 162 and in the client application. It will result in crashes and possibly link
 163 errors.</p>
 164 </div>
 165 <p>The build targets are put in a directory called bin, and under it they are
 166 sorted in directories depending on the toolset and build variant used.</p>
 167 <p>To build the examples, just change directory to the examples directory and
 168 invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> from there. To build and run the tests, go to the test
 169 directory and run <tt class="docutils literal"><span class="pre">bjam</span></tt>.</p>
 170 <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
 171 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
 172 cygwin, if you're building with gcc in cygwin you'll have to run it from a cygwin terminal.
 173 Also, make sure the paths are correct in the different environments. In cygwin, the paths
 174 (<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.
 175 <tt class="docutils literal"><span class="pre">/cygdrive/c/boost_1_33_1</span></tt>). In the windows environment, they should have the typical
 176 windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_33_1</span></tt>).</p>
 177 <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.
 178 For more build configuration flags see <a class="reference" href="#build-configurations">Build configurations</a>.</p>
 179 <p>Build features:</p>
 180 <table border="1" class="docutils">
 181 <colgroup>
 182 <col width="32%" />
 183 <col width="68%" />
 184 </colgroup>
 185 <thead valign="bottom">
 186 <tr><th class="head">boost build feature</th>
 187 <th class="head">values</th>
 188 </tr>
 189 </thead>
 190 <tbody valign="top">
 191 <tr><td><tt class="docutils literal"><span class="pre">logging</span></tt></td>
 192 <td><ul class="first last simple">
 193 <li><tt class="docutils literal"><span class="pre">none</span></tt> - no logging.</li>
 194 <li><tt class="docutils literal"><span class="pre">default</span></tt> - basic session logging.</li>
 195 <li><tt class="docutils literal"><span class="pre">verbose</span></tt> - verbose peer wire logging.</li>
 196 </ul>
 197 </td>
 198 </tr>
 199 <tr><td><tt class="docutils literal"><span class="pre">dht-support</span></tt></td>
 200 <td><ul class="first last simple">
 201 <li><tt class="docutils literal"><span class="pre">on</span></tt> - build with support for tracker less
 202 torrents and DHT support.</li>
 203 <li><tt class="docutils literal"><span class="pre">logging</span></tt> - build with DHT support and verbose
 204 logging of the DHT protocol traffic.</li>
 205 <li><tt class="docutils literal"><span class="pre">off</span></tt> - build without DHT support.</li>
 206 </ul>
 207 </td>
 208 </tr>
 209 <tr><td><tt class="docutils literal"><span class="pre">link</span></tt></td>
 210 <td><ul class="first last simple">
 211 <li><tt class="docutils literal"><span class="pre">static</span></tt> - builds libtorrent as a static
 212 library (.a / .lib)</li>
 213 <li><tt class="docutils literal"><span class="pre">shared</span></tt> - builds libtorrent as a shared
 214 library (.so / .dll).</li>
 215 </ul>
 216 </td>
 217 </tr>
 218 <tr><td><tt class="docutils literal"><span class="pre">runtime-link</span></tt></td>
 219 <td><ul class="first last simple">
 220 <li><tt class="docutils literal"><span class="pre">static</span></tt> - links statically against the
 221 run-time library (if available on your
 222 platform).</li>
 223 <li><tt class="docutils literal"><span class="pre">shared</span></tt> - link dynamically against the
 224 run-time library (default).</li>
 225 </ul>
 226 </td>
 227 </tr>
 228 <tr><td><tt class="docutils literal"><span class="pre">variant</span></tt></td>
 229 <td><ul class="first last simple">
 230 <li><tt class="docutils literal"><span class="pre">debug</span></tt> - builds libtorrent with debug
 231 information and invariant checks.</li>
 232 <li><tt class="docutils literal"><span class="pre">release</span></tt> - builds libtorrent in release mode
 233 without invariant checks and with optimization.</li>
 234 <li><tt class="docutils literal"><span class="pre">profile</span></tt> - builds libtorrent with profile
 235 information.</li>
 236 </ul>
 237 </td>
 238 </tr>
 239 <tr><td><tt class="docutils literal"><span class="pre">openssl</span></tt></td>
 240 <td><ul class="first last simple">
 241 <li><tt class="docutils literal"><span class="pre">on</span></tt> - openssl will be used instead of the
 242 public domain SHA-1 implementation shipped with
 243 libtorrent. <tt class="docutils literal"><span class="pre">crypto.lib</span></tt> or <tt class="docutils literal"><span class="pre">libcrypto.a</span></tt>
 244 will be required for linking.</li>
 245 <li><tt class="docutils literal"><span class="pre">off</span></tt> - the shipped SHA-1 implementation will
 246 be used, and there will be no dependency on
 247 openssl.</li>
 248 </ul>
 249 </td>
 250 </tr>
 251 <tr><td><tt class="docutils literal"><span class="pre">character-set</span></tt></td>
 252 <td><p class="first">This setting will only have an affect on windows.
 253 Other platforms are expected to support UTF-8.</p>
 254 <ul class="last simple">
 255 <li><tt class="docutils literal"><span class="pre">ansi</span></tt> - The ansi version of the win32 API is
 256 used.</li>
 257 <li><tt class="docutils literal"><span class="pre">unicode</span></tt> - The unicode version of the win32
 258 API is used.</li>
 259 </ul>
 260 </td>
 261 </tr>
 262 </tbody>
 263 </table>
 264 <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
 265 the name of the feature, just the value.</p>
 266 <p>The logs created when building vlog or log mode are put in a directory called
 267 <tt class="docutils literal"><span class="pre">libtorrent_logs</span></tt> in the current working directory.</p>
 268 <p>When building the example client on windows, you need to build with
 269 <tt class="docutils literal"><span class="pre">link=static</span></tt> otherwise you may get unresolved external symbols for some
 270 boost.program-options symbols.</p>
 271 <p>For more information, see the <a class="reference" href="http://www.boost.org/tools/build/v2/index.html">Boost build v2 documentation</a>.</p>
 272 <p>To build all possible variants of libtorrent (good for testing when making
 273 sure all build variants will actually compile), you can invoke this command:</p>
 274 <pre class="literal-block">
 275 bjam debug release link=shared link=static logging=verbose logging=default \
 276 logging=none dht-support=on dht-support=logging dht-support=off
 277 </pre>
 278 </div>
 279 </div>
 280 <div class="section">
 281 <h2><a id="building-with-autotools" name="building-with-autotools">building with autotools</a></h2>
 282 <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
 283 unix/linux systems comes with these preinstalled.</p>
 284 <p>The prerequisites for building libtorrent is boost.thread, boost.date_time
 285 and boost.filesystem. Those are the <em>compiled</em> boost libraries needed. The
 286 headers-only libraries needed include (but is not necessarily limited to)
 287 boost.bind, boost.ref, boost.multi_index, boost.optional, boost.lexical_cast,
 288 boost.integer, boost.iterator, boost.tuple, boost.array, boost.function,
 289 boost.smart_ptr, boost.preprocessor, boost.static_assert.</p>
 290 <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
 291 and boost.program_options.</p>
 292 <div class="section">
 293 <h3><a id="step-1-generating-the-build-system" name="step-1-generating-the-build-system">Step 1: Generating the build system</a></h3>
 294 <p>No build system is present if libtorrent is checked out from CVS - it
 295 needs to be generated first. If you're building from a released tarball,
 296 you may skip directly to <a class="reference" href="#step-2-running-configure">Step 2: Running configure</a>.</p>
 297 <p>Execute the following commands, in the given order, to generate
 298 the build system:</p>
 299 <pre class="literal-block">
 300 aclocal -I m4
 301 autoheader
 302 libtoolize --copy --force
 303 automake --add-missing --copy --gnu
 304 autoconf
 305 </pre>
 306 <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>
 307 </div>
 308 <div class="section">
 309 <h3><a id="step-2-running-configure" name="step-2-running-configure">Step 2: Running configure</a></h3>
 310 <p>In your shell, change directory to the libtorrent directory and run
 311 <tt class="docutils literal"><span class="pre">./configure</span></tt>. This will look for libraries and C++ features that libtorrent
 312 is dependent on. If something is missing or can't be found it will print an
 313 error telling you what failed.</p>
 314 <p>The most likely problem you may encounter is that the configure script won't
 315 find the boost libraries. Make sure you have boost installed on your system.
 316 The easiest way to install boost is usually to use the preferred package
 317 system on your platform. Usually libraries and headers are installed in
 318 standard directories where the compiler will find them, but sometimes that
 319 may not be the case. For example when installing boost on darwin using
 320 darwinports (the package system based on BSD ports) all libraries are
 321 installed to <tt class="docutils literal"><span class="pre">/opt/local/lib</span></tt> and headers are installed to
 322 <tt class="docutils literal"><span class="pre">/opt/local/include</span></tt>. By default the compiler will not look in these
 323 directories. You have to set the enviornment variables <tt class="docutils literal"><span class="pre">LDFLAGS</span></tt> and
 324 <tt class="docutils literal"><span class="pre">CXXFLAGS</span></tt> in order to make the compiler find those libs. In this example
 325 you'd set them like this:</p>
 326 <pre class="literal-block">
 327 export LDFLAGS=-L/opt/local/lib
 328 export CXXFLAGS=-I/opt/local/include
 329 </pre>
 330 <p>It was observed on FreeBSD (release 6.0) that one needs to add '-lpthread' to
 331 LDFLAGS, as Boost::Thread detection will fail without it, even if
 332 Boost::Thread is installed.</p>
 333 <p>If you need to set these variables, it may be a good idea to add those lines
 334 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>
 335 <p>If the boost libraries are named with a suffix on your platform, you may use
 336 the <tt class="docutils literal"><span class="pre">--with-boost-thread=</span></tt> option to specify the suffix used for the thread
 337 library in this case. For more information about these options, run:</p>
 338 <pre class="literal-block">
 339 ./configure --help
 340 </pre>
 341 <p>On gentoo the boost libraries that are built with multi-threading support have
 342 the suffix <tt class="docutils literal"><span class="pre">mt</span></tt>.</p>
 343 <p>You know that the boost libraries were found if you see the following output
 344 from the configure script:</p>
 345 <pre class="literal-block">
 346 checking whether the Boost::DateTime library is available... yes
 347 checking for main in -lboost_date_time... yes
 348 checking whether the Boost::Filesystem library is available... yes
 349 checking for main in -lboost_filesystem... yes
 350 checking whether the Boost::Thread library is available... yes
 351 checking for main in -lboost_thread... yes
 352 </pre>
 353 <p>Another possible source of problems may be if the path to your libtorrent
 354 directory contains spaces. Make sure you either rename the directories with
 355 spaces in their names to remove the spaces or move the libtorrent directory.</p>
 356 </div>
 357 <div class="section">
 358 <h3><a id="creating-a-debug-build" name="creating-a-debug-build">Creating a debug build</a></h3>
 359 <p>To tell configure to build a debug version (with debug info, asserts
 360 and invariant checks enabled), you have to run the configure script
 361 with the following option:</p>
 362 <pre class="literal-block">
 363 ./configure --enable-debug=yes
 364 </pre>
 365 </div>
 366 <div class="section">
 367 <h3><a id="creating-a-release-build" name="creating-a-release-build">Creating a release build</a></h3>
 368 <p>To tell the configure to build a release version (without debug info,
 369 asserts and invariant checks), you have to run the configure script
 370 with the following option:</p>
 371 <pre class="literal-block">
 372 ./configure --enable-debug=no
 373 </pre>
 374 <p>The above option make use of -DNDEBUG, which is used throughout libtorrent.</p>
 375 </div>
 376 <div class="section">
 377 <h3><a id="id7" name="id7">Step 3: Building libtorrent</a></h3>
 378 <p>Once the configure script is run successfully, you just type <tt class="docutils literal"><span class="pre">make</span></tt> and
 379 libtorrent, the examples and the tests will be built.</p>
 380 <p>When libtorrent is built it may be a good idea to run the tests, you do this
 381 by running <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt>.</p>
 382 <p>If you want to build a release version (without debug info, asserts and
 383 invariant checks), you have to rerun the configure script and rebuild, like this:</p>
 384 <pre class="literal-block">
 385 ./configure --disable-debug
 386 make clean
 387 make
 388 </pre>
 389 </div>
 390 </div>
 391 <div class="section">
 392 <h2><a id="building-with-other-build-systems" name="building-with-other-build-systems">building with other build systems</a></h2>
 393 <p>If you're making your own project file, note that there are two versions of
 394 the file abstraction. There's one <tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which relies on windows
 395 file API that supports files larger than 2 Gigabytes. This does not work in
 396 vc6 for some reason, possibly because it may require windows NT and above.
 397 The other file, <tt class="docutils literal"><span class="pre">file.cpp</span></tt> is the default implementation that simply relies
 398 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>
 399 etc.), this implementation doesn't do anything special to support unicode
 400 filenames, so if your target is Windows 2000 and up, you may want to use
 401 <tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which supports unicode filenames.</p>
 402 <p>If you're building in MS Visual Studio, you may have to set the compiler
 403 options &quot;force conformance in for loop scope&quot;, &quot;treat wchar_t as built-in
 404 type&quot; and &quot;Enable Run-Time Type Info&quot; to Yes. For a detailed description
 405 on how to build libtorrent with VS 2005, see <a class="reference" href="vs2005_build_notes.html">this document</a>.</p>
 406 </div>
 407 <div class="section">
 408 <h2><a id="build-configurations" name="build-configurations">build configurations</a></h2>
 409 <p>By default libtorrent is built In debug mode, and will have pretty expensive
 410 invariant checks and asserts built into it. If you want to disable such checks
 411 (you want to do that in a release build) you can see the table below for which
 412 defines you can use to control the build.</p>
 413 <table border="1" class="docutils">
 414 <colgroup>
 415 <col width="40%" />
 416 <col width="60%" />
 417 </colgroup>
 418 <thead valign="bottom">
 419 <tr><th class="head">macro</th>
 420 <th class="head">description</th>
 421 </tr>
 422 </thead>
 423 <tbody valign="top">
 424 <tr><td><tt class="docutils literal"><span class="pre">NDEBUG</span></tt></td>
 425 <td>If you define this macro, all asserts,
 426 invariant checks and general debug code will be
 427 removed. This option takes precedence over
 428 other debug settings.</td>
 429 </tr>
 430 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_LOGGING</span></tt></td>
 431 <td>This macro will enable logging of the session
 432 events, such as tracker announces and incoming
 433 connections (as well as blocked connections).</td>
 434 </tr>
 435 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt></td>
 436 <td>If you define this macro, every peer connection
 437 will log its traffic to a log file as well as
 438 the session log.</td>
 439 </tr>
 440 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_STORAGE_DEBUG</span></tt></td>
 441 <td>This will enable extra expensive invariant
 442 checks in the storage, including logging of
 443 piece sorting.</td>
 444 </tr>
 445 <tr><td><tt class="docutils literal"><span class="pre">UNICODE</span></tt></td>
 446 <td>If building on windows this will make sure the
 447 UTF-8 strings in pathnames are converted into
 448 UTF-16 before they are passed to the file
 449 operations.</td>
 450 </tr>
 451 <tr><td><tt class="docutils literal"><span class="pre">LITTLE_ENDIAN</span></tt></td>
 452 <td>This will use the little endian version of the
 453 sha-1 code. If defined on a big-endian system
 454 the sha-1 hashes will be incorrect and fail.
 455 If it is not defined and <tt class="docutils literal"><span class="pre">__BIG_ENDIAN__</span></tt>
 456 isn't defined either (it is defined by Apple's
 457 GCC) both little-endian and big-endian versions
 458 will be built and the correct code will be
 459 chosen at run-time.</td>
 460 </tr>
 461 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_LINKING_SHARED</span></tt></td>
 462 <td>If this is defined when including the
 463 libtorrent headers, the classes and functions
 464 will be tagged with <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt>
 465 on msvc and default visibility on GCC 4 and
 466 later. Set this in your project if you're
 467 linking against libtorrent as a shared library.
 468 (This is set by the Jamfile when
 469 <tt class="docutils literal"><span class="pre">link=shared</span></tt> is set).</td>
 470 </tr>
 471 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_BUILDING_SHARED</span></tt></td>
 472 <td>If this is defined, the functions and classes
 473 in libtorrent are marked with
 474 <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> on msvc, or with
 475 default visibility on GCC 4 and later. This
 476 should be defined when building libtorrent as
 477 a shared library. (This is set by the Jamfile
 478 when <tt class="docutils literal"><span class="pre">link=shared</span></tt> is set).</td>
 479 </tr>
 480 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt></td>
 481 <td>If this is defined, the support for trackerless
 482 torrents will be disabled.</td>
 483 </tr>
 484 <tr><td><tt class="docutils literal"><span class="pre">TORRENT_DHT_VERBOSE_LOGGING</span></tt></td>
 485 <td>This will enable verbose logging of the DHT
 486 protocol traffic.</td>
 487 </tr>
 488 </tbody>
 489 </table>
 490 <p>If you experience that libtorrent uses unreasonable amounts of cpu, it will
 491 definitely help to define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt>, since it will remove the invariant checks
 492 within the library.</p>
 493 </div>
 494 </div>
 495 </div>
 496 </body>
 497 </html>