Getting Started

Downloading an official release

You can find links to the latest official release from the project’s official website:

All previous stable versions of cpp-netlib can be downloaded from Github from this url:

Each release is available as gzipped (Using the command tar xzf cpp-netlib.tar.gz) or bzipped (Using tar xjf cpp-netlib.tar.bz2) tarball, or as a zipfile (unzip cpp-netlib.zip, or on Windows using a tool such as 7zip).

Downloading a development version

The cpp-netlib uses Git for source control, so to use any development versions Git must be installed on your system.

Using the command line, the command to get the latest code is:

shell$ git clone git://github.com/cpp-netlib/cpp-netlib.git

This should be enough information get to started. To do more complex things with Git, such as pulling changes or checking out a new branch, refer to the Git documentation.

Note

Previous versions of cpp-netlib referred to the mikhailberis repository as the main development repository. This account is still valid, but not always up-to-date. In the interest of consistency, the main repository has been changed to cpp-netlib.

Windows users need to use msysGit, and to invoke the command above from a shell.

For fans of Subversion, the same code can be checked out from http://svn.github.com/cpp-netlib/cpp-netlib.git.

Note

The cpp-netlib project is hosted on GitHub and follows the prescribed development model for GitHub based projects. This means in case you want to submit patches, you will have to create a fork of the project (read up on forking) and then submit a pull request (read up on submitting pull requests).

Getting Boost

cpp-netlib depends on Boost. It should work for any version of Boost above 1.58.0. If Boost is not installed on your system, the latest package can be found on the Boost web-site. The environment variable BOOST_ROOT must be defined, which must be the full path name of the top directory of the Boost distribution. Although Boost is mostly header only, applications built using cpp-netlib still requires linking with Boost.System, Boost.Date_time, and Boost.Regex.

Note

You can follow the steps in the Boost Getting Started guide to install Boost into your development system.

Warning

There is a known incompatibility between cpp-netlib and Boost 1.46.1 on some compilers. It is not recommended to use cpp-netlib with Boost 1.46.1. Some have reported though that Boost 1.47.0 and cpp-netlib work together better.

Getting CMake

The cpp-netlib uses CMake to generate platform-specific build files. If you intend to run the test suite, you can follow the instructions below. The cpp-netlib requires CMake version 2.8 or higher.

Let’s assume that you have unpacked the cpp-netlib at the top of your HOME directory. On Unix-like systems you will typically be able to change into your HOME directory using the command cd ~. This sample below assumes that the ~/cpp-netlib directory exists, and is the top-level directory of the cpp-netlib release.

Building with CMake

To build the tests that come with cpp-netlib, we first need to configure the build system to use our compiler of choice. This is done by running the cmake command at the top-level directory of cpp-netlib with additional parameters:

$ mkdir ~/cpp-netlib-build
$ cd ~/cpp-netlib-build
$ cmake -DCMAKE_BUILD_TYPE=Debug \
>       -DCMAKE_C_COMPILER=gcc   \
>       -DCMAKE_CXX_COMPILER=g++ \
>       ../cpp-netlib

Note

While it’s not compulsory, it’s recommended that cpp-netlib is built outside the source directory. For the purposes of documentation, we’ll assume that all builds are done in ~/cpp-netlib-build.

If you intend to use the SSL support when using the HTTP client libraries in cpp-netlib, you may need to build it with OpenSSL installed or at least available to CMake. If you have the development headers for OpenSSL installed on your system when you build cpp-netlib, CMake will be able to detect it and set the BOOST_NETWORK_ENABLE_HTTPS macro when building the library to support HTTPS URIs.

One example for building the library with OpenSSL support with a custom (non-installed) version of OpenSSL is by doing the following:

$ cmake -DCMAKE_BUILD_TYPE=Debug \
>       -DCMAKE_C_COMPILER=clang \
>       -DCMAKE_CXX_COMPILER=clang++ \
>       -DOPENSSL_ROOT_DIR=/Users/dberris/homebrew/Cellar/openssl/1.0.1f
>       ../cpp-netlib

You can also use a different root directory for the Boost project by using the -DBOOST_ROOT configuration option to CMake. This is useful if you intend to build the library with a specific version of Boost that you’ve built in a separate directory:

$ cmake -DCMAKE_BUILD_TYPE=Debug \
>       -DCMAKE_C_COMPILER=clang \
>       -DCMAKE_CXX_COMPILER=clang++ \
>       -DOPENSSL_ROOT_DIR=/Users/dberris/homebrew/Cellar/openssl/1.0.1f \
>       -DBOOST_ROOT=/Users/dberris/Source/boost_1_55_0
>       ../cpp-netlib

Building on Linux

On Linux, this will generate the appropriate Makefiles that will enable you to build and run the tests and examples that come with cpp-netlib. To build the tests, you can run make in the same top-level directory of ~/cpp-netlib-build:

$ make

Note

Just like with traditional GNU Make, you can add the -j parameter to specify how many parallel builds to run. In case you’re in a sufficiently powerful system and would like to parallelize the build into 4 jobs, you can do this with:

make -j4

As a caveat, cpp-netlib is heavy on template metaprogramming and will require a lot of computing and memory resources to build the individual tests. Do this at the risk of thrashing your system. However, this compile-time burden is much reduced in recent versions.

Once the build has completed, you can now run the test suite by issuing:

$ make test

You can install cpp-netlib by issuing:

$ sudo make install

By default this installs cpp-netlib into /usr/local.

Note

As of version 0.9.3, cpp-netlib produces three static libraries. Using GCC on Linux these are:

libcppnetlib-client-connections.a
libcppnetlib-server-parsers.a
libcppnetlib-uri.a

Users can find them in ~/cpp-netlib-build/libs/network/src.

Building On Windows

If you’re using the Microsoft Visual C++ compiler or the Microsoft Visual Studio IDE and you would like to build cpp-netlib from within Visual Studio, you can look for the solution and project files as the artifacts of the call to cmake – the file should be named CPP-NETLIB.sln (the solution) along with a number of project files for Visual Studio.

Note

As of version 0.9.3, cpp-netlib produces three static libraries. Using Visual C++ on Windows they are:

cppnetlib-client-connections.lib
cppnetlib-server-parsers.lib
cppnetlib-uri.lib

Users can find them in ~/cpp-netlib-build/libs/network/src.

Using cpp-netlib

CMake projects

Projects using CMake can add the following lines in their CMakeLists.txt to be able to use cpp-netlib:

set ( CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} ~/cpp-netlib-build )
find_package ( cppnetlib 0.13.0 REQUIRED )
include_directories ( ${CPPNETLIB_INCLUDE_DIRS} )
target_link_libraries ( MyApplication ${CPPNETLIB_LIBRARIES} )

Note

Setting CMAKE_PREFIX_PATH is only required when cpp-netlib is not installed to a location that CMake searches. When cpp-netlib is installed to the default location (/usr/local), CMake can find it.

Note

We assume that MyApplication is the application that you are building and which depends on cpp-netlib.

Reporting Issues, Getting Support

In case you find yourself stuck or if you’ve found a bug (or you want to just join the discussion) you have a few options to choose from.

For reporting bugs, feature requests, and asking questions about the implementation and/or the documentation, you can go to the GitHub issues page for the project at http://github.com/cpp-netlib/cpp-netlib/issues.

You can also opt to join the developers mailing list for a more personal interaction with the developers of the project. You can join the mailing list through http://groups.google.com/forum/#!forum/cpp-netlib.