11.. _getting_started :
22
33*****************
4- Gettingstarted
4+ GettingStarted
55*****************
66
77Downloading an official release
@@ -43,6 +43,15 @@ http://svn.github.com/mikhailberis/cpp-netlib.git.
4343.. _msysGit :http://code.google.com/p/msysgit/downloads/list
4444.. _Subversion :http://subversion.tigris.org/
4545
46+ ..note ::The :mod:`cpp-netlib` project is hosted on GitHub_ and follows the
47+ prescribed development model forGitHub _ based projects. This means in case
48+ you want to submit patches, you will have to create a fork of the project
49+ (read up onforking _) and then submit a pull request (read up on submitting
50+ `pull requests `_).
51+
52+ .. _forking :http://help.github.com/forking/
53+ .. _`pull requests` :http://help.github.com/pull-requests/
54+
4655Getting Boost
4756=============
4857
@@ -52,47 +61,105 @@ latest package can be found on the `Boost web-site`_. The environment
5261variable ``BOOST_ROOT `` must be defined, which must be the full path
5362name of the top directory of the Boost distribution. Although Boost
5463is mostly header only, applications built using:mod: `cpp-netlib `
55- still requires linking with `Boost.System `_.
64+ still requires linking with `Boost.System `_, `Boost.Date_time `_, and
65+ `Boost.Regex `_.
5666
5767.. _Boost :http://www.boost.org/doc/libs/release/more/getting_started/index.html
5868.. _`Boost web-site` :http://www.boost.org/users/download/
5969.. _`Boost.System` :http://www.boost.org/libs/system/index.html
70+ .. _`Boost.Date_time` :http://www.boost.org/libs/date_time/index.html
71+ .. _`Boost.Regex` :http://www.boost.org/libs/regex/index.html
6072
61- ..todo ::
73+ ..note ::You can follow the steps in the `Boost Getting Started`_ guide to
74+ install Boost into your development system.
6275
63- Make this a little more accessible, perhaps with CLI examples.
76+ .. _`Boost Getting Started` :
77+ http://www.boost.org/doc/libs/release/more/getting_started/index.html
6478
6579Getting CMake
6680=============
6781
68- The:mod: `cpp-netlib ` usesCMake _.
82+ The:mod: `cpp-netlib ` usesCMake _ to generate platform-specific build files. If
83+ you intend to run the test suite, you can follow the instructions below.
84+ Otherwise, you don't need CMake to use:mod: `cpp-netlib ` in your project. The
85+ :mod: `cpp-netlib ` requires CMake version 2.8 or higher.
6986
7087.. _CMake :http://www.cmake.org/
7188
72- Open a command line in the:mod: `cpp-netlib ` home directory.
73- ``cmake `` requires the code to be built out of source, so you need to
74- create a separate directory.
89+ Let's assume that you have unpacked the:mod: `cpp-netlib ` at the top of your
90+ HOME directory. On Unix-like systems you will typically be able to change into
91+ your HOME directory using the command ``cd ~ ``. This sample below assumes that
92+ the ``~/cpp-netlib `` directory exists, and is the top-level directory of the
93+ :mod: `cpp-netlib ` release.
7594
76- Build Instructions
77- ==================
95+ Building with CMake
96+ ===================
7897
79- Invoke ``cmake `` in the build directory, this generates a Makefile.
80- Then, invoke ``make `` to build everything (unit tests and examples).
81- To run the tests, invoke ``make test ``.
98+ To build the tests that come with cpp-netlib, we first need to configure the
99+ build system to use our compiler of choice. This is done by running the
100+ ``cmake `` command at the top-level directory of:mod: `cpp-netlib ` with
101+ additional parameters::
82102
83- ::
103+ $ cd ~/cpp-netlib
104+ $ cmake -DCMAKE_BUILD_TYPE=Debug \
105+ > -DCMAKE_C_COMPILER=gcc \
106+ > -DCMAKE_CXX_COMPILER=g++ \
107+ > .
108+
109+ On Linux, this will generate the appropriate Makefiles that will enable you to
110+ build and run the tests and examples that come with:mod: `cpp-netlib `. To build
111+ the tests, you can run ``make `` in the same top-level directory of
112+ :mod: `cpp-netlib `::
113+
114+ $ make
115+
116+ ..note ::Just like with traditional GNU Make, you can add the ``-j`` parameter
117+ to specify how many parallel builds to run. In case you're in a sufficiently
118+ powerful system and would like to parallelize the build into 4 jobs, you can
119+ do this with::
120+
121+ make -j4
122+
123+ As a caveat,:mod: `cpp-netlib ` is heavy on template metaprogramming and will
124+ require a lot of computing and memory resources to build the individual
125+ tests. Do this at the risk ofthrashing _ your system.
126+
127+ .. _thrashing :http://en.wikipedia.org/wiki/Thrashing_(computer_science)
128+
129+ Once the build has completed, you can now run the test suite by issuing::
130+
131+ $ make test
132+
133+ Building On Windows
134+ ~~~~~~~~~~~~~~~~~~~
135+
136+ If you're using the Microsoft Visual C++ compiler or the Microsoft Visual Studio
137+ IDE and you would like to build cpp-netlib from within Visual Studio, you can
138+ look for the solution and project files as the artifacts of the call to
139+ ``cmake `` -- the file should be named ``cpp-netlib.sln `` (the solution) along
140+ with a number of project files for Visual Studio.
141+
142+ Reporting Issues, Getting Support
143+ =================================
84144
85- shell$ make
86- shell$ make test
145+ In case you find yourself stuck or if you've found a bug (or you want to just
146+ join the discussion) you have a few options to choose from.
87147
88- This will build all unit tests andexamples (located in the
89- `` libs/network/tests `` and `` libs/network/examples `` subdirectory
90- respectively). There is no library to build for :mod: ` cpp-netlib ` .
148+ For reporting bugs, feature requests, andasking questions about the
149+ implementation and/or the documentation, you can go to the GitHub issues page
150+ for the project at http://github.com/mikhailberis/ cpp-netlib/issues .
91151
92- ..todo ::
152+ You can also opt to join the developers mailing list for a more personal
153+ interaction with the developers of the project. You can join the mailing list
154+ through https://lists.sourceforge.net/lists/listinfo/cpp-netlib-devel.
93155
94- Platform-specific instructions.
156+ You may also choose to get commercial support from the maintainers of the
157+ project, in which case you can reach them through:
95158
96- ..todo ::
159+ Dean Michael Berris - <me@deanberris.com>
160+
161+ Glyn Matthews
162+
163+ Mike Dickey
164+
97165
98- Mailing list, issues, contacting developers etc.