wornvirtue
/
premiere-libtorrent
forked from premiere/premiere-libtorrent
1
0
Fork 0
Code Pull Requests Activity

removed olf workarounds for vc6.5 and added documentation for building with autotools

This commit is contained in:
Arvid Norberg 2005-08-15 18:03:57 +00:00
parent 6969db4e7d
commit d19c2c6483
13 changed files with 488 additions and 448 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

430
docs/manual.html
View File

@ -22,10 +22,12 @@
<div class="contents topic" id="contents"> <div class="contents topic" id="contents">
<p class="topic-title first"><a name="contents">Contents</a></p> <p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="simple"> <ul class="simple">
<li><a class="reference" href="#introduction" id="id21" name="id21">introduction</a></li> <li><a class="reference" href="#introduction" id="id19" name="id19">introduction</a></li>
<li><a class="reference" href="#downloading-and-building" id="id22" name="id22">downloading and building</a><ul> <li><a class="reference" href="#downloading-and-building" id="id20" name="id20">downloading and building</a><ul>
<li><a class="reference" href="#cygwin-and-msvc" id="id23" name="id23">cygwin and msvc</a></li> <li><a class="reference" href="#building-with-bbv2" id="id21" name="id21">building with BBv2</a></li>
<li><a class="reference" href="#release-and-debug-builds" id="id24" name="id24">release and debug builds</a></li> <li><a class="reference" href="#building-with-autotools" id="id22" name="id22">building with autotools</a></li>
<li><a class="reference" href="#building-with-other-build-systems" id="id23" name="id23">Building with other build systems</a></li>
<li><a class="reference" href="#build-configurations" id="id24" name="id24">Build configurations</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#using" id="id25" name="id25">using</a></li> <li><a class="reference" href="#using" id="id25" name="id25">using</a></li>
@ -133,28 +135,23 @@
<li><a class="reference" href="#make-torrent" id="id111" name="id111">make_torrent</a></li> <li><a class="reference" href="#make-torrent" id="id111" name="id111">make_torrent</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#detailed-build-instructions" id="id112" name="id112">detailed build instructions</a><ul> <li><a class="reference" href="#fast-resume" id="id112" name="id112">fast resume</a><ul>
<li><a class="reference" href="#building-with-bbv2" id="id113" name="id113">building with BBv2</a></li> <li><a class="reference" href="#file-format" id="id113" name="id113">file format</a></li>
<li><a class="reference" href="#building-with-autotools" id="id114" name="id114">building with autotools</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#fast-resume" id="id115" name="id115">fast resume</a><ul> <li><a class="reference" href="#threads" id="id114" name="id114">threads</a></li>
<li><a class="reference" href="#file-format" id="id116" name="id116">file format</a></li> <li><a class="reference" href="#storage-allocation" id="id115" name="id115">storage allocation</a><ul>
<li><a class="reference" href="#full-allocation" id="id116" name="id116">full allocation</a></li>
<li><a class="reference" href="#compact-allocation" id="id117" name="id117">compact allocation</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#threads" id="id117" name="id117">threads</a></li> <li><a class="reference" href="#extensions" id="id118" name="id118">extensions</a><ul>
<li><a class="reference" href="#storage-allocation" id="id118" name="id118">storage allocation</a><ul> <li><a class="reference" href="#chat-messages" id="id119" name="id119">chat messages</a></li>
<li><a class="reference" href="#full-allocation" id="id119" name="id119">full allocation</a></li> <li><a class="reference" href="#metadata-from-peers" id="id120" name="id120">metadata from peers</a></li>
<li><a class="reference" href="#compact-allocation" id="id120" name="id120">compact allocation</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference" href="#extensions" id="id121" name="id121">extensions</a><ul> <li><a class="reference" href="#filename-checks" id="id121" name="id121">filename checks</a></li>
<li><a class="reference" href="#chat-messages" id="id122" name="id122">chat messages</a></li> <li><a class="reference" href="#acknowledgements" id="id122" name="id122">acknowledgements</a></li>
<li><a class="reference" href="#metadata-from-peers" id="id123" name="id123">metadata from peers</a></li>
</ul>
</li>
<li><a class="reference" href="#filename-checks" id="id124" name="id124">filename checks</a></li>
<li><a class="reference" href="#acknowledgements" id="id125" name="id125">acknowledgements</a></li>
</ul> </ul>
</div> </div>
<div class="section" id="introduction"> <div class="section" id="introduction">
@ -171,35 +168,42 @@ example client.</p>
<li>to be very easy to use</li> <li>to be very easy to use</li>
</ul> </ul>
</blockquote> </blockquote>
<p>libtorrent is not finished. It is an ongoing project (including this documentation). <p>libtorrent is still being developed, however it is stable. It is an ongoing
The current state includes the following features:</p> project (including this documentation). The current state includes the
following features:</p>
<blockquote> <blockquote>
<ul class="simple"> <ul class="simple">
<li>multitracker extension support (as <a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">described by John Hoffman</a>)</li> <li>multitracker extension support (as <a class="reference" href="http://home.elp.rr.com/tur/multitracker-spec.txt">specified by John Hoffman</a>)</li>
<li>serves multiple torrents on a single port and a single thread</li> <li>serves multiple torrents on a single port and a single thread</li>
<li>supports http proxies and proxy authentication</li> <li>supports http proxies and proxy authentication</li>
<li>gzipped tracker-responses</li> <li>gzipped tracker-responses</li>
<li>piece picking on block-level like in <a class="reference" href="http://azureus.sourceforge.net">Azureus</a> (as opposed to piece-level).</li> <li>piece picking on block-level like in <a class="reference" href="http://azureus.sourceforge.net">Azureus</a> (as opposed to piece-level).
This means it can download parts of the same piece from different peers.
It will also prefer to download whole pieces from single peers if the
download speed is high enough from that particular peer.</li>
<li>queues torrents for file check, instead of checking all of them in parallel.</li> <li>queues torrents for file check, instead of checking all of them in parallel.</li>
<li>uses separate threads for checking files and for main downloader, with a fool-proof <li>uses separate threads for checking files and for main downloader, with a
thread-safe library interface. (i.e. There's no way for the user to cause a deadlock).</li> fool-proof thread-safe library interface. (i.e. There's no way for the
<li>can limit the upload and download bandwidth usage and the maximum number of unchoked peers</li> user to cause a deadlock). (see <a class="reference" href="#threads">threads</a>)</li>
<li>piece-wise, unordered, file allocation</li> <li>can limit the upload and download bandwidth usage and the maximum number of
unchoked peers</li>
<li>piece-wise, unordered, incremental file allocation</li>
<li>implements fair trade. User settable trade-ratio, must at least be 1:1, <li>implements fair trade. User settable trade-ratio, must at least be 1:1,
but one can choose to trade 1 for 2 or any other ratio that isn't unfair to the other but one can choose to trade 1 for 2 or any other ratio that isn't unfair
party. (i.e. real tit for tat)</li> to the other party.</li>
<li>fast resume support, a way to get rid of the costly piece check at the start <li>fast resume support, a way to get rid of the costly piece check at the
of a resumed torrent. Saves the storage state, piece_picker state as well as all local start of a resumed torrent. Saves the storage state, piece_picker state
peers in a separate fast-resume file.</li> as well as all local peers in a separate fast-resume file.</li>
<li>supports the extension protocol <a class="reference" href="http://nolar.com/azureus/extended.htm">described by Nolar</a>. See <a class="reference" href="#extensions">extensions</a>.</li> <li>supports the extension protocol <a class="reference" href="http://nolar.com/azureus/extended.htm">specified by Nolar</a>. See <a class="reference" href="#extensions">extensions</a>.</li>
<li>supports files &gt; 2 gigabytes.</li> <li>supports files &gt; 2 gigabytes.</li>
<li>supports the <tt class="docutils literal"><span class="pre">no_peer_id=1</span></tt> extension that will ease the load off trackers.</li> <li>supports the <tt class="docutils literal"><span class="pre">no_peer_id=1</span></tt> extension that will ease the load off trackers.</li>
<li>supports the <a class="reference" href="udp_tracker_protocol.html">udp-tracker protocol</a> by Olaf van der Spek.</li> <li>supports the <a class="reference" href="udp_tracker_protocol.html">udp-tracker protocol</a> by Olaf van der Spek.</li>
<li>possibility to limit the number of connections.</li> <li>possibility to limit the number of connections.</li>
<li>delays have messages if there's no other outgoing traffic to the peer, and doesn't <li>delays have messages if there's no other outgoing traffic to the peer, and
send have messages to peers that already has the piece. This saves bandwidth.</li> doesn't send have messages to peers that already has the piece. This saves
<li>does not have any requirements on the piece order in a torrent that it resumes. This bandwidth.</li>
means it can resume a torrent downloaded by any client.</li> <li>does not have any requirements on the piece order in a torrent that it
resumes. This means it can resume a torrent downloaded by any client.</li>
<li>adjusts the length of the request queue depending on download rate.</li> <li>adjusts the length of the request queue depending on download rate.</li>
<li>supports the <tt class="docutils literal"><span class="pre">compact=1</span></tt> tracker parameter.</li> <li>supports the <tt class="docutils literal"><span class="pre">compact=1</span></tt> tracker parameter.</li>
<li>selective downloading. The ability to select which parts of a torrent you <li>selective downloading. The ability to select which parts of a torrent you
@ -207,14 +211,14 @@ want to download.</li>
<li>ip filter</li> <li>ip filter</li>
</ul> </ul>
</blockquote> </blockquote>
<p>libtorrent is portable at least among Windows, MacOSX and other UNIX-systems. It uses Boost.Thread, <p>libtorrent is portable at least among Windows, MacOS X and other UNIX-systems. It uses Boost.Thread,
Boost.Filesystem, Boost.Date_time and various other boost libraries as well as zlib.</p> Boost.Filesystem, Boost.Date_time and various other boost libraries as well as zlib.</p>
<p>libtorrent has been successfully compiled and tested on:</p> <p>libtorrent has been successfully compiled and tested on:</p>
<blockquote> <blockquote>
<ul class="simple"> <ul class="simple">
<li>Windows 2000 vc7.1</li> <li>Windows 2000 vc7.1</li>
<li>Linux x86 GCC 3.0.4, GCC 3.2.3, GCC 3.4.2</li> <li>Linux x86 GCC 3.0.4, GCC 3.2.3, GCC 3.4.2</li>
<li>MacOS X, (Apple's) GCC 3.3, (Apple's) GCC 4.0</li> <li>MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0</li>
<li>SunOS 5.8 GCC 3.1</li> <li>SunOS 5.8 GCC 3.1</li>
<li>Cygwin GCC 3.3.3</li> <li>Cygwin GCC 3.3.3</li>
</ul> </ul>
@ -230,53 +234,202 @@ Boost.Filesystem, Boost.Date_time and various other boost libraries as well as z
</div> </div>
<div class="section" id="downloading-and-building"> <div class="section" id="downloading-and-building">
<h1><a name="downloading-and-building">downloading and building</a></h1> <h1><a name="downloading-and-building">downloading and building</a></h1>
<p>To acquire the latest version of libtorrent, you'll have to grab it from CVS. You'll find instructions <p>To acquire the latest version of libtorrent, you'll have to grab it from CVS.
on how to do this <a class="reference" href="http://sourceforge.net/cvs/?group_id=79942">here</a> (see Anonymous CVS access).</p> You'll find instructions on how to do this <a class="reference" href="http://sourceforge.net/cvs/?group_id=79942">here</a> (see Anonymous CVS access).</p>
<p>The easiest way to build libtorrent is probably to use <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=80982&amp;release_id=278763">boost-build</a>. Make sure you install it <p>The build systems supported &quot;out of the box&quot; in libtorrent are boost-build v2
correctly by setting the environment variable <tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt> to point to your boost build (BBv2) and autotools (for unix-like systems). If you still can't build after
installation. Also you have to modify the <tt class="docutils literal"><span class="pre">user_config.jam</span></tt> to reflect the toolsets you have installed. following these instructions, you can usually get help in the <tt class="docutils literal"><span class="pre">#libtorrent</span></tt>
(if you're building with gcc, uncomment the line &quot;using gcc ;&quot;)</p> IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
<p>You also need to install <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586&amp;package_id=8041&amp;release_id=284047">boost</a> (at least version 1.32.0).</p> <div class="section" id="building-with-bbv2">
<p>Before you invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> you have to set the environment variable <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></tt> to the <h2><a name="building-with-bbv2">building with BBv2</a></h2>
path where you installed boost. This will be used to build and link against the required <p>The primary reason to use boost-build is that it will automatically build the
boost libraries as well as be used as include path for boost headers.</p> dependent boost libraries with the correct compiler settings, in order to
<p>To build you just have to run:</p> ensure that the build targets are link compatible (see <a class="reference" 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>
<div class="section" id="step-1-download-boost">
<h3><a name="step-1-download-boost">Step 1: Download boost</a></h3>
<p>You'll find boost <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586">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_33_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.32 of the boost library
in order to build libtorrent.</p>
<p>If you use 1.32, you need to download BBv2 separately, so for now, let's
assume you will use version 1.33.</p>
</div>
<div class="section" id="step-2-setup-bbv2">
<h3><a name="step-2-setup-bbv2">Step 2: Setup BBv2</a></h3>
<p>First you need to build <tt class="docutils literal"><span class="pre">bjam</span></tt>. You do this by opening a terminal (In
windows, run <tt class="docutils literal"><span class="pre">cmd</span></tt>). Change directory to
<tt class="docutils literal"><span class="pre">c:\boost_1_33_0\tools\build\jam_src</span></tt>. Then run the script called
<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
place it in a directory starting with <tt class="docutils literal"><span class="pre">bin.</span></tt> and then have the name of your
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
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
<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
to the search paths by modifying the environment variable called <tt class="docutils literal"><span class="pre">PATH</span></tt>).</p>
<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
that the boost-build system is implemented on. So boost-build uses <tt class="docutils literal"><span class="pre">bjam</span></tt>.
So, to complete the installation you need to make two more things. You need to
set the environment variable <tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt>. This is the path that tells
<tt class="docutils literal"><span class="pre">bjam</span></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_33_0\tools\build\v2</span></tt>.</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_33\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 7.1 (2003), just add a line:</p>
<pre class="literal-block"> <pre class="literal-block">
bjam &lt;toolset&gt; link=static using msvc : 7.1 ;
</pre> </pre>
<p>in the libtorrent directory.</p> <p>If you use GCC, add the line:</p>
<p>If you're building on a platform where dlls share the same heap, you can build libtorrent <pre class="literal-block">
as a dll too, by typing <tt class="docutils literal"><span class="pre">link=shared</span></tt> instead of <tt class="docutils literal"><span class="pre">link=static</span></tt>.</p> using gcc ;
<p>To build on MacOS X, you need the latest version of boost-build, from the <a class="reference" href="http://sourceforge.net/cvs/?group_id=7586">boost cvs</a>.</p> </pre>
<p>If you're making your own project file, note that there are two versions of the file <p>If you have more than one version of GCC installed, you can add the
abstraction. There's one <tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which relies on windows file API that supports commandline used to invoke g++ after the version number, like this:</p>
files larger than 2 Gigabytes. This does not work in vc6 for some reason, possibly because <pre class="literal-block">
it may require windows NT and above. The other file, <tt class="docutils literal"><span class="pre">file.cpp</span></tt> is the default using gcc : 3.3 : g++-3.3 ;
implementation that simply relies on the standard low level io routines (read, write etc.), using gcc : 4.0 : g++-4.0 ;
this is the preferred implementation that should be used in all cases.</p> </pre>
<p>If you're having problems building, see <a class="reference" href="#detailed-build-instructions">detailed build instructions</a>.</p> <p>Another toolset worth mentioning is the <tt class="docutils literal"><span class="pre">darwin</span></tt> toolset (For MacOS X).
<div class="section" id="cygwin-and-msvc"> From Tiger (10.4) MacOS X comes with both GCC 3.3 and GCC 4.0. Then you can
<h2><a name="cygwin-and-msvc">cygwin and msvc</a></h2> 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>
</div>
<div class="section" id="step-3-building-libtorrent">
<h3><a name="step-3-building-libtorrent">Step 3: Building libtorrent</a></h3>
<p>When building libtorrent, the <tt class="docutils literal"><span class="pre">Jamfile</span></tt> expects the environment variable
<tt class="docutils literal"><span class="pre">BOOST_ROOT</span></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_33_0</span></tt>.</p>
<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
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
</pre>
<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"><span class="pre">release</span></tt>, <tt class="docutils literal"><span class="pre">debug</span></tt>,
<tt class="docutils literal"><span class="pre">profile</span></tt>.</p>
<p>If you're building on a platform where dlls share the same heap, you can build
libtorrent as a dll too, by typing <tt class="docutils literal"><span class="pre">link=shared</span></tt>, or <tt class="docutils literal"><span class="pre">link=static</span></tt> to
explicitly build a static library.</p>
<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>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 <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
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 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
cygwin, if you're building with gcc (mingw) you'll have to run it from a cygwin terminal. 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 Also, make sure the paths are correct in the different environments. In cygwin, the paths
(<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. (<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.
<tt class="docutils literal"><span class="pre">/cygdrive/c/boost_1_32_0</span></tt>). In the windows environment, they should have the typical <tt class="docutils literal"><span class="pre">/cygdrive/c/boost_1_33_0</span></tt>). In the windows environment, they should have the typical
windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_32_0</span></tt>).</p> windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_33_0</span></tt>).</p>
<p>If you're building in developer studio, you may have to set the compiler options <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.
&quot;force conformance in for loop scope&quot;, &quot;treat wchar_t as built-in type&quot; and There are two other build variants available in the <tt class="docutils literal"><span class="pre">Jamfile</span></tt>. debug_log
&quot;Enable Run-Time Type Info&quot; to Yes.</p> and release_log, these two variants inherits from the debug and release
variants respectively, but adds extra logging (<tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGIN</span></tt>).
For more build configuration flags see <a class="reference" href="#build-configurations">Build configurations</a>.</p>
<p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> has the following build variants:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">release</span></tt> - release version without any logging</li>
<li><tt class="docutils literal"><span class="pre">release_log</span></tt> - release version with standard logging</li>
<li><tt class="docutils literal"><span class="pre">release_vlog</span></tt> - release version with verbose logging (all peer connections are logged)</li>
<li><tt class="docutils literal"><span class="pre">debug</span></tt> - debug version without any logging</li>
<li><tt class="docutils literal"><span class="pre">debug_log</span></tt> - debug version with standard logging</li>
<li><tt class="docutils literal"><span class="pre">debug_vlog</span></tt> - debug version with verbose logging</li>
</ul>
</blockquote>
</div> </div>
<div class="section" id="release-and-debug-builds"> </div>
<h2><a name="release-and-debug-builds">release and debug builds</a></h2> <div class="section" id="building-with-autotools">
<p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> can build both a release and debug version of libtorrent. In debug mode, <h2><a name="building-with-autotools">building with autotools</a></h2>
libtorrent will have pretty expensive invariant checks and asserts built into it. If you <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
want to disable such checks (you want to do that in a release build) you can see the unix/linux systems comes with these preinstalled.</p>
table below for which defines you can use to control the build. The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> will define <div class="section" id="step-1-running-configure">
<tt class="docutils literal"><span class="pre">NDEBUG</span></tt> when it's building a release build. There are two other build variants available <h3><a name="step-1-running-configure">Step 1: Running configure</a></h3>
in the <tt class="docutils literal"><span class="pre">Jamfile</span></tt>. debug_log and release_log, these two variants inherits from the <p>In your shell, change directory to the libtorrent directory and run
debug and release variants respectively, but adds extra logging (<tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGIN</span></tt>).</p> <tt class="docutils literal"><span class="pre">./configure</span></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 in some cases 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"><span class="pre">/opt/local/lib</span></tt> and headers are installed to
<tt class="docutils literal"><span class="pre">/opt/local/include</span></tt>. By default the compiler will not look in these
directories. You have to set the enviornment variables <tt class="docutils literal"><span class="pre">LDFLAGS</span></tt> and
<tt class="docutils literal"><span class="pre">CXXFLAGS</span></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>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>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="step-2-building-libtorrent">
<h3><a name="step-2-building-libtorrent">Step 2: Building libtorrent</a></h3>
<p>Once the configure script is run successfully, you just type <tt class="docutils literal"><span class="pre">make</span></tt> and
libtorrent, the examples and the tests will be built.</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><a name="building-with-other-build-systems">Building with other build systems</a></h2>
<p>If you're making your own project file, note that there are two versions of
the file abstraction. There's one <tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which relies on windows
file API that supports files larger than 2 Gigabytes. This does not work in
vc6 for some reason, possibly because it may require windows NT and above.
The other file, <tt class="docutils literal"><span class="pre">file.cpp</span></tt> is the default implementation that simply relies
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>
etc.), this implementation doesn't do anything special to support unicode
filenames, so if your target is Windows 2000 and up, you may want to use
<tt class="docutils literal"><span class="pre">file_win.cpp</span></tt> which supports unicode filenames.</p>
<p>If you're building in MS Visual Studio, you may have to set the compiler
options &quot;force conformance in for loop scope&quot;, &quot;treat wchar_t as built-in
type&quot; and &quot;Enable Run-Time Type Info&quot; to Yes.</p>
</div>
<div class="section" id="build-configurations">
<h2><a name="build-configurations">Build configurations</a></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"> <table border="1" class="docutils">
<colgroup> <colgroup>
<col width="40%" /> <col width="40%" />
@ -313,17 +466,6 @@ piece sorting.</td>
</table> </table>
<p>If you experience that libtorrent uses unreasonable amounts of cpu, it will definately help to <p>If you experience that libtorrent uses unreasonable amounts of cpu, it will definately help to
define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt>, since it will remove the invariant checks within the library.</p> define <tt class="docutils literal"><span class="pre">NDEBUG</span></tt>, since it will remove the invariant checks within the library.</p>
<p>The <tt class="docutils literal"><span class="pre">Jamfile</span></tt> has the following build variants:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">release</span></tt> - release version without any logging</li>
<li><tt class="docutils literal"><span class="pre">release_log</span></tt> - release version with standard logging</li>
<li><tt class="docutils literal"><span class="pre">release_vlog</span></tt> - release version with verbose logging (all peer connections are logged)</li>
<li><tt class="docutils literal"><span class="pre">debug</span></tt> - debug version without any logging</li>
<li><tt class="docutils literal"><span class="pre">debug_log</span></tt> - debug version with standard logging</li>
<li><tt class="docutils literal"><span class="pre">debug_vlog</span></tt> - debug version with verbose logging</li>
</ul>
</blockquote>
</div> </div>
</div> </div>
<div class="section" id="using"> <div class="section" id="using">
@ -2521,104 +2663,20 @@ int main(int argc, char* argv[])
</pre> </pre>
</div> </div>
</div> </div>
<div class="section" id="detailed-build-instructions">
<h1><a name="detailed-build-instructions">detailed build instructions</a></h1>
<p>The build systems supported &quot;out of the box&quot; in libtorrent are boost-build v2 (BBv2) and
autotools (for unix-like systems).</p>
<div class="section" id="building-with-bbv2">
<h2><a name="building-with-bbv2">building with BBv2</a></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" 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>
<div class="section" id="step-1-download-boost">
<h3><a name="step-1-download-boost">Step 1: Download boost</a></h3>
<p>You'll find boost <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=7586">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_33_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.32 of the boost library in order to build libtorrent.</p>
<p>If you use 1.32, you need to download BBv2 separately, so for now, let's assume you will
use version 1.33.</p>
</div>
<div class="section" id="step-2-setup-bbv2">
<h3><a name="step-2-setup-bbv2">Step 2: Setup BBv2</a></h3>
<p>First you need to build <tt class="docutils literal"><span class="pre">bjam</span></tt>. You do this by opening a terminal (In windows, run <tt class="docutils literal"><span class="pre">cmd</span></tt>).
Change directory to <tt class="docutils literal"><span class="pre">c:\boost_1_33_0\tools\build\jam_src</span></tt>. Then run the script called
<tt class="docutils literal"><span class="pre">build.bat</span></tt> or «build.sh« on a unix system. This will build <tt class="docutils literal"><span class="pre">bjam</span></tt> and place it in a directory
starting with <tt class="docutils literal"><span class="pre">bin.</span></tt> and then have the name of your 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 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 <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 paths by modifying the
environment variable called <tt class="docutils literal"><span class="pre">PATH</span></tt>).</p>
<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 that the boost-build
system is implemented on. So boost-build uses <tt class="docutils literal"><span class="pre">bjam</span></tt>. So, to complete the installation you need
to make two more things. You need to set the environment variable <tt class="docutils literal"><span class="pre">BOOST_BUILD_PATH</span></tt>. This is
the path that tells <tt class="docutils literal"><span class="pre">bjam</span></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_33_0\tools\build\v2</span></tt>.</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_33\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 7.1 (2003), just add a line:</p>
<pre class="literal-block">
using msvc : 7.1 ;
</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"><span class="pre">darwin</span></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 between the semi-colons and colons are important!</p>
</div>
<div class="section" id="step-3-building-libtorrent">
<h3><a name="step-3-building-libtorrent">Step 3: Building libtorrent</a></h3>
<p>When building libtorrent, the <tt class="docutils literal"><span class="pre">Jamfile</span></tt> expects the environment variable <tt class="docutils literal"><span class="pre">BOOST_ROOT</span></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_33_0</span></tt>.</p>
<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 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
</pre>
<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"><span class="pre">release</span></tt>, <tt class="docutils literal"><span class="pre">debug</span></tt>, <tt class="docutils literal"><span class="pre">profile</span></tt>.</p>
<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>
</div>
</div>
<div class="section" id="building-with-autotools">
<h2><a name="building-with-autotools">building with autotools</a></h2>
<p><em>TODO</em></p>
</div>
</div>
<div class="section" id="fast-resume"> <div class="section" id="fast-resume">
<h1><a name="fast-resume">fast resume</a></h1> <h1><a name="fast-resume">fast resume</a></h1>
<p>The fast resume mechanism is a way to remember which pieces are downloaded and where they <p>The fast resume mechanism is a way to remember which pieces are downloaded
are put between sessions. You can generate fast resume data by calling and where they are put between sessions. You can generate fast resume data by
<tt class="docutils literal"><span class="pre">torrent_handle::write_resume_data()</span></tt> on <a class="reference" href="#torrent-handle">torrent_handle</a>. You can then save this data calling <tt class="docutils literal"><span class="pre">torrent_handle::write_resume_data()</span></tt> on <a class="reference" href="#torrent-handle">torrent_handle</a>. You can
to disk and use it when resuming the torrent. libtorrent will not check the piece hashes then save this data to disk and use it when resuming the torrent. libtorrent
then, and rely on the information given in the fast-resume data. The fast-resume data will not check the piece hashes then, and rely on the information given in the
also contains information about which blocks, in the unfinished pieces, were downloaded, fast-resume data. The fast-resume data also contains information about which
so it will not have to start from scratch on the partially downloaded pieces.</p> blocks, in the unfinished pieces, were downloaded, so it will not have to
start from scratch on the partially downloaded pieces.</p>
<p>To use the fast-resume data you simply give it to <a class="reference" href="#add-torrent">add_torrent()</a>, and it <p>To use the fast-resume data you simply give it to <a class="reference" href="#add-torrent">add_torrent()</a>, and it
will skip the time consuming checks. It may have to do the checking anyway, if the will skip the time consuming checks. It may have to do the checking anyway, if
fast-resume data is corrupt or doesn't fit the storage for that torrent, then it will the fast-resume data is corrupt or doesn't fit the storage for that torrent,
not trust the fast-resume data and just do the checking.</p> then it will not trust the fast-resume data and just do the checking.</p>
<div class="section" id="file-format"> <div class="section" id="file-format">
<h2><a name="file-format">file format</a></h2> <h2><a name="file-format">file format</a></h2>
<p>The file format is a bencoded dictionary containing the following fields:</p> <p>The file format is a bencoded dictionary containing the following fields:</p>

