blob: 09e3e27403ecdfc342049e021ed34675acf5f54b [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
Ivan Yeoba1a4a92015-01-11 00:45:57 -080012- Ubuntu 14.04 (64-bit and 32-bit)
Davide Pesaventoe11c8d82016-04-16 14:32:07 +020013- Ubuntu 16.04 (64-bit and 32-bit)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070014- OS X 10.8
15- OS X 10.9
Ivan Yeoba1a4a92015-01-11 00:45:57 -080016- OS X 10.10
Davide Pesaventoe11c8d82016-04-16 14:32:07 +020017- OS X 10.11
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
Davide Pesaventoe11c8d82016-04-16 14:32:07 +020063 sudo apt-get install build-essential libcrypto++-dev libsqlite3-dev libboost-all-dev
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070064
Ivan Yeoba1a4a92015-01-11 00:45:57 -080065- Fedora
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070066
67 In a terminal, enter::
68
69 sudo yum install gcc-g++ git
Alexander Afanasyev01515792014-12-16 14:20:01 -080070 sudo yum install sqlite-devel cryptopp-devel boost-devel
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070071
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
Ivan Yeoba1a4a92015-01-11 00:45:57 -080085- On OS X with MacPorts::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070086
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
Ivan Yeoba1a4a92015-01-11 00:45:57 -080095- On Ubuntu::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070096
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
Ivan Yeoba1a4a92015-01-11 00:45:57 -0800100- On Fedora::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700101
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800102 sudo 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
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700105.. _build:
106
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700107Build
108-----
109
110(These are instructions to build ndn-cxx. To do development of ndn-cxx
111code and update the build system, see Development.)
112
113To build in a terminal, change directory to the ndn-cxx root. Enter:
114
115::
116
117 ./waf configure
118 ./waf
119 sudo ./waf install
120
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700121By default, only the shared version of ndn-cxx library is built. To build the static library,
122use ``--enable-static`` option for ``./waf configure`` command. For example::
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700123
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700124 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700125
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700126To disable build of the shared library and build only the static library, use additional
127``--disable-shared`` option. Note that at least one version of the library needs to be
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700128enabled.
129
130::
131
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700132 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700133
134
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700135After the shared library is built and installed, some systems require additional actions.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700136
137 - on Linux::
138
139 sudo ldconfig
140
141 - on FreeBSD::
142
143 sudo ldconfig -m
144
145 .. note::
146 When library is installed in a non-standard path (in general: not in ``/usr/lib`` or
147 ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
148 additional actions may be necessary.
149
150 The installation path should be added to ``/etc/ld.so.conf`` (or in
151 ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
152
153 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
154
155 Alternatively, ``LD_LIBRARY_PATH`` environment variable should be set to the location of
156 the library::
157
158 export LD_LIBRARY_PATH=/usr/local/lib
159
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700160This builds and installs the following items:
161
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700162- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled)
163- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
164 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on OS X):
165 shared NDN C++ library (if enabled)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700166- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all
167 neccessary flags to build against the library. For example, if
168 pkgconfig or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
169 configured properly (or ``<LIBPATH>/pkgconfig`` is a default path),
170 ``pkgconfig --libs --clflags libndn-cxx`` will return all necessary
171 compile and link flags for the library.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700172- ``<BINPATH>/ndncatchunks3``: a simplified equivalent to ndncatchunks2
173 in NDNx package
174- ``<BINPATH>/ndnputchunks3``: a simplified equivalent to ndnputchunks2
175 in NDNx package
176- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates
177- ``<BINPATH>/ndnsec-*``: convenience scripts for ``ndnsec`` tools
178
179If configured with tests: ``./waf configure --with-tests``), the above
180commands will also produce:
181
182- ``build/unit-tests``: A unit test binary for the library
183
Junxiao Shie04bd832014-11-29 23:02:38 -07001841.5GB available memory per CPU core is necessary for efficient compilation.
185On a multi-core machine with less than 1.5GB available memory per CPU core,
186limit the objects being compiled in parallel with ``./waf -jN`` where N is the amount
187of available memory divided by 1.5GB (eg. ``./waf -j1`` for 1.5GB memory),
188which could usually avoid memory thrashing and result in faster compilation.
189
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700190Build with examples
191-------------------
192
193By default, examples in ``examples/`` are not build. To enable them, use
194``--with-examples`` configure option:
195
196::
197
198 ./waf configure --with-examples
199 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700200 sudo ./waf install
201
202:ref:`Additional step <build>`:
203
204 - on Linux::
205
206 sudo ldconfig
207
208 - on FreeBSD::
209
210 sudo ldconfig -m
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700211
212To run examples:
213
214::
215
216 # trivial producer app
217 ./build/examples/producer
218
219 # trivial consumer app
220 ./build/examples/consumer
221
222 # trivial consumer app with timers
223 ./build/examples/consumer-with-timer
224
225If you want to test out a sample application, just create a ``.cpp`` file in ``examples/``
226folder and it will be compiled on the next run on ``./waf``. For example:
227
228::
229
230 cp examples/consumer.cpp examples/my-new-consumer-app.cpp
231 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700232 sudo ./waf install
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700233 ./build/examples/my-new-consumer-app
234
235
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700236Debug symbols
237~~~~~~~~~~~~~
238
239The default compiler flags enable debug symbols to be included in binaries (i.e., ``-g``
240flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``). This
241potentially allows more meaningful debugging information if your application crashes.
242
243If it is undesirable, default flags can be easily overridden:
244
245::
246
247 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
248 ./waf
249 sudo ./waf install
250
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700251:ref:`Additional step <build>`:
252
253 - on Linux::
254
255 sudo ldconfig
256
257 - on FreeBSD::
258
259 sudo ldconfig -m
260
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700261Documentation
262-------------
263
264ndn-cxx tutorials and API documentation can be built using the following
265commands:
266
267::
268
269 # Full set of documentation (tutorials + API) in build/docs
270 ./waf docs
271
272 # Only tutorials in `build/docs`
273 ./waf sphinx
274
275 # Only API docs in `build/docs/doxygen`
276 ./waf doxgyen
277
278Manpages are automatically created and installed during the normal build
279process (e.g., during ``./waf`` and ``./waf install``), if
280``python-sphinx`` module is detected during ``./waf configure`` stage.
281By default, manpages are installed into ``${PREFIX}/share/man`` (where
282default value for ``PREFIX`` is ``/usr/local``). This location can be
283changed during ``./waf configure`` stage using ``--prefix``,
284``--datarootdir``, or ``--mandir`` options.
285
286For more details, refer to ``./waf --help``.
287
288Development Build
289-----------------
290
291The following is the suggested configure commands for development build.
292
293::
294
295 ./waf configure --debug --with-tests
296 ./waf
297 sudo ./waf install
298
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700299:ref:`Additional step <build>`:
300
301 - on Linux::
302
303 sudo ldconfig
304
305 - on FreeBSD::
306
307 sudo ldconfig -m
308
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700309In the development build all compiler optimizations are disabled by
310default and all warnings are treated as error. The default behavior can
311be overridden by setting ``CXXFLAGS`` environment variable before
312running ``./waf configure``:
313
314::
315
316 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
317 ...
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800318
319Customize Compiler
320------------------
321
322To customize compiler, set ``CXX`` environment variable to point to compiler binary and, in
323some case, specify type of the compiler using ``--check-cxx-compiler``. For example, when
324using clang compiler on Linux system, use the following:
325
326::
327
328 CXX=clang++ ./waf configure --check-cxx-compiler=clang++