blob: f9041e05f73bfe13b17d8fc415bfc6c616547dd3 [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
Eric Newberry935d7fe2017-10-29 15:09:36 -070012- Ubuntu 14.04 (64-bit)
Davide Pesaventoe11c8d82016-04-16 14:32:07 +020013- Ubuntu 16.04 (64-bit and 32-bit)
Eric Newberry935d7fe2017-10-29 15:09:36 -070014- Ubuntu 17.10 (64-bit)
Davide Pesaventoe11c8d82016-04-16 14:32:07 +020015- OS X 10.11
Davide Pesavento0530b5b2016-11-07 03:23:58 +010016- macOS 10.12
Eric Newberry935d7fe2017-10-29 15:09:36 -070017- macOS 10.13
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``
Davide Pesavento0530b5b2016-11-07 03:23:58 +010036- OpenSSL >= 1.0.1
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070037- ``pkg-config``
Davide Pesaventoe6e6fde2016-04-16 14:44:45 +020038- Boost libraries >= 1.54
Davide Pesavento0530b5b2016-11-07 03:23:58 +010039- OSX Security framework (on OSX/macOS platform only)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070040
41Following are the detailed steps for each platform to install the compiler, all necessary
42development tools and libraries, and ndn-cxx prerequisites.
43
Davide Pesavento0530b5b2016-11-07 03:23:58 +010044- OS X / macOS
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070045
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070046 Install Xcode from AppStore or at least Command Line Tools (``xcode-select --install``)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070047
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070048 * When using MacPorts
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070049
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070050 In a terminal, enter::
51
Davide Pesavento006b7ce2017-08-16 00:55:02 -040052 sudo port install pkgconfig boost sqlite3 openssl
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070053
54 * When using Homebrew
55
56 In a terminal, enter::
57
Davide Pesavento006b7ce2017-08-16 00:55:02 -040058 brew install boost openssl pkg-config
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070059
Junxiao Shi190bee22015-02-14 19:21:36 -070060 .. note::
61
Davide Pesavento0530b5b2016-11-07 03:23:58 +010062 If a major OS upgrade is performed after installing dependencies with
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070063 MacPorts or Homebrew, remember to reinstall all packages.
Junxiao Shi190bee22015-02-14 19:21:36 -070064
Ivan Yeoba1a4a92015-01-11 00:45:57 -080065- Ubuntu
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070066
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070067 In a terminal, enter::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070068
Davide Pesavento006b7ce2017-08-16 00:55:02 -040069 sudo apt-get install build-essential libsqlite3-dev libboost-all-dev libssl-dev
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070070
Ivan Yeoba1a4a92015-01-11 00:45:57 -080071- Fedora
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070072
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070073 In a terminal, enter::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070074
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070075 sudo yum install gcc-g++ git
Davide Pesavento006b7ce2017-08-16 00:55:02 -040076 sudo yum install sqlite-devel boost-devel openssl-devel
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070077
78Optional:
79~~~~~~~~~
80
81To build tutorials, manpages, and API documentation the following
82dependencies need to be installed:
83
84- ``doxygen``
85- ``graphviz``
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070086- ``python-sphinx`` and sphinx extensions ``sphinxcontrib-doxylink``,
87 ``sphinxcontrib-googleanalytics``
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070088
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070089The following lists steps for common platforms to install these prerequisites:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070090
Davide Pesavento0530b5b2016-11-07 03:23:58 +010091- On OS X / macOS with MacPorts::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070092
93 sudo port install doxygen graphviz py27-sphinx sphinx_select
94 sudo port select sphinx py27-sphinx
95
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070096 # Install sphinx extensions
97 sudo port install py27-pip
98 sudo port select pip pip27
99 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
100
Ivan Yeoba1a4a92015-01-11 00:45:57 -0800101- On Ubuntu::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700102
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700103 sudo apt-get install doxygen graphviz python-sphinx python-pip
104 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700105
Ivan Yeoba1a4a92015-01-11 00:45:57 -0800106- On Fedora::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700107
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800108 sudo yum install doxygen graphviz python-sphinx
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700109 sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700110
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700111.. _build:
112
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700113Build
114-----
115
116(These are instructions to build ndn-cxx. To do development of ndn-cxx
117code and update the build system, see Development.)
118
119To build in a terminal, change directory to the ndn-cxx root. Enter:
120
121::
122
123 ./waf configure
124 ./waf
125 sudo ./waf install
126
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700127By default, only the shared version of ndn-cxx library is built. To build the static library,
128use ``--enable-static`` option for ``./waf configure`` command. For example::
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700129
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700130 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700131
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700132To disable build of the shared library and build only the static library, use additional
133``--disable-shared`` option. Note that at least one version of the library needs to be
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700134enabled.
135
136::
137
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700138 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700139
140
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700141After the shared library is built and installed, some systems require additional actions.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700142
143 - on Linux::
144
145 sudo ldconfig
146
147 - on FreeBSD::
148
149 sudo ldconfig -m
150
151 .. note::
152 When library is installed in a non-standard path (in general: not in ``/usr/lib`` or
153 ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
154 additional actions may be necessary.
155
156 The installation path should be added to ``/etc/ld.so.conf`` (or in
157 ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
158
159 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
160
161 Alternatively, ``LD_LIBRARY_PATH`` environment variable should be set to the location of
162 the library::
163
164 export LD_LIBRARY_PATH=/usr/local/lib
165
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700166This builds and installs the following items:
167
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700168- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled)
169- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
170 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on OS X):
171 shared NDN C++ library (if enabled)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700172- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all
173 neccessary flags to build against the library. For example, if
174 pkgconfig or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
175 configured properly (or ``<LIBPATH>/pkgconfig`` is a default path),
176 ``pkgconfig --libs --clflags libndn-cxx`` will return all necessary
177 compile and link flags for the library.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700178- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates
179- ``<BINPATH>/ndnsec-*``: convenience scripts for ``ndnsec`` tools
180
181If configured with tests: ``./waf configure --with-tests``), the above
182commands will also produce:
183
184- ``build/unit-tests``: A unit test binary for the library
185
Junxiao Shie04bd832014-11-29 23:02:38 -07001861.5GB available memory per CPU core is necessary for efficient compilation.
187On a multi-core machine with less than 1.5GB available memory per CPU core,
188limit the objects being compiled in parallel with ``./waf -jN`` where N is the amount
189of available memory divided by 1.5GB (eg. ``./waf -j1`` for 1.5GB memory),
190which could usually avoid memory thrashing and result in faster compilation.
191
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700192Build with examples
193-------------------
194
195By default, examples in ``examples/`` are not build. To enable them, use
196``--with-examples`` configure option:
197
198::
199
200 ./waf configure --with-examples
201 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700202 sudo ./waf install
203
204:ref:`Additional step <build>`:
205
206 - on Linux::
207
208 sudo ldconfig
209
210 - on FreeBSD::
211
212 sudo ldconfig -m
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700213
214To run examples:
215
216::
217
218 # trivial producer app
219 ./build/examples/producer
220
221 # trivial consumer app
222 ./build/examples/consumer
223
224 # trivial consumer app with timers
225 ./build/examples/consumer-with-timer
226
227If you want to test out a sample application, just create a ``.cpp`` file in ``examples/``
228folder and it will be compiled on the next run on ``./waf``. For example:
229
230::
231
232 cp examples/consumer.cpp examples/my-new-consumer-app.cpp
233 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700234 sudo ./waf install
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700235 ./build/examples/my-new-consumer-app
236
237
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700238Debug symbols
239~~~~~~~~~~~~~
240
241The default compiler flags enable debug symbols to be included in binaries (i.e., ``-g``
242flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``). This
243potentially allows more meaningful debugging information if your application crashes.
244
245If it is undesirable, default flags can be easily overridden:
246
247::
248
249 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
250 ./waf
251 sudo ./waf install
252
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700253:ref:`Additional step <build>`:
254
255 - on Linux::
256
257 sudo ldconfig
258
259 - on FreeBSD::
260
261 sudo ldconfig -m
262
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700263Documentation
264-------------
265
266ndn-cxx tutorials and API documentation can be built using the following
267commands:
268
269::
270
271 # Full set of documentation (tutorials + API) in build/docs
272 ./waf docs
273
274 # Only tutorials in `build/docs`
275 ./waf sphinx
276
277 # Only API docs in `build/docs/doxygen`
278 ./waf doxgyen
279
280Manpages are automatically created and installed during the normal build
281process (e.g., during ``./waf`` and ``./waf install``), if
282``python-sphinx`` module is detected during ``./waf configure`` stage.
283By default, manpages are installed into ``${PREFIX}/share/man`` (where
284default value for ``PREFIX`` is ``/usr/local``). This location can be
285changed during ``./waf configure`` stage using ``--prefix``,
286``--datarootdir``, or ``--mandir`` options.
287
288For more details, refer to ``./waf --help``.
289
290Development Build
291-----------------
292
293The following is the suggested configure commands for development build.
294
295::
296
297 ./waf configure --debug --with-tests
298 ./waf
299 sudo ./waf install
300
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700301:ref:`Additional step <build>`:
302
303 - on Linux::
304
305 sudo ldconfig
306
307 - on FreeBSD::
308
309 sudo ldconfig -m
310
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700311In the development build all compiler optimizations are disabled by
312default and all warnings are treated as error. The default behavior can
313be overridden by setting ``CXXFLAGS`` environment variable before
314running ``./waf configure``:
315
316::
317
318 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
319 ...
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800320
321Customize Compiler
322------------------
323
Davide Pesavento0530b5b2016-11-07 03:23:58 +0100324To choose a custom C++ compiler for building ndn-cxx, set ``CXX`` environment
325variable to point to the compiler binary. For example, to build with clang on
326Linux, use the following:
Alexander Afanasyev5946ed12015-01-19 23:41:39 -0800327
328::
329
Davide Pesavento0530b5b2016-11-07 03:23:58 +0100330 CXX=clang++ ./waf configure