Getting Started — cpp-netlib v0.13.0

# Getting Started

## Downloading an official release

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

> http://cpp-netlib.org/

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

> http://github.com/cpp-netlib/cpp-netlib/downloads

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.