Skip to content

Commit 7abfd9b

Browse files
deanberrisdeanberris
committed
Adding some more changes and clarifications to the Getting Started section.
1 parent eab1664 commit 7abfd9b

File tree

1 file changed

+90
-23
lines changed

1 file changed

+90
-23
lines changed

‎libs/network/doc/getting_started.rst

Lines changed: 90 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _getting_started:
22

33
*****************
4-
Getting started
4+
Getting Started
55
*****************
66

77
Downloading 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 for GitHub_ 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 on forking_) 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+
4655
Getting Boost
4756
=============
4857

@@ -52,47 +61,105 @@ latest package can be found on the `Boost web-site`_. The environment
5261
variable ``BOOST_ROOT`` must be defined, which must be the full path
5362
name of the top directory of the Boost distribution. Although Boost
5463
is 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

6579
Getting CMake
6680
=============
6781

68-
The :mod:`cpp-netlib` uses CMake_.
82+
The :mod:`cpp-netlib` uses CMake_ 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 of thrashing_ 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 and examples (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, and asking 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.

0 commit comments

Comments
 (0)