blob: 5d94e351d4a4d0237f5f5376d5bbb7f404f0f592 [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
Davide Pesavento7c4ad512018-04-28 15:20:11 -040012- Ubuntu 16.04 (amd64, armhf, i386)
13- Ubuntu 18.04 (amd64)
Davide Pesaventoe11c8d82016-04-16 14:32:07 +020014- OS X 10.11
Davide Pesavento0530b5b2016-11-07 03:23:58 +010015- macOS 10.12
Eric Newberry935d7fe2017-10-29 15:09:36 -070016- macOS 10.13
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070017
18ndn-cxx is known to work on the following platforms, although they are not officially
19supported:
20
Davide Pesavento7c4ad512018-04-28 15:20:11 -040021- Debian >= 9
22- Fedora >= 24
Ivan Yeoba1a4a92015-01-11 00:45:57 -080023- Gentoo Linux
Davide Pesavento7c4ad512018-04-28 15:20:11 -040024- Raspbian >= 2017-08-16
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070025
26Prerequisites
27-------------
28
29Required:
30~~~~~~~~~
31
Davide Pesaventoca660f12018-06-16 14:01:51 -040032- GCC >= 5.3, or clang >= 3.6
Davide Pesavento7c4ad512018-04-28 15:20:11 -040033- ``python2`` >= 2.7, or ``python3`` >= 3.4
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070034- ``libsqlite3``
Davide Pesavento844b0932018-05-07 01:00:16 -040035- OpenSSL >= 1.0.2
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070036- ``pkg-config``
Davide Pesavento844b0932018-05-07 01:00:16 -040037- Boost libraries >= 1.58
Davide Pesavento0530b5b2016-11-07 03:23:58 +010038- OSX Security framework (on OSX/macOS platform only)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070039
40Following are the detailed steps for each platform to install the compiler, all necessary
41development tools and libraries, and ndn-cxx prerequisites.
42
Davide Pesavento0530b5b2016-11-07 03:23:58 +010043- OS X / macOS
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070044
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070045 Install Xcode from AppStore or at least Command Line Tools (``xcode-select --install``)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070046
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070047 * When using MacPorts
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070048
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070049 In a terminal, enter::
50
Davide Pesavento006b7ce2017-08-16 00:55:02 -040051 sudo port install pkgconfig boost sqlite3 openssl
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070052
53 * When using Homebrew
54
55 In a terminal, enter::
56
Davide Pesavento006b7ce2017-08-16 00:55:02 -040057 brew install boost openssl pkg-config
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070058
Junxiao Shi190bee22015-02-14 19:21:36 -070059 .. note::
60
Davide Pesavento0530b5b2016-11-07 03:23:58 +010061 If a major OS upgrade is performed after installing dependencies with
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070062 MacPorts or Homebrew, remember to reinstall all packages.
Junxiao Shi190bee22015-02-14 19:21:36 -070063
Ivan Yeoba1a4a92015-01-11 00:45:57 -080064- Ubuntu
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070065
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070066 In a terminal, enter::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070067
Davide Pesavento006b7ce2017-08-16 00:55:02 -040068 sudo apt-get install build-essential libsqlite3-dev libboost-all-dev libssl-dev
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070069
Ivan Yeoba1a4a92015-01-11 00:45:57 -080070- Fedora
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070071
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070072 In a terminal, enter::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070073
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070074 sudo yum install gcc-g++ git
Davide Pesavento006b7ce2017-08-16 00:55:02 -040075 sudo yum install sqlite-devel boost-devel openssl-devel
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070076
77Optional:
78~~~~~~~~~
79
80To build tutorials, manpages, and API documentation the following
81dependencies need to be installed:
82
83- ``doxygen``
84- ``graphviz``
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070085- ``python-sphinx`` and sphinx extensions ``sphinxcontrib-doxylink``,
86 ``sphinxcontrib-googleanalytics``
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070087
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070088The following lists steps for common platforms to install these prerequisites:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070089
Davide Pesavento0530b5b2016-11-07 03:23:58 +010090- On OS X / macOS with MacPorts::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070091
92 sudo port install doxygen graphviz py27-sphinx sphinx_select
93 sudo port select sphinx py27-sphinx
94
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070095 # Install sphinx extensions
96 sudo port install py27-pip
97 sudo port select pip pip27
98 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
99
Ivan Yeoba1a4a92015-01-11 00:45:57 -0800100- On Ubuntu::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700101
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700102 sudo apt-get install doxygen graphviz python-sphinx python-pip
103 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700104
Ivan Yeoba1a4a92015-01-11 00:45:57 -0800105- On Fedora::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700106
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800107 sudo yum install doxygen graphviz python-sphinx
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700108 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700109
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700110.. _build:
111
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700112Build
113-----
114
115(These are instructions to build ndn-cxx. To do development of ndn-cxx
116code and update the build system, see Development.)
117
118To build in a terminal, change directory to the ndn-cxx root. Enter:
119
120::
121
122 ./waf configure
123 ./waf
124 sudo ./waf install
125
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700126By default, only the shared version of ndn-cxx library is built. To build the static library,
127use ``--enable-static`` option for ``./waf configure`` command. For example::
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700128
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700129 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700130
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700131To disable build of the shared library and build only the static library, use additional
132``--disable-shared`` option. Note that at least one version of the library needs to be
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700133enabled.
134
135::
136
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700137 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700138
139
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700140After the shared library is built and installed, some systems require additional actions.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700141
142 - on Linux::
143
144 sudo ldconfig
145
146 - on FreeBSD::
147
148 sudo ldconfig -m
149
150 .. note::
151 When library is installed in a non-standard path (in general: not in ``/usr/lib`` or
152 ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
153 additional actions may be necessary.
154
155 The installation path should be added to ``/etc/ld.so.conf`` (or in
156 ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
157
158 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
159
160 Alternatively, ``LD_LIBRARY_PATH`` environment variable should be set to the location of
161 the library::
162
163 export LD_LIBRARY_PATH=/usr/local/lib
164
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700165This builds and installs the following items:
166
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700167- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled)
168- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
169 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on OS X):
170 shared NDN C++ library (if enabled)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700171- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all
172 neccessary flags to build against the library. For example, if
173 pkgconfig or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
174 configured properly (or ``<LIBPATH>/pkgconfig`` is a default path),
175 ``pkgconfig --libs --clflags libndn-cxx`` will return all necessary
176 compile and link flags for the library.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700177- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates
178- ``<BINPATH>/ndnsec-*``: convenience scripts for ``ndnsec`` tools
179
180If configured with tests: ``./waf configure --with-tests``), the above
181commands will also produce:
182
183- ``build/unit-tests``: A unit test binary for the library
184
Junxiao Shie04bd832014-11-29 23:02:38 -07001851.5GB available memory per CPU core is necessary for efficient compilation.
186On a multi-core machine with less than 1.5GB available memory per CPU core,
187limit the objects being compiled in parallel with ``./waf -jN`` where N is the amount
188of available memory divided by 1.5GB (eg. ``./waf -j1`` for 1.5GB memory),
189which could usually avoid memory thrashing and result in faster compilation.
190
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700191Build with examples
192-------------------
193
194By default, examples in ``examples/`` are not build. To enable them, use
195``--with-examples`` configure option:
196
197::
198
199 ./waf configure --with-examples
200 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700201 sudo ./waf install
202
203:ref:`Additional step <build>`:
204
205 - on Linux::
206
207 sudo ldconfig
208
209 - on FreeBSD::
210
211 sudo ldconfig -m
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700212
213To run examples:
214
215::
216
217 # trivial producer app
218 ./build/examples/producer
219
220 # trivial consumer app
221 ./build/examples/consumer
222
223 # trivial consumer app with timers
224 ./build/examples/consumer-with-timer
225
226If you want to test out a sample application, just create a ``.cpp`` file in ``examples/``
227folder and it will be compiled on the next run on ``./waf``. For example:
228
229::
230
231 cp examples/consumer.cpp examples/my-new-consumer-app.cpp
232 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700233 sudo ./waf install
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700234 ./build/examples/my-new-consumer-app
235
236
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700237Debug symbols
238~~~~~~~~~~~~~
239
240The default compiler flags enable debug symbols to be included in binaries (i.e., ``-g``
241flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``). This
242potentially allows more meaningful debugging information if your application crashes.
243
244If it is undesirable, default flags can be easily overridden:
245
246::
247
248 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
249 ./waf
250 sudo ./waf install
251
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700252:ref:`Additional step <build>`:
253
254 - on Linux::
255
256 sudo ldconfig
257
258 - on FreeBSD::
259
260 sudo ldconfig -m
261
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700262Documentation
263-------------
264
265ndn-cxx tutorials and API documentation can be built using the following
266commands:
267
268::
269
270 # Full set of documentation (tutorials + API) in build/docs
271 ./waf docs
272
273 # Only tutorials in `build/docs`
274 ./waf sphinx
275
276 # Only API docs in `build/docs/doxygen`
277 ./waf doxgyen
278
279Manpages are automatically created and installed during the normal build
280process (e.g., during ``./waf`` and ``./waf install``), if
281``python-sphinx`` module is detected during ``./waf configure`` stage.
282By default, manpages are installed into ``${PREFIX}/share/man`` (where
283default value for ``PREFIX`` is ``/usr/local``). This location can be
284changed during ``./waf configure`` stage using ``--prefix``,
285``--datarootdir``, or ``--mandir`` options.
286
287For more details, refer to ``./waf --help``.
288
289Development Build
290-----------------
291
292The following is the suggested configure commands for development build.
293
294::
295
296 ./waf configure --debug --with-tests
297 ./waf
298 sudo ./waf install
299
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700300:ref:`Additional step <build>`:
301
302 - on Linux::
303
304 sudo ldconfig
305
306 - on FreeBSD::
307
308 sudo ldconfig -m
309
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700310In the development build all compiler optimizations are disabled by
311default and all warnings are treated as error. The default behavior can
312be overridden by setting ``CXXFLAGS`` environment variable before
313running ``./waf configure``:
314
315::
316
317 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
318 ...
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800319
320Customize Compiler
321------------------
322
Davide Pesavento0530b5b2016-11-07 03:23:58 +0100323To choose a custom C++ compiler for building ndn-cxx, set ``CXX`` environment
324variable to point to the compiler binary. For example, to build with clang on
325Linux, use the following:
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800326
327::
328
Davide Pesavento0530b5b2016-11-07 03:23:58 +0100329 CXX=clang++ ./waf configure