<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 <aclass="reference"href="http://sourceforge.net/cvs/?group_id=79942">here</a> (see Anonymous CVS access).</p>
<p>The build systems supported "out of the box" in libtorrent are boost-build v2
(BBv2) and autotools (for unix-like systems). If you still can't build after
following these instructions, you can usually get help in the <ttclass="docutils literal"><spanclass="pre">#libtorrent</span></tt>
IRC channel on <ttclass="docutils literal"><spanclass="pre">irc.freenode.net</span></tt>.</p>
<h2><aid="building-from-cvs"name="building-from-cvs">building from cvs</a></h2>
<p>To build libtorrent from cvs you need to check out the libtorrent sources from
sourceforge and also check out the asio sources from its sourceforge cvs.
If you downloaded a release tarball, you can skip this section.</p>
<p>To prepare the directory structure for building, follow these steps:</p>
<ulclass="simple">
<li>Check out libtorrent (<aclass="reference"href="http://sourceforge.net/cvs/?group_id=79942">instructions</a>).</li>
<li>Check out asio (<aclass="reference"href="http://sourceforge.net/cvs/?group_id=122478">instructions</a>).</li>
<li>Copy the <ttclass="docutils literal"><spanclass="pre">asio/include/asio/</span></tt> directory into the <ttclass="docutils literal"><spanclass="pre">libtorrent/include/libtorrent/</span></tt>
directory. Alternatively you can make a symbolic link.</li>
<li>Copy <ttclass="docutils literal"><spanclass="pre">asio/include/asio.hpp</span></tt> into <ttclass="docutils literal"><spanclass="pre">libtorrent/include/libtorrent</span></tt>.</li>
</ul>
<p>Now the libtorrent directory is ready for building. Follow the steps in one
of the following sections depending on which build system you prefer to use.</p>
<p>First you need to build <ttclass="docutils literal"><spanclass="pre">bjam</span></tt>. You do this by opening a terminal (In
windows, run <ttclass="docutils literal"><spanclass="pre">cmd</span></tt>). Change directory to
<ttclass="docutils literal"><spanclass="pre">c:\boost_1_33_1\tools\build\jam_src</span></tt>. Then run the script called
<ttclass="docutils literal"><spanclass="pre">build.bat</span></tt> or <ttclass="docutils literal"><spanclass="pre">build.sh</span></tt> on a unix system. This will build <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> and
place it in a directory starting with <ttclass="docutils literal"><spanclass="pre">bin.</span></tt> and then have the name of your
platform. Copy the <ttclass="docutils literal"><spanclass="pre">bjam.exe</span></tt> (or <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> on a unix system) to a place
that's in you shell's <ttclass="docutils literal"><spanclass="pre">PATH</span></tt>. On linux systems a place commonly used may be
<ttclass="docutils literal"><spanclass="pre">/usr/local/bin</span></tt> or on windows <ttclass="docutils literal"><spanclass="pre">c:\windows</span></tt> (you can also add directories
to the search paths by modifying the environment variable called <ttclass="docutils literal"><spanclass="pre">PATH</span></tt>).</p>
<p>Now you have <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> installed. <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> can be considered an interpreter
that the boost-build system is implemented on. So boost-build uses <ttclass="docutils literal"><spanclass="pre">bjam</span></tt>.
So, to complete the installation you need to make two more things. You need to
set the environment variable <ttclass="docutils literal"><spanclass="pre">BOOST_BUILD_PATH</span></tt>. This is the path that tells
<ttclass="docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">c:\boost_1_33_1\tools\build\v2</span></tt>.</p>
<p>To set an environment variable in windows, type for example:</p>
<preclass="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
<ttclass="docutils literal"><spanclass="pre">user-config.jam</span></tt> file. It is located in <ttclass="docutils literal"><spanclass="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>
<preclass="literal-block">
using msvc : 7.1 ;
</pre>
<p>If you use GCC, add the line:</p>
<preclass="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>
<preclass="literal-block">
using gcc : 3.3 : g++-3.3 ;
using gcc : 4.0 : g++-4.0 ;
</pre>
<p>Another toolset worth mentioning is the <ttclass="docutils literal"><spanclass="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>
<preclass="literal-block">
using darwin : 3.3 : g++-3.3 ;
using darwin : 4.0 : g++-4.0 ;
</pre>
<p>Note that the spaces around the semi-colons and colons are important!</p>
<p>When building libtorrent, the <ttclass="docutils literal"><spanclass="pre">Jamfile</span></tt> expects the environment variable
<ttclass="docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">c:\boost_1_33_1</span></tt>.</p>
<p>Then the only thing left is simply to invoke <ttclass="docutils literal"><spanclass="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>
<preclass="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 <ttclass="docutils literal"><spanclass="pre">release</span></tt>, <ttclass="docutils literal"><spanclass="pre">debug</span></tt>,
<p>You can build libtorrent as a dll too, by typing <ttclass="docutils literal"><spanclass="pre">link=shared</span></tt>, or
<ttclass="docutils literal"><spanclass="pre">link=static</span></tt> to build a static library. <ttclass="docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">runtime-link</span></tt> feature on the commandline, either to <ttclass="docutils literal"><spanclass="pre">shared</span></tt>
or <ttclass="docutils literal"><spanclass="pre">static</span></tt>. Most operating systems will only allow linking shared against
the runtime, but on windows you can do both. Example:</p>
<preclass="literal-block">
bjam msvc-7.1 link=static runtime-link=static
</pre>
<divclass="warning">
<pclass="first admonition-title">Warning</p>
<pclass="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
<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 <ttclass="docutils literal"><spanclass="pre">bjam</span></tt> from there. To build and run the tests, go to the test
directory and run <ttclass="docutils literal"><spanclass="pre">bjam</span></tt>.</p>
<p>Note that if you're building on windows using the <ttclass="docutils literal"><spanclass="pre">msvc</span></tt> toolset, you cannot run it
from a cygwin terminal, you'll have to run it from a <ttclass="docutils literal"><spanclass="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
(<ttclass="docutils literal"><spanclass="pre">BOOST_BUILD_PATH</span></tt> and <ttclass="docutils literal"><spanclass="pre">BOOST_ROOT</span></tt>) should be in the typical unix-format (e.g.
<ttclass="docutils literal"><spanclass="pre">/cygdrive/c/boost_1_33_1</span></tt>). In the windows environment, they should have the typical
windows format (<ttclass="docutils literal"><spanclass="pre">c:/boost_1_33_1</span></tt>).</p>
<p>The <ttclass="docutils literal"><spanclass="pre">Jamfile</span></tt> will define <ttclass="docutils literal"><spanclass="pre">NDEBUG</span></tt> when it's building a release build.
For more build configuration flags see <aclass="reference"href="#build-configurations">Build configurations</a>.</p>
<p>First of all, you need to install <ttclass="docutils literal"><spanclass="pre">automake</span></tt> and <ttclass="docutils literal"><spanclass="pre">autoconf</span></tt>. Many
unix/linux systems comes with these preinstalled.</p>
<p>On darwin/OSX you have to run <ttclass="docutils literal"><spanclass="pre">glibtoolize</span></tt> instead of <ttclass="docutils literal"><spanclass="pre">libtoolize</span></tt>.</p>
<p>In your shell, change directory to the libtorrent directory and run
<ttclass="docutils literal"><spanclass="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 <ttclass="docutils literal"><spanclass="pre">/opt/local/lib</span></tt> and headers are installed to
<ttclass="docutils literal"><spanclass="pre">/opt/local/include</span></tt>. By default the compiler will not look in these
directories. You have to set the enviornment variables <ttclass="docutils literal"><spanclass="pre">LDFLAGS</span></tt> and
<ttclass="docutils literal"><spanclass="pre">CXXFLAGS</span></tt> in order to make the compiler find those libs. In this example
you'd set them like this:</p>
<preclass="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 <ttclass="docutils literal"><spanclass="pre">~/.profile</span></tt> or <ttclass="docutils literal"><spanclass="pre">~/.tcshrc</span></tt> depending on your shell.</p>
<p>If you're making your own project file, note that there are two versions of
the file abstraction. There's one <ttclass="docutils literal"><spanclass="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, <ttclass="docutils literal"><spanclass="pre">file.cpp</span></tt> is the default implementation that simply relies
on the standard low level io routines (<ttclass="docutils literal"><spanclass="pre">read()</span></tt>, <ttclass="docutils literal"><spanclass="pre">write()</span></tt>, <ttclass="docutils literal"><spanclass="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
<ttclass="docutils literal"><spanclass="pre">file_win.cpp</span></tt> which supports unicode filenames.</p>
<p>If you're building in MS Visual Studio, you may have to set the compiler
options "force conformance in for loop scope", "treat wchar_t as built-in
type" and "Enable Run-Time Type Info" to Yes. For a detailed description
on how to build libtorrent with VS 2005, see <aclass="reference"href="vs2005_build_notes.html">this document</a>.</p>
