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