blob: 756224908582aa8e1b1ea73d647ae0f50ed6185e [file] [log] [blame]
Alexander Afanasyevabaab522014-04-30 20:42:11 -07001.. _Getting Started with ndn-cxx:
2
Alexander Afanasyevc5452c52014-04-29 17:21:51 -07003Getting started with ndn-cxx
4============================
5
6Supported platforms
7-------------------
8
9ndn-cxx uses continuous integration and has been tested on the following
10platforms:
11
12- Ubuntu 12.04 (64-bit and 32-bit)
13- Ubuntu 13.10 (64-bit and 32-bit)
14- OS X 10.8
15- OS X 10.9
16
17ndn-cxx is known to work on the following platforms, although they are not officially
18supported:
19
20- Ubuntu 14.04
21- Fedora >= 20
22- FreeBSD >= 10.0
23- Raspberry Pi
24
25Prerequisites
26-------------
27
28Required:
29~~~~~~~~~
30
31- ``python`` >= 2.6
32- ``libcrypto``
33- ``libsqlite3``
34- ``libcrypto++``
35- ``pkg-config``
36- Boost libraries >= 1.48
37- OSX Security framework (on OSX platform only)
38
39Following are the detailed steps for each platform to install the compiler, all necessary
40development tools and libraries, and ndn-cxx prerequisites.
41
42- OS X
43
44 Install Xcode. In Xcode Preferences > Downloads, install "Command
45 Line Tools".
46
47 If using MacPorts, dependencies can be installed using the following
48 commands::
49
50 sudo port install pkgconfig boost sqlite3 libcryptopp
51
52- Ubuntu 12.04, Ubuntu 13.10
53
54 In a terminal, enter::
55
56 sudo apt-get install build-essential
57 sudo apt-get install libssl-dev libsqlite3-dev libcrypto++-dev
58
59 # For Ubuntu 12.04
60 sudo apt-get install libboost1.48-all-dev
61
62 # For Ubuntu 13.10
63 sudo apt-get install libboost-all-dev
64
65- Fedora >=20
66
67 In a terminal, enter::
68
69 sudo yum install gcc-g++ git
70 sudo yum install openssl-devel sqlite-devel cryptopp-devel boost-devel
71
72Optional:
73~~~~~~~~~
74
75To build tutorials, manpages, and API documentation the following
76dependencies need to be installed:
77
78- ``doxygen``
79- ``graphviz``
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070080- ``python-sphinx`` and sphinx extensions ``sphinxcontrib-doxylink``,
81 ``sphinxcontrib-googleanalytics``
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070082
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070083The following lists steps for common platforms to install these prerequisites:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070084
85- On OS X 10.8 and 10.9 with MacPorts::
86
87 sudo port install doxygen graphviz py27-sphinx sphinx_select
88 sudo port select sphinx py27-sphinx
89
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070090 # Install sphinx extensions
91 sudo port install py27-pip
92 sudo port select pip pip27
93 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
94
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070095- On Ubuntu >= 12.04::
96
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070097 sudo apt-get install doxygen graphviz python-sphinx python-pip
98 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070099
100- On Fedora >= 20::
101
102 sudp yum install doxygen graphviz python-sphinx
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700103 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700104
105Build
106-----
107
108(These are instructions to build ndn-cxx. To do development of ndn-cxx
109code and update the build system, see Development.)
110
111To build in a terminal, change directory to the ndn-cxx root. Enter:
112
113::
114
115 ./waf configure
116 ./waf
117 sudo ./waf install
118
119This builds and installs the following items:
120
121- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library
122- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all
123 neccessary flags to build against the library. For example, if
124 pkgconfig or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
125 configured properly (or ``<LIBPATH>/pkgconfig`` is a default path),
126 ``pkgconfig --libs --clflags libndn-cxx`` will return all necessary
127 compile and link flags for the library.
128- ``<BINPATH>/tlvdump``: a simple tool to dump contents of
129 TLV-formatted data
130- ``<BINPATH>/ndncatchunks3``: a simplified equivalent to ndncatchunks2
131 in NDNx package
132- ``<BINPATH>/ndnputchunks3``: a simplified equivalent to ndnputchunks2
133 in NDNx package
134- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates
135- ``<BINPATH>/ndnsec-*``: convenience scripts for ``ndnsec`` tools
136
137If configured with tests: ``./waf configure --with-tests``), the above
138commands will also produce:
139
140- ``build/unit-tests``: A unit test binary for the library
141
Junxiao Shie04bd832014-11-29 23:02:38 -07001421.5GB available memory per CPU core is necessary for efficient compilation.
143On a multi-core machine with less than 1.5GB available memory per CPU core,
144limit the objects being compiled in parallel with ``./waf -jN`` where N is the amount
145of available memory divided by 1.5GB (eg. ``./waf -j1`` for 1.5GB memory),
146which could usually avoid memory thrashing and result in faster compilation.
147
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700148Build with examples
149-------------------
150
151By default, examples in ``examples/`` are not build. To enable them, use
152``--with-examples`` configure option:
153
154::
155
156 ./waf configure --with-examples
157 ./waf
158
159To run examples:
160
161::
162
163 # trivial producer app
164 ./build/examples/producer
165
166 # trivial consumer app
167 ./build/examples/consumer
168
169 # trivial consumer app with timers
170 ./build/examples/consumer-with-timer
171
172If you want to test out a sample application, just create a ``.cpp`` file in ``examples/``
173folder and it will be compiled on the next run on ``./waf``. For example:
174
175::
176
177 cp examples/consumer.cpp examples/my-new-consumer-app.cpp
178 ./waf
179 ./build/examples/my-new-consumer-app
180
181
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700182Debug symbols
183~~~~~~~~~~~~~
184
185The default compiler flags enable debug symbols to be included in binaries (i.e., ``-g``
186flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``). This
187potentially allows more meaningful debugging information if your application crashes.
188
189If it is undesirable, default flags can be easily overridden:
190
191::
192
193 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
194 ./waf
195 sudo ./waf install
196
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700197Documentation
198-------------
199
200ndn-cxx tutorials and API documentation can be built using the following
201commands:
202
203::
204
205 # Full set of documentation (tutorials + API) in build/docs
206 ./waf docs
207
208 # Only tutorials in `build/docs`
209 ./waf sphinx
210
211 # Only API docs in `build/docs/doxygen`
212 ./waf doxgyen
213
214Manpages are automatically created and installed during the normal build
215process (e.g., during ``./waf`` and ``./waf install``), if
216``python-sphinx`` module is detected during ``./waf configure`` stage.
217By default, manpages are installed into ``${PREFIX}/share/man`` (where
218default value for ``PREFIX`` is ``/usr/local``). This location can be
219changed during ``./waf configure`` stage using ``--prefix``,
220``--datarootdir``, or ``--mandir`` options.
221
222For more details, refer to ``./waf --help``.
223
224Development Build
225-----------------
226
227The following is the suggested configure commands for development build.
228
229::
230
231 ./waf configure --debug --with-tests
232 ./waf
233 sudo ./waf install
234
235In the development build all compiler optimizations are disabled by
236default and all warnings are treated as error. The default behavior can
237be overridden by setting ``CXXFLAGS`` environment variable before
238running ``./waf configure``:
239
240::
241
242 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
243 ...