blob: 4ad0fba5731733b62a8935c78a59b8eed1c6cd8f [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)
Eric Newberry935d7fe2017-10-29 15:09:36 -070012- macOS 10.13
Davide Pesavento534b8412018-12-08 19:19:09 -050013- macOS 10.14
Alexander Afanasyevcf8ffd42019-12-29 17:58:53 -080014- macOS 10.15
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 Pesavento78338c52020-04-20 23:00:02 -040020- Debian 10 (Buster)
Davide Pesavento2349e282020-03-24 14:28:03 -040021- Fedora >= 29
Ivan Yeoba1a4a92015-01-11 00:45:57 -080022- Gentoo Linux
Davide Pesavento78338c52020-04-20 23:00:02 -040023- Raspbian >= 2019-06-20 (Buster)
Davide Pesaventod776a932020-03-20 18:42:36 -040024- FreeBSD >= 11.3
Davide Pesavento534b8412018-12-08 19:19:09 -050025
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070026Prerequisites
27-------------
28
Davide Pesaventoab7300b2020-04-09 00:51:41 -040029Required
30~~~~~~~~
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070031
Davide Pesavento71c622b2020-04-24 01:39:01 -040032- GCC >= 7.4 or clang >= 4.0 (on Linux and FreeBSD)
33- Xcode >= 9.0 (on macOS)
Davide Pesavento78338c52020-04-20 23:00:02 -040034- Python >= 3.6
Davide Pesaventoab7300b2020-04-09 00:51:41 -040035- pkg-config
Davide Pesavento78338c52020-04-20 23:00:02 -040036- Boost >= 1.65.1
Davide Pesavento534b8412018-12-08 19:19:09 -050037- OpenSSL >= 1.0.2
Davide Pesaventod776a932020-03-20 18:42:36 -040038- SQLite 3.x
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070039
Davide Pesaventoab7300b2020-04-09 00:51:41 -040040To build ndn-cxx from source, one must first install a C++ compiler and all necessary
41development tools and libraries:
Davide Pesaventod776a932020-03-20 18:42:36 -040042
Davide Pesavento933a5672020-07-03 22:32:43 -040043- On **Ubuntu**
Davide Pesaventod776a932020-03-20 18:42:36 -040044
45 In a terminal, enter::
46
Davide Pesavento2349e282020-03-24 14:28:03 -040047 sudo apt install g++ pkg-config python3-minimal libboost-all-dev libssl-dev libsqlite3-dev
Davide Pesaventod776a932020-03-20 18:42:36 -040048
Davide Pesavento933a5672020-07-03 22:32:43 -040049- On **CentOS** and **Fedora**
Davide Pesaventod776a932020-03-20 18:42:36 -040050
51 In a terminal, enter::
52
Davide Pesavento2349e282020-03-24 14:28:03 -040053 sudo dnf install gcc-c++ pkgconf-pkg-config python3 boost-devel openssl-devel sqlite-devel
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070054
Davide Pesavento933a5672020-07-03 22:32:43 -040055- On **macOS**
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070056
Davide Pesaventod776a932020-03-20 18:42:36 -040057 * Install either Xcode (from the App Store) or the Command Line Tools
58 (with ``xcode-select --install``)
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070059
Davide Pesavento534b8412018-12-08 19:19:09 -050060 * If using Homebrew (recommended), enter the following in a terminal::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070061
Davide Pesavento534b8412018-12-08 19:19:09 -050062 brew install boost openssl pkg-config
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070063
Davide Pesavento933a5672020-07-03 22:32:43 -040064 .. warning::
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070065
Davide Pesavento534b8412018-12-08 19:19:09 -050066 If a major OS upgrade is performed after installing the dependencies
67 with Homebrew, remember to reinstall all packages.
Alexander Afanasyev67cb75c2016-06-15 12:34:58 -070068
Davide Pesavento933a5672020-07-03 22:32:43 -040069- On **FreeBSD**
Davide Pesavento534b8412018-12-08 19:19:09 -050070
71 In a terminal, enter::
72
Davide Pesaventod776a932020-03-20 18:42:36 -040073 sudo pkg install pkgconf python3 boost-libs openssl sqlite3
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070074
Davide Pesaventoab7300b2020-04-09 00:51:41 -040075Optional
76~~~~~~~~
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070077
Davide Pesaventoab7300b2020-04-09 00:51:41 -040078To build tutorials, manpages, and API documentation the following additional dependencies
79need to be installed:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070080
Davide Pesaventoab7300b2020-04-09 00:51:41 -040081- doxygen
82- graphviz
Davide Pesavento933a5672020-07-03 22:32:43 -040083- sphinx >= 1.3
Davide Pesaventoab7300b2020-04-09 00:51:41 -040084- sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070085
Davide Pesaventod776a932020-03-20 18:42:36 -040086The following lists the steps to install these prerequisites on various common platforms.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070087
Davide Pesavento933a5672020-07-03 22:32:43 -040088- On **Ubuntu**:
89
90 .. code-block:: sh
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070091
Davide Pesavento534b8412018-12-08 19:19:09 -050092 sudo apt install doxygen graphviz python3-pip
93 sudo pip3 install sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070094
Davide Pesavento933a5672020-07-03 22:32:43 -040095- On **CentOS** and **Fedora**:
96
97 .. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070098
Davide Pesavento2349e282020-03-24 14:28:03 -040099 sudo dnf config-manager --enable PowerTools # on CentOS only
100 sudo dnf install doxygen graphviz python3-pip
101 pip3 install --user sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700102
Davide Pesavento933a5672020-07-03 22:32:43 -0400103- On **macOS**:
104
105 .. code-block:: sh
Davide Pesaventod776a932020-03-20 18:42:36 -0400106
107 brew install doxygen graphviz
108 sudo pip install sphinx sphinxcontrib-doxylink
109
Davide Pesavento933a5672020-07-03 22:32:43 -0400110- On **FreeBSD**:
111
112 .. code-block:: sh
Davide Pesavento534b8412018-12-08 19:19:09 -0500113
Davide Pesaventod776a932020-03-20 18:42:36 -0400114 sudo pkg install doxygen graphviz py37-sphinx
Davide Pesavento534b8412018-12-08 19:19:09 -0500115
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700116Build
117-----
118
Davide Pesavento534b8412018-12-08 19:19:09 -0500119.. note::
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400120 These are instructions for regular builds of ndn-cxx (release mode). If you are
121 planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700122
Davide Pesavento933a5672020-07-03 22:32:43 -0400123To build in a terminal, change directory to the ndn-cxx root, then enter:
124
125.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700126
Davide Pesavento2349e282020-03-24 14:28:03 -0400127 ./waf configure # on CentOS, add --without-pch
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700128 ./waf
129 sudo ./waf install
130
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400131By default, only the shared variant of the ndn-cxx library will be built. To build the
Davide Pesavento933a5672020-07-03 22:32:43 -0400132static library, pass ``--enable-static`` to the ``./waf configure`` command:
133
134.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700135
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700136 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700137
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400138To disable the build of the shared library and build only the static library, use the
139additional ``--disable-shared`` option. Note that at least one variant of the library
140needs to be enabled.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700141
Davide Pesavento933a5672020-07-03 22:32:43 -0400142.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700143
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700144 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700145
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400146On Linux, it is necessary to run the following command after the shared library has
Davide Pesavento933a5672020-07-03 22:32:43 -0400147been installed:
148
149.. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700150
Davide Pesavento534b8412018-12-08 19:19:09 -0500151 sudo ldconfig
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700152
Davide Pesavento534b8412018-12-08 19:19:09 -0500153.. note::
154 When the library is installed in a non-standard path (in general: not in ``/usr/lib``
155 or ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
156 additional actions may be necessary.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700157
Davide Pesavento534b8412018-12-08 19:19:09 -0500158 The installation path should be added to ``/etc/ld.so.conf`` (or in
Davide Pesavento933a5672020-07-03 22:32:43 -0400159 ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example:
160
161 .. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700162
Davide Pesavento534b8412018-12-08 19:19:09 -0500163 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700164
Davide Pesavento534b8412018-12-08 19:19:09 -0500165 Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
Davide Pesavento933a5672020-07-03 22:32:43 -0400166 the installation directory of the shared library:
167
168 .. code-block:: sh
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700169
Davide Pesavento534b8412018-12-08 19:19:09 -0500170 export LD_LIBRARY_PATH=/usr/local/lib
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700171
Davide Pesavento534b8412018-12-08 19:19:09 -0500172The ``./waf install`` command installs the following files:
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700173
Davide Pesavento534b8412018-12-08 19:19:09 -0500174- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled).
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700175- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
Davide Pesavento534b8412018-12-08 19:19:09 -0500176 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on macOS):
177 shared NDN C++ library (if enabled).
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400178- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all necessary flags to
179 build against the library. For example, if the ``pkg-config`` or ``pkgconf-pkg-config``
180 package is installed and ``PKG_CONFIG_PATH`` is configured properly (or if
181 ``<LIBPATH>/pkgconfig`` is a default search path), the command ``pkg-config --cflags
182 --libs libndn-cxx`` will return all necessary compile and link flags for the library.
Davide Pesavento534b8412018-12-08 19:19:09 -0500183- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates.
184- ``<BINPATH>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700185
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400186If configured with tests (``./waf configure --with-tests``), the above commands
187will also produce:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700188
Davide Pesavento534b8412018-12-08 19:19:09 -0500189- ``build/unit-tests``: a unit test binary for the library.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700190
Davide Pesaventoab7300b2020-04-09 00:51:41 -04001911.5 GB available memory per CPU core is necessary for efficient compilation. On a
192multi-core machine with less than 1.5 GB available memory per CPU core, limit the
193objects being compiled in parallel with ``./waf -jN``, where N is the amount of
194available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
195should avoid memory thrashing and result in faster compilation.
Junxiao Shie04bd832014-11-29 23:02:38 -0700196
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700197Build with examples
198-------------------
199
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400200By default, the examples in the ``examples/`` directory will not be built. To enable
Davide Pesavento933a5672020-07-03 22:32:43 -0400201them, pass ``--with-examples`` during the configuration step:
202
203.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700204
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400205 ./waf configure --with-examples # on CentOS, add --without-pch
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700206 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700207 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400208 sudo ldconfig # on Linux only
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700209
Davide Pesavento933a5672020-07-03 22:32:43 -0400210To run the examples:
211
212.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700213
214 # trivial producer app
215 ./build/examples/producer
216
217 # trivial consumer app
218 ./build/examples/consumer
219
220 # trivial consumer app with timers
221 ./build/examples/consumer-with-timer
222
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400223If you want to make a new sample application, just create a ``.cpp`` file inside the
Davide Pesavento933a5672020-07-03 22:32:43 -0400224``examples/`` directory and it will be compiled during the next run of ``./waf``:
225
226.. code-block:: sh
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700227
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400228 cp examples/consumer.cpp examples/my-new-app.cpp
229 ... # edit examples/my-new-app.cpp with your preferred editor
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700230 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700231 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400232 sudo ldconfig # on Linux only
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400233 ./build/examples/my-new-app
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700234
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700235Debug symbols
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400236-------------
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700237
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400238The default compiler flags include debug symbols in binaries. This should provide
239more meaningful debugging information if ndn-cxx or your application crashes.
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700240
Eric Newberrybdfb53a2020-10-01 10:43:46 -0700241If this is not desired, the default flags can be overridden to disable debug symbols.
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400242The following example shows how to completely disable debug symbols and configure
243ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.
244
Davide Pesavento933a5672020-07-03 22:32:43 -0400245.. code-block:: sh
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700246
247 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
248 ./waf
249 sudo ./waf install
250
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400251Customizing the compiler
252------------------------
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700253
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400254To build ndn-cxx with a different compiler (rather than the platform default), set the
255``CXX`` environment variable to point to the compiler binary. For example, to build
Davide Pesavento933a5672020-07-03 22:32:43 -0400256with clang on Linux, use the following:
257
258.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700259
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400260 CXX=clang++ ./waf configure
261
262Building the documentation
263--------------------------
264
Eric Newberrybdfb53a2020-10-01 10:43:46 -0700265Tutorials and API documentation can be built using the following commands:
Davide Pesavento933a5672020-07-03 22:32:43 -0400266
267.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700268
269 # Full set of documentation (tutorials + API) in build/docs
270 ./waf docs
271
Davide Pesavento2349e282020-03-24 14:28:03 -0400272 # Only tutorials in build/docs
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700273 ./waf sphinx
274
Davide Pesavento2349e282020-03-24 14:28:03 -0400275 # Only API docs in build/docs/doxygen
Sepehr Abdous4fc6db22018-08-22 15:26:06 -0700276 ./waf doxygen
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700277
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400278If ``sphinx-build`` is detected during ``./waf configure``, manpages will automatically
279be built and installed during the normal build process (i.e., during ``./waf`` and
280``./waf install``). By default, manpages will be installed into ``${PREFIX}/share/man``
281(the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
282during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
283``--mandir`` options.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700284
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400285For further details, please refer to ``./waf --help``.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700286
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400287.. _Development build:
Davide Pesavento534b8412018-12-08 19:19:09 -0500288
289Development build
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700290-----------------
291
Davide Pesavento933a5672020-07-03 22:32:43 -0400292The following is the suggested build procedure for development builds:
293
294.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700295
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400296 ./waf configure --debug --with-tests # on CentOS, add --without-pch
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700297 ./waf
298 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400299 sudo ldconfig # on Linux only
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700300
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400301In a development build, most compiler optimizations will be disabled and all warnings
302will be treated as errors. This default behavior can be overridden by setting the
Davide Pesavento933a5672020-07-03 22:32:43 -0400303``CXXFLAGS`` environment variable before running ``./waf configure``, for example:
304
305.. code-block:: sh
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700306
307 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
308 ...