blob: f893d1af554bb5cb62f1ad6dd8a338bd8ffa435b [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)
Alexander Afanasyevcf8ffd42019-12-29 17:58:53 -080011- Ubuntu 19.10 (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
43- Ubuntu
44
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 Pesavento2349e282020-03-24 14:28:03 -040049- 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 Pesavento534b8412018-12-08 19:19:09 -050055- 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 Pesavento534b8412018-12-08 19:19:09 -050064 .. note::
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 Pesavento534b8412018-12-08 19:19:09 -050069- FreeBSD
70
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
83- sphinx
84- 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 Pesavento534b8412018-12-08 19:19:09 -050088- On Ubuntu::
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -070089
Davide Pesavento534b8412018-12-08 19:19:09 -050090 sudo apt install doxygen graphviz python3-pip
91 sudo pip3 install sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070092
Davide Pesavento2349e282020-03-24 14:28:03 -040093- On CentOS and Fedora::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070094
Davide Pesavento2349e282020-03-24 14:28:03 -040095 sudo dnf config-manager --enable PowerTools # on CentOS only
96 sudo dnf install doxygen graphviz python3-pip
97 pip3 install --user sphinx sphinxcontrib-doxylink
Alexander Afanasyevc5452c52014-04-29 17:21:51 -070098
Davide Pesaventod776a932020-03-20 18:42:36 -040099- On macOS::
100
101 brew install doxygen graphviz
102 sudo pip install sphinx sphinxcontrib-doxylink
103
Davide Pesavento534b8412018-12-08 19:19:09 -0500104- On FreeBSD::
105
Davide Pesaventod776a932020-03-20 18:42:36 -0400106 sudo pkg install doxygen graphviz py37-sphinx
Davide Pesavento534b8412018-12-08 19:19:09 -0500107
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700108Build
109-----
110
Davide Pesavento534b8412018-12-08 19:19:09 -0500111.. note::
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400112 These are instructions for regular builds of ndn-cxx (release mode). If you are
113 planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700114
Davide Pesavento534b8412018-12-08 19:19:09 -0500115To build in a terminal, change directory to the ndn-cxx root, then enter::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700116
Davide Pesavento2349e282020-03-24 14:28:03 -0400117 ./waf configure # on CentOS, add --without-pch
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700118 ./waf
119 sudo ./waf install
120
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400121By default, only the shared variant of the ndn-cxx library will be built. To build the
122static library, pass ``--enable-static`` to the ``./waf configure`` command::
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700123
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700124 ./waf configure --enable-static
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700125
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400126To disable the build of the shared library and build only the static library, use the
127additional ``--disable-shared`` option. Note that at least one variant of the library
128needs to be enabled.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700129
130::
131
Spyridon Mastorakis5ebfda62015-07-21 20:57:40 -0700132 ./waf configure --enable-static --disable-shared
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700133
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400134On Linux, it is necessary to run the following command after the shared library has
135been installed::
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700136
Davide Pesavento534b8412018-12-08 19:19:09 -0500137 sudo ldconfig
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700138
Davide Pesavento534b8412018-12-08 19:19:09 -0500139.. note::
140 When the library is installed in a non-standard path (in general: not in ``/usr/lib``
141 or ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
142 additional actions may be necessary.
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700143
Davide Pesavento534b8412018-12-08 19:19:09 -0500144 The installation path should be added to ``/etc/ld.so.conf`` (or in
145 ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700146
Davide Pesavento534b8412018-12-08 19:19:09 -0500147 echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700148
Davide Pesavento534b8412018-12-08 19:19:09 -0500149 Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
150 the installation directory of the shared library::
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700151
Davide Pesavento534b8412018-12-08 19:19:09 -0500152 export LD_LIBRARY_PATH=/usr/local/lib
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700153
Davide Pesavento534b8412018-12-08 19:19:09 -0500154The ``./waf install`` command installs the following files:
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700155
Davide Pesavento534b8412018-12-08 19:19:09 -0500156- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled).
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700157- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
Davide Pesavento534b8412018-12-08 19:19:09 -0500158 ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on macOS):
159 shared NDN C++ library (if enabled).
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400160- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all necessary flags to
161 build against the library. For example, if the ``pkg-config`` or ``pkgconf-pkg-config``
162 package is installed and ``PKG_CONFIG_PATH`` is configured properly (or if
163 ``<LIBPATH>/pkgconfig`` is a default search path), the command ``pkg-config --cflags
164 --libs libndn-cxx`` will return all necessary compile and link flags for the library.
Davide Pesavento534b8412018-12-08 19:19:09 -0500165- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates.
166- ``<BINPATH>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700167
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400168If configured with tests (``./waf configure --with-tests``), the above commands
169will also produce:
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700170
Davide Pesavento534b8412018-12-08 19:19:09 -0500171- ``build/unit-tests``: a unit test binary for the library.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700172
Davide Pesaventoab7300b2020-04-09 00:51:41 -04001731.5 GB available memory per CPU core is necessary for efficient compilation. On a
174multi-core machine with less than 1.5 GB available memory per CPU core, limit the
175objects being compiled in parallel with ``./waf -jN``, where N is the amount of
176available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
177should avoid memory thrashing and result in faster compilation.
Junxiao Shie04bd832014-11-29 23:02:38 -0700178
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700179Build with examples
180-------------------
181
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400182By default, the examples in the ``examples/`` directory will not be built. To enable
183them, pass ``--with-examples`` during the configuration step::
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700184
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400185 ./waf configure --with-examples # on CentOS, add --without-pch
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700186 ./waf
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700187 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400188 sudo ldconfig # on Linux only
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700189
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400190To run the examples::
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700191
192 # trivial producer app
193 ./build/examples/producer
194
195 # trivial consumer app
196 ./build/examples/consumer
197
198 # trivial consumer app with timers
199 ./build/examples/consumer-with-timer
200
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400201If you want to make a new sample application, just create a ``.cpp`` file inside the
202``examples/`` directory and it will be compiled during the next run of ``./waf``::
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700203
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400204 cp examples/consumer.cpp examples/my-new-app.cpp
205 ... # edit examples/my-new-app.cpp with your preferred editor
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
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400209 ./build/examples/my-new-app
Alexander Afanasyevc8bcd452014-05-12 17:58:47 -0700210
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700211Debug symbols
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400212-------------
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700213
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400214The default compiler flags include debug symbols in binaries. This should provide
215more meaningful debugging information if ndn-cxx or your application crashes.
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700216
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400217If this is undesirable, the default flags can be overridden to disable debug symbols.
218The following example shows how to completely disable debug symbols and configure
219ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.
220
221::
Alexander Afanasyev9b0e1142014-05-08 00:17:34 -0700222
223 CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
224 ./waf
225 sudo ./waf install
226
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400227Customizing the compiler
228------------------------
Alexander Afanasyev7ed29432015-06-05 18:01:16 -0700229
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400230To build ndn-cxx with a different compiler (rather than the platform default), set the
231``CXX`` environment variable to point to the compiler binary. For example, to build
232with clang on Linux, use the following::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700233
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400234 CXX=clang++ ./waf configure
235
236Building the documentation
237--------------------------
238
239ndn-cxx tutorials and API documentation can be built using the following commands::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700240
241 # Full set of documentation (tutorials + API) in build/docs
242 ./waf docs
243
Davide Pesavento2349e282020-03-24 14:28:03 -0400244 # Only tutorials in build/docs
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700245 ./waf sphinx
246
Davide Pesavento2349e282020-03-24 14:28:03 -0400247 # Only API docs in build/docs/doxygen
Sepehr Abdous4fc6db22018-08-22 15:26:06 -0700248 ./waf doxygen
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700249
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400250If ``sphinx-build`` is detected during ``./waf configure``, manpages will automatically
251be built and installed during the normal build process (i.e., during ``./waf`` and
252``./waf install``). By default, manpages will be installed into ``${PREFIX}/share/man``
253(the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
254during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
255``--mandir`` options.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700256
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400257For further details, please refer to ``./waf --help``.
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700258
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400259.. _Development build:
Davide Pesavento534b8412018-12-08 19:19:09 -0500260
261Development build
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700262-----------------
263
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400264The following is the suggested build procedure for development builds::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700265
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400266 ./waf configure --debug --with-tests # on CentOS, add --without-pch
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700267 ./waf
268 sudo ./waf install
Davide Pesavento2349e282020-03-24 14:28:03 -0400269 sudo ldconfig # on Linux only
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700270
Davide Pesaventoab7300b2020-04-09 00:51:41 -0400271In a development build, most compiler optimizations will be disabled and all warnings
272will be treated as errors. This default behavior can be overridden by setting the
273``CXXFLAGS`` environment variable before running ``./waf configure``, for example::
Alexander Afanasyevc5452c52014-04-29 17:21:51 -0700274
275 CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
276 ...