430
docs/manual.rst
View File

@ -21,34 +21,41 @@ The main goals of libtorrent are:
* to be memory efficient * to be memory efficient
* to be very easy to use * to be very easy to use
libtorrent is not finished. It is an ongoing project (including this documentation). libtorrent is still being developed, however it is stable. It is an ongoing
The current state includes the following features: project (including this documentation). The current state includes the
following features:
* multitracker extension support (as `described by John Hoffman`__) * multitracker extension support (as `specified by John Hoffman`__)
* serves multiple torrents on a single port and a single thread * serves multiple torrents on a single port and a single thread
* supports http proxies and proxy authentication * supports http proxies and proxy authentication
* gzipped tracker-responses * gzipped tracker-responses
* piece picking on block-level like in Azureus_ (as opposed to piece-level). * piece picking on block-level like in Azureus_ (as opposed to piece-level).
This means it can download parts of the same piece from different peers.
It will also prefer to download whole pieces from single peers if the
download speed is high enough from that particular peer.
* queues torrents for file check, instead of checking all of them in parallel. * queues torrents for file check, instead of checking all of them in parallel.
* uses separate threads for checking files and for main downloader, with a fool-proof * uses separate threads for checking files and for main downloader, with a
thread-safe library interface. (i.e. There's no way for the user to cause a deadlock). fool-proof thread-safe library interface. (i.e. There's no way for the
* can limit the upload and download bandwidth usage and the maximum number of unchoked peers user to cause a deadlock). (see threads_)
* piece-wise, unordered, file allocation * can limit the upload and download bandwidth usage and the maximum number of
unchoked peers
* piece-wise, unordered, incremental file allocation
* implements fair trade. User settable trade-ratio, must at least be 1:1, * implements fair trade. User settable trade-ratio, must at least be 1:1,
but one can choose to trade 1 for 2 or any other ratio that isn't unfair to the other but one can choose to trade 1 for 2 or any other ratio that isn't unfair
party. (i.e. real tit for tat) to the other party.
* fast resume support, a way to get rid of the costly piece check at the start * fast resume support, a way to get rid of the costly piece check at the
of a resumed torrent. Saves the storage state, piece_picker state as well as all local start of a resumed torrent. Saves the storage state, piece_picker state
peers in a separate fast-resume file. as well as all local peers in a separate fast-resume file.
* supports the extension protocol `described by Nolar`__. See extensions_. * supports the extension protocol `specified by Nolar`__. See extensions_.
* supports files > 2 gigabytes. * supports files > 2 gigabytes.
* supports the ``no_peer_id=1`` extension that will ease the load off trackers. * supports the ``no_peer_id=1`` extension that will ease the load off trackers.
* supports the `udp-tracker protocol`__ by Olaf van der Spek. * supports the `udp-tracker protocol`__ by Olaf van der Spek.
* possibility to limit the number of connections. * possibility to limit the number of connections.
* delays have messages if there's no other outgoing traffic to the peer, and doesn't * delays have messages if there's no other outgoing traffic to the peer, and
send have messages to peers that already has the piece. This saves bandwidth. doesn't send have messages to peers that already has the piece. This saves
* does not have any requirements on the piece order in a torrent that it resumes. This bandwidth.
means it can resume a torrent downloaded by any client. * does not have any requirements on the piece order in a torrent that it
resumes. This means it can resume a torrent downloaded by any client.
* adjusts the length of the request queue depending on download rate. * adjusts the length of the request queue depending on download rate.
* supports the ``compact=1`` tracker parameter. * supports the ``compact=1`` tracker parameter.
* selective downloading. The ability to select which parts of a torrent you * selective downloading. The ability to select which parts of a torrent you
@ -61,14 +68,14 @@ __ http://nolar.com/azureus/extended.htm
__ udp_tracker_protocol.html __ udp_tracker_protocol.html
libtorrent is portable at least among Windows, MacOSX and other UNIX-systems. It uses Boost.Thread, libtorrent is portable at least among Windows, MacOS X and other UNIX-systems. It uses Boost.Thread,
Boost.Filesystem, Boost.Date_time and various other boost libraries as well as zlib. Boost.Filesystem, Boost.Date_time and various other boost libraries as well as zlib.
libtorrent has been successfully compiled and tested on: libtorrent has been successfully compiled and tested on:
* Windows 2000 vc7.1 * Windows 2000 vc7.1
* Linux x86 GCC 3.0.4, GCC 3.2.3, GCC 3.4.2 * Linux x86 GCC 3.0.4, GCC 3.2.3, GCC 3.4.2
* MacOS X, (Apple's) GCC 3.3, (Apple's) GCC 4.0 * MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0
* SunOS 5.8 GCC 3.1 * SunOS 5.8 GCC 3.1
* Cygwin GCC 3.3.3 * Cygwin GCC 3.3.3
@ -85,74 +92,238 @@ libtorrent is released under the BSD-license_.
downloading and building downloading and building
======================== ========================
To acquire the latest version of libtorrent, you'll have to grab it from CVS. You'll find instructions To acquire the latest version of libtorrent, you'll have to grab it from CVS.
on how to do this here__ (see Anonymous CVS access). You'll find instructions on how to do this here__ (see Anonymous CVS access).
__ http://sourceforge.net/cvs/?group_id=79942 __ http://sourceforge.net/cvs/?group_id=79942
The easiest way to build libtorrent is probably to use `boost-build`_. Make sure you install it The build systems supported "out of the box" in libtorrent are boost-build v2
correctly by setting the environment variable ``BOOST_BUILD_PATH`` to point to your boost build (BBv2) and autotools (for unix-like systems). If you still can't build after
installation. Also you have to modify the ``user_config.jam`` to reflect the toolsets you have installed. following these instructions, you can usually get help in the ``#libtorrent``
(if you're building with gcc, uncomment the line "using gcc ;") IRC channel on ``irc.freenode.net``.
.. _`boost-build`: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=80982&release_id=278763
You also need to install boost__ (at least version 1.32.0). building with BBv2
------------------
__ http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=284047 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 `boost guidelines`__
for some details on this issue).
Before you invoke ``bjam`` you have to set the environment variable ``BOOST_ROOT`` to the __ http://boost.org/more/separate_compilation.html
path where you installed boost. This will be used to build and link against the required
boost libraries as well as be used as include path for boost headers.
To build you just have to run:: 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).
bjam <toolset> link=static
in the libtorrent directory. Step 1: Download boost
~~~~~~~~~~~~~~~~~~~~~~
If you're building on a platform where dlls share the same heap, you can build libtorrent You'll find boost here__.
as a dll too, by typing ``link=shared`` instead of ``link=static``.
To build on MacOS X, you need the latest version of boost-build, from the `boost cvs`__. __ http://sourceforge.net/project/showfiles.php?group_id=7586
__ http://sourceforge.net/cvs/?group_id=7586 Extract the archive to some directory where you want it. For the sake of this
guide, let's assume you extract the package to ``c:\boost_1_33_0`` (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.32 of the boost library
in order to build libtorrent.
If you're making your own project file, note that there are two versions of the file If you use 1.32, you need to download BBv2 separately, so for now, let's
abstraction. There's one ``file_win.cpp`` which relies on windows file API that supports assume you will use version 1.33.
files larger than 2 Gigabytes. This does not work in vc6 for some reason, possibly because
it may require windows NT and above. The other file, ``file.cpp`` is the default
implementation that simply relies on the standard low level io routines (read, write etc.),
this is the preferred implementation that should be used in all cases.
If you're having problems building, see `detailed build instructions`_.
cygwin and msvc Step 2: Setup BBv2
--------------- ~~~~~~~~~~~~~~~~~~
First you need to build ``bjam``. You do this by opening a terminal (In
windows, run ``cmd``). Change directory to
``c:\boost_1_33_0\tools\build\jam_src``. Then run the script called
``build.bat`` or ``build.sh`` on a unix system. This will build ``bjam`` and
place it in a directory starting with ``bin.`` and then have the name of your
platform. Copy the ``bjam.exe`` (or ``bjam`` on a unix system) to a place
that's in you shell's ``PATH``. On linux systems a place commonly used may be
``/usr/local/bin`` or on windows ``c:\windows`` (you can also add directories
to the search paths by modifying the environment variable called ``PATH``).
Now you have ``bjam`` installed. ``bjam`` can be considered an interpreter
that the boost-build system is implemented on. So boost-build uses ``bjam``.
So, to complete the installation you need to make two more things. You need to
set the environment variable ``BOOST_BUILD_PATH``. This is the path that tells
``bjam`` 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 ``c:\boost_1_33_0\tools\build\v2``.
The last thing to do to complete the setup of BBv2 is to modify your
``user-config.jam`` file. It is located in ``c:\boost_1_33\tools\build\v2``.
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 7.1 (2003), just add a line::
using msvc : 7.1 ;
If you use GCC, add the line::
using gcc ;
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::
using gcc : 3.3 : g++-3.3 ;
using gcc : 4.0 : g++-4.0 ;
Another toolset worth mentioning is the ``darwin`` 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::
using darwin : 3.3 : g++-3.3 ;
using darwin : 4.0 : g++-4.0 ;
Note that the spaces around the semi-colons and colons are important!
Step 3: Building libtorrent
~~~~~~~~~~~~~~~~~~~~~~~~~~~
When building libtorrent, the ``Jamfile`` expects the environment variable
``BOOST_ROOT`` 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 ``c:\boost_1_33_0``.
Then the only thing left is simply to invoke ``bjam``. If you want to specify
a specific toolset to use (compiler) you can just add that to the commandline.
For example::
bjam msvc-7.1
bjam gcc-3.3
To build different versions you can also just add the name of the build
variant. Some default build variants in BBv2 are ``release``, ``debug``,
``profile``.
If you're building on a platform where dlls share the same heap, you can build
libtorrent as a dll too, by typing ``link=shared``, or ``link=static`` to
explicitly build a static library.
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.
Note that if you're building on windows using the ``msvc`` toolset, you cannot run it Note that if you're building on windows using the ``msvc`` toolset, you cannot run it
from a cygwin terminal, you'll have to run it from a ``cmd`` terminal. The same goes for from a cygwin terminal, you'll have to run it from a ``cmd`` terminal. The same goes for
cygwin, if you're building with gcc (mingw) you'll have to run it from a cygwin terminal. 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 Also, make sure the paths are correct in the different environments. In cygwin, the paths
(``BOOST_BUILD_PATH`` and ``BOOST_ROOT``) should be in the typical unix-format (e.g. (``BOOST_BUILD_PATH`` and ``BOOST_ROOT``) should be in the typical unix-format (e.g.
``/cygdrive/c/boost_1_32_0``). In the windows environment, they should have the typical ``/cygdrive/c/boost_1_33_0``). In the windows environment, they should have the typical
windows format (``c:/boost_1_32_0``). windows format (``c:/boost_1_33_0``).
If you're building in developer studio, you may have to set the compiler options The ``Jamfile`` will define ``NDEBUG`` when it's building a release build.
"force conformance in for loop scope", "treat wchar_t as built-in type" and There are two other build variants available in the ``Jamfile``. debug_log
"Enable Run-Time Type Info" to Yes. and release_log, these two variants inherits from the debug and release
variants respectively, but adds extra logging (``TORRENT_VERBOSE_LOGGIN``).
For more build configuration flags see `Build configurations`_.
The ``Jamfile`` has the following build variants:
* ``release`` - release version without any logging
* ``release_log`` - release version with standard logging
* ``release_vlog`` - release version with verbose logging (all peer connections are logged)
* ``debug`` - debug version without any logging
* ``debug_log`` - debug version with standard logging
* ``debug_vlog`` - debug version with verbose logging
release and debug builds building with autotools
------------------------ -----------------------
The ``Jamfile`` can build both a release and debug version of libtorrent. In debug mode, First of all, you need to install ``automake`` and ``autoconf``. Many
libtorrent will have pretty expensive invariant checks and asserts built into it. If you unix/linux systems comes with these preinstalled.
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. The ``Jamfile`` will define Step 1: Running configure
``NDEBUG`` when it's building a release build. There are two other build variants available ~~~~~~~~~~~~~~~~~~~~~~~~~
in the ``Jamfile``. debug_log and release_log, these two variants inherits from the
debug and release variants respectively, but adds extra logging (``TORRENT_VERBOSE_LOGGIN``). In your shell, change directory to the libtorrent directory and run
``./configure``. 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.
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 in some cases 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 ``/opt/local/lib`` and headers are installed to
``/opt/local/include``. By default the compiler will not look in these
directories. You have to set the enviornment variables ``LDFLAGS`` and
``CXXFLAGS`` in order to make the compiler find those libs. In this example
you'd set them like this::
export LDFLAGS=-L/opt/local/lib
export CXXFLAGS=-I/opt/local/include
If you need to set these variables, it may be a good idea to add those lines
to your ``~/.profile`` or ``~/.tcshrc`` depending on your shell.
You know that the boost libraries were found if you see the following output
from the configure script::
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
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.
Step 2: Building libtorrent
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once the configure script is run successfully, you just type ``make`` and
libtorrent, the examples and the tests will be built.
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::
./configure --disable-debug
make clean
make
Building with other build systems
---------------------------------
If you're making your own project file, note that there are two versions of
the file abstraction. There's one ``file_win.cpp`` which relies on windows
file API that supports files larger than 2 Gigabytes. This does not work in
vc6 for some reason, possibly because it may require windows NT and above.
The other file, ``file.cpp`` is the default implementation that simply relies
on the standard low level io routines (``read()``, ``write()``, ``open()``
etc.), this implementation doesn't do anything special to support unicode
filenames, so if your target is Windows 2000 and up, you may want to use
``file_win.cpp`` which supports unicode filenames.
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.
Build configurations
--------------------
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.
+--------------------------------+-------------------------------------------------+ +--------------------------------+-------------------------------------------------+
| macro | description | | macro | description |
@ -179,15 +350,6 @@ debug and release variants respectively, but adds extra logging (``TORRENT_VERBO
If you experience that libtorrent uses unreasonable amounts of cpu, it will definately help to If you experience that libtorrent uses unreasonable amounts of cpu, it will definately help to
define ``NDEBUG``, since it will remove the invariant checks within the library. define ``NDEBUG``, since it will remove the invariant checks within the library.
The ``Jamfile`` has the following build variants:
* ``release`` - release version without any logging
* ``release_log`` - release version with standard logging
* ``release_vlog`` - release version with verbose logging (all peer connections are logged)
* ``debug`` - debug version without any logging
* ``debug_log`` - debug version with standard logging
* ``debug_vlog`` - debug version with verbose logging
using using
===== =====
@ -2574,127 +2736,23 @@ Shows how to create a torrent from a directory tree::
return 0; return 0;
} }
detailed build instructions
===========================
The build systems supported "out of the box" in libtorrent are boost-build v2 (BBv2) and
autotools (for unix-like systems).
building with BBv2
------------------
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 `boost guidelines`__ for some details on this issue).
__ http://boost.org/more/separate_compilation.html
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).
Step 1: Download boost
~~~~~~~~~~~~~~~~~~~~~~
You'll find boost here__.
__ http://sourceforge.net/project/showfiles.php?group_id=7586
Extract the archive to some directory where you want it. For the sake of this guide,
let's assume you extract the package to ``c:\boost_1_33_0`` (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.32 of the boost library in order to build libtorrent.
If you use 1.32, you need to download BBv2 separately, so for now, let's assume you will
use version 1.33.
Step 2: Setup BBv2
~~~~~~~~~~~~~~~~~~
First you need to build ``bjam``. You do this by opening a terminal (In windows, run ``cmd``).
Change directory to ``c:\boost_1_33_0\tools\build\jam_src``. Then run the script called
``build.bat`` or «build.sh« on a unix system. This will build ``bjam`` and place it in a directory
starting with ``bin.`` and then have the name of your platform. Copy the ``bjam.exe`` (or ``bjam``
on a unix system) to a place that's in you shell's ``PATH``. On linux systems a place commonly used
may be ``/usr/local/bin`` or on windows ``c:\windows`` (you can also add paths by modifying the
environment variable called ``PATH``).
Now you have ``bjam`` installed. ``bjam`` can be considered an interpreter that the boost-build
system is implemented on. So boost-build uses ``bjam``. So, to complete the installation you need
to make two more things. You need to set the environment variable ``BOOST_BUILD_PATH``. This is
the path that tells ``bjam`` 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 ``c:\boost_1_33_0\tools\build\v2``.
The last thing to do to complete the setup of BBv2 is to modify your ``user-config.jam`` file. It
is located in ``c:\boost_1_33\tools\build\v2``. 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 7.1 (2003), just add a line::
using msvc : 7.1 ;
If you use GCC, add the line::
using gcc ;
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::
using gcc : 3.3 : g++-3.3 ;
using gcc : 4.0 : g++-4.0 ;
Another toolset worth mentioning is the ``darwin`` 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::
using darwin : 3.3 : g++-3.3 ;
using darwin : 4.0 : g++-4.0 ;
Note that the spaces between the semi-colons and colons are important!
Step 3: Building libtorrent
~~~~~~~~~~~~~~~~~~~~~~~~~~~
When building libtorrent, the ``Jamfile`` expects the environment variable ``BOOST_ROOT`` 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 ``c:\boost_1_33_0``.
Then the only thing left is simply to invoke ``bjam``. If you want to specify a specific toolset to
use (compiler) you can just add that to the commandline. For example::
bjam msvc-7.1
bjam gcc-3.3
to build different versions you can also just add the name of the build variant. Some default build
variants in BBv2 are ``release``, ``debug``, ``profile``.
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.
building with autotools
-----------------------
*TODO*
fast resume fast resume
=========== ===========
The fast resume mechanism is a way to remember which pieces are downloaded and where they The fast resume mechanism is a way to remember which pieces are downloaded
are put between sessions. You can generate fast resume data by calling and where they are put between sessions. You can generate fast resume data by
``torrent_handle::write_resume_data()`` on torrent_handle_. You can then save this data calling ``torrent_handle::write_resume_data()`` on torrent_handle_. You can
to disk and use it when resuming the torrent. libtorrent will not check the piece hashes then save this data to disk and use it when resuming the torrent. libtorrent
then, and rely on the information given in the fast-resume data. The fast-resume data will not check the piece hashes then, and rely on the information given in the
also contains information about which blocks, in the unfinished pieces, were downloaded, fast-resume data. The fast-resume data also contains information about which
so it will not have to start from scratch on the partially downloaded pieces. blocks, in the unfinished pieces, were downloaded, so it will not have to
start from scratch on the partially downloaded pieces.
To use the fast-resume data you simply give it to `add_torrent()`_, and it To use the fast-resume data you simply give it to `add_torrent()`_, and it
will skip the time consuming checks. It may have to do the checking anyway, if the will skip the time consuming checks. It may have to do the checking anyway, if
fast-resume data is corrupt or doesn't fit the storage for that torrent, then it will the fast-resume data is corrupt or doesn't fit the storage for that torrent,
not trust the fast-resume data and just do the checking. then it will not trust the fast-resume data and just do the checking.
file format file format
----------- -----------

