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

split the documentation up a bit

This commit is contained in:
Arvid Norberg 2006-08-28 00:36:00 +00:00
parent 22deb903db
commit 3f38ae9ef1
13 changed files with 1728 additions and 1548 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

377
docs/building.html Normal file
View File

@ -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&#64;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&#64;rasterbar.com">arvid&#64;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 &quot;out of the box&quot; 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&amp;package_id=8041&amp;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 &quot;force conformance in for loop scope&quot;, &quot;treat wchar_t as built-in
type&quot; and &quot;Enable Run-Time Type Info&quot; to Yes. 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>

386
docs/building.rst Normal file
View File

@ -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.

257
docs/examples.html Normal file
View File

@ -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&#64;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&#64;rasterbar.com">arvid&#64;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 &lt;iostream&gt;
#include &lt;fstream&gt;
#include &lt;iterator&gt;
#include &lt;iomanip&gt;
#include &quot;libtorrent/entry.hpp&quot;
#include &quot;libtorrent/bencode.hpp&quot;
#include &quot;libtorrent/torrent_info.hpp&quot;
int main(int argc, char* argv[])
{
using namespace libtorrent;
if (argc != 2)
{
std::cerr &lt;&lt; &quot;usage: dump_torrent torrent-file\n&quot;;
return 1;
}
try
{
std::ifstream in(argv[1], std::ios_base::binary);
in.unsetf(std::ios_base::skipws);
entry e = bdecode(std::istream_iterator&lt;char&gt;(in)
, std::istream_iterator&lt;char&gt;());
std::cout &lt;&lt; &quot;\n\n----- raw info -----\n\n&quot;;
e.print(std::cout);
torrent_info t(e);
// print info about torrent
std::cout &lt;&lt; &quot;\n\n----- torrent file info -----\n\n&quot;;
std::cout &lt;&lt; &quot;trackers:\n&quot;;
for (std::vector&lt;announce_entry&gt;::const_iterator i
= t.trackers().begin(); i != t.trackers().end(); ++i)
{
std::cout &lt;&lt; i-&gt;tier &lt;&lt; &quot;: &quot; &lt;&lt; i-&gt;url &lt;&lt; &quot;\n&quot;;
}
std::cout &lt;&lt; &quot;number of pieces: &quot; &lt;&lt; t.num_pieces() &lt;&lt; &quot;\n&quot;;
std::cout &lt;&lt; &quot;piece length: &quot; &lt;&lt; t.piece_length() &lt;&lt; &quot;\n&quot;;
std::cout &lt;&lt; &quot;info hash: &quot; &lt;&lt; t.info_hash() &lt;&lt; &quot;\n&quot;;
std::cout &lt;&lt; &quot;comment: &quot; &lt;&lt; t.comment() &lt;&lt; &quot;\n&quot;;
std::cout &lt;&lt; &quot;created by: &quot; &lt;&lt; t.creator() &lt;&lt; &quot;\n&quot;;
std::cout &lt;&lt; &quot;files:\n&quot;;
for (torrent_info::file_iterator i = t.begin_files();
i != t.end_files(); ++i)
{
std::cout &lt;&lt; &quot; &quot; &lt;&lt; std::setw(11) &lt;&lt; i-&gt;size
&lt;&lt; &quot; &quot; &lt;&lt; i-&gt;path.string() &lt;&lt; &quot;\n&quot;;
}
}
catch (std::exception&amp; e)
{
std::cout &lt;&lt; e.what() &lt;&lt; &quot;\n&quot;;
}
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 &lt;iostream&gt;
#include &lt;fstream&gt;
#include &lt;iterator&gt;
#include &lt;exception&gt;
#include &lt;boost/format.hpp&gt;
#include &lt;boost/date_time/posix_time/posix_time.hpp&gt;
#include &quot;libtorrent/entry.hpp&quot;
#include &quot;libtorrent/bencode.hpp&quot;
#include &quot;libtorrent/session.hpp&quot;
int main(int argc, char* argv[])
{
using namespace libtorrent;
if (argc != 2)
{
std::cerr &lt;&lt; &quot;usage: ./simple_cient torrent-file\n&quot;
&quot;to stop the client, press return.\n&quot;;
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&lt;char&gt;(in)
, std::istream_iterator&lt;char&gt;());
s.add_torrent(torrent_info(e), &quot;&quot;);
// wait for the user to end
char a;
std::cin.unsetf(std::ios_base::skipws);
std::cin &gt;&gt; a;
}
catch (std::exception&amp; e)
{
std::cout &lt;&lt; e.what() &lt;&lt; &quot;\n&quot;;
}
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 &lt;iostream&gt;
#include &lt;fstream&gt;
#include &lt;iterator&gt;
#include &lt;iomanip&gt;
#include &quot;libtorrent/entry.hpp&quot;
#include &quot;libtorrent/bencode.hpp&quot;
#include &quot;libtorrent/torrent_info.hpp&quot;
#include &quot;libtorrent/file.hpp&quot;
#include &quot;libtorrent/storage.hpp&quot;
#include &quot;libtorrent/hasher.hpp&quot;
#include &lt;boost/filesystem/operations.hpp&gt;
#include &lt;boost/filesystem/path.hpp&gt;
#include &lt;boost/filesystem/fstream.hpp&gt;
using namespace boost::filesystem;
using namespace libtorrent;
void add_files(torrent_info&amp; t, path const&amp; p, path const&amp; l)
{
path f(p / l);
if (is_directory(f))
{
for (directory_iterator i(f), end; i != end; ++i)
add_files(t, p, l / i-&gt;leaf());
}
else
{
std::cerr &lt;&lt; &quot;adding \&quot;&quot; &lt;&lt; l.string() &lt;&lt; &quot;\&quot;\n&quot;;
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 &lt;&lt; &quot;usage: make_torrent &lt;output torrent-file&gt; &quot;
&quot;&lt;announce url&gt; &lt;file or directory to create torrent from&gt;\n&quot;;
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 = &quot;libtorrent&quot;;
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&lt;char&gt; buf(piece_size);
for (int i = 0; i &lt; num; ++i)
{
st.read(&amp;buf[0], i, 0, t.piece_size(i));
hasher h(&amp;buf[0], t.piece_size(i));
t.set_hash(i, h.final());
std::cerr &lt;&lt; (i+1) &lt;&lt; &quot;/&quot; &lt;&lt; num &lt;&lt; &quot;\r&quot;;
}
t.set_creator(creator_str);
// create the torrent and print it to out
entry e = t.create_torrent();
libtorrent::bencode(std::ostream_iterator&lt;char&gt;(out), e);
}
catch (std::exception&amp; e)
{
std::cerr &lt;&lt; e.what() &lt;&lt; &quot;\n&quot;;
}
return 0;
}
</pre>
</div>
</div>
</div>
</body>
</html>

238
docs/examples.rst Normal file
View File

@ -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;
}

