blob: 45652abaeef73f6480ef55cba58512312a494bde [file] [log] [blame]
Alexander Afanasyevc5452c52014-04-29 17:21:51 -07001Getting started with ndn-cxx
2============================
3
4Supported platforms
5-------------------
6
Davide Pesaventoab7300b2020-04-09 00:51:41 -04007ndn-cxx is built against a continuous integration system and has been tested on the
8following platforms:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -07009
Davide Pesaventof6625002022-07-31 17:15:02 -040010- Ubuntu 18.04
11- Ubuntu 20.04
12- Ubuntu 22.04
13- Debian 11
14- CentOS Stream 9
15- macOS 10.15
16- macOS 11
17- macOS 12
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
Davide Pesaventof6625002022-07-31 17:15:02 -040022- Alpine >= 3.12
23- Fedora >= 29
24- Gentoo Linux
25- Raspberry Pi OS (formerly Raspbian) >= 2019-06-20
26- FreeBSD >= 12.0
Davide Pesavento534b8412018-12-08 19:19:09 -050027
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070028Prerequisites
29-------------
30
Davide Pesaventoab7300b2020-04-09 00:51:41 -040031Required
32~~~~~~~~
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070033
Davide Pesaventof6625002022-07-31 17:15:02 -040034- GCC >= 7.4 or clang >= 6.0 (if you are on Linux or FreeBSD)
35- Xcode >= 11.3 or corresponding version of Command Line Tools (if you are on macOS)
36- Python >= 3.6
37- pkg-config
38- Boost >= 1.65.1
39- OpenSSL >= 1.1.1
40- SQLite 3.x
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070041
Davide Pesaventoab7300b2020-04-09 00:51:41 -040042To build ndn-cxx from source, one must first install a C++ compiler and all necessary
43development tools and libraries:
Davide Pesaventod776a932020-03-20 18:42:36 -040044
Davide Pesavento933a5672020-07-03 22:32:43 -040045- On **Ubuntu**
Davide Pesaventod776a932020-03-20 18:42:36 -040046
47 In a terminal, enter::
48
Davide Pesavento30ed6282021-07-25 20:05:06 -040049 sudo apt install build-essential pkg-config python3-minimal libboost-all-dev libssl-dev libsqlite3-dev
Davide Pesaventod776a932020-03-20 18:42:36 -040050
Davide Pesavento933a5672020-07-03 22:32:43 -040051- On **CentOS** and **Fedora**
Davide Pesaventod776a932020-03-20 18:42:36 -040052
53 In a terminal, enter::
54
Davide Pesavento2349e282020-03-24 14:28:03 -040055 sudo dnf install gcc-c++ pkgconf-pkg-config python3 boost-devel openssl-devel sqlite-devel
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070056
Davide Pesavento933a5672020-07-03 22:32:43 -040057- On **macOS**
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070058
Davide Pesaventod776a932020-03-20 18:42:36 -040059 * Install either Xcode (from the App Store) or the Command Line Tools
60 (with ``xcode-select --install``)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070061
Davide Pesaventocad94b02021-04-09 21:23:03 -040062 * If using Homebrew (recommended), enter the following in a terminal:
63
64 .. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070065
Davide Pesavento534b8412018-12-08 19:19:09 -050066 brew install boost openssl pkg-config
Davide Pesaventocad94b02021-04-09 21:23:03 -040067 brew install python # only on macOS 10.14 and earlier
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070068
Davide Pesavento933a5672020-07-03 22:32:43 -040069 .. warning::
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070070
Davide Pesavento534b8412018-12-08 19:19:09 -050071 If a major OS upgrade is performed after installing the dependencies
72 with Homebrew, remember to reinstall all packages.
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070073
Davide Pesavento933a5672020-07-03 22:32:43 -040074- On **FreeBSD**
Davide Pesavento534b8412018-12-08 19:19:09 -050075
76 In a terminal, enter::
77
Davide Pesaventod776a932020-03-20 18:42:36 -040078 sudo pkg install pkgconf python3 boost-libs openssl sqlite3
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070079
Davide Pesaventoab7300b2020-04-09 00:51:41 -040080Optional
81~~~~~~~~
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070082
Davide Pesavento01cea502021-07-31 19:25:42 -040083To build tutorials, man pages, and API documentation the following additional dependencies
Davide Pesaventoab7300b2020-04-09 00:51:41 -040084need to be installed:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070085
Davide Pesaventof6625002022-07-31 17:15:02 -040086- doxygen
87- graphviz
88- sphinx >= 1.3
89- sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070090
Davide Pesaventod776a932020-03-20 18:42:36 -040091The following lists the steps to install these prerequisites on various common platforms.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070092
Davide Pesavento3ffae262021-08-27 18:48:22 -040093.. note::
94 On Linux, you may need to add ``$HOME/.local/bin`` to the ``PATH`` environment variable
95 for your user, for example:
96
97 .. code-block:: sh
98
99 export PATH="${HOME}/.local/bin${PATH:+:}${PATH}"
100
Davide Pesavento933a5672020-07-03 22:32:43 -0400101- On **Ubuntu**:
102
103 .. code-block:: sh
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700104
Davide Pesavento534b8412018-12-08 19:19:09 -0500105 sudo apt install doxygen graphviz python3-pip
Davide Pesavento30ed6282021-07-25 20:05:06 -0400106 pip3 install --user sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700107
Davide Pesavento933a5672020-07-03 22:32:43 -0400108- On **CentOS** and **Fedora**:
109
110 .. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700111
Davide Pesavento2349e282020-03-24 14:28:03 -0400112 sudo dnf install doxygen graphviz python3-pip
113 pip3 install --user sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700114
Davide Pesavento933a5672020-07-03 22:32:43 -0400115- On **macOS**:
116
117 .. code-block:: sh
Davide Pesaventod776a932020-03-20 18:42:36 -0400118
119 brew install doxygen graphviz
Davide Pesavento30ed6282021-07-25 20:05:06 -0400120 sudo pip3 install sphinx sphinxcontrib-doxylink
Davide Pesaventod776a932020-03-20 18:42:36 -0400121
Davide Pesavento933a5672020-07-03 22:32:43 -0400122- On **FreeBSD**:
123
124 .. code-block:: sh
Davide Pesavento534b8412018-12-08 19:19:09 -0500125
Davide Pesaventod776a932020-03-20 18:42:36 -0400126 sudo pkg install doxygen graphviz py37-sphinx
Davide Pesavento534b8412018-12-08 19:19:09 -0500127
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700128Build
129-----
130
Davide Pesavento534b8412018-12-08 19:19:09 -0500131.. note::
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400132 These are instructions for regular builds of ndn-cxx (release mode). If you are
133 planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700134
Davide Pesavento933a5672020-07-03 22:32:43 -0400135To build in a terminal, change directory to the ndn-cxx root, then enter:
136
137.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700138
Davide Pesaventofbca6112022-07-03 16:31:04 -0400139 ./waf configure
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700140 ./waf
141 sudo ./waf install
142
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400143By default, only the shared variant of the ndn-cxx library will be built. To build the
Davide Pesavento933a5672020-07-03 22:32:43 -0400144static library, pass ``--enable-static`` to the ``./waf configure`` command:
145
146.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700147
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700148 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700149
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400150To disable the build of the shared library and build only the static library, use the
151additional ``--disable-shared`` option. Note that at least one variant of the library
152needs to be enabled.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700153
Davide Pesavento933a5672020-07-03 22:32:43 -0400154.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700155
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700156 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700157
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400158On Linux, it is necessary to run the following command after the shared library has
Davide Pesavento933a5672020-07-03 22:32:43 -0400159been installed:
160
161.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700162
Davide Pesavento534b8412018-12-08 19:19:09 -0500163 sudo ldconfig
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700164
Davide Pesavento534b8412018-12-08 19:19:09 -0500165.. note::
Davide Pesaventofbca6112022-07-03 16:31:04 -0400166 When the library is installed in a non-default location (in general: not in ``/usr/lib``
167 or ``/usr/local/lib``; on some Linux distros like Fedora and its derivatives, including
168 CentOS: not in ``/usr/lib``), the following additional actions may be necessary.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700169
Davide Pesaventofbca6112022-07-03 16:31:04 -0400170 The library installation path should be added to ``/etc/ld.so.conf`` or in
171 ``/etc/ld.so.conf.d/*.conf`` **before** running ``ldconfig``. For example:
Davide Pesavento933a5672020-07-03 22:32:43 -0400172
173 .. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700174
Davide Pesavento534b8412018-12-08 19:19:09 -0500175 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700176
Davide Pesavento534b8412018-12-08 19:19:09 -0500177 Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
Davide Pesavento933a5672020-07-03 22:32:43 -0400178 the installation directory of the shared library:
179
180 .. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700181
Davide Pesavento534b8412018-12-08 19:19:09 -0500182 export LD_LIBRARY_PATH=/usr/local/lib
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700183
Davide Pesavento534b8412018-12-08 19:19:09 -0500184The ``./waf install`` command installs the following files:
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700185
Davide Pesavento534b8412018-12-08 19:19:09 -0500186- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled).
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700187- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
Davide Pesavento534b8412018-12-08 19:19:09 -0500188 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on macOS):
189 shared NDN C++ library (if enabled).
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400190- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all necessary flags to
191 build against the library. For example, if the ``pkg-config`` or ``pkgconf-pkg-config``
192 package is installed and ``PKG_CONFIG_PATH`` is configured properly (or if
193 ``<LIBPATH>/pkgconfig`` is a default search path), the command ``pkg-config --cflags
194 --libs libndn-cxx`` will return all necessary compile and link flags for the library.
Davide Pesavento534b8412018-12-08 19:19:09 -0500195- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates.
196- ``<BINPATH>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700197
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400198If configured with tests (``./waf configure --with-tests``), the above commands
199will also produce:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700200
Davide Pesavento534b8412018-12-08 19:19:09 -0500201- ``build/unit-tests``: a unit test binary for the library.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700202
Davide Pesaventoab7300b2020-04-09 00:51:41 -04002031.5 GB available memory per CPU core is necessary for efficient compilation. On a
204multi-core machine with less than 1.5 GB available memory per CPU core, limit the
205objects being compiled in parallel with ``./waf -jN``, where N is the amount of
206available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
207should avoid memory thrashing and result in faster compilation.
Junxiao Shie04bd832014-11-29 23:02:38 -0700208
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700209Build with examples
210-------------------
211
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400212By default, the examples in the ``examples/`` directory will not be built. To enable
Davide Pesavento933a5672020-07-03 22:32:43 -0400213them, pass ``--with-examples`` during the configuration step:
214
215.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700216
Davide Pesaventofbca6112022-07-03 16:31:04 -0400217 ./waf configure --with-examples
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700218 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700219 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400220 sudo ldconfig # on Linux only
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700221
Davide Pesavento933a5672020-07-03 22:32:43 -0400222To run the examples:
223
224.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700225
226 # trivial producer app
227 ./build/examples/producer
228
229 # trivial consumer app
230 ./build/examples/consumer
231
232 # trivial consumer app with timers
233 ./build/examples/consumer-with-timer
234
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400235If you want to make a new sample application, just create a ``.cpp`` file inside the
Davide Pesavento933a5672020-07-03 22:32:43 -0400236``examples/`` directory and it will be compiled during the next run of ``./waf``:
237
238.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700239
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400240 cp examples/consumer.cpp examples/my-new-app.cpp
241 ... # edit examples/my-new-app.cpp with your preferred editor
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700242 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700243 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400244 sudo ldconfig # on Linux only
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400245 ./build/examples/my-new-app
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700246
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700247Debug symbols
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400248-------------
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700249
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400250The default compiler flags include debug symbols in binaries. This should provide
251more meaningful debugging information if ndn-cxx or your application crashes.
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700252
Eric Newberrybdfb53a2020-10-01 10:43:46 -0700253If this is not desired, the default flags can be overridden to disable debug symbols.
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400254The following example shows how to completely disable debug symbols and configure
255ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.
256
Davide Pesavento933a5672020-07-03 22:32:43 -0400257.. code-block:: sh
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700258
259 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
260 ./waf
261 sudo ./waf install
262
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400263Customizing the compiler
264------------------------
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700265
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400266To build ndn-cxx with a different compiler (rather than the platform default), set the
267``CXX`` environment variable to point to the compiler binary. For example, to build
Davide Pesavento933a5672020-07-03 22:32:43 -0400268with clang on Linux, use the following:
269
270.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700271
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400272 CXX=clang++ ./waf configure
273
274Building the documentation
275--------------------------
276
Eric Newberrybdfb53a2020-10-01 10:43:46 -0700277Tutorials and API documentation can be built using the following commands:
Davide Pesavento933a5672020-07-03 22:32:43 -0400278
279.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700280
281 # Full set of documentation (tutorials + API) in build/docs
282 ./waf docs
283
Davide Pesavento2349e282020-03-24 14:28:03 -0400284 # Only tutorials in build/docs
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700285 ./waf sphinx
286
Davide Pesavento2349e282020-03-24 14:28:03 -0400287 # Only API docs in build/docs/doxygen
Sepehr Abdous4fc6db22018-08-22 15:26:06 -0700288 ./waf doxygen
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700289
Davide Pesavento01cea502021-07-31 19:25:42 -0400290If ``sphinx-build`` is detected during ``./waf configure``, man pages will automatically
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400291be built and installed during the normal build process (i.e., during ``./waf`` and
Davide Pesavento01cea502021-07-31 19:25:42 -0400292``./waf install``). By default, man pages will be installed into ``${PREFIX}/share/man``
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400293(the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
294during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
295``--mandir`` options.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700296
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400297For further details, please refer to ``./waf --help``.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700298
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400299.. _Development build:
Davide Pesavento534b8412018-12-08 19:19:09 -0500300
301Development build
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700302-----------------
303
Davide Pesavento933a5672020-07-03 22:32:43 -0400304The following is the suggested build procedure for development builds:
305
306.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700307
Davide Pesaventofbca6112022-07-03 16:31:04 -0400308 ./waf configure --debug --with-tests
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700309 ./waf
310 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400311 sudo ldconfig # on Linux only
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700312
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400313In a development build, most compiler optimizations will be disabled and all warnings
314will be treated as errors. This default behavior can be overridden by setting the
Davide Pesavento933a5672020-07-03 22:32:43 -0400315``CXXFLAGS`` environment variable before running ``./waf configure``, for example:
316
317.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700318
319 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
320 ...