forked from premiere/premiere-libtorrent
split the documentation up a bit
This commit is contained in:
parent
22deb903db
commit
3f38ae9ef1
|
@ -0,0 +1,377 @@
|
||||||
|
<?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.3.9: http://docutils.sourceforge.net/" />
|
||||||
|
<title>libtorrent manual</title>
|
||||||
|
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="document" id="libtorrent-manual">
|
||||||
|
<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" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<div class="contents topic" id="table-of-contents">
|
||||||
|
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
|
||||||
|
<ul class="simple">
|
||||||
|
<li><a class="reference" href="#downloading-and-building" id="id6" name="id6">downloading and building</a><ul>
|
||||||
|
<li><a class="reference" href="#building-with-bbv2" id="id7" name="id7">building with BBv2</a></li>
|
||||||
|
<li><a class="reference" href="#building-with-autotools" id="id8" name="id8">building with autotools</a></li>
|
||||||
|
<li><a class="reference" href="#building-with-other-build-systems" id="id9" name="id9">building with other build systems</a></li>
|
||||||
|
<li><a class="reference" href="#build-configurations" id="id10" name="id10">build configurations</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="downloading-and-building">
|
||||||
|
<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 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 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"><span class="pre">#libtorrent</span></tt>
|
||||||
|
IRC channel on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</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&package_id=8041&release_id=376197">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_1</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.1.</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_1\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_1\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_33_1\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_33_1\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 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_1</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 link=static
|
||||||
|
bjam gcc-3.3 link=static
|
||||||
|
bjam darwin-4.0 link=static
|
||||||
|
</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>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 build a static library. <tt class="docutils literal"><span class="pre">link=shared</span></tt> is the default.</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"><span class="pre">shared</span></tt>
|
||||||
|
or <tt class="docutils literal"><span class="pre">static</span></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="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.</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"><span class="pre">bjam</span></tt> from there. To build and run the tests, go to the test
|
||||||
|
directory and run <tt class="docutils literal"><span class="pre">bjam</span></tt>.</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
|
||||||
|
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 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"><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_33_1</span></tt>). In the windows environment, they should have the typical
|
||||||
|
windows format (<tt class="docutils literal"><span class="pre">c:/boost_1_33_1</span></tt>).</p>
|
||||||
|
<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.
|
||||||
|
There are two other build variants available in the <tt class="docutils literal"><span class="pre">Jamfile</span></tt>. debug_log
|
||||||
|
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_LOGGING</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>
|
||||||
|
<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>
|
||||||
|
<p>The logs created when building vlog or log mode are put in a directory called
|
||||||
|
<tt class="docutils literal"><span class="pre">libtorrent_logs</span></tt> in the current working directory.</p>
|
||||||
|
<p>When building the example client on windows, you need to build with
|
||||||
|
<tt class="docutils literal"><span class="pre">link=static</span></tt> otherwise you may get unresolved external symbols for some
|
||||||
|
boost.program-options symbols.</p>
|
||||||
|
<p>For more information, see the <a class="reference" href="http://www.boost.org/tools/build/v2/index.html">Boost build v2 documentation</a>.</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="building-with-autotools">
|
||||||
|
<h2><a name="building-with-autotools">building with autotools</a></h2>
|
||||||
|
<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
|
||||||
|
unix/linux systems comes with these preinstalled.</p>
|
||||||
|
<div class="section" id="step-1-generating-the-build-system">
|
||||||
|
<h3><a name="step-1-generating-the-build-system">Step 1: Generating the build system</a></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" href="#step-2-running-configure">Step 2: Running configure</a>.</p>
|
||||||
|
<p>Execute the following commands, in the given order, to generate
|
||||||
|
the build system:</p>
|
||||||
|
<ul class="simple">
|
||||||
|
<li>aclocal -I m4</li>
|
||||||
|
<li>autoheader</li>
|
||||||
|
<li>libtoolize --copy --force</li>
|
||||||
|
<li>automake --add-missing --copy --gnu</li>
|
||||||
|
<li>autoconf</li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="step-2-running-configure">
|
||||||
|
<h3><a name="step-2-running-configure">Step 2: Running configure</a></h3>
|
||||||
|
<p>In your shell, change directory to the libtorrent directory and run
|
||||||
|
<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 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"><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>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>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><a name="creating-a-debug-build">Creating a debug build</a></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><a name="creating-a-release-build">Creating a release build</a></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="id5">
|
||||||
|
<h3><a name="id5">Step 3: 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>When libtorrent is built it may be a good idea to run the tests, you do this
|
||||||
|
by running <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></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><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 "force conformance in for loop scope", "treat wchar_t as built-in
|
||||||
|
type" and "Enable Run-Time Type Info" to Yes. For a detailed description
|
||||||
|
on how to build libtorrent with VS 2005, see <a class="reference" href="vs2005_build_notes.html">this document</a>.</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">
|
||||||
|
<colgroup>
|
||||||
|
<col width="40%" />
|
||||||
|
<col width="60%" />
|
||||||
|
</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"><span class="pre">NDEBUG</span></tt></td>
|
||||||
|
<td>If you define this macro, all asserts,
|
||||||
|
invariant checks and general debug code will be
|
||||||
|
removed. This option takes precedence over
|
||||||
|
other debug settings.</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_LOGGING</span></tt></td>
|
||||||
|
<td>This macro will enable logging of the session
|
||||||
|
events, such as tracker announces and incoming
|
||||||
|
connections (as well as blocked connections).</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_VERBOSE_LOGGING</span></tt></td>
|
||||||
|
<td>If you define this macro, every peer connection
|
||||||
|
will log its traffic to a log file as well as
|
||||||
|
the session log.</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_STORAGE_DEBUG</span></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"><span class="pre">UNICODE</span></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"><span class="pre">LITTLE_ENDIAN</span></tt></td>
|
||||||
|
<td>This will use the little endian version of the
|
||||||
|
sha-1 code. If defined on a big-endian system
|
||||||
|
the sha-1 hashes will be incorrect and fail.
|
||||||
|
If it is not defined and <tt class="docutils literal"><span class="pre">__BIG_ENDIAN__</span></tt>
|
||||||
|
isn't defined either (it is defined by Apple's
|
||||||
|
GCC) both little-endian and big-endian versions
|
||||||
|
will be built and the correct code will be
|
||||||
|
chosen at run-time.</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_LINKING_SHARED</span></tt></td>
|
||||||
|
<td>If this is defined when including the
|
||||||
|
libtorrent headers, the classes and functions
|
||||||
|
will be tagged with <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></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"><span class="pre">link=shared</span></tt> is set).</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_BUILDING_SHARED</span></tt></td>
|
||||||
|
<td>If this is defined, the functions and classes
|
||||||
|
in libtorrent are marked with
|
||||||
|
<tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></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"><span class="pre">link=shared</span></tt> is set).</td>
|
||||||
|
</tr>
|
||||||
|
<tr><td><tt class="docutils literal"><span class="pre">TORRENT_DISABLE_DHT</span></tt></td>
|
||||||
|
<td>If this is defined, the support for trackerless
|
||||||
|
torrents will be disabled.</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"><span class="pre">NDEBUG</span></tt>, since it will remove the invariant checks
|
||||||
|
within the library.</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</body>
|
||||||
|
</html>
|
|
@ -0,0 +1,386 @@
|
||||||
|
=================
|
||||||
|
libtorrent manual
|
||||||
|
=================
|
||||||
|
|
||||||
|
:Author: Arvid Norberg, arvid@rasterbar.com
|
||||||
|
|
||||||
|
.. contents:: Table of contents
|
||||||
|
:depth: 2
|
||||||
|
:backlinks: none
|
||||||
|
|
||||||
|
downloading and building
|
||||||
|
========================
|
||||||
|
|
||||||
|
To acquire the latest version of libtorrent, you'll have to grab it from CVS.
|
||||||
|
You'll find instructions on how to do this here__ (see Anonymous CVS access).
|
||||||
|
|
||||||
|
__ http://sourceforge.net/cvs/?group_id=79942
|
||||||
|
|
||||||
|
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 ``#libtorrent``
|
||||||
|
IRC channel on ``irc.freenode.net``.
|
||||||
|
|
||||||
|
|
||||||
|
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&package_id=8041&release_id=376197
|
||||||
|
|
||||||
|
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_1`` (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.1.
|
||||||
|
|
||||||
|
|
||||||
|
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_1\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_1\tools\build\v2``.
|
||||||
|
|
||||||
|
To set an environment variable in windows, type for example::
|
||||||
|
|
||||||
|
set BOOST_BUILD_PATH=c:\boost_1_33_1\tools\build\v2
|
||||||
|
|
||||||
|
In a terminal window.
|
||||||
|
|
||||||
|
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_1\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_1``.
|
||||||
|
|
||||||
|
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 link=static
|
||||||
|
bjam gcc-3.3 link=static
|
||||||
|
bjam darwin-4.0 link=static
|
||||||
|
|
||||||
|
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``.
|
||||||
|
|
||||||
|
You can build libtorrent as a dll too, by typing ``link=shared``, or
|
||||||
|
``link=static`` to build a static library. ``link=shared`` is the default.
|
||||||
|
|
||||||
|
If you want to explicitly say how to link against the runtime library, you
|
||||||
|
can set the ``runtime-link`` feature on the commandline, either to ``shared``
|
||||||
|
or ``static``. Most operating systems will only allow linking shared against
|
||||||
|
the runtime, but on windows you can do both. Example::
|
||||||
|
|
||||||
|
bjam msvc-7.1 link=static runtime-link=static
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
To build the examples, just change directory to the examples directory and
|
||||||
|
invoke ``bjam`` from there. To build and run the tests, go to the test
|
||||||
|
directory and run ``bjam``.
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
(``BOOST_BUILD_PATH`` and ``BOOST_ROOT``) should be in the typical unix-format (e.g.
|
||||||
|
``/cygdrive/c/boost_1_33_1``). In the windows environment, they should have the typical
|
||||||
|
windows format (``c:/boost_1_33_1``).
|
||||||
|
|
||||||
|
The ``Jamfile`` will define ``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_LOGGING``).
|
||||||
|
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
|
||||||
|
|
||||||
|
The logs created when building vlog or log mode are put in a directory called
|
||||||
|
``libtorrent_logs`` in the current working directory.
|
||||||
|
|
||||||
|
When building the example client on windows, you need to build with
|
||||||
|
``link=static`` otherwise you may get unresolved external symbols for some
|
||||||
|
boost.program-options symbols.
|
||||||
|
|
||||||
|
For more information, see the `Boost build v2 documentation`__.
|
||||||
|
|
||||||
|
__ http://www.boost.org/tools/build/v2/index.html
|
||||||
|
|
||||||
|
building with autotools
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
First of all, you need to install ``automake`` and ``autoconf``. Many
|
||||||
|
unix/linux systems comes with these preinstalled.
|
||||||
|
|
||||||
|
Step 1: Generating the build system
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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 `Step 2: Running configure`_.
|
||||||
|
|
||||||
|
Execute the following commands, in the given order, to generate
|
||||||
|
the build system:
|
||||||
|
|
||||||
|
* aclocal -I m4
|
||||||
|
* autoheader
|
||||||
|
* libtoolize --copy --force
|
||||||
|
* automake --add-missing --copy --gnu
|
||||||
|
* autoconf
|
||||||
|
|
||||||
|
|
||||||
|
Step 2: Running configure
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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 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 ``/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
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Creating a debug build
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
./configure --enable-debug=yes
|
||||||
|
|
||||||
|
Creating a release build
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
./configure --enable-debug=no
|
||||||
|
|
||||||
|
The above option make use of -DNDEBUG, which is used throughout libtorrent.
|
||||||
|
|
||||||
|
Step 3: Building libtorrent
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Once the configure script is run successfully, you just type ``make`` and
|
||||||
|
libtorrent, the examples and the tests will be built.
|
||||||
|
|
||||||
|
When libtorrent is built it may be a good idea to run the tests, you do this
|
||||||
|
by running ``make check``.
|
||||||
|
|
||||||
|
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. For a detailed description
|
||||||
|
on how to build libtorrent with VS 2005, see `this document`_.
|
||||||
|
|
||||||
|
.. _`this document`: vs2005_build_notes.html
|
||||||
|
|
||||||
|
|
||||||
|
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 |
|
||||||
|
+================================+=================================================+
|
||||||
|
| ``NDEBUG`` | If you define this macro, all asserts, |
|
||||||
|
| | invariant checks and general debug code will be |
|
||||||
|
| | removed. This option takes precedence over |
|
||||||
|
| | other debug settings. |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
| ``TORRENT_LOGGING`` | This macro will enable logging of the session |
|
||||||
|
| | events, such as tracker announces and incoming |
|
||||||
|
| | connections (as well as blocked connections). |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
| ``TORRENT_VERBOSE_LOGGING`` | If you define this macro, every peer connection |
|
||||||
|
| | will log its traffic to a log file as well as |
|
||||||
|
| | the session log. |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
| ``TORRENT_STORAGE_DEBUG`` | This will enable extra expensive invariant |
|
||||||
|
| | checks in the storage, including logging of |
|
||||||
|
| | piece sorting. |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
| ``UNICODE`` | 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. |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
| ``LITTLE_ENDIAN`` | This will use the little endian version of the |
|
||||||
|
| | sha-1 code. If defined on a big-endian system |
|
||||||
|
| | the sha-1 hashes will be incorrect and fail. |
|
||||||
|
| | If it is not defined and ``__BIG_ENDIAN__`` |
|
||||||
|
| | isn't defined either (it is defined by Apple's |
|
||||||
|
| | GCC) both little-endian and big-endian versions |
|
||||||
|
| | will be built and the correct code will be |
|
||||||
|
| | chosen at run-time. |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
| ``TORRENT_LINKING_SHARED`` | If this is defined when including the |
|
||||||
|
| | libtorrent headers, the classes and functions |
|
||||||
|
| | will be tagged with ``__declspec(dllimport)`` |
|
||||||
|
| | 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 |
|
||||||
|
| | ``link=shared`` is set). |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
| ``TORRENT_BUILDING_SHARED`` | If this is defined, the functions and classes |
|
||||||
|
| | in libtorrent are marked with |
|
||||||
|
| | ``__declspec(dllexport)`` 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 ``link=shared`` is set). |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
| ``TORRENT_DISABLE_DHT`` | If this is defined, the support for trackerless |
|
||||||
|
|Ê | torrents will be disabled. |
|
||||||
|
+--------------------------------+-------------------------------------------------+
|
||||||
|
|
||||||
|
|
||||||
|
If you experience that libtorrent uses unreasonable amounts of cpu, it will
|
||||||
|
definitely help to define ``NDEBUG``, since it will remove the invariant checks
|
||||||
|
within the library.
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,257 @@
|
||||||
|
<?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.3.9: http://docutils.sourceforge.net/" />
|
||||||
|
<title>libtorrent Examples</title>
|
||||||
|
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="document" id="libtorrent-examples">
|
||||||
|
<h1 class="title">libtorrent Examples</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" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<div class="contents topic" id="table-of-contents">
|
||||||
|
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
|
||||||
|
<ul class="simple">
|
||||||
|
<li><a class="reference" href="#examples" id="id2" name="id2">examples</a><ul>
|
||||||
|
<li><a class="reference" href="#dump-torrent" id="id3" name="id3">dump_torrent</a></li>
|
||||||
|
<li><a class="reference" href="#simple-client" id="id4" name="id4">simple client</a></li>
|
||||||
|
<li><a class="reference" href="#make-torrent" id="id5" name="id5">make_torrent</a></li>
|
||||||
|
</ul>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="examples">
|
||||||
|
<h1><a name="examples">examples</a></h1>
|
||||||
|
<p>Except for the example programs in this manual, there's also a bigger example
|
||||||
|
of a (little bit) more complete client, <tt class="docutils literal"><span class="pre">client_test</span></tt>. There are separate
|
||||||
|
instructions for how to use it <a class="reference" href="client_test.html">here</a> if you'd like to try it.</p>
|
||||||
|
<div class="section" id="dump-torrent">
|
||||||
|
<h2><a name="dump-torrent">dump_torrent</a></h2>
|
||||||
|
<p>This is an example of a program that will take a torrent-file as a parameter and
|
||||||
|
print information about it to std out:</p>
|
||||||
|
<pre class="literal-block">
|
||||||
|
#include <iostream>
|
||||||
|
#include <fstream>
|
||||||
|
#include <iterator>
|
||||||
|
#include <iomanip>
|
||||||
|
|
||||||
|
#include "libtorrent/entry.hpp"
|
||||||
|
#include "libtorrent/bencode.hpp"
|
||||||
|
#include "libtorrent/torrent_info.hpp"
|
||||||
|
|
||||||
|
|
||||||
|
int main(int argc, char* argv[])
|
||||||
|
{
|
||||||
|
using namespace libtorrent;
|
||||||
|
|
||||||
|
if (argc != 2)
|
||||||
|
{
|
||||||
|
std::cerr << "usage: dump_torrent torrent-file\n";
|
||||||
|
return 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
try
|
||||||
|
{
|
||||||
|
std::ifstream in(argv[1], std::ios_base::binary);
|
||||||
|
in.unsetf(std::ios_base::skipws);
|
||||||
|
entry e = bdecode(std::istream_iterator<char>(in)
|
||||||
|
, std::istream_iterator<char>());
|
||||||
|
|
||||||
|
std::cout << "\n\n----- raw info -----\n\n";
|
||||||
|
e.print(std::cout);
|
||||||
|
|
||||||
|
torrent_info t(e);
|
||||||
|
|
||||||
|
// print info about torrent
|
||||||
|
std::cout << "\n\n----- torrent file info -----\n\n";
|
||||||
|
std::cout << "trackers:\n";
|
||||||
|
for (std::vector<announce_entry>::const_iterator i
|
||||||
|
= t.trackers().begin(); i != t.trackers().end(); ++i)
|
||||||
|
{
|
||||||
|
std::cout << i->tier << ": " << i->url << "\n";
|
||||||
|
}
|
||||||
|
|
||||||
|
std::cout << "number of pieces: " << t.num_pieces() << "\n";
|
||||||
|
std::cout << "piece length: " << t.piece_length() << "\n";
|
||||||
|
std::cout << "info hash: " << t.info_hash() << "\n";
|
||||||
|
std::cout << "comment: " << t.comment() << "\n";
|
||||||
|
std::cout << "created by: " << t.creator() << "\n";
|
||||||
|
std::cout << "files:\n";
|
||||||
|
for (torrent_info::file_iterator i = t.begin_files();
|
||||||
|
i != t.end_files(); ++i)
|
||||||
|
{
|
||||||
|
std::cout << " " << std::setw(11) << i->size
|
||||||
|
<< " " << i->path.string() << "\n";
|
||||||
|
}
|
||||||
|
|
||||||
|
}
|
||||||
|
catch (std::exception& e)
|
||||||
|
{
|
||||||
|
std::cout << e.what() << "\n";
|
||||||
|
}
|
||||||
|
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="simple-client">
|
||||||
|
<h2><a name="simple-client">simple client</a></h2>
|
||||||
|
<p>This is a simple client. It doesn't have much output to keep it simple:</p>
|
||||||
|
<pre class="literal-block">
|
||||||
|
#include <iostream>
|
||||||
|
#include <fstream>
|
||||||
|
#include <iterator>
|
||||||
|
#include <exception>
|
||||||
|
|
||||||
|
#include <boost/format.hpp>
|
||||||
|
#include <boost/date_time/posix_time/posix_time.hpp>
|
||||||
|
|
||||||
|
#include "libtorrent/entry.hpp"
|
||||||
|
#include "libtorrent/bencode.hpp"
|
||||||
|
#include "libtorrent/session.hpp"
|
||||||
|
|
||||||
|
int main(int argc, char* argv[])
|
||||||
|
{
|
||||||
|
using namespace libtorrent;
|
||||||
|
|
||||||
|
if (argc != 2)
|
||||||
|
{
|
||||||
|
std::cerr << "usage: ./simple_cient torrent-file\n"
|
||||||
|
"to stop the client, press return.\n";
|
||||||
|
return 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
try
|
||||||
|
{
|
||||||
|
session s;
|
||||||
|
s.listen_on(std::make_pair(6881, 6889));
|
||||||
|
|
||||||
|
std::ifstream in(argv[1], std::ios_base::binary);
|
||||||
|
in.unsetf(std::ios_base::skipws);
|
||||||
|
entry e = bdecode(std::istream_iterator<char>(in)
|
||||||
|
, std::istream_iterator<char>());
|
||||||
|
s.add_torrent(torrent_info(e), "");
|
||||||
|
|
||||||
|
// wait for the user to end
|
||||||
|
char a;
|
||||||
|
std::cin.unsetf(std::ios_base::skipws);
|
||||||
|
std::cin >> a;
|
||||||
|
}
|
||||||
|
catch (std::exception& e)
|
||||||
|
{
|
||||||
|
std::cout << e.what() << "\n";
|
||||||
|
}
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="make-torrent">
|
||||||
|
<h2><a name="make-torrent">make_torrent</a></h2>
|
||||||
|
<p>Shows how to create a torrent from a directory tree:</p>
|
||||||
|
<pre class="literal-block">
|
||||||
|
#include <iostream>
|
||||||
|
#include <fstream>
|
||||||
|
#include <iterator>
|
||||||
|
#include <iomanip>
|
||||||
|
|
||||||
|
#include "libtorrent/entry.hpp"
|
||||||
|
#include "libtorrent/bencode.hpp"
|
||||||
|
#include "libtorrent/torrent_info.hpp"
|
||||||
|
#include "libtorrent/file.hpp"
|
||||||
|
#include "libtorrent/storage.hpp"
|
||||||
|
#include "libtorrent/hasher.hpp"
|
||||||
|
|
||||||
|
#include <boost/filesystem/operations.hpp>
|
||||||
|
#include <boost/filesystem/path.hpp>
|
||||||
|
#include <boost/filesystem/fstream.hpp>
|
||||||
|
|
||||||
|
using namespace boost::filesystem;
|
||||||
|
using namespace libtorrent;
|
||||||
|
|
||||||
|
void add_files(torrent_info& t, path const& p, path const& l)
|
||||||
|
{
|
||||||
|
path f(p / l);
|
||||||
|
if (is_directory(f))
|
||||||
|
{
|
||||||
|
for (directory_iterator i(f), end; i != end; ++i)
|
||||||
|
add_files(t, p, l / i->leaf());
|
||||||
|
}
|
||||||
|
else
|
||||||
|
{
|
||||||
|
std::cerr << "adding \"" << l.string() << "\"\n";
|
||||||
|
file fi(f, file::in);
|
||||||
|
fi.seek(0, file::end);
|
||||||
|
libtorrent::size_type size = fi.tell();
|
||||||
|
t.add_file(l, size);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
int main(int argc, char* argv[])
|
||||||
|
{
|
||||||
|
using namespace libtorrent;
|
||||||
|
using namespace boost::filesystem;
|
||||||
|
|
||||||
|
if (argc != 4)
|
||||||
|
{
|
||||||
|
std::cerr << "usage: make_torrent <output torrent-file> "
|
||||||
|
"<announce url> <file or directory to create torrent from>\n";
|
||||||
|
return 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
boost::filesystem::path::default_name_check(native);
|
||||||
|
|
||||||
|
try
|
||||||
|
{
|
||||||
|
torrent_info t;
|
||||||
|
path full_path = initial_path() / path(argv[3]);
|
||||||
|
ofstream out(initial_path() / path(argv[1]), std::ios_base::binary);
|
||||||
|
|
||||||
|
int piece_size = 256 * 1024;
|
||||||
|
char const* creator_str = "libtorrent";
|
||||||
|
|
||||||
|
add_files(t, full_path.branch_path(), full_path.leaf());
|
||||||
|
t.set_piece_size(piece_size);
|
||||||
|
|
||||||
|
storage st(t, full_path.branch_path());
|
||||||
|
t.add_tracker(argv[2]);
|
||||||
|
|
||||||
|
// calculate the hash for all pieces
|
||||||
|
int num = t.num_pieces();
|
||||||
|
std::vector<char> buf(piece_size);
|
||||||
|
for (int i = 0; i < num; ++i)
|
||||||
|
{
|
||||||
|
st.read(&buf[0], i, 0, t.piece_size(i));
|
||||||
|
hasher h(&buf[0], t.piece_size(i));
|
||||||
|
t.set_hash(i, h.final());
|
||||||
|
std::cerr << (i+1) << "/" << num << "\r";
|
||||||
|
}
|
||||||
|
|
||||||
|
t.set_creator(creator_str);
|
||||||
|
|
||||||
|
// create the torrent and print it to out
|
||||||
|
entry e = t.create_torrent();
|
||||||
|
libtorrent::bencode(std::ostream_iterator<char>(out), e);
|
||||||
|
}
|
||||||
|
catch (std::exception& e)
|
||||||
|
{
|
||||||
|
std::cerr << e.what() << "\n";
|
||||||
|
}
|
||||||
|
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</body>
|
||||||
|
</html>
|
|
@ -0,0 +1,238 @@
|
||||||
|
===================
|
||||||
|
libtorrent Examples
|
||||||
|
===================
|
||||||
|
|
||||||
|
:Author: Arvid Norberg, arvid@rasterbar.com
|
||||||
|
|
||||||
|
.. contents:: Table of contents
|
||||||
|
:depth: 2
|
||||||
|
:backlinks: none
|
||||||
|
|
||||||
|
examples
|
||||||
|
========
|
||||||
|
|
||||||
|
Except for the example programs in this manual, there's also a bigger example
|
||||||
|
of a (little bit) more complete client, ``client_test``. There are separate
|
||||||
|
instructions for how to use it here__ if you'd like to try it.
|
||||||
|
|
||||||
|
__ client_test.html
|
||||||
|
|
||||||
|
dump_torrent
|
||||||
|
------------
|
||||||
|
|
||||||
|
This is an example of a program that will take a torrent-file as a parameter and
|
||||||
|
print information about it to std out::
|
||||||
|
|
||||||
|
|
||||||
|
#include <iostream>
|
||||||
|
#include <fstream>
|
||||||
|
#include <iterator>
|
||||||
|
#include <iomanip>
|
||||||
|
|
||||||
|
#include "libtorrent/entry.hpp"
|
||||||
|
#include "libtorrent/bencode.hpp"
|
||||||
|
#include "libtorrent/torrent_info.hpp"
|
||||||
|
|
||||||
|
|
||||||
|
int main(int argc, char* argv[])
|
||||||
|
{
|
||||||
|
using namespace libtorrent;
|
||||||
|
|
||||||
|
if (argc != 2)
|
||||||
|
{
|
||||||
|
std::cerr << "usage: dump_torrent torrent-file\n";
|
||||||
|
return 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
try
|
||||||
|
{
|
||||||
|
std::ifstream in(argv[1], std::ios_base::binary);
|
||||||
|
in.unsetf(std::ios_base::skipws);
|
||||||
|
entry e = bdecode(std::istream_iterator<char>(in)
|
||||||
|
, std::istream_iterator<char>());
|
||||||
|
|
||||||
|
std::cout << "\n\n----- raw info -----\n\n";
|
||||||
|
e.print(std::cout);
|
||||||
|
|
||||||
|
torrent_info t(e);
|
||||||
|
|
||||||
|
// print info about torrent
|
||||||
|
std::cout << "\n\n----- torrent file info -----\n\n";
|
||||||
|
std::cout << "trackers:\n";
|
||||||
|
for (std::vector<announce_entry>::const_iterator i
|
||||||
|
= t.trackers().begin(); i != t.trackers().end(); ++i)
|
||||||
|
{
|
||||||
|
std::cout << i->tier << ": " << i->url << "\n";
|
||||||
|
}
|
||||||
|
|
||||||
|
std::cout << "number of pieces: " << t.num_pieces() << "\n";
|
||||||
|
std::cout << "piece length: " << t.piece_length() << "\n";
|
||||||
|
std::cout << "info hash: " << t.info_hash() << "\n";
|
||||||
|
std::cout << "comment: " << t.comment() << "\n";
|
||||||
|
std::cout << "created by: " << t.creator() << "\n";
|
||||||
|
std::cout << "files:\n";
|
||||||
|
for (torrent_info::file_iterator i = t.begin_files();
|
||||||
|
i != t.end_files(); ++i)
|
||||||
|
{
|
||||||
|
std::cout << " " << std::setw(11) << i->size
|
||||||
|
<< " " << i->path.string() << "\n";
|
||||||
|
}
|
||||||
|
|
||||||
|
}
|
||||||
|
catch (std::exception& e)
|
||||||
|
{
|
||||||
|
std::cout << e.what() << "\n";
|
||||||
|
}
|
||||||
|
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
simple client
|
||||||
|
-------------
|
||||||
|
|
||||||
|
This is a simple client. It doesn't have much output to keep it simple::
|
||||||
|
|
||||||
|
#include <iostream>
|
||||||
|
#include <fstream>
|
||||||
|
#include <iterator>
|
||||||
|
#include <exception>
|
||||||
|
|
||||||
|
#include <boost/format.hpp>
|
||||||
|
#include <boost/date_time/posix_time/posix_time.hpp>
|
||||||
|
|
||||||
|
#include "libtorrent/entry.hpp"
|
||||||
|
#include "libtorrent/bencode.hpp"
|
||||||
|
#include "libtorrent/session.hpp"
|
||||||
|
|
||||||
|
int main(int argc, char* argv[])
|
||||||
|
{
|
||||||
|
using namespace libtorrent;
|
||||||
|
|
||||||
|
if (argc != 2)
|
||||||
|
{
|
||||||
|
std::cerr << "usage: ./simple_cient torrent-file\n"
|
||||||
|
"to stop the client, press return.\n";
|
||||||
|
return 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
try
|
||||||
|
{
|
||||||
|
session s;
|
||||||
|
s.listen_on(std::make_pair(6881, 6889));
|
||||||
|
|
||||||
|
std::ifstream in(argv[1], std::ios_base::binary);
|
||||||
|
in.unsetf(std::ios_base::skipws);
|
||||||
|
entry e = bdecode(std::istream_iterator<char>(in)
|
||||||
|
, std::istream_iterator<char>());
|
||||||
|
s.add_torrent(torrent_info(e), "");
|
||||||
|
|
||||||
|
// wait for the user to end
|
||||||
|
char a;
|
||||||
|
std::cin.unsetf(std::ios_base::skipws);
|
||||||
|
std::cin >> a;
|
||||||
|
}
|
||||||
|
catch (std::exception& e)
|
||||||
|
{
|
||||||
|
std::cout << e.what() << "\n";
|
||||||
|
}
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
make_torrent
|
||||||
|
------------
|
||||||
|
|
||||||
|
Shows how to create a torrent from a directory tree::
|
||||||
|
|
||||||
|
#include <iostream>
|
||||||
|
#include <fstream>
|
||||||
|
#include <iterator>
|
||||||
|
#include <iomanip>
|
||||||
|
|
||||||
|
#include "libtorrent/entry.hpp"
|
||||||
|
#include "libtorrent/bencode.hpp"
|
||||||
|
#include "libtorrent/torrent_info.hpp"
|
||||||
|
#include "libtorrent/file.hpp"
|
||||||
|
#include "libtorrent/storage.hpp"
|
||||||
|
#include "libtorrent/hasher.hpp"
|
||||||
|
|
||||||
|
#include <boost/filesystem/operations.hpp>
|
||||||
|
#include <boost/filesystem/path.hpp>
|
||||||
|
#include <boost/filesystem/fstream.hpp>
|
||||||
|
|
||||||
|
using namespace boost::filesystem;
|
||||||
|
using namespace libtorrent;
|
||||||
|
|
||||||
|
void add_files(torrent_info& t, path const& p, path const& l)
|
||||||
|
{
|
||||||
|
path f(p / l);
|
||||||
|
if (is_directory(f))
|
||||||
|
{
|
||||||
|
for (directory_iterator i(f), end; i != end; ++i)
|
||||||
|
add_files(t, p, l / i->leaf());
|
||||||
|
}
|
||||||
|
else
|
||||||
|
{
|
||||||
|
std::cerr << "adding \"" << l.string() << "\"\n";
|
||||||
|
file fi(f, file::in);
|
||||||
|
fi.seek(0, file::end);
|
||||||
|
libtorrent::size_type size = fi.tell();
|
||||||
|
t.add_file(l, size);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
int main(int argc, char* argv[])
|
||||||
|
{
|
||||||
|
using namespace libtorrent;
|
||||||
|
using namespace boost::filesystem;
|
||||||
|
|
||||||
|
if (argc != 4)
|
||||||
|
{
|
||||||
|
std::cerr << "usage: make_torrent <output torrent-file> "
|
||||||
|
"<announce url> <file or directory to create torrent from>\n";
|
||||||
|
return 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
boost::filesystem::path::default_name_check(native);
|
||||||
|
|
||||||
|
try
|
||||||
|
{
|
||||||
|
torrent_info t;
|
||||||
|
path full_path = initial_path() / path(argv[3]);
|
||||||
|
ofstream out(initial_path() / path(argv[1]), std::ios_base::binary);
|
||||||
|
|
||||||
|
int piece_size = 256 * 1024;
|
||||||
|
char const* creator_str = "libtorrent";
|
||||||
|
|
||||||
|
add_files(t, full_path.branch_path(), full_path.leaf());
|
||||||
|
t.set_piece_size(piece_size);
|
||||||
|
|
||||||
|
storage st(t, full_path.branch_path());
|
||||||
|
t.add_tracker(argv[2]);
|
||||||
|
|
||||||
|
// calculate the hash for all pieces
|
||||||
|
int num = t.num_pieces();
|
||||||
|
std::vector<char> buf(piece_size);
|
||||||
|
for (int i = 0; i < num; ++i)
|
||||||
|
{
|
||||||
|
st.read(&buf[0], i, 0, t.piece_size(i));
|
||||||
|
hasher h(&buf[0], t.piece_size(i));
|
||||||
|
t.set_hash(i, h.final());
|
||||||
|
std::cerr << (i+1) << "/" << num << "\r";
|
||||||
|
}
|
||||||
|
|
||||||
|
t.set_creator(creator_str);
|
||||||
|
|
||||||
|
// create the torrent and print it to out
|
||||||
|
entry e = t.create_torrent();
|
||||||
|
libtorrent::bencode(std::ostream_iterator<char>(out), e);
|
||||||
|
}
|
||||||
|
catch (std::exception& e)
|
||||||
|
{
|
||||||
|
std::cerr << e.what() << "\n";
|
||||||
|
}
|
||||||
|
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,124 @@
|
||||||
|
<?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.3.9: http://docutils.sourceforge.net/" />
|
||||||
|
<title>libtorrent manual</title>
|
||||||
|
<meta name="author" content="Arvid Norberg, arvid@rasterbar.com" />
|
||||||
|
<link rel="stylesheet" href="style.css" type="text/css" />
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="document" id="libtorrent-manual">
|
||||||
|
<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" href="mailto:arvid@rasterbar.com">arvid@rasterbar.com</a></td></tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
<div class="contents topic" id="table-of-contents">
|
||||||
|
<p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
|
||||||
|
<ul class="simple">
|
||||||
|
<li><a class="reference" href="#introduction" id="id6" name="id6">introduction</a></li>
|
||||||
|
<li><a class="reference" href="#features" id="id7" name="id7">features</a></li>
|
||||||
|
<li><a class="reference" href="#portability" id="id8" name="id8">portability</a></li>
|
||||||
|
<li><a class="reference" href="#license" id="id9" name="id9">license</a></li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="introduction">
|
||||||
|
<h1><a name="introduction">introduction</a></h1>
|
||||||
|
<p>libtorrent is a C++ library that aims to be a good alternative to all the
|
||||||
|
other bittorrent implementations around. It is a
|
||||||
|
library and not a full featured client, although it comes with a working
|
||||||
|
example client.</p>
|
||||||
|
<p>The main goals of libtorrent are:</p>
|
||||||
|
<ul class="simple">
|
||||||
|
<li>to be cpu efficient</li>
|
||||||
|
<li>to be memory efficient</li>
|
||||||
|
<li>to be very easy to use</li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="features">
|
||||||
|
<h1><a name="features">features</a></h1>
|
||||||
|
<p>libtorrent is still being developed, however it is stable. It is an ongoing
|
||||||
|
project (including this documentation). The current state includes the
|
||||||
|
following features:</p>
|
||||||
|
<ul class="simple">
|
||||||
|
<li>Trackerless torrents (using a kademlia DHT)</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 in a single thread</li>
|
||||||
|
<li>gzipped tracker-responses</li>
|
||||||
|
<li><a class="reference" href="manual.html#http-seeding">HTTP seeding</a>, as <a class="reference" href="http://www.getright.com/seedtorrent.html">specified by Michael Burford of GetRight</a>.</li>
|
||||||
|
<li>piece picking on block-level (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>supports http proxies and proxy authentication</li>
|
||||||
|
<li>uses separate threads for checking files and for main downloader, with a
|
||||||
|
fool-proof thread-safe library interface. (i.e. There's no way for the
|
||||||
|
user to cause a deadlock). (see <a class="reference" href="manual.html#threads">threads</a>)</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,
|
||||||
|
but one can choose to trade 1 for 2 or any other ratio that isn't unfair
|
||||||
|
to the other party.</li>
|
||||||
|
<li>fast resume support, a way to get rid of the costly piece check at the
|
||||||
|
start of a resumed torrent. Saves the storage state, piece_picker state
|
||||||
|
as well as all local peers in a separate fast-resume file.</li>
|
||||||
|
<li>supports an <a class="reference" href="extension_protocol.html">extension protocol</a>. See <a class="reference" href="manual.html#extensions">extensions</a>.</li>
|
||||||
|
<li>supports files > 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 <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>delays have messages if there's no other outgoing traffic to the peer, and
|
||||||
|
doesn't send have messages to peers that already has the piece. This saves
|
||||||
|
bandwidth.</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>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
|
||||||
|
want to download.</li>
|
||||||
|
<li>ip filter</li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="portability">
|
||||||
|
<h1><a name="portability">portability</a></h1>
|
||||||
|
<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 <a class="reference" href="http://www.zlib.org">zlib</a> (shipped) and <a class="reference" href="http://asio.sf.net">asio</a> (shipped). At least version
|
||||||
|
1.33.1 of boost is required.</p>
|
||||||
|
<p>Since libtorrent uses asio, it will take full advantage of high performance
|
||||||
|
network APIs on the most popular platforms. I/O completion ports on windows,
|
||||||
|
epoll on linux and kqueue on MacOS X and BSD.</p>
|
||||||
|
<p>libtorrent has been successfully compiled and tested on:</p>
|
||||||
|
<ul class="simple">
|
||||||
|
<li>Windows 2000 vc7.1, vc8</li>
|
||||||
|
<li>Linux x86 GCC 3.3, GCC 3.4.2</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>Cygwin GCC 3.3.3</li>
|
||||||
|
</ul>
|
||||||
|
<p>Fails on:</p>
|
||||||
|
<ul class="simple">
|
||||||
|
<li>GCC 2.95.4</li>
|
||||||
|
<li>msvc6</li>
|
||||||
|
</ul>
|
||||||
|
</div>
|
||||||
|
<div class="section" id="license">
|
||||||
|
<h1><a name="license">license</a></h1>
|
||||||
|
<p>libtorrent is released under the <a class="reference" href="http://www.opensource.org/licenses/bsd-license.php">BSD-license</a>.</p>
|
||||||
|
<p>This means that you can use the library in your project without having to
|
||||||
|
release its source code. The only requirement is that you give credit
|
||||||
|
to the author of the library by including the libtorrent license in your
|
||||||
|
software or documentation.</p>
|
||||||
|
<p><a class="reference" href="projects.html">Here's</a> a list of some projects that uses libtorrent.</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</body>
|
||||||
|
</html>
|
|
@ -0,0 +1,123 @@
|
||||||
|
=================
|
||||||
|
libtorrent manual
|
||||||
|
=================
|
||||||
|
|
||||||
|
:Author: Arvid Norberg, arvid@rasterbar.com
|
||||||
|
|
||||||
|
.. contents:: Table of contents
|
||||||
|
:depth: 2
|
||||||
|
:backlinks: none
|
||||||
|
|
||||||
|
introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
libtorrent is a C++ library that aims to be a good alternative to all the
|
||||||
|
other bittorrent implementations around. It is a
|
||||||
|
library and not a full featured client, although it comes with a working
|
||||||
|
example client.
|
||||||
|
|
||||||
|
The main goals of libtorrent are:
|
||||||
|
|
||||||
|
* to be cpu efficient
|
||||||
|
* to be memory efficient
|
||||||
|
* to be very easy to use
|
||||||
|
|
||||||
|
features
|
||||||
|
========
|
||||||
|
|
||||||
|
libtorrent is still being developed, however it is stable. It is an ongoing
|
||||||
|
project (including this documentation). The current state includes the
|
||||||
|
following features:
|
||||||
|
|
||||||
|
* Trackerless torrents (using a kademlia DHT)
|
||||||
|
* multitracker extension support (as `specified by John Hoffman`__)
|
||||||
|
* serves multiple torrents on a single port and in a single thread
|
||||||
|
* gzipped tracker-responses
|
||||||
|
* `HTTP seeding`_, as `specified by Michael Burford of GetRight`__.
|
||||||
|
* piece picking on block-level (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.
|
||||||
|
* supports http proxies and proxy authentication
|
||||||
|
* uses separate threads for checking files and for main downloader, with a
|
||||||
|
fool-proof thread-safe library interface. (i.e. There's no way for the
|
||||||
|
user to cause a deadlock). (see threads_)
|
||||||
|
* 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,
|
||||||
|
but one can choose to trade 1 for 2 or any other ratio that isn't unfair
|
||||||
|
to the other party.
|
||||||
|
* fast resume support, a way to get rid of the costly piece check at the
|
||||||
|
start of a resumed torrent. Saves the storage state, piece_picker state
|
||||||
|
as well as all local peers in a separate fast-resume file.
|
||||||
|
* supports an `extension protocol`__. See extensions_.
|
||||||
|
* supports files > 2 gigabytes.
|
||||||
|
* supports the ``no_peer_id=1`` extension that will ease the load off trackers.
|
||||||
|
* supports the `udp-tracker protocol`__ by Olaf van der Spek.
|
||||||
|
* possibility to limit the number of connections.
|
||||||
|
* delays have messages if there's no other outgoing traffic to the peer, and
|
||||||
|
doesn't send have messages to peers that already has the piece. This saves
|
||||||
|
bandwidth.
|
||||||
|
* 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.
|
||||||
|
* supports the ``compact=1`` tracker parameter.
|
||||||
|
* selective downloading. The ability to select which parts of a torrent you
|
||||||
|
want to download.
|
||||||
|
* ip filter
|
||||||
|
|
||||||
|
__ http://home.elp.rr.com/tur/multitracker-spec.txt
|
||||||
|
__ http://www.getright.com/seedtorrent.html
|
||||||
|
__ extension_protocol.html
|
||||||
|
__ udp_tracker_protocol.html
|
||||||
|
|
||||||
|
portability
|
||||||
|
===========
|
||||||
|
|
||||||
|
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_ (shipped) and asio_ (shipped). At least version
|
||||||
|
1.33.1 of boost is required.
|
||||||
|
|
||||||
|
.. _zlib: http://www.zlib.org
|
||||||
|
.. _asio: http://asio.sf.net
|
||||||
|
|
||||||
|
Since libtorrent uses asio, it will take full advantage of high performance
|
||||||
|
network APIs on the most popular platforms. I/O completion ports on windows,
|
||||||
|
epoll on linux and kqueue on MacOS X and BSD.
|
||||||
|
|
||||||
|
libtorrent has been successfully compiled and tested on:
|
||||||
|
|
||||||
|
* Windows 2000 vc7.1, vc8
|
||||||
|
* Linux x86 GCC 3.3, GCC 3.4.2
|
||||||
|
* MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0
|
||||||
|
* SunOS 5.8 GCC 3.1
|
||||||
|
* Cygwin GCC 3.3.3
|
||||||
|
|
||||||
|
Fails on:
|
||||||
|
|
||||||
|
* GCC 2.95.4
|
||||||
|
* msvc6
|
||||||
|
|
||||||
|
license
|
||||||
|
=======
|
||||||
|
|
||||||
|
libtorrent is released under the BSD-license_.
|
||||||
|
|
||||||
|
.. _BSD-license: http://www.opensource.org/licenses/bsd-license.php
|
||||||
|
|
||||||
|
This means that you can use the library in your project without having to
|
||||||
|
release its source code. The only requirement is that you give credit
|
||||||
|
to the author of the library by including the libtorrent license in your
|
||||||
|
software or documentation.
|
||||||
|
|
||||||
|
`Here's`__ a list of some projects that uses libtorrent.
|
||||||
|
|
||||||
|
__ projects.html
|
||||||
|
|
||||||
|
.. _`http seeding`: manual.html#http-seeding
|
||||||
|
.. _threads: manual.html#threads
|
||||||
|
.. _extensions: manual.html#extensions
|
||||||
|
|
|
@ -4,45 +4,37 @@
|
||||||
<head>
|
<head>
|
||||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||||
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
|
<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
|
||||||
<title>libtorrent</title>
|
<title></title>
|
||||||
<link rel="stylesheet" href="style.css" type="text/css" />
|
<link rel="stylesheet" href="style.css" type="text/css" />
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
<div class="document" id="libtorrent">
|
<div class="document">
|
||||||
<h1 class="title">libtorrent</h1>
|
<div id="librarySidebar"><ul class="simple">
|
||||||
<table border="1" class="menu docutils">
|
<li><a class="reference" href="features.html">features</a></li>
|
||||||
<colgroup>
|
<li><a class="reference" href="building.html">building libtorrent</a></li>
|
||||||
<col width="19%" />
|
<li><a class="reference" href="examples.html">examples</a></li>
|
||||||
<col width="14%" />
|
<li><a class="reference" href="manual.html">api documentation</a></li>
|
||||||
<col width="14%" />
|
<li><a class="reference" href="client_test.png">screenshot</a></li>
|
||||||
<col width="11%" />
|
<li><a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a></li>
|
||||||
<col width="15%" />
|
<li><a class="reference" href="projects.html">who's using libtorrent?</a></li>
|
||||||
<col width="26%" />
|
<li><a class="reference" href="http://sourceforge.net/tracker/?group_id=79942&atid=558250">report bugs</a></li>
|
||||||
</colgroup>
|
<li><a class="reference" href="http://www.sourceforge.net/projects/libtorrent">sourceforge page</a></li>
|
||||||
<tbody valign="top">
|
</ul>
|
||||||
<tr><td><a class="reference" href="http://www.sourceforge.net/projects/libtorrent">sourceforge page</a></td>
|
</div>
|
||||||
<td><a class="reference" href="manual.html">documentation</a></td>
|
<div id="libraryBody"><div class="section" id="libtorrent">
|
||||||
<td><a class="reference" href="http://sourceforge.net/tracker/?group_id=79942&atid=558250">report bugs</a></td>
|
<h1><a name="libtorrent">libtorrent</a></h1>
|
||||||
<td><a class="reference" href="client_test.png">screenshot</a></td>
|
|
||||||
<td><a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a></td>
|
|
||||||
<td><a class="reference" href="projects.html">who's using libtorrent?</a></td>
|
|
||||||
</tr>
|
|
||||||
</tbody>
|
|
||||||
</table>
|
|
||||||
<p>libtorrent is a C++ library that aims to be a good alternative to all the
|
<p>libtorrent is a C++ library that aims to be a good alternative to all the
|
||||||
other bittorrent implementations around. It is a
|
other bittorrent implementations around. It is a
|
||||||
library and not a full featured client, although it comes with a working
|
library and not a full featured client, although it comes with a working
|
||||||
<a class="reference" href="client_test.html">example client</a>.</p>
|
<a class="reference" href="client_test.html">example client</a>.</p>
|
||||||
<p>The main goals of libtorrent are:</p>
|
<p>The main goals of libtorrent are:</p>
|
||||||
<blockquote>
|
|
||||||
<ul class="simple">
|
<ul class="simple">
|
||||||
<li>to be cpu efficient</li>
|
<li>to be cpu efficient</li>
|
||||||
<li>to be memory efficient</li>
|
<li>to be memory efficient</li>
|
||||||
<li>to be very easy to use</li>
|
<li>to be very easy to use</li>
|
||||||
</ul>
|
</ul>
|
||||||
</blockquote>
|
|
||||||
<div class="section" id="donate">
|
<div class="section" id="donate">
|
||||||
<h1><a name="donate">Donate</a></h1>
|
<h2><a name="donate">Donate</a></h2>
|
||||||
<p>Support the development of libtorrent</p>
|
<p>Support the development of libtorrent</p>
|
||||||
<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
|
<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
|
||||||
<input type="hidden" name="cmd" value="_xclick">
|
<input type="hidden" name="cmd" value="_xclick">
|
||||||
|
@ -55,17 +47,18 @@ library and not a full featured client, although it comes with a working
|
||||||
border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
|
border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
|
||||||
</form></div>
|
</form></div>
|
||||||
<div class="section" id="feedback">
|
<div class="section" id="feedback">
|
||||||
<h1><a name="feedback">Feedback</a></h1>
|
<h2><a name="feedback">Feedback</a></h2>
|
||||||
<p>There's a <a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a>, general libtorrent discussion.</p>
|
<p>There's a <a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a>, general libtorrent discussion.</p>
|
||||||
<p>You can usually find me as hydri in <tt class="docutils literal"><span class="pre">#libtorrent</span></tt> on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
|
<p>You can usually find me as hydri in <tt class="docutils literal"><span class="pre">#libtorrent</span></tt> on <tt class="docutils literal"><span class="pre">irc.freenode.net</span></tt>.</p>
|
||||||
</div>
|
</div>
|
||||||
<div class="section" id="acknowledgements">
|
<div class="section" id="acknowledgements">
|
||||||
<h1><a name="acknowledgements">Acknowledgements</a></h1>
|
<h2><a name="acknowledgements">Acknowledgements</a></h2>
|
||||||
<p>Written by Arvid Norberg. Copyright (c) 2003</p>
|
<p>Written by Arvid Norberg. Copyright (c) 2003</p>
|
||||||
<p>Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
|
<p>Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
|
||||||
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</p>
|
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</p>
|
||||||
<p>Project is hosted by sourceforge.</p>
|
<p>Project is hosted by sourceforge.</p>
|
||||||
<p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
|
<p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
|
||||||
|
</div></div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</body>
|
</body>
|
||||||
|
|
|
@ -1,20 +1,36 @@
|
||||||
|
.. raw:: html
|
||||||
|
|
||||||
|
<div id="librarySidebar">
|
||||||
|
|
||||||
|
|
||||||
|
* features_
|
||||||
|
* `building libtorrent`_
|
||||||
|
* examples_
|
||||||
|
* `api documentation`_
|
||||||
|
* screenshot_
|
||||||
|
* `mailing list`_
|
||||||
|
* `who's using libtorrent?`_
|
||||||
|
* `report bugs`_
|
||||||
|
* `sourceforge page`_
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
|
||||||
|
</div>
|
||||||
|
<div id="libraryBody">
|
||||||
|
|
||||||
==========
|
==========
|
||||||
libtorrent
|
libtorrent
|
||||||
==========
|
==========
|
||||||
|
|
||||||
|
.. _features: features.html
|
||||||
.. class:: menu
|
.. _`building libtorrent`: building.html
|
||||||
|
.. _examples: examples.html
|
||||||
=================== ============== ============== =========== =============== ==========================
|
.. _`api documentation`: manual.html
|
||||||
`sourceforge page`_ documentation_ `report bugs`_ screenshot_ `mailing list`_ `who's using libtorrent?`_
|
|
||||||
=================== ============== ============== =========== =============== ==========================
|
|
||||||
|
|
||||||
.. _sourceforge page: http://www.sourceforge.net/projects/libtorrent
|
|
||||||
.. _documentation: manual.html
|
|
||||||
.. _`report bugs`: http://sourceforge.net/tracker/?group_id=79942&atid=558250
|
|
||||||
.. _screenshot: client_test.png
|
.. _screenshot: client_test.png
|
||||||
.. _mailing list: http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss
|
.. _mailing list: http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss
|
||||||
.. _`who's using libtorrent?`: projects.html
|
.. _`who's using libtorrent?`: projects.html
|
||||||
|
.. _`report bugs`: http://sourceforge.net/tracker/?group_id=79942&atid=558250
|
||||||
|
.. _sourceforge page: http://www.sourceforge.net/projects/libtorrent
|
||||||
|
|
||||||
libtorrent is a C++ library that aims to be a good alternative to all the
|
libtorrent is a C++ library that aims to be a good alternative to all the
|
||||||
other bittorrent implementations around. It is a
|
other bittorrent implementations around. It is a
|
||||||
|
@ -25,9 +41,9 @@ __ client_test.html
|
||||||
|
|
||||||
The main goals of libtorrent are:
|
The main goals of libtorrent are:
|
||||||
|
|
||||||
* to be cpu efficient
|
* to be cpu efficient
|
||||||
* to be memory efficient
|
* to be memory efficient
|
||||||
* to be very easy to use
|
* to be very easy to use
|
||||||
|
|
||||||
|
|
||||||
Donate
|
Donate
|
||||||
|
@ -76,4 +92,7 @@ Project is hosted by sourceforge.
|
||||||
.. |sf_logo| image:: http://sourceforge.net/sflogo.php?group_id=7994
|
.. |sf_logo| image:: http://sourceforge.net/sflogo.php?group_id=7994
|
||||||
__ http://sourceforge.net
|
__ http://sourceforge.net
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
|
932
docs/manual.html
932
docs/manual.html
File diff suppressed because it is too large
Load Diff
728
docs/manual.rst
728
docs/manual.rst
|
@ -1,6 +1,6 @@
|
||||||
=================
|
============================
|
||||||
libtorrent manual
|
libtorrent API Documentation
|
||||||
=================
|
============================
|
||||||
|
|
||||||
:Author: Arvid Norberg, arvid@rasterbar.com
|
:Author: Arvid Norberg, arvid@rasterbar.com
|
||||||
:Version: 0.11
|
:Version: 0.11
|
||||||
|
@ -9,481 +9,6 @@ libtorrent manual
|
||||||
:depth: 2
|
:depth: 2
|
||||||
:backlinks: none
|
:backlinks: none
|
||||||
|
|
||||||
introduction
|
|
||||||
============
|
|
||||||
|
|
||||||
libtorrent is a C++ library that aims to be a good alternative to all the
|
|
||||||
other bittorrent implementations around. It is a
|
|
||||||
library and not a full featured client, although it comes with a working
|
|
||||||
example client.
|
|
||||||
|
|
||||||
The main goals of libtorrent are:
|
|
||||||
|
|
||||||
* to be cpu efficient
|
|
||||||
* to be memory efficient
|
|
||||||
* to be very easy to use
|
|
||||||
|
|
||||||
libtorrent is still being developed, however it is stable. It is an ongoing
|
|
||||||
project (including this documentation). The current state includes the
|
|
||||||
following features:
|
|
||||||
|
|
||||||
* Trackerless torrents (using a kademlia DHT)
|
|
||||||
* multitracker extension support (as `specified by John Hoffman`__)
|
|
||||||
* serves multiple torrents on a single port and in a single thread
|
|
||||||
* gzipped tracker-responses
|
|
||||||
* `HTTP seeding`_, as `specified by Michael Burford of GetRight`__.
|
|
||||||
* piece picking on block-level (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.
|
|
||||||
* supports http proxies and proxy authentication
|
|
||||||
* uses separate threads for checking files and for main downloader, with a
|
|
||||||
fool-proof thread-safe library interface. (i.e. There's no way for the
|
|
||||||
user to cause a deadlock). (see threads_)
|
|
||||||
* 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,
|
|
||||||
but one can choose to trade 1 for 2 or any other ratio that isn't unfair
|
|
||||||
to the other party.
|
|
||||||
* fast resume support, a way to get rid of the costly piece check at the
|
|
||||||
start of a resumed torrent. Saves the storage state, piece_picker state
|
|
||||||
as well as all local peers in a separate fast-resume file.
|
|
||||||
* supports an `extension protocol`__. See extensions_.
|
|
||||||
* supports files > 2 gigabytes.
|
|
||||||
* supports the ``no_peer_id=1`` extension that will ease the load off trackers.
|
|
||||||
* supports the `udp-tracker protocol`__ by Olaf van der Spek.
|
|
||||||
* possibility to limit the number of connections.
|
|
||||||
* delays have messages if there's no other outgoing traffic to the peer, and
|
|
||||||
doesn't send have messages to peers that already has the piece. This saves
|
|
||||||
bandwidth.
|
|
||||||
* 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.
|
|
||||||
* supports the ``compact=1`` tracker parameter.
|
|
||||||
* selective downloading. The ability to select which parts of a torrent you
|
|
||||||
want to download.
|
|
||||||
* ip filter
|
|
||||||
|
|
||||||
__ http://home.elp.rr.com/tur/multitracker-spec.txt
|
|
||||||
__ http://www.getright.com/seedtorrent.html
|
|
||||||
__ extension_protocol.html
|
|
||||||
__ udp_tracker_protocol.html
|
|
||||||
|
|
||||||
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_ (shipped) and asio_ (shipped). At least version
|
|
||||||
1.33.1 of boost is required.
|
|
||||||
|
|
||||||
.. _zlib: http://www.zlib.org
|
|
||||||
.. _asio: http://asio.sf.net
|
|
||||||
|
|
||||||
Since libtorrent uses asio, it will take full advantage of high performance
|
|
||||||
network APIs on the most popular platforms. I/O completion ports on windows,
|
|
||||||
epoll on linux and kqueue on MacOS X and BSD.
|
|
||||||
|
|
||||||
libtorrent has been successfully compiled and tested on:
|
|
||||||
|
|
||||||
* Windows 2000 vc7.1, vc8
|
|
||||||
* Linux x86 GCC 3.3, GCC 3.4.2
|
|
||||||
* MacOS X (darwin), (Apple's) GCC 3.3, (Apple's) GCC 4.0
|
|
||||||
* SunOS 5.8 GCC 3.1
|
|
||||||
* Cygwin GCC 3.3.3
|
|
||||||
|
|
||||||
Fails on:
|
|
||||||
|
|
||||||
* GCC 2.95.4
|
|
||||||
* msvc6
|
|
||||||
|
|
||||||
libtorrent is released under the BSD-license_.
|
|
||||||
|
|
||||||
.. _BSD-license: http://www.opensource.org/licenses/bsd-license.php
|
|
||||||
|
|
||||||
This means that you can use the library in your project without having to
|
|
||||||
release its source code. The only requirement is that you give credit
|
|
||||||
to the author of the library by including the libtorrent license in your
|
|
||||||
software or documentation.
|
|
||||||
|
|
||||||
`Here's`__ a list of some projects that uses libtorrent.
|
|
||||||
|
|
||||||
__ projects.html
|
|
||||||
|
|
||||||
downloading and building
|
|
||||||
========================
|
|
||||||
|
|
||||||
To acquire the latest version of libtorrent, you'll have to grab it from CVS.
|
|
||||||
You'll find instructions on how to do this here__ (see Anonymous CVS access).
|
|
||||||
|
|
||||||
__ http://sourceforge.net/cvs/?group_id=79942
|
|
||||||
|
|
||||||
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 ``#libtorrent``
|
|
||||||
IRC channel on ``irc.freenode.net``.
|
|
||||||
|
|
||||||
|
|
||||||
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&package_id=8041&release_id=376197
|
|
||||||
|
|
||||||
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_1`` (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.1.
|
|
||||||
|
|
||||||
|
|
||||||
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_1\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_1\tools\build\v2``.
|
|
||||||
|
|
||||||
To set an environment variable in windows, type for example::
|
|
||||||
|
|
||||||
set BOOST_BUILD_PATH=c:\boost_1_33_1\tools\build\v2
|
|
||||||
|
|
||||||
In a terminal window.
|
|
||||||
|
|
||||||
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_1\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_1``.
|
|
||||||
|
|
||||||
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 link=static
|
|
||||||
bjam gcc-3.3 link=static
|
|
||||||
bjam darwin-4.0 link=static
|
|
||||||
|
|
||||||
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``.
|
|
||||||
|
|
||||||
You can build libtorrent as a dll too, by typing ``link=shared``, or
|
|
||||||
``link=static`` to build a static library. ``link=shared`` is the default.
|
|
||||||
|
|
||||||
If you want to explicitly say how to link against the runtime library, you
|
|
||||||
can set the ``runtime-link`` feature on the commandline, either to ``shared``
|
|
||||||
or ``static``. Most operating systems will only allow linking shared against
|
|
||||||
the runtime, but on windows you can do both. Example::
|
|
||||||
|
|
||||||
bjam msvc-7.1 link=static runtime-link=static
|
|
||||||
|
|
||||||
.. warning::
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
To build the examples, just change directory to the examples directory and
|
|
||||||
invoke ``bjam`` from there. To build and run the tests, go to the test
|
|
||||||
directory and run ``bjam``.
|
|
||||||
|
|
||||||
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
|
|
||||||
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
|
|
||||||
(``BOOST_BUILD_PATH`` and ``BOOST_ROOT``) should be in the typical unix-format (e.g.
|
|
||||||
``/cygdrive/c/boost_1_33_1``). In the windows environment, they should have the typical
|
|
||||||
windows format (``c:/boost_1_33_1``).
|
|
||||||
|
|
||||||
The ``Jamfile`` will define ``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_LOGGING``).
|
|
||||||
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
|
|
||||||
|
|
||||||
The logs created when building vlog or log mode are put in a directory called
|
|
||||||
``libtorrent_logs`` in the current working directory.
|
|
||||||
|
|
||||||
When building the example client on windows, you need to build with
|
|
||||||
``link=static`` otherwise you may get unresolved external symbols for some
|
|
||||||
boost.program-options symbols.
|
|
||||||
|
|
||||||
For more information, see the `Boost build v2 documentation`__.
|
|
||||||
|
|
||||||
__ http://www.boost.org/tools/build/v2/index.html
|
|
||||||
|
|
||||||
building with autotools
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
First of all, you need to install ``automake`` and ``autoconf``. Many
|
|
||||||
unix/linux systems comes with these preinstalled.
|
|
||||||
|
|
||||||
Step 1: Generating the build system
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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 `Step 2: Running configure`_.
|
|
||||||
|
|
||||||
Execute the following commands, in the given order, to generate
|
|
||||||
the build system:
|
|
||||||
|
|
||||||
* aclocal -I m4
|
|
||||||
* autoheader
|
|
||||||
* libtoolize --copy --force
|
|
||||||
* automake --add-missing --copy --gnu
|
|
||||||
* autoconf
|
|
||||||
|
|
||||||
|
|
||||||
Step 2: Running configure
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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 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 ``/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
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Creating a debug build
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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::
|
|
||||||
|
|
||||||
./configure --enable-debug=yes
|
|
||||||
|
|
||||||
Creating a release build
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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::
|
|
||||||
|
|
||||||
./configure --enable-debug=no
|
|
||||||
|
|
||||||
The above option make use of -DNDEBUG, which is used throughout libtorrent.
|
|
||||||
|
|
||||||
Step 3: Building libtorrent
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Once the configure script is run successfully, you just type ``make`` and
|
|
||||||
libtorrent, the examples and the tests will be built.
|
|
||||||
|
|
||||||
When libtorrent is built it may be a good idea to run the tests, you do this
|
|
||||||
by running ``make check``.
|
|
||||||
|
|
||||||
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. For a detailed description
|
|
||||||
on how to build libtorrent with VS 2005, see `this document`_.
|
|
||||||
|
|
||||||
.. _`this document`: vs2005_build_notes.html
|
|
||||||
|
|
||||||
|
|
||||||
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 |
|
|
||||||
+================================+=================================================+
|
|
||||||
| ``NDEBUG`` | If you define this macro, all asserts, |
|
|
||||||
| | invariant checks and general debug code will be |
|
|
||||||
| | removed. This option takes precedence over |
|
|
||||||
| | other debug settings. |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
| ``TORRENT_LOGGING`` | This macro will enable logging of the session |
|
|
||||||
| | events, such as tracker announces and incoming |
|
|
||||||
| | connections (as well as blocked connections). |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
| ``TORRENT_VERBOSE_LOGGING`` | If you define this macro, every peer connection |
|
|
||||||
| | will log its traffic to a log file as well as |
|
|
||||||
| | the session log. |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
| ``TORRENT_STORAGE_DEBUG`` | This will enable extra expensive invariant |
|
|
||||||
| | checks in the storage, including logging of |
|
|
||||||
| | piece sorting. |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
| ``UNICODE`` | 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. |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
| ``LITTLE_ENDIAN`` | This will use the little endian version of the |
|
|
||||||
| | sha-1 code. If defined on a big-endian system |
|
|
||||||
| | the sha-1 hashes will be incorrect and fail. |
|
|
||||||
| | If it is not defined and ``__BIG_ENDIAN__`` |
|
|
||||||
| | isn't defined either (it is defined by Apple's |
|
|
||||||
| | GCC) both little-endian and big-endian versions |
|
|
||||||
| | will be built and the correct code will be |
|
|
||||||
| | chosen at run-time. |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
| ``TORRENT_LINKING_SHARED`` | If this is defined when including the |
|
|
||||||
| | libtorrent headers, the classes and functions |
|
|
||||||
| | will be tagged with ``__declspec(dllimport)`` |
|
|
||||||
| | 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 |
|
|
||||||
| | ``link=shared`` is set). |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
| ``TORRENT_BUILDING_SHARED`` | If this is defined, the functions and classes |
|
|
||||||
| | in libtorrent are marked with |
|
|
||||||
| | ``__declspec(dllexport)`` 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 ``link=shared`` is set). |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
| ``TORRENT_DISABLE_DHT`` | If this is defined, the support for trackerless |
|
|
||||||
|Ê | torrents will be disabled. |
|
|
||||||
+--------------------------------+-------------------------------------------------+
|
|
||||||
|
|
||||||
|
|
||||||
If you experience that libtorrent uses unreasonable amounts of cpu, it will
|
|
||||||
definitely help to define ``NDEBUG``, since it will remove the invariant checks
|
|
||||||
within the library.
|
|
||||||
|
|
||||||
overview
|
overview
|
||||||
========
|
========
|
||||||
|
|
||||||
|
@ -517,7 +42,8 @@ The ``session`` class has the following synopsis::
|
||||||
{
|
{
|
||||||
|
|
||||||
session(fingerprint const& print
|
session(fingerprint const& print
|
||||||
= libtorrent::fingerprint("LT", 0, 1, 0, 0));
|
= libtorrent::fingerprint(
|
||||||
|
"LT", 0, 1, 0, 0));
|
||||||
|
|
||||||
session(
|
session(
|
||||||
fingerprint const& print
|
fingerprint const& print
|
||||||
|
@ -542,9 +68,11 @@ The ``session`` class has the following synopsis::
|
||||||
void remove_torrent(torrent_handle const& h);
|
void remove_torrent(torrent_handle const& h);
|
||||||
|
|
||||||
void disable_extensions();
|
void disable_extensions();
|
||||||
void enable_extension(peer_connection::extension_index);
|
void enable_extension(
|
||||||
|
peer_connection::extension_index);
|
||||||
|
|
||||||
void set_settings(session_settings const& settings);
|
void set_settings(
|
||||||
|
session_settings const& settings);
|
||||||
|
|
||||||
void set_upload_rate_limit(int bytes_per_second);
|
void set_upload_rate_limit(int bytes_per_second);
|
||||||
void set_download_rate_limit(int bytes_per_second);
|
void set_download_rate_limit(int bytes_per_second);
|
||||||
|
@ -567,9 +95,11 @@ The ``session`` class has the following synopsis::
|
||||||
|
|
||||||
void start_dht();
|
void start_dht();
|
||||||
void stop_dht();
|
void stop_dht();
|
||||||
void set_dht_settings(dht_settings const& settings);
|
void set_dht_settings(
|
||||||
|
dht_settings const& settings);
|
||||||
entry dht_state() const;
|
entry dht_state() const;
|
||||||
void add_dht_node(std::pair<std::string, int> const& node);
|
void add_dht_node(std::pair<std::string
|
||||||
|
, int> const& node);
|
||||||
|
|
||||||
};
|
};
|
||||||
|
|
||||||
|
@ -581,7 +111,8 @@ session()
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
session(fingerprint const& print = libtorrent::fingerprint("LT", 0, 1, 0, 0));
|
session(fingerprint const& print
|
||||||
|
= libtorrent::fingerprint("LT", 0, 1, 0, 0));
|
||||||
session(fingerprint const& print
|
session(fingerprint const& print
|
||||||
, std::pair<int, int> listen_port_range
|
, std::pair<int, int> listen_port_range
|
||||||
, char const* listen_interface = 0);
|
, char const* listen_interface = 0);
|
||||||
|
@ -1216,6 +747,8 @@ Returns an ``entry`` representing the bencoded tree of data that makes up a .tor
|
||||||
You can save this data as a torrent file with bencode() (see `bdecode() bencode()`_), for a
|
You can save this data as a torrent file with bencode() (see `bdecode() bencode()`_), for a
|
||||||
complete example, see make_torrent_.
|
complete example, see make_torrent_.
|
||||||
|
|
||||||
|
.. _make_torrent: examples.html#make_torrent
|
||||||
|
|
||||||
This function is not const because it will also set the info-hash of the ``torrent_info``
|
This function is not const because it will also set the info-hash of the ``torrent_info``
|
||||||
object.
|
object.
|
||||||
|
|
||||||
|
@ -3151,233 +2684,6 @@ doesn't meet the requirements on what information has to be present in a torrent
|
||||||
};
|
};
|
||||||
|
|
||||||
|
|
||||||
examples
|
|
||||||
========
|
|
||||||
|
|
||||||
Except for the example programs in this manual, there's also a bigger example
|
|
||||||
of a (little bit) more complete client, ``client_test``. There are separate
|
|
||||||
instructions for how to use it here__ if you'd like to try it.
|
|
||||||
|
|
||||||
__ client_test.html
|
|
||||||
|
|
||||||
dump_torrent
|
|
||||||
------------
|
|
||||||
|
|
||||||
This is an example of a program that will take a torrent-file as a parameter and
|
|
||||||
print information about it to std out::
|
|
||||||
|
|
||||||
|
|
||||||
#include <iostream>
|
|
||||||
#include <fstream>
|
|
||||||
#include <iterator>
|
|
||||||
#include <iomanip>
|
|
||||||
|
|
||||||
#include "libtorrent/entry.hpp"
|
|
||||||
#include "libtorrent/bencode.hpp"
|
|
||||||
#include "libtorrent/torrent_info.hpp"
|
|
||||||
|
|
||||||
|
|
||||||
int main(int argc, char* argv[])
|
|
||||||
{
|
|
||||||
using namespace libtorrent;
|
|
||||||
|
|
||||||
if (argc != 2)
|
|
||||||
{
|
|
||||||
std::cerr << "usage: dump_torrent torrent-file\n";
|
|
||||||
return 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
try
|
|
||||||
{
|
|
||||||
std::ifstream in(argv[1], std::ios_base::binary);
|
|
||||||
in.unsetf(std::ios_base::skipws);
|
|
||||||
entry e = bdecode(std::istream_iterator<char>(in), std::istream_iterator<char>());
|
|
||||||
|
|
||||||
std::cout << "\n\n----- raw info -----\n\n";
|
|
||||||
e.print(std::cout);
|
|
||||||
|
|
||||||
torrent_info t(e);
|
|
||||||
|
|
||||||
// print info about torrent
|
|
||||||
std::cout << "\n\n----- torrent file info -----\n\n";
|
|
||||||
std::cout << "trackers:\n";
|
|
||||||
for (std::vector<announce_entry>::const_iterator i = t.trackers().begin();
|
|
||||||
i != t.trackers().end(); ++i)
|
|
||||||
{
|
|
||||||
std::cout << i->tier << ": " << i->url << "\n";
|
|
||||||
}
|
|
||||||
|
|
||||||
std::cout << "number of pieces: " << t.num_pieces() << "\n";
|
|
||||||
std::cout << "piece length: " << t.piece_length() << "\n";
|
|
||||||
std::cout << "info hash: " << t.info_hash() << "\n";
|
|
||||||
std::cout << "comment: " << t.comment() << "\n";
|
|
||||||
std::cout << "created by: " << t.creator() << "\n";
|
|
||||||
std::cout << "files:\n";
|
|
||||||
for (torrent_info::file_iterator i = t.begin_files();
|
|
||||||
i != t.end_files(); ++i)
|
|
||||||
{
|
|
||||||
std::cout << " " << std::setw(11) << i->size
|
|
||||||
<< " " << i->path.string() << "\n";
|
|
||||||
}
|
|
||||||
|
|
||||||
}
|
|
||||||
catch (std::exception& e)
|
|
||||||
{
|
|
||||||
std::cout << e.what() << "\n";
|
|
||||||
}
|
|
||||||
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
simple client
|
|
||||||
-------------
|
|
||||||
|
|
||||||
This is a simple client. It doesn't have much output to keep it simple::
|
|
||||||
|
|
||||||
#include <iostream>
|
|
||||||
#include <fstream>
|
|
||||||
#include <iterator>
|
|
||||||
#include <exception>
|
|
||||||
|
|
||||||
#include <boost/format.hpp>
|
|
||||||
#include <boost/date_time/posix_time/posix_time.hpp>
|
|
||||||
|
|
||||||
#include "libtorrent/entry.hpp"
|
|
||||||
#include "libtorrent/bencode.hpp"
|
|
||||||
#include "libtorrent/session.hpp"
|
|
||||||
|
|
||||||
int main(int argc, char* argv[])
|
|
||||||
{
|
|
||||||
using namespace libtorrent;
|
|
||||||
|
|
||||||
if (argc != 2)
|
|
||||||
{
|
|
||||||
std::cerr << "usage: ./simple_cient torrent-file\n"
|
|
||||||
"to stop the client, press return.\n";
|
|
||||||
return 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
try
|
|
||||||
{
|
|
||||||
session s;
|
|
||||||
s.listen_on(std::make_pair(6881, 6889));
|
|
||||||
|
|
||||||
std::ifstream in(argv[1], std::ios_base::binary);
|
|
||||||
in.unsetf(std::ios_base::skipws);
|
|
||||||
entry e = bdecode(std::istream_iterator<char>(in)
|
|
||||||
, std::istream_iterator<char>());
|
|
||||||
s.add_torrent(torrent_info(e), "");
|
|
||||||
|
|
||||||
// wait for the user to end
|
|
||||||
char a;
|
|
||||||
std::cin.unsetf(std::ios_base::skipws);
|
|
||||||
std::cin >> a;
|
|
||||||
}
|
|
||||||
catch (std::exception& e)
|
|
||||||
{
|
|
||||||
std::cout << e.what() << "\n";
|
|
||||||
}
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
make_torrent
|
|
||||||
------------
|
|
||||||
|
|
||||||
Shows how to create a torrent from a directory tree::
|
|
||||||
|
|
||||||
#include <iostream>
|
|
||||||
#include <fstream>
|
|
||||||
#include <iterator>
|
|
||||||
#include <iomanip>
|
|
||||||
|
|
||||||
#include "libtorrent/entry.hpp"
|
|
||||||
#include "libtorrent/bencode.hpp"
|
|
||||||
#include "libtorrent/torrent_info.hpp"
|
|
||||||
#include "libtorrent/file.hpp"
|
|
||||||
#include "libtorrent/storage.hpp"
|
|
||||||
#include "libtorrent/hasher.hpp"
|
|
||||||
|
|
||||||
#include <boost/filesystem/operations.hpp>
|
|
||||||
#include <boost/filesystem/path.hpp>
|
|
||||||
#include <boost/filesystem/fstream.hpp>
|
|
||||||
|
|
||||||
using namespace boost::filesystem;
|
|
||||||
using namespace libtorrent;
|
|
||||||
|
|
||||||
void add_files(torrent_info& t, path const& p, path const& l)
|
|
||||||
{
|
|
||||||
path f(p / l);
|
|
||||||
if (is_directory(f))
|
|
||||||
{
|
|
||||||
for (directory_iterator i(f), end; i != end; ++i)
|
|
||||||
add_files(t, p, l / i->leaf());
|
|
||||||
}
|
|
||||||
else
|
|
||||||
{
|
|
||||||
std::cerr << "adding \"" << l.string() << "\"\n";
|
|
||||||
file fi(f, file::in);
|
|
||||||
fi.seek(0, file::end);
|
|
||||||
libtorrent::size_type size = fi.tell();
|
|
||||||
t.add_file(l, size);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
int main(int argc, char* argv[])
|
|
||||||
{
|
|
||||||
using namespace libtorrent;
|
|
||||||
using namespace boost::filesystem;
|
|
||||||
|
|
||||||
if (argc != 4)
|
|
||||||
{
|
|
||||||
std::cerr << "usage: make_torrent <output torrent-file> "
|
|
||||||
"<announce url> <file or directory to create torrent from>\n";
|
|
||||||
return 1;
|
|
||||||
}
|
|
||||||
|
|
||||||
boost::filesystem::path::default_name_check(native);
|
|
||||||
|
|
||||||
try
|
|
||||||
{
|
|
||||||
torrent_info t;
|
|
||||||
path full_path = initial_path() / path(argv[3]);
|
|
||||||
ofstream out(initial_path() / path(argv[1]), std::ios_base::binary);
|
|
||||||
|
|
||||||
int piece_size = 256 * 1024;
|
|
||||||
char const* creator_str = "libtorrent";
|
|
||||||
|
|
||||||
add_files(t, full_path.branch_path(), full_path.leaf());
|
|
||||||
t.set_piece_size(piece_size);
|
|
||||||
|
|
||||||
storage st(t, full_path.branch_path());
|
|
||||||
t.add_tracker(argv[2]);
|
|
||||||
|
|
||||||
// calculate the hash for all pieces
|
|
||||||
int num = t.num_pieces();
|
|
||||||
std::vector<char> buf(piece_size);
|
|
||||||
for (int i = 0; i < num; ++i)
|
|
||||||
{
|
|
||||||
st.read(&buf[0], i, 0, t.piece_size(i));
|
|
||||||
hasher h(&buf[0], t.piece_size(i));
|
|
||||||
t.set_hash(i, h.final());
|
|
||||||
std::cerr << (i+1) << "/" << num << "\r";
|
|
||||||
}
|
|
||||||
|
|
||||||
t.set_creator(creator_str);
|
|
||||||
|
|
||||||
// create the torrent and print it to out
|
|
||||||
entry e = t.create_torrent();
|
|
||||||
libtorrent::bencode(std::ostream_iterator<char>(out), e);
|
|
||||||
}
|
|
||||||
catch (std::exception& e)
|
|
||||||
{
|
|
||||||
std::cerr << e.what() << "\n";
|
|
||||||
}
|
|
||||||
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
fast resume
|
fast resume
|
||||||
===========
|
===========
|
||||||
|
|
||||||
|
|
|
@ -37,7 +37,7 @@ well). Written by Christophe Dumez.</p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr><td><p class="first"><strong>btg</strong></p>
|
<tr><td><p class="first"><strong>btg</strong></p>
|
||||||
<p><a class="reference" href="http://developer.berlios.de/projects/btg/">btg</a> is a <a href="#id1" name="id2"><span class="problematic" id="id2">*</span></a>nix bittorrent client
|
<p class="last"><a class="reference" href="http://developer.berlios.de/projects/btg/">btg</a> is a unix bittorrent client
|
||||||
which is run as a daemon. It has
|
which is run as a daemon. It has
|
||||||
multiple user interfaces which
|
multiple user interfaces which
|
||||||
connects to the daemon. One GUI
|
connects to the daemon. One GUI
|
||||||
|
@ -46,9 +46,6 @@ connects to the daemon. One GUI
|
||||||
(accessable through a web browser).
|
(accessable through a web browser).
|
||||||
Written by Michael Wojciechowski
|
Written by Michael Wojciechowski
|
||||||
and Johan Ström.</p>
|
and Johan Ström.</p>
|
||||||
<div class="last system-message" id="id1">
|
|
||||||
<p class="system-message-title">System Message: <a name="id1">WARNING/2</a> (<tt class="docutils">projects.rst</tt>, line 27); <em><a href="#id2">backlink</a></em></p>
|
|
||||||
Inline emphasis start-string without end-string.</div>
|
|
||||||
</td>
|
</td>
|
||||||
<td><div class="image first last"><img alt="btg_thumb.jpg" class="first last" src="btg_thumb.jpg" /></div>
|
<td><div class="image first last"><img alt="btg_thumb.jpg" class="first last" src="btg_thumb.jpg" /></div>
|
||||||
</td>
|
</td>
|
||||||
|
|
|
@ -23,7 +23,7 @@ project listed here, let me_ know.
|
||||||
+-------------------------------------+-----------------------------------------------+
|
+-------------------------------------+-----------------------------------------------+
|
||||||
| **btg** | .. image:: btg_thumb.jpg |
|
| **btg** | .. image:: btg_thumb.jpg |
|
||||||
| | |
|
| | |
|
||||||
| btg_ is a *nix bittorrent client | |
|
| btg_ is a unix bittorrent client | |
|
||||||
| which is run as a daemon. It has | |
|
| which is run as a daemon. It has | |
|
||||||
| multiple user interfaces which | |
|
| multiple user interfaces which | |
|
||||||
| connects to the daemon. One GUI | |
|
| connects to the daemon. One GUI | |
|
||||||
|
|
|
@ -274,6 +274,18 @@ dd pre {
|
||||||
|
|
||||||
li p, li li { font-size: 100%; }
|
li p, li li { font-size: 100%; }
|
||||||
|
|
||||||
|
#librarySidebar {
|
||||||
|
float: left;
|
||||||
|
width: 150px;
|
||||||
|
}
|
||||||
|
|
||||||
|
#libraryBody {
|
||||||
|
border-left: solid 1px #eee;
|
||||||
|
padding-left: 10px;
|
||||||
|
margin-left: 158px;
|
||||||
|
margin-right: 10px;
|
||||||
|
}
|
||||||
|
|
||||||
/* IE Hacks */
|
/* IE Hacks */
|
||||||
|
|
||||||
/* Hides from IE-mac \*/
|
/* Hides from IE-mac \*/
|
||||||
|
|
Loading…
Reference in New Issue