124
docs/features.html Normal file
View File

@ -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&#64;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&#64;rasterbar.com">arvid&#64;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 &gt; 2 gigabytes.</li>
<li>supports the <tt class="docutils literal"><span class="pre">no_peer_id=1</span></tt> extension that will ease the load off trackers.</li>
<li>supports the <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>

123
docs/features.rst Normal file
View File

@ -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

47
docs/index.html
View File

@ -4,45 +4,37 @@
<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</title>
<title></title>
<link rel="stylesheet" href="style.css" type="text/css" />
</head>
<body>
<div class="document" id="libtorrent">
<h1 class="title">libtorrent</h1>
<table border="1" class="menu docutils">
<colgroup>
<col width="19%" />
<col width="14%" />
<col width="14%" />
<col width="11%" />
<col width="15%" />
<col width="26%" />
</colgroup>
<tbody valign="top">
<tr><td><a class="reference" href="http://www.sourceforge.net/projects/libtorrent">sourceforge page</a></td>
<td><a class="reference" href="manual.html">documentation</a></td>
<td><a class="reference" href="http://sourceforge.net/tracker/?group_id=79942&amp;atid=558250">report bugs</a></td>
<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>
<div class="document">
<div id="librarySidebar"><ul class="simple">
<li><a class="reference" href="features.html">features</a></li>
<li><a class="reference" href="building.html">building libtorrent</a></li>
<li><a class="reference" href="examples.html">examples</a></li>
<li><a class="reference" href="manual.html">api documentation</a></li>
<li><a class="reference" href="client_test.png">screenshot</a></li>
<li><a class="reference" href="http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss">mailing list</a></li>
<li><a class="reference" href="projects.html">who's using libtorrent?</a></li>
<li><a class="reference" href="http://sourceforge.net/tracker/?group_id=79942&amp;atid=558250">report bugs</a></li>
<li><a class="reference" href="http://www.sourceforge.net/projects/libtorrent">sourceforge page</a></li>
</ul>
</div>
<div id="libraryBody"><div class="section" id="libtorrent">
<h1><a name="libtorrent">libtorrent</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
<a class="reference" href="client_test.html">example client</a>.</p>
<p>The main goals of libtorrent are:</p>
<blockquote>
<ul class="simple">
<li>to be cpu efficient</li>
<li>to be memory efficient</li>
<li>to be very easy to use</li>
</ul>
</blockquote>
<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>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
<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!">
</form></div>
<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>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 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>Contributions by Magnus Jonsson, Daniel Wallin and Cory Nelson</p>
<p>Thanks to Reimond Retz for bugfixes, suggestions and testing</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>
</div></div>
</div>
</div>
</body>

