premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity

update build docs

This commit is contained in:
arvidn 2018-10-12 10:09:43 +02:00 committed by Arvid Norberg
parent fbf9f73d43
commit 7608598da8
1 changed files with 120 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
docs/building.rst
View File

@ -71,12 +71,15 @@ to step 3 (assuming you also have boost build installed).
Step 1: Download boost
~~~~~~~~~~~~~~~~~~~~~~
If you want to build against boost installed on your system, you can skip this
strep. Just make sure to have `BOOST_ROOT` unset for the `b2` invocation.
You'll find boost here__.
__ https://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041&release_id=619445
__ https://www.boost.org/users/download/#live
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_64_0`` (I'm using
guide, let's assume you extract the package to ``c:\boost_1_68_0`` (I'm using
a windows path in this example since if you're on linux/unix you're more likely
to use the autotools). You'll need at least version 1.49 of the boost library
in order to build libtorrent.
@ -85,39 +88,41 @@ in order to build libtorrent.
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_64_0\tools\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``).
If you have installed ``boost-build`` via a package manager, you can skip this
step. If not, you need to build boost build from the boost source package.
Now you have ``bjam`` installed. ``bjam`` can be considered an interpreter
that the boost-build system is implemented on. So boost-build uses ``bjam``.
First you need to build ``b2``. You do this by opening a terminal (In windows,
run ``cmd``). Change directory to ``c:\boost_1_68_0\tools\build``. Then run the
script called ``bootstrap.bat`` or ``bootstrap.sh`` on a unix system. This will
build ``b2`` and place it in a directory ``src/engine/bin.<os-architecture>``.
Copy the ``b2.exe`` (or ``b2`` 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 ``b2`` installed. ``b2`` can be considered an interpreter
that the boost-build system is implemented on. So boost-build uses ``b2``.
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
``b2`` 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_64_0\tools\build\v2``.
it to ``c:\boost_1_68_0\tools\build``.
To set an environment variable in windows, type for example::
set BOOST_BUILD_PATH=c:\boost_1_64_0\tools\build\v2
set BOOST_BUILD_PATH=c:\boost_1_68_0\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_64_0\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 12 (2013), just add a line::
The last thing to do is to configure which compiler(s) to use. Create a file
``user-config.jam`` in your home directory. Depending on your platform and which
compiler you're using, you should add a line for each compiler and compiler
version you have installed on your system that you want to be able to use with
BBv2. For example, if you're using Microsoft Visual Studio 12 (2013), just add a
line::
using msvc : 12.0 ;
using msvc : 14.0 ;
If you use GCC, add the line::
@ -126,8 +131,8 @@ If you use GCC, add the line::
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 ;
using gcc : 6.0 : g++-6 ;
using gcc : 7.0 : g++-7 ;
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
@ -146,25 +151,26 @@ Also see the `official installation instructions`_.
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_64_0``. You only need this if you're
building against a source distribution of boost.
When building libtorrent, boost is either picked up from system installed
locations or from a boost source package, if the ``BOOST_ROOT`` environment
variable is set pointing to one. If you're building boost from source, set
``BOOST_ROOT`` to your boost directory, e.g. ``c:\boost_1_68_0``.
Then the only thing left is simply to invoke ``bjam``. If you want to specify
Then the only thing left is simply to invoke ``b2``. If you want to specify
a specific toolset to use (compiler) you can just add that to the commandline.
For example::
bjam msvc-7.1
bjam gcc-3.3
bjam darwin-4.0
b2 msvc-14.0
b2 gcc-7.0
b2 darwin-4.0
.. note::
If the environment variable ``BOOST_ROOT`` is not set, the jamfile will
attempt to link against "installed" boost libraries. i.e. assume the headers
and libraries are available in default search paths.
In this case it's critical that you build your project with the same version
of C++ and the same build flags as the system libraries were built with.
To build different versions you can also just add the name of the build
variant. Some default build variants in BBv2 are ``release``, ``debug``,
@ -178,13 +184,13 @@ 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
b2 msvc-14.0 link=static runtime-link=static
.. note::
When building on windows, the path boost-build puts targets in may be too
long. If you get an error message like: "The input line is long", try to
pass --abbreviate-paths on the bjam command line.
pass --hash on the ``b2`` command line.
.. warning::
@ -193,40 +199,32 @@ the runtime, but on windows you can do both. Example::
and in the client application. It will result in crashes and possibly link
errors.
.. note::
With boost-build V2 (Milestone 11), the darwin toolset uses the ``-s`` linker
option to strip debug symbols. This option is buggy in Apple's GCC, and
will make the executable crash on startup. On Mac OS X, instead build
your release executables with the ``debug-symbols=on`` option, and
later strip your executable with ``strip``.
.. note::
Some linux systems requires linking against ``librt`` in order to access
the POSIX clock functions. If you get an error complaining about a missing
symbol ``clock_gettime``, you have to give ``need-librt=yes`` on the
bjam command line. This will make libtorrent link against ``librt``.
b2 command line. This will make libtorrent link against ``librt``.
.. note::
When building on Solaris, you might have to specify ``stdlib=sun-stlport``
on the bjam command line.
When building on Solaris, you may have to specify ``stdlib=sun-stlport``
on the b2 command line.
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``.
invoke ``b2`` from there. To build and run the tests, go to the test
directory and run ``b2``.
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_64_0``). In the windows environment, they should have the typical
windows format (``c:/boost_1_64_0``).
``/cygdrive/c/boost_1_68_0``). In the windows environment, they should have the typical
windows format (``c:/boost_1_68_0``).
.. note::
In Jamfiles, spaces are separators. It's typically easiest to avoid spaces
@ -313,13 +311,11 @@ Build features:
| | * ``pre1.1`` - link against the old windows names |
| | (i.e. ``ssleay32`` and ``libeay32``. |
+--------------------------+----------------------------------------------------+
| ``allocator`` | * ``pool`` - default, uses pool allocators for |
| ``piece-allocator`` | * ``valloc`` - default, uses ``valloc()`` or |
| | ``_aligned_malloc()`` for disk cache blocks. |
| | send buffers. |
| | * ``system`` - uses ``malloc()`` and ``free()`` |
| | instead. Might be useful to debug buffer issues |
| | with tools like electric fence or libgmalloc. |
| | * ``debug`` - instruments buffer usage to catch |
| | bugs in libtorrent. |
| | * ``memalign`` - uses ``memalign()``. |
| | * ``posix_memalign`` - uses ``posix_memalign()``. |
+--------------------------+----------------------------------------------------+
| ``link`` | * ``static`` - builds libtorrent as a static |
| | library (.a / .lib) |
@ -377,6 +373,26 @@ Build features:
| | is written with stack traces of blocking calls |
| | ordered by the number of them. |
+--------------------------+----------------------------------------------------+
| ``utp-log`` | * ``off`` - default. Do not print verbose uTP |
| | log. |
| | * ``on`` - Print verbose uTP log, used to debug |
| | the uTP implementation. |
+--------------------------+----------------------------------------------------+
| ``picker-debugging`` | * ``off`` - no extra invariant checks in piece |
| | picker. |
| | * ``on`` - include additional invariant checks in |
| | piece picker. Used for testing the piece picker. |
+--------------------------+----------------------------------------------------+
| ``extensions`` | * ``on`` - enable extensions to the bittorrent |
| | protocol. |
| | * ``off`` - disable bittorrent extensions. |
+--------------------------+----------------------------------------------------+
| ``pic`` | * ``off`` - default. Build without specifying |
| | ``-fPIC``. |
| | * ``on`` - Force build with ``-fPIC`` (useful for |
| | building a static library to be linked into a |
| | shared library). |
+--------------------------+----------------------------------------------------+
The ``variant`` feature is *implicit*, which means you don't need to specify
the name of the feature, just the value.
@ -391,124 +407,73 @@ boost.program-options symbols.
For more information, see the `Boost build v2 documentation`__, or more
specifically `the section on builtin features`__.
__ https://www.boost.org/tools/build/v2/index.html
__ https://www.boost.org/doc/html/bbv2/reference.html#bbv2.advanced.builtins.features
__ https://boostorg.github.io/build/manual/develop/index.html
__ https://boostorg.github.io/build/manual/develop/index.html#bbv2.overview.builtins.features
building with autotools
-----------------------
building with cmake
-------------------
First of all, you need to install ``automake`` and ``autoconf``. Many
unix/linux systems comes with these preinstalled.
The prerequisites for building libtorrent are boost.system, boost.chrono and
boost.random. Those are the *compiled* boost libraries needed. The headers-only
libraries needed include (but is not necessarily limited to)
boost.multi_index, boost.optional, boost.multiprecision,
boost.iterator, boost.preprocessor, boost.static_assert, boost.intrusive.
First of all, you need to install ``cmake``. Additionally you need a build
system to actually schedule builds, for example ``ninja``.
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`_.
Run ``cmake`` in the libtorrent root directory, like this::
Execute the following command to generate the build system::
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_STANDARD=11 -G Ninja .
./autotool.sh
The ``CMAKE_CXX_STANDARD`` has to be at least 11, but you may want to raise it
to ``14`` or ``17`` if your project use a newer version of the C++ standard.
Step 2: Running configure
~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
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 detection of boost sometimes fail in subtle ways. If you have the
``BOOST_ROOT`` environment variable set, it may find the pre-built system
libraries, but use the header files from your source package. To avoid this,
invoke ``cmake`` with ``BOOST_ROOT`` set to an empty string:
``BOOST_ROOT="" cmake ...``.
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::
Other build options are:
export LDFLAGS=-L/opt/local/lib
export CXXFLAGS=-I/opt/local/include
+-----------------------+---------------------------------------------------+
| ``BUILD_SHARED_LIBS`` | Defaults ``ON``. Builds libtorrent as a shared |
| | library. |
+-----------------------+---------------------------------------------------+
| ``static_runtime`` | Defaults ``OFF``. Link libtorrent statically |
| | against the runtime libraries. |
+-----------------------+---------------------------------------------------+
| ``build_tests`` | Defaults ``OFF``. Also build the libtorrent |
| | testa. |
+-----------------------+---------------------------------------------------+
| ``build_examples`` | Defaults ``OFF``. Also build the examples in the |
| | examples directory. |
+-----------------------+---------------------------------------------------+
| ``build_tools`` | Defaults ``OFF``. Also build the tools in the |
| | tools directory. |
+-----------------------+---------------------------------------------------+
| ``python-bindings`` | Defaults ``OFF``. Also build the python bindings |
| | in bindings/python directory. |
+-----------------------+---------------------------------------------------+
| ``encryption`` | Defaults ``ON``. Support trackers and bittorrent |
| | over TLS, and obfuscated bittorrent connections. |
+-----------------------+---------------------------------------------------+
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.
Options are set on the ``cmake`` command line with the ``-D`` option.
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.
If the boost libraries are named with a suffix on your platform, you may use
the ``--with-boost-thread=`` option to specify the suffix used for the thread
library in this case. For more information about these options, run::
./configure --help
On gentoo the boost libraries that are built with multi-threading support have
the suffix ``mt``.
You know that the boost libraries were found if you see the following output
from the configure script::
Checking for boost libraries:
checking for boostlib >= 1.53... yes
checking whether the Boost::System library is available... yes
checking for exit in -lboost_system... yes
checking whether the Boost::Chrono library is available... yes
checking for exit in -lboost_chrono-mt... yes
checking whether the Boost::Random library is available... yes
checking for exit in -lboost_random-mt... 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
Step 2: Building libtorrent
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once the configure script is run successfully, you just type ``make`` and
libtorrent, the examples and the tests will be built.
In the terminal, run::
When libtorrent is built it may be a good idea to run the tests, you do this
by running ``make check``.
ninja -j8
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::
(the number after 8 specifies the number of parallel jobs to build in).
./configure --disable-debug
make clean
make
If you enabled test in the configuration step, to run them, run::
ctest -j8
building with other build systems
---------------------------------