blob: 3fb4e59eb189eec5a460f9077e270ec2572dd59c [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 Pesavento2349e282020-03-24 14:28:03 -040010- Ubuntu 18.04 (amd64, armhf, i386)
Davide Pesavento933a5672020-07-03 22:32:43 -040011- Ubuntu 20.04 (amd64)
Alexander Afanasyev778ad712022-01-27 14:01:55 -050012- Ubuntu 21.10 (amd64)
Alexander Afanasyevcf8ffd42019-12-29 17:58:53 -080013- macOS 10.15
Davide Pesavento83f8d162021-09-26 21:58:36 -040014- macOS 11 (Intel only)
Davide Pesavento2349e282020-03-24 14:28:03 -040015- CentOS 8
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070016
17ndn-cxx is known to work on the following platforms, although they are not officially
18supported:
19
Davide Pesavento3ffae262021-08-27 18:48:22 -040020- Alpine >= 3.12
21- Debian >= 10
Davide Pesavento2349e282020-03-24 14:28:03 -040022- Fedora >= 29
Ivan Yeoba1a4a92015-01-11 00:45:57 -080023- Gentoo Linux
Davide Pesavento3ffae262021-08-27 18:48:22 -040024- Raspberry Pi OS (formerly Raspbian) >= 2019-06-20
Davide Pesaventod776a932020-03-20 18:42:36 -040025- FreeBSD >= 11.3
Davide Pesavento3ffae262021-08-27 18:48:22 -040026- macOS 10.14
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 Pesavento71c622b2020-04-24 01:39:01 -040034- GCC >= 7.4 or clang >= 4.0 (on Linux and FreeBSD)
35- Xcode >= 9.0 (on macOS)
Davide Pesavento78338c52020-04-20 23:00:02 -040036- Python >= 3.6
Davide Pesaventoab7300b2020-04-09 00:51:41 -040037- pkg-config
Davide Pesavento78338c52020-04-20 23:00:02 -040038- Boost >= 1.65.1
Davide Pesavento273ea012022-02-20 17:50:02 -050039- OpenSSL >= 1.1.1
Davide Pesaventod776a932020-03-20 18:42:36 -040040- 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 Pesaventoab7300b2020-04-09 00:51:41 -040086- doxygen
87- graphviz
Davide Pesavento933a5672020-07-03 22:32:43 -040088- sphinx >= 1.3
Davide Pesaventoab7300b2020-04-09 00:51:41 -040089- 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 Pesaventocad94b02021-04-09 21:23:03 -0400112 sudo dnf config-manager --enable powertools # on CentOS only
Davide Pesavento2349e282020-03-24 14:28:03 -0400113 sudo dnf install doxygen graphviz python3-pip
114 pip3 install --user sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700115
Davide Pesavento933a5672020-07-03 22:32:43 -0400116- On **macOS**:
117
118 .. code-block:: sh
Davide Pesaventod776a932020-03-20 18:42:36 -0400119
120 brew install doxygen graphviz
Davide Pesavento30ed6282021-07-25 20:05:06 -0400121 sudo pip3 install sphinx sphinxcontrib-doxylink
Davide Pesaventod776a932020-03-20 18:42:36 -0400122
Davide Pesavento933a5672020-07-03 22:32:43 -0400123- On **FreeBSD**:
124
125 .. code-block:: sh
Davide Pesavento534b8412018-12-08 19:19:09 -0500126
Davide Pesaventod776a932020-03-20 18:42:36 -0400127 sudo pkg install doxygen graphviz py37-sphinx
Davide Pesavento534b8412018-12-08 19:19:09 -0500128
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700129Build
130-----
131
Davide Pesavento534b8412018-12-08 19:19:09 -0500132.. note::
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400133 These are instructions for regular builds of ndn-cxx (release mode). If you are
134 planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700135
Davide Pesavento933a5672020-07-03 22:32:43 -0400136To build in a terminal, change directory to the ndn-cxx root, then enter:
137
138.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700139
Davide Pesavento2349e282020-03-24 14:28:03 -0400140 ./waf configure # on CentOS, add --without-pch
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700141 ./waf
142 sudo ./waf install
143
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400144By default, only the shared variant of the ndn-cxx library will be built. To build the
Davide Pesavento933a5672020-07-03 22:32:43 -0400145static library, pass ``--enable-static`` to the ``./waf configure`` command:
146
147.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700148
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700149 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700150
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400151To disable the build of the shared library and build only the static library, use the
152additional ``--disable-shared`` option. Note that at least one variant of the library
153needs to be enabled.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700154
Davide Pesavento933a5672020-07-03 22:32:43 -0400155.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700156
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700157 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700158
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400159On Linux, it is necessary to run the following command after the shared library has
Davide Pesavento933a5672020-07-03 22:32:43 -0400160been installed:
161
162.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700163
Davide Pesavento534b8412018-12-08 19:19:09 -0500164 sudo ldconfig
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700165
Davide Pesavento534b8412018-12-08 19:19:09 -0500166.. note::
167 When the library is installed in a non-standard path (in general: not in ``/usr/lib``
168 or ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
169 additional actions may be necessary.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700170
Davide Pesavento534b8412018-12-08 19:19:09 -0500171 The installation path should be added to ``/etc/ld.so.conf`` (or in
Davide Pesavento933a5672020-07-03 22:32:43 -0400172 ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example:
173
174 .. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700175
Davide Pesavento534b8412018-12-08 19:19:09 -0500176 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700177
Davide Pesavento534b8412018-12-08 19:19:09 -0500178 Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
Davide Pesavento933a5672020-07-03 22:32:43 -0400179 the installation directory of the shared library:
180
181 .. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700182
Davide Pesavento534b8412018-12-08 19:19:09 -0500183 export LD_LIBRARY_PATH=/usr/local/lib
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700184
Davide Pesavento534b8412018-12-08 19:19:09 -0500185The ``./waf install`` command installs the following files:
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700186
Davide Pesavento534b8412018-12-08 19:19:09 -0500187- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled).
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700188- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
Davide Pesavento534b8412018-12-08 19:19:09 -0500189 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on macOS):
190 shared NDN C++ library (if enabled).
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400191- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all necessary flags to
192 build against the library. For example, if the ``pkg-config`` or ``pkgconf-pkg-config``
193 package is installed and ``PKG_CONFIG_PATH`` is configured properly (or if
194 ``<LIBPATH>/pkgconfig`` is a default search path), the command ``pkg-config --cflags
195 --libs libndn-cxx`` will return all necessary compile and link flags for the library.
Davide Pesavento534b8412018-12-08 19:19:09 -0500196- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates.
197- ``<BINPATH>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700198
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400199If configured with tests (``./waf configure --with-tests``), the above commands
200will also produce:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700201
Davide Pesavento534b8412018-12-08 19:19:09 -0500202- ``build/unit-tests``: a unit test binary for the library.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700203
Davide Pesaventoab7300b2020-04-09 00:51:41 -04002041.5 GB available memory per CPU core is necessary for efficient compilation. On a
205multi-core machine with less than 1.5 GB available memory per CPU core, limit the
206objects being compiled in parallel with ``./waf -jN``, where N is the amount of
207available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
208should avoid memory thrashing and result in faster compilation.
Junxiao Shie04bd832014-11-29 23:02:38 -0700209
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700210Build with examples
211-------------------
212
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400213By default, the examples in the ``examples/`` directory will not be built. To enable
Davide Pesavento933a5672020-07-03 22:32:43 -0400214them, pass ``--with-examples`` during the configuration step:
215
216.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700217
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400218 ./waf configure --with-examples # on CentOS, add --without-pch
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700219 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700220 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400221 sudo ldconfig # on Linux only
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700222
Davide Pesavento933a5672020-07-03 22:32:43 -0400223To run the examples:
224
225.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700226
227 # trivial producer app
228 ./build/examples/producer
229
230 # trivial consumer app
231 ./build/examples/consumer
232
233 # trivial consumer app with timers
234 ./build/examples/consumer-with-timer
235
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400236If you want to make a new sample application, just create a ``.cpp`` file inside the
Davide Pesavento933a5672020-07-03 22:32:43 -0400237``examples/`` directory and it will be compiled during the next run of ``./waf``:
238
239.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700240
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400241 cp examples/consumer.cpp examples/my-new-app.cpp
242 ... # edit examples/my-new-app.cpp with your preferred editor
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700243 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700244 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400245 sudo ldconfig # on Linux only
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400246 ./build/examples/my-new-app
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700247
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700248Debug symbols
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400249-------------
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700250
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400251The default compiler flags include debug symbols in binaries. This should provide
252more meaningful debugging information if ndn-cxx or your application crashes.
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700253
Eric Newberrybdfb53a2020-10-01 10:43:46 -0700254If this is not desired, the default flags can be overridden to disable debug symbols.
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400255The following example shows how to completely disable debug symbols and configure
256ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.
257
Davide Pesavento933a5672020-07-03 22:32:43 -0400258.. code-block:: sh
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700259
260 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
261 ./waf
262 sudo ./waf install
263
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400264Customizing the compiler
265------------------------
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700266
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400267To build ndn-cxx with a different compiler (rather than the platform default), set the
268``CXX`` environment variable to point to the compiler binary. For example, to build
Davide Pesavento933a5672020-07-03 22:32:43 -0400269with clang on Linux, use the following:
270
271.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700272
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400273 CXX=clang++ ./waf configure
274
275Building the documentation
276--------------------------
277
Eric Newberrybdfb53a2020-10-01 10:43:46 -0700278Tutorials and API documentation can be built using the following commands:
Davide Pesavento933a5672020-07-03 22:32:43 -0400279
280.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700281
282 # Full set of documentation (tutorials + API) in build/docs
283 ./waf docs
284
Davide Pesavento2349e282020-03-24 14:28:03 -0400285 # Only tutorials in build/docs
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700286 ./waf sphinx
287
Davide Pesavento2349e282020-03-24 14:28:03 -0400288 # Only API docs in build/docs/doxygen
Sepehr Abdous4fc6db22018-08-22 15:26:06 -0700289 ./waf doxygen
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700290
Davide Pesavento01cea502021-07-31 19:25:42 -0400291If ``sphinx-build`` is detected during ``./waf configure``, man pages will automatically
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400292be built and installed during the normal build process (i.e., during ``./waf`` and
Davide Pesavento01cea502021-07-31 19:25:42 -0400293``./waf install``). By default, man pages will be installed into ``${PREFIX}/share/man``
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400294(the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
295during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
296``--mandir`` options.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700297
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400298For further details, please refer to ``./waf --help``.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700299
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400300.. _Development build:
Davide Pesavento534b8412018-12-08 19:19:09 -0500301
302Development build
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700303-----------------
304
Davide Pesavento933a5672020-07-03 22:32:43 -0400305The following is the suggested build procedure for development builds:
306
307.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700308
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400309 ./waf configure --debug --with-tests # on CentOS, add --without-pch
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700310 ./waf
311 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400312 sudo ldconfig # on Linux only
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700313
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400314In a development build, most compiler optimizations will be disabled and all warnings
315will be treated as errors. This default behavior can be overridden by setting the
Davide Pesavento933a5672020-07-03 22:32:43 -0400316``CXXFLAGS`` environment variable before running ``./waf configure``, for example:
317
318.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700319
320 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
321 ...