Downloading and installing the library

Download

In order to download libtins, please visit project's github page.

It is highly recommended that you download the latest source code so you are less likely to encounter bugs and you will have access to more features. Using the following links you can download it:

Or clone the git repository by executing: 

git clone https://github.com/mfontanini/libtins.git

Download binary/precompiled distributions

There are some precompiled versions of the library that you can download so you don't have to compile it yourself.

Windows

The library is automatically built after every commit to the master branch on Windows using the appveyor platform

You can get the the latest version of the Windows binary package, compiled using Visual Studio 2013, here. You can pick between a 32 and 64 bits build, using debug or release mode (make sure to pick the right one or you'll get linker errors if you compile your code in debug mode and try to link with libtins compiled in release mode).

You will find the appropriate .zip file inside the "artifacts" tab.

In order to use it, just unpack the package into a directory and then add the include folder into your application's include directories, and add the tins.lib file as a linker dependency.

Please have a look at the using on Windows section and see some notes on how to use it.

OSX

You can install the latest version of libtins (3.3) on OSX using homebrew: 

homebrew install libtins

Compilation requirements

libtins depends on both, libpcap and libcrypto. The latter is provided by the OpenSSL library and it is only required if you want to allow WPA2 decryption. This feature can be disabled by using -DLIBTINS_ENABLE_WPA2=0 while executing CMake.

Since version 3.1, libtins started using CMake as its build system. Therefore, you also need it in order to compile the library.

You should be able to install both libraries and CMake through your distribution's package manager.

For Debian based systems(Ubuntu, Linux Mint, etc), you can install them by executing this command as root: 

apt-get install libpcap-dev libssl-dev cmake

For Red Hat based systems(RHEL, Fedora, CentOS, etc), you can install them by executing the following command as root: 

yum install libpcap-devel openssl-devel cmake

For Windows, you can download binary distribution of CMake from their website. You should do the same for OpenSSL if you want to enable WPA2 decryption support.

You should also download the WinPCAP developer package, which is the Windows version of libpcap.

Compiling libtins on Linux/BSD/OSX

Now you've got everything you need for compiling libtins. In order to compile, just execute the following commands: 

mkdir build
cd build
cmake ../
make

If you want to enable C++11 support(many non-copyable classes will be movable, plus, it will run faster), use the -DLIBTINS_ENABLE_CXX11=1 switch: 

cmake ../ -DLIBTINS_ENABLE_CXX11=1

Now you've compiled the library. The shared object will be located in the .libs directory. If you want to install libtins in the default include and library path, so you can use it easily in your applications, run this command as root: 

make install

This will tipically install the shared objects in /usr/local/lib and the header files in /usr/local/include.

Note that unless you want to restart your system before using the library, you'll probably need to update ldconfig's cache, by issuing: 

ldconfig

Compiling libtins on Windows

Compiling libtins on Windows has been made easy since version 3.1. The next steps asume you are using Visual Studio, and you have installed both CMake and the Winpcap developer pack.

First, open a console (cmd.exe, git bash, MSYS, any will do) and cd into the directory in which libtins sources are located. Now execute the following commands, using the path to the WinPCAP developer pack: 

mkdir build
cd build
# Replace with the WinPCAP developer pack path
# This disables WPA2 decryption.
cmake ../ -DPCAP_ROOT_DIR=PathTo_WinPCAP_DevPack -DLIBTINS_ENABLE_WPA2=0 -DLIBTINS_BUILD_SHARED=0

Now, this will have generated a Visual Studio solution. You have to choices:

Compiling using Visual Studio

The first one is to open the generated solution and compile it from Visual Studio. In order to do so, open the file build/libtins.sln. Then select the "tins" project, and build it. You might want to compile in Release mode, which can be selected from the Build menu.

Compiling using CMake

You can also compile directly using CMake. The only drawback here is that you can't select a Release mode compilation. If you are okay with this, execute: 

cmake --build .

The generated .lib file will be in build/lib/Debug/.

Despite the compilation method you used, you should have a look at the notes on using libtins on Windows.

Using libtins

Once you have compiled libtins, using it is just as simple as including the appropriate headers and linking against it.

Headers

libtins' headers are inside a directory named tins, inside your default include directory. You can include individual headers, or just #include <tins/tins.h>, which will include all of them.

Linking

In order to link your application with libtins on GCC or clang, use the -ltins flag: 

g++ app.cpp -o app -ltins

Using libtins on Windows

If you are using a static build of libtins on Windows, then you have link your application with tins.lib. You also need to add this macro definition to your project: 

TINS_STATIC

This will make your project use libtins without trying to import symbols from a DLL but from the static library.

You will also need to include the following linker dependencies on your project: 

Ws2_32.lib
Iphlpapi.lib
wpcap.lib

The first two will be found by the compiler, so you don't need to provide a full path. The latter is WinPCAP's static library, which comes with the developers pack.