45
docs/index.rst
View File

@ -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
==========
.. class:: menu
=================== ============== ============== =========== =============== ==========================
`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
.. _features: features.html
.. _`building libtorrent`: building.html
.. _examples: examples.html
.. _`api documentation`: manual.html
.. _screenshot: client_test.png
.. _mailing list: http://lists.sourceforge.net/lists/listinfo/libtorrent-discuss
.. _`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
other bittorrent implementations around. It is a
@ -25,9 +41,9 @@ __ client_test.html
The main goals of libtorrent are:
* to be cpu efficient
* to be memory efficient
* to be very easy to use
* to be cpu efficient
* to be memory efficient
* to be very easy to use
Donate
@ -76,4 +92,7 @@ Project is hosted by sourceforge.
.. |sf_logo| image:: http://sourceforge.net/sflogo.php?group_id=7994
__ http://sourceforge.net
.. raw:: html
</div>

932
docs/manual.html
View File

File diff suppressed because it is too large Load Diff

728
docs/manual.rst
View File

@ -1,6 +1,6 @@
=================
libtorrent manual
=================
============================
libtorrent API Documentation
============================
:Author: Arvid Norberg, arvid@rasterbar.com
:Version: 0.11
@ -9,481 +9,6 @@ libtorrent manual
: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
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
========
@ -517,7 +42,8 @@ The ``session`` class has the following synopsis::
{
session(fingerprint const& print
= libtorrent::fingerprint("LT", 0, 1, 0, 0));
= libtorrent::fingerprint(
"LT", 0, 1, 0, 0));
session(
fingerprint const& print
@ -542,9 +68,11 @@ The ``session`` class has the following synopsis::
void remove_torrent(torrent_handle const& h);
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_download_rate_limit(int bytes_per_second);
@ -567,9 +95,11 @@ The ``session`` class has the following synopsis::
void start_dht();
void stop_dht();
void set_dht_settings(dht_settings const& settings);
void set_dht_settings(
dht_settings const& settings);
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
, std::pair<int, int> listen_port_range
, 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
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``
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
===========

5
docs/projects.html
View File

@ -37,7 +37,7 @@ well). Written by Christophe Dumez.</p>
</td>
</tr>
<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
multiple user interfaces which
connects to the daemon. One GUI
@ -46,9 +46,6 @@ connects to the daemon. One GUI
(accessable through a web browser).
Written by Michael Wojciechowski
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><div class="image first last"><img alt="btg_thumb.jpg" class="first last" src="btg_thumb.jpg" /></div>
</td>

2
docs/projects.rst
View File

@ -23,7 +23,7 @@ project listed here, let me_ know.
+-------------------------------------+-----------------------------------------------+
| **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 | |
| multiple user interfaces which | |
| connects to the daemon. One GUI | |

12
docs/style.css
View File

@ -274,6 +274,18 @@ dd pre {
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 */
/* Hides from IE-mac \*/