blob: 798ac408969a80a05f52541c1b9de030f095fe59 [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 Pesavento762548b2023-03-05 11:02:02 -050010- Ubuntu 20.04 (focal)
11- Ubuntu 22.04 (jammy)
12- Debian 11 (bullseye)
Davide Pesaventoe1005da2023-10-31 20:35:02 -040013- Debian 12 (bookworm)
Davide Pesaventof6625002022-07-31 17:15:02 -040014- CentOS Stream 9
Davide Pesaventoe1005da2023-10-31 20:35:02 -040015- macOS 11 / 12 / 13 / 14
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070016
Davide Pesavento762548b2023-03-05 11:02:02 -050017ndn-cxx should also work on the following platforms, although they are not officially
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070018supported:
19
Davide Pesavento762548b2023-03-05 11:02:02 -050020- Any other recent version of Ubuntu not listed above
Davide Pesaventoe1005da2023-10-31 20:35:02 -040021- Fedora >= 33
Davide Pesaventof6625002022-07-31 17:15:02 -040022- Alpine >= 3.12
Davide Pesaventoe1005da2023-10-31 20:35:02 -040023- Any version of Raspberry Pi OS based on Debian 11 (bullseye) or later
Davide Pesavento762548b2023-03-05 11:02:02 -050024- macOS 10.15
Davide Pesaventoea5ce492022-09-30 20:25:25 -040025- FreeBSD >= 12.2
Davide Pesavento534b8412018-12-08 19:19:09 -050026
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070027Prerequisites
28-------------
29
Davide Pesaventoab7300b2020-04-09 00:51:41 -040030Required
31~~~~~~~~
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070032
Davide Pesavento762548b2023-03-05 11:02:02 -050033- GCC >= 9.3 or clang >= 7.0 (if you are on Linux or FreeBSD)
34- Xcode >= 12.4 or corresponding version of Command Line Tools (if you are on macOS)
35- Python >= 3.8
Davide Pesaventof6625002022-07-31 17:15:02 -040036- pkg-config
Davide Pesavento550d8c92023-11-05 01:30:01 -040037- Boost >= 1.71.0
Davide Pesaventof6625002022-07-31 17:15:02 -040038- OpenSSL >= 1.1.1
39- SQLite 3.x
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070040
Davide Pesaventoab7300b2020-04-09 00:51:41 -040041To build ndn-cxx from source, one must first install a C++ compiler and all necessary
42development tools and libraries:
Davide Pesaventod776a932020-03-20 18:42:36 -040043
Davide Pesavento87208f92022-08-30 19:51:23 -040044- On **Debian** and **Ubuntu**
Davide Pesaventod776a932020-03-20 18:42:36 -040045
46 In a terminal, enter::
47
Davide Pesavento30ed6282021-07-25 20:05:06 -040048 sudo apt install build-essential pkg-config python3-minimal libboost-all-dev libssl-dev libsqlite3-dev
Davide Pesaventod776a932020-03-20 18:42:36 -040049
Davide Pesavento933a5672020-07-03 22:32:43 -040050- On **CentOS** and **Fedora**
Davide Pesaventod776a932020-03-20 18:42:36 -040051
52 In a terminal, enter::
53
Davide Pesavento2349e282020-03-24 14:28:03 -040054 sudo dnf install gcc-c++ pkgconf-pkg-config python3 boost-devel openssl-devel sqlite-devel
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070055
Davide Pesavento933a5672020-07-03 22:32:43 -040056- On **macOS**
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070057
Davide Pesaventod776a932020-03-20 18:42:36 -040058 * Install either Xcode (from the App Store) or the Command Line Tools
59 (with ``xcode-select --install``)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070060
Davide Pesaventocad94b02021-04-09 21:23:03 -040061 * If using Homebrew (recommended), enter the following in a terminal:
62
63 .. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070064
Davide Pesavento534b8412018-12-08 19:19:09 -050065 brew install boost openssl pkg-config
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070066
Davide Pesavento933a5672020-07-03 22:32:43 -040067 .. warning::
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070068
Davide Pesavento534b8412018-12-08 19:19:09 -050069 If a major OS upgrade is performed after installing the dependencies
70 with Homebrew, remember to reinstall all packages.
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070071
Davide Pesavento933a5672020-07-03 22:32:43 -040072- On **FreeBSD**
Davide Pesavento534b8412018-12-08 19:19:09 -050073
74 In a terminal, enter::
75
Davide Pesaventod776a932020-03-20 18:42:36 -040076 sudo pkg install pkgconf python3 boost-libs openssl sqlite3
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070077
Davide Pesaventoab7300b2020-04-09 00:51:41 -040078Optional
79~~~~~~~~
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070080
Davide Pesavento01cea502021-07-31 19:25:42 -040081To build tutorials, man pages, and API documentation the following additional dependencies
Davide Pesaventoab7300b2020-04-09 00:51:41 -040082need to be installed:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070083
Davide Pesaventof6625002022-07-31 17:15:02 -040084- doxygen
85- graphviz
Davide Pesavento02bbfa72022-09-21 20:53:03 -040086- sphinx >= 4.0
Davide Pesaventof6625002022-07-31 17:15:02 -040087- sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070088
Davide Pesaventod776a932020-03-20 18:42:36 -040089The following lists the steps to install these prerequisites on various common platforms.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070090
Davide Pesavento3ffae262021-08-27 18:48:22 -040091.. note::
92 On Linux, you may need to add ``$HOME/.local/bin`` to the ``PATH`` environment variable
93 for your user, for example:
94
95 .. code-block:: sh
96
97 export PATH="${HOME}/.local/bin${PATH:+:}${PATH}"
98
Davide Pesavento87208f92022-08-30 19:51:23 -040099- On **Debian** and **Ubuntu**:
Davide Pesavento933a5672020-07-03 22:32:43 -0400100
101 .. code-block:: sh
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700102
Davide Pesavento534b8412018-12-08 19:19:09 -0500103 sudo apt install doxygen graphviz python3-pip
Davide Pesavento30ed6282021-07-25 20:05:06 -0400104 pip3 install --user sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700105
Davide Pesavento933a5672020-07-03 22:32:43 -0400106- On **CentOS** and **Fedora**:
107
108 .. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700109
Davide Pesavento2349e282020-03-24 14:28:03 -0400110 sudo dnf install doxygen graphviz python3-pip
111 pip3 install --user sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700112
Davide Pesavento933a5672020-07-03 22:32:43 -0400113- On **macOS**:
114
115 .. code-block:: sh
Davide Pesaventod776a932020-03-20 18:42:36 -0400116
117 brew install doxygen graphviz
Davide Pesavento30ed6282021-07-25 20:05:06 -0400118 sudo pip3 install sphinx sphinxcontrib-doxylink
Davide Pesaventod776a932020-03-20 18:42:36 -0400119
Davide Pesavento933a5672020-07-03 22:32:43 -0400120- On **FreeBSD**:
121
122 .. code-block:: sh
Davide Pesavento534b8412018-12-08 19:19:09 -0500123
Davide Pesaventoea5ce492022-09-30 20:25:25 -0400124 sudo pkg install doxygen graphviz py39-sphinx
Davide Pesavento534b8412018-12-08 19:19:09 -0500125
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700126Build
127-----
128
Davide Pesavento534b8412018-12-08 19:19:09 -0500129.. note::
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400130 These are instructions for regular builds of ndn-cxx (release mode). If you are
131 planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700132
Davide Pesavento933a5672020-07-03 22:32:43 -0400133To build in a terminal, change directory to the ndn-cxx root, then enter:
134
135.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700136
Davide Pesaventofbca6112022-07-03 16:31:04 -0400137 ./waf configure
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700138 ./waf
139 sudo ./waf install
140
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400141By default, only the shared variant of the ndn-cxx library will be built. To build the
Davide Pesavento933a5672020-07-03 22:32:43 -0400142static library, pass ``--enable-static`` to the ``./waf configure`` command:
143
144.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700145
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700146 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700147
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400148To disable the build of the shared library and build only the static library, use the
149additional ``--disable-shared`` option. Note that at least one variant of the library
150needs to be enabled.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700151
Davide Pesavento933a5672020-07-03 22:32:43 -0400152.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700153
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700154 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700155
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400156On Linux, it is necessary to run the following command after the shared library has
Davide Pesavento933a5672020-07-03 22:32:43 -0400157been installed:
158
159.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700160
Davide Pesavento534b8412018-12-08 19:19:09 -0500161 sudo ldconfig
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700162
Davide Pesavento534b8412018-12-08 19:19:09 -0500163.. note::
Davide Pesaventofbca6112022-07-03 16:31:04 -0400164 When the library is installed in a non-default location (in general: not in ``/usr/lib``
165 or ``/usr/local/lib``; on some Linux distros like Fedora and its derivatives, including
166 CentOS: not in ``/usr/lib``), the following additional actions may be necessary.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700167
Davide Pesaventofbca6112022-07-03 16:31:04 -0400168 The library installation path should be added to ``/etc/ld.so.conf`` or in
169 ``/etc/ld.so.conf.d/*.conf`` **before** running ``ldconfig``. For example:
Davide Pesavento933a5672020-07-03 22:32:43 -0400170
171 .. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700172
Davide Pesavento534b8412018-12-08 19:19:09 -0500173 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700174
Davide Pesavento534b8412018-12-08 19:19:09 -0500175 Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
Davide Pesavento933a5672020-07-03 22:32:43 -0400176 the installation directory of the shared library:
177
178 .. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700179
Davide Pesavento534b8412018-12-08 19:19:09 -0500180 export LD_LIBRARY_PATH=/usr/local/lib
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700181
Davide Pesavento534b8412018-12-08 19:19:09 -0500182The ``./waf install`` command installs the following files:
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700183
Davide Pesavento534b8412018-12-08 19:19:09 -0500184- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled).
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700185- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
Davide Pesavento534b8412018-12-08 19:19:09 -0500186 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on macOS):
187 shared NDN C++ library (if enabled).
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400188- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all necessary flags to
189 build against the library. For example, if the ``pkg-config`` or ``pkgconf-pkg-config``
190 package is installed and ``PKG_CONFIG_PATH`` is configured properly (or if
191 ``<LIBPATH>/pkgconfig`` is a default search path), the command ``pkg-config --cflags
192 --libs libndn-cxx`` will return all necessary compile and link flags for the library.
Davide Pesavento576c21b2022-11-29 20:00:22 -0500193- ``<BINPATH>/ndnsec``: command-line tool to manage NDN keys and certificates.
Davide Pesavento534b8412018-12-08 19:19:09 -0500194- ``<BINPATH>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700195
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400196If configured with tests (``./waf configure --with-tests``), the above commands
197will also produce:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700198
Davide Pesavento534b8412018-12-08 19:19:09 -0500199- ``build/unit-tests``: a unit test binary for the library.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700200
Davide Pesaventoab7300b2020-04-09 00:51:41 -04002011.5 GB available memory per CPU core is necessary for efficient compilation. On a
202multi-core machine with less than 1.5 GB available memory per CPU core, limit the
203objects being compiled in parallel with ``./waf -jN``, where N is the amount of
204available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
205should avoid memory thrashing and result in faster compilation.
Junxiao Shie04bd832014-11-29 23:02:38 -0700206
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700207Build with examples
208-------------------
209
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400210By default, the examples in the ``examples/`` directory will not be built. To enable
Davide Pesavento933a5672020-07-03 22:32:43 -0400211them, pass ``--with-examples`` during the configuration step:
212
213.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700214
Davide Pesaventofbca6112022-07-03 16:31:04 -0400215 ./waf configure --with-examples
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700216 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700217 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400218 sudo ldconfig # on Linux only
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700219
Davide Pesavento933a5672020-07-03 22:32:43 -0400220To run the examples:
221
222.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700223
224 # trivial producer app
225 ./build/examples/producer
226
227 # trivial consumer app
228 ./build/examples/consumer
229
230 # trivial consumer app with timers
231 ./build/examples/consumer-with-timer
232
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400233If you want to make a new sample application, just create a ``.cpp`` file inside the
Davide Pesavento933a5672020-07-03 22:32:43 -0400234``examples/`` directory and it will be compiled during the next run of ``./waf``:
235
236.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700237
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400238 cp examples/consumer.cpp examples/my-new-app.cpp
239 ... # edit examples/my-new-app.cpp with your preferred editor
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700240 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700241 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400242 sudo ldconfig # on Linux only
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400243 ./build/examples/my-new-app
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700244
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700245Debug symbols
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400246-------------
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700247
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400248The default compiler flags include debug symbols in binaries. This should provide
249more meaningful debugging information if ndn-cxx or your application crashes.
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700250
Eric Newberrybdfb53a2020-10-01 10:43:46 -0700251If this is not desired, the default flags can be overridden to disable debug symbols.
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400252The following example shows how to completely disable debug symbols and configure
253ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.
254
Davide Pesavento933a5672020-07-03 22:32:43 -0400255.. code-block:: sh
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700256
257 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
258 ./waf
259 sudo ./waf install
260
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400261Customizing the compiler
262------------------------
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700263
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400264To build ndn-cxx with a different compiler (rather than the platform default), set the
265``CXX`` environment variable to point to the compiler binary. For example, to build
Davide Pesavento933a5672020-07-03 22:32:43 -0400266with clang on Linux, use the following:
267
268.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700269
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400270 CXX=clang++ ./waf configure
271
272Building the documentation
273--------------------------
274
Eric Newberrybdfb53a2020-10-01 10:43:46 -0700275Tutorials and API documentation can be built using the following commands:
Davide Pesavento933a5672020-07-03 22:32:43 -0400276
277.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700278
279 # Full set of documentation (tutorials + API) in build/docs
280 ./waf docs
281
Davide Pesavento2349e282020-03-24 14:28:03 -0400282 # Only tutorials in build/docs
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700283 ./waf sphinx
284
Davide Pesavento2349e282020-03-24 14:28:03 -0400285 # Only API docs in build/docs/doxygen
Sepehr Abdous4fc6db22018-08-22 15:26:06 -0700286 ./waf doxygen
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700287
Davide Pesavento01cea502021-07-31 19:25:42 -0400288If ``sphinx-build`` is detected during ``./waf configure``, man pages will automatically
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400289be built and installed during the normal build process (i.e., during ``./waf`` and
Davide Pesavento01cea502021-07-31 19:25:42 -0400290``./waf install``). By default, man pages will be installed into ``${PREFIX}/share/man``
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400291(the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
292during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
293``--mandir`` options.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700294
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400295For further details, please refer to ``./waf --help``.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700296
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400297.. _Development build:
Davide Pesavento534b8412018-12-08 19:19:09 -0500298
299Development build
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700300-----------------
301
Davide Pesavento933a5672020-07-03 22:32:43 -0400302The following is the suggested build procedure for development builds:
303
304.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700305
Davide Pesaventofbca6112022-07-03 16:31:04 -0400306 ./waf configure --debug --with-tests
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700307 ./waf
308 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400309 sudo ldconfig # on Linux only
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700310
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400311In a development build, most compiler optimizations will be disabled and all warnings
312will be treated as errors. This default behavior can be overridden by setting the
Davide Pesavento933a5672020-07-03 22:32:43 -0400313``CXXFLAGS`` environment variable before running ``./waf configure``, for example:
314
315.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700316
Davide Pesavento81de5d92022-12-30 01:08:05 -0500317 CXXFLAGS="-O1 -g3 -Wall" ./waf configure --debug --with-tests
318 ./waf