blob: a4f422df706f1e0f2816fb4601ea43b4d1618191 [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)
Ivan Yeoba1a4a92015-01-11 00:45:57 -080013- Ubuntu 14.04 (64-bit and 32-bit)
Eric Newberry42db0452015-11-01 19:16:05 -070014- Ubuntu 15.10 (64-bit)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070015- OS X 10.8
16- OS X 10.9
Ivan Yeoba1a4a92015-01-11 00:45:57 -080017- OS X 10.10
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070018
19ndn-cxx is known to work on the following platforms, although they are not officially
20supported:
21
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070022- Fedora >= 20
Ivan Yeoba1a4a92015-01-11 00:45:57 -080023- CentOS >= 6.2
24- Gentoo Linux
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070025- FreeBSD >= 10.0
Ivan Yeoba1a4a92015-01-11 00:45:57 -080026- Raspbian >= 3.12
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070027
28Prerequisites
29-------------
30
31Required:
32~~~~~~~~~
33
34- ``python`` >= 2.6
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070035- ``libsqlite3``
36- ``libcrypto++``
37- ``pkg-config``
38- Boost libraries >= 1.48
39- OSX Security framework (on OSX platform only)
40
41Following are the detailed steps for each platform to install the compiler, all necessary
42development tools and libraries, and ndn-cxx prerequisites.
43
44- OS X
45
46 Install Xcode. In Xcode Preferences > Downloads, install "Command
47 Line Tools".
48
49 If using MacPorts, dependencies can be installed using the following
50 commands::
51
52 sudo port install pkgconfig boost sqlite3 libcryptopp
53
Junxiao Shi190bee22015-02-14 19:21:36 -070054 .. note::
55
56 If a major OS X system upgrade is performed after installing dependencies with MacPorts,
57 remember to `reinstall all ports <https://trac.macports.org/wiki/Migration>`__.
58
Ivan Yeoba1a4a92015-01-11 00:45:57 -080059- Ubuntu
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070060
61 In a terminal, enter::
62
63 sudo apt-get install build-essential
Alexander Afanasyev01515792014-12-16 14:20:01 -080064 sudo apt-get install libsqlite3-dev libcrypto++-dev
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070065
66 # For Ubuntu 12.04
67 sudo apt-get install libboost1.48-all-dev
68
Ivan Yeoba1a4a92015-01-11 00:45:57 -080069 # For all other Ubuntu versions
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070070 sudo apt-get install libboost-all-dev
71
Ivan Yeoba1a4a92015-01-11 00:45:57 -080072- Fedora
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070073
74 In a terminal, enter::
75
76 sudo yum install gcc-g++ git
Alexander Afanasyev01515792014-12-16 14:20:01 -080077 sudo yum install sqlite-devel cryptopp-devel boost-devel
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070078
79Optional:
80~~~~~~~~~
81
82To build tutorials, manpages, and API documentation the following
83dependencies need to be installed:
84
85- ``doxygen``
86- ``graphviz``
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070087- ``python-sphinx`` and sphinx extensions ``sphinxcontrib-doxylink``,
88 ``sphinxcontrib-googleanalytics``
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070089
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070090The following lists steps for common platforms to install these prerequisites:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070091
Ivan Yeoba1a4a92015-01-11 00:45:57 -080092- On OS X with MacPorts::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070093
94 sudo port install doxygen graphviz py27-sphinx sphinx_select
95 sudo port select sphinx py27-sphinx
96
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070097 # Install sphinx extensions
98 sudo port install py27-pip
99 sudo port select pip pip27
100 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
101
Ivan Yeoba1a4a92015-01-11 00:45:57 -0800102- On Ubuntu::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700103
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700104 sudo apt-get install doxygen graphviz python-sphinx python-pip
105 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700106
Ivan Yeoba1a4a92015-01-11 00:45:57 -0800107- On Fedora::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700108
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800109 sudo yum install doxygen graphviz python-sphinx
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700110 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700111
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700112.. _build:
113
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700114Build
115-----
116
117(These are instructions to build ndn-cxx. To do development of ndn-cxx
118code and update the build system, see Development.)
119
120To build in a terminal, change directory to the ndn-cxx root. Enter:
121
122::
123
124 ./waf configure
125 ./waf
126 sudo ./waf install
127
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700128By default, only the shared version of ndn-cxx library is built. To build the static library,
129use ``--enable-static`` option for ``./waf configure`` command. For example::
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700130
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700131 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700132
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700133To disable build of the shared library and build only the static library, use additional
134``--disable-shared`` option. Note that at least one version of the library needs to be
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700135enabled.
136
137::
138
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700139 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700140
141
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700142After the shared library is built and installed, some systems require additional actions.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700143
144 - on Linux::
145
146 sudo ldconfig
147
148 - on FreeBSD::
149
150 sudo ldconfig -m
151
152 .. note::
153 When library is installed in a non-standard path (in general: not in ``/usr/lib`` or
154 ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
155 additional actions may be necessary.
156
157 The installation path should be added to ``/etc/ld.so.conf`` (or in
158 ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
159
160 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
161
162 Alternatively, ``LD_LIBRARY_PATH`` environment variable should be set to the location of
163 the library::
164
165 export LD_LIBRARY_PATH=/usr/local/lib
166
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700167This builds and installs the following items:
168
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700169- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled)
170- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
171 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on OS X):
172 shared NDN C++ library (if enabled)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700173- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all
174 neccessary flags to build against the library. For example, if
175 pkgconfig or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
176 configured properly (or ``<LIBPATH>/pkgconfig`` is a default path),
177 ``pkgconfig --libs --clflags libndn-cxx`` will return all necessary
178 compile and link flags for the library.
179- ``<BINPATH>/tlvdump``: a simple tool to dump contents of
180 TLV-formatted data
181- ``<BINPATH>/ndncatchunks3``: a simplified equivalent to ndncatchunks2
182 in NDNx package
183- ``<BINPATH>/ndnputchunks3``: a simplified equivalent to ndnputchunks2
184 in NDNx package
185- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates
186- ``<BINPATH>/ndnsec-*``: convenience scripts for ``ndnsec`` tools
187
188If configured with tests: ``./waf configure --with-tests``), the above
189commands will also produce:
190
191- ``build/unit-tests``: A unit test binary for the library
192
Junxiao Shie04bd832014-11-29 23:02:38 -07001931.5GB available memory per CPU core is necessary for efficient compilation.
194On a multi-core machine with less than 1.5GB available memory per CPU core,
195limit the objects being compiled in parallel with ``./waf -jN`` where N is the amount
196of available memory divided by 1.5GB (eg. ``./waf -j1`` for 1.5GB memory),
197which could usually avoid memory thrashing and result in faster compilation.
198
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700199Build with examples
200-------------------
201
202By default, examples in ``examples/`` are not build. To enable them, use
203``--with-examples`` configure option:
204
205::
206
207 ./waf configure --with-examples
208 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700209 sudo ./waf install
210
211:ref:`Additional step <build>`:
212
213 - on Linux::
214
215 sudo ldconfig
216
217 - on FreeBSD::
218
219 sudo ldconfig -m
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700220
221To run examples:
222
223::
224
225 # trivial producer app
226 ./build/examples/producer
227
228 # trivial consumer app
229 ./build/examples/consumer
230
231 # trivial consumer app with timers
232 ./build/examples/consumer-with-timer
233
234If you want to test out a sample application, just create a ``.cpp`` file in ``examples/``
235folder and it will be compiled on the next run on ``./waf``. For example:
236
237::
238
239 cp examples/consumer.cpp examples/my-new-consumer-app.cpp
240 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700241 sudo ./waf install
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700242 ./build/examples/my-new-consumer-app
243
244
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700245Debug symbols
246~~~~~~~~~~~~~
247
248The default compiler flags enable debug symbols to be included in binaries (i.e., ``-g``
249flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``). This
250potentially allows more meaningful debugging information if your application crashes.
251
252If it is undesirable, default flags can be easily overridden:
253
254::
255
256 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
257 ./waf
258 sudo ./waf install
259
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700260:ref:`Additional step <build>`:
261
262 - on Linux::
263
264 sudo ldconfig
265
266 - on FreeBSD::
267
268 sudo ldconfig -m
269
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700270Documentation
271-------------
272
273ndn-cxx tutorials and API documentation can be built using the following
274commands:
275
276::
277
278 # Full set of documentation (tutorials + API) in build/docs
279 ./waf docs
280
281 # Only tutorials in `build/docs`
282 ./waf sphinx
283
284 # Only API docs in `build/docs/doxygen`
285 ./waf doxgyen
286
287Manpages are automatically created and installed during the normal build
288process (e.g., during ``./waf`` and ``./waf install``), if
289``python-sphinx`` module is detected during ``./waf configure`` stage.
290By default, manpages are installed into ``${PREFIX}/share/man`` (where
291default value for ``PREFIX`` is ``/usr/local``). This location can be
292changed during ``./waf configure`` stage using ``--prefix``,
293``--datarootdir``, or ``--mandir`` options.
294
295For more details, refer to ``./waf --help``.
296
297Development Build
298-----------------
299
300The following is the suggested configure commands for development build.
301
302::
303
304 ./waf configure --debug --with-tests
305 ./waf
306 sudo ./waf install
307
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700308:ref:`Additional step <build>`:
309
310 - on Linux::
311
312 sudo ldconfig
313
314 - on FreeBSD::
315
316 sudo ldconfig -m
317
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700318In the development build all compiler optimizations are disabled by
319default and all warnings are treated as error. The default behavior can
320be overridden by setting ``CXXFLAGS`` environment variable before
321running ``./waf configure``:
322
323::
324
325 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
326 ...
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800327
328Customize Compiler
329------------------
330
331To customize compiler, set ``CXX`` environment variable to point to compiler binary and, in
332some case, specify type of the compiler using ``--check-cxx-compiler``. For example, when
333using clang compiler on Linux system, use the following:
334
335::
336
337 CXX=clang++ ./waf configure --check-cxx-compiler=clang++