Skip to content

Latest commit

 

History

History
194 lines (141 loc) · 7.35 KB

getting_started.rst

File metadata and controls

194 lines (141 loc) · 7.35 KB

Getting Started

Downloading an official release

All stable versions of :mod:`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 :mod:`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 :mod:`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 :mod:`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

:mod:`cpp-netlib` depends on Boost. It should work for any version of Boost above 1.45.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 :mod:`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 :mod:`cpp-netlib` and Boost 1.46.1 on some compilers. It is not recommended to use :mod:`cpp-netlib` with Boost 1.46.1. Some have reported though that Boost 1.47.0 and :mod:`cpp-netlib` work together better.

Getting CMake

The :mod:`cpp-netlib` uses CMake to generate platform-specific build files. If you intend to run the test suite, you can follow the instructions below. Otherwise, you don't need CMake to use :mod:`cpp-netlib` in your project. The :mod:`cpp-netlib` requires CMake version 2.8 or higher.

Let's assume that you have unpacked the :mod:`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 :mod:`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 :mod:`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 :mod:`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.

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 :mod:`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, :mod:`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

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, :mod:`cpp-netlib` produces three static libraries. Using GCC on Linux these are:

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

And 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.

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.