7
include/libtorrent/fingerprint.hpp
View File

@ -38,13 +38,6 @@ POSSIBILITY OF SUCH DAMAGE.
#include "libtorrent/peer_id.hpp" #include "libtorrent/peer_id.hpp"
#if defined(_MSC_VER) && _MSC_VER < 1300
namespace std
{
using ::strlen;
}
#endif
namespace libtorrent namespace libtorrent
{ {

4
include/libtorrent/size_type.hpp
View File

@ -45,11 +45,7 @@ POSSIBILITY OF SUCH DAMAGE.
namespace libtorrent namespace libtorrent
{ {
#if defined(_MSC_VER) && _MSC_VER < 1300
typedef int size_type;
#else
typedef boost::int64_t size_type; typedef boost::int64_t size_type;
#endif
} }

7
src/escape_string.cpp
View File

@ -38,13 +38,6 @@ POSSIBILITY OF SUCH DAMAGE.
#include <cctype> #include <cctype>
#include <algorithm> #include <algorithm>
#if defined(_MSC_VER) && _MSC_VER < 1300
namespace std
{
using ::isalnum;
}
#endif
namespace libtorrent namespace libtorrent
{ {
std::string unescape_string(std::string const& s) std::string unescape_string(std::string const& s)

4
src/http_tracker_connection.cpp
View File

@ -278,11 +278,7 @@ namespace libtorrent
if (sent == (int)m_send_buffer.size()) if (sent == (int)m_send_buffer.size())
{ {
#if defined(_MSC_VER) && _MSC_VER < 1300
m_send_buffer.erase(m_send_buffer.begin(), m_send_buffer.end());
#else
m_send_buffer.clear(); m_send_buffer.clear();
#endif
} }
else if (sent > 0) else if (sent > 0)
{ {

10
src/identify_client.cpp
View File

@ -46,16 +46,6 @@ POSSIBILITY OF SUCH DAMAGE.
#include "libtorrent/identify_client.hpp" #include "libtorrent/identify_client.hpp"
#include "libtorrent/fingerprint.hpp" #include "libtorrent/fingerprint.hpp"
#if defined(_MSC_VER) && _MSC_VER < 1300
namespace std
{
using ::isprint;
using ::isdigit;
using ::toupper;
using ::isalnum;
}
#endif
namespace namespace
{ {

11
src/peer_connection.cpp
View File

@ -45,17 +45,6 @@ POSSIBILITY OF SUCH DAMAGE.
#include "libtorrent/io.hpp" #include "libtorrent/io.hpp"
#include "libtorrent/version.hpp" #include "libtorrent/version.hpp"
#if defined(_MSC_VER) && _MSC_VER < 1300
#define for if (false) {} else for
namespace std
{
using ::isprint;
}
#endif
#define VERBOSE
using namespace boost::posix_time; using namespace boost::posix_time;
namespace libtorrent namespace libtorrent

9
src/piece_picker.cpp
View File

@ -42,15 +42,6 @@ POSSIBILITY OF SUCH DAMAGE.
#include "libtorrent/peer_connection.hpp" #include "libtorrent/peer_connection.hpp"
#endif #endif
#if defined(_MSC_VER) && _MSC_VER < 1300
#define for if (false) {} else for
namespace std
{
template<class T>
inline T min(T a, T b) { return a<b?a:b; }
}
#endif
namespace libtorrent namespace libtorrent
{ {

4
src/policy.cpp
View File

@ -49,10 +49,6 @@ POSSIBILITY OF SUCH DAMAGE.
#include "libtorrent/alert_types.hpp" #include "libtorrent/alert_types.hpp"
#include "libtorrent/invariant_check.hpp" #include "libtorrent/invariant_check.hpp"
#if defined(_MSC_VER) && _MSC_VER < 1300
# define for if (false) {} else for
#endif
namespace libtorrent namespace libtorrent
{ {
class peer_connection; class peer_connection;

4
src/sha1.cpp
View File

@ -19,10 +19,6 @@ changelog at the end of the file.
#include <boost/cstdint.hpp> #include <boost/cstdint.hpp>
#if defined _MSC_VER && _MSC_VER < 1300
#define for if (false) {} else for
#endif
struct SHA1_CTX struct SHA1_CTX
{ {
boost::uint32_t state[5]; boost::uint32_t state[5];

9
src/storage.cpp
View File

@ -70,15 +70,6 @@ POSSIBILITY OF SUCH DAMAGE.
#include "libtorrent/file.hpp" #include "libtorrent/file.hpp"
#include "libtorrent/invariant_check.hpp" #include "libtorrent/invariant_check.hpp"
#if defined(_MSC_VER) && _MSC_VER < 1300
#define for if (false) {} else for
namespace std
{
using ::srand;
using ::rename;
}
#endif
#if BOOST_VERSION < 103200 #if BOOST_VERSION < 103200
bool operator<(boost::filesystem::path const& lhs bool operator<(boost::filesystem::path const& lhs
, boost::filesystem::path const& rhs) , boost::filesystem::path const& rhs)

7
src/torrent.cpp
View File

@ -64,13 +64,6 @@ POSSIBILITY OF SUCH DAMAGE.
#include "libtorrent/identify_client.hpp" #include "libtorrent/identify_client.hpp"
#include "libtorrent/alert_types.hpp" #include "libtorrent/alert_types.hpp"
#if defined(_MSC_VER) && _MSC_VER < 1300
namespace std
{
using ::isalnum;
};
#endif
using namespace libtorrent; using namespace libtorrent;
using namespace boost::posix_time; using namespace boost::posix_time;