docs/INSTALL.rst - ndn-cxx - Gitiles

 Getting started with ndn-cxx
 ============================

 Supported platforms
 -------------------

 ndn-cxx is built against a continuous integration system and has been tested on the
 following platforms:

 -  Ubuntu 18.04 (amd64, armhf, i386)
 -  Ubuntu 19.10 (amd64)
 -  macOS 10.13
 -  macOS 10.14
 -  macOS 10.15
 -  CentOS 8

 ndn-cxx is known to work on the following platforms, although they are not officially
 supported:

 -  Debian 10 (Buster)
 -  Fedora >= 29
 -  Gentoo Linux
 -  Raspbian >= 2019-06-20 (Buster)
 -  FreeBSD >= 11.3

 Prerequisites
 -------------

 Required
 ~~~~~~~~

 -  GCC >= 7.4 or clang >= 4.0 (on Linux and FreeBSD)
 -  Xcode >= 9.0 (on macOS)
 -  Python >= 3.6
 -  pkg-config
 -  Boost >= 1.65.1
 -  OpenSSL >= 1.0.2
 -  SQLite 3.x

 To build ndn-cxx from source, one must first install a C++ compiler and all necessary
 development tools and libraries:

 - Ubuntu

     In a terminal, enter::

         sudo apt install g++ pkg-config python3-minimal libboost-all-dev libssl-dev libsqlite3-dev

 - CentOS and Fedora

     In a terminal, enter::

         sudo dnf install gcc-c++ pkgconf-pkg-config python3 boost-devel openssl-devel sqlite-devel

 - macOS

     * Install either Xcode (from the App Store) or the Command Line Tools
       (with ``xcode-select --install``)

     * If using Homebrew (recommended), enter the following in a terminal::

         brew install boost openssl pkg-config

       .. note::

         If a major OS upgrade is performed after installing the dependencies
         with Homebrew, remember to reinstall all packages.

 - FreeBSD

     In a terminal, enter::

         sudo pkg install pkgconf python3 boost-libs openssl sqlite3

 Optional
 ~~~~~~~~

 To build tutorials, manpages, and API documentation the following additional dependencies
 need to be installed:

 -  doxygen
 -  graphviz
 -  sphinx
 -  sphinxcontrib-doxylink

 The following lists the steps to install these prerequisites on various common platforms.

 - On Ubuntu::

     sudo apt install doxygen graphviz python3-pip
     sudo pip3 install sphinx sphinxcontrib-doxylink

 - On CentOS and Fedora::

     sudo dnf config-manager --enable PowerTools  # on CentOS only
     sudo dnf install doxygen graphviz python3-pip
     pip3 install --user sphinx sphinxcontrib-doxylink

 - On macOS::

     brew install doxygen graphviz
     sudo pip install sphinx sphinxcontrib-doxylink

 - On FreeBSD::

     sudo pkg install doxygen graphviz py37-sphinx

 Build
 -----

 .. note::
   These are instructions for regular builds of ndn-cxx (release mode). If you are
   planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.

 To build in a terminal, change directory to the ndn-cxx root, then enter::

     ./waf configure  # on CentOS, add --without-pch
     ./waf
     sudo ./waf install

 By default, only the shared variant of the ndn-cxx library will be built. To build the
 static library, pass ``--enable-static`` to the ``./waf configure`` command::

     ./waf configure --enable-static

 To disable the build of the shared library and build only the static library, use the
 additional ``--disable-shared`` option.  Note that at least one variant of the library
 needs to be enabled.

 ::

     ./waf configure --enable-static --disable-shared

 On Linux, it is necessary to run the following command after the shared library has
 been installed::

     sudo ldconfig

 .. note::
   When the library is installed in a non-standard path (in general: not in ``/usr/lib``
   or ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
   additional actions may be necessary.

   The installation path should be added to ``/etc/ld.so.conf`` (or in
   ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::

       echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf

   Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
   the installation directory of the shared library::

       export LD_LIBRARY_PATH=/usr/local/lib

 The ``./waf install`` command installs the following files:

 -  ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled).
 -  ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
    ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on macOS):
    shared NDN C++ library (if enabled).
 -  ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all necessary flags to
    build against the library. For example, if the ``pkg-config`` or ``pkgconf-pkg-config``
    package is installed and ``PKG_CONFIG_PATH`` is configured properly (or if
    ``<LIBPATH>/pkgconfig`` is a default search path), the command ``pkg-config --cflags
    --libs libndn-cxx`` will return all necessary compile and link flags for the library.
 -  ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates.
 -  ``<BINPATH>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.

 If configured with tests (``./waf configure --with-tests``), the above commands
 will also produce:

 -  ``build/unit-tests``: a unit test binary for the library.

 1.5 GB available memory per CPU core is necessary for efficient compilation. On a
 multi-core machine with less than 1.5 GB available memory per CPU core, limit the
 objects being compiled in parallel with ``./waf -jN``, where N is the amount of
 available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
 should avoid memory thrashing and result in faster compilation.

 Build with examples
 -------------------

 By default, the examples in the ``examples/`` directory will not be built. To enable
 them, pass ``--with-examples`` during the configuration step::

     ./waf configure --with-examples  # on CentOS, add --without-pch
     ./waf
     sudo ./waf install
     sudo ldconfig  # on Linux only

 To run the examples::

     # trivial producer app
     ./build/examples/producer

     # trivial consumer app
     ./build/examples/consumer

     # trivial consumer app with timers
     ./build/examples/consumer-with-timer

 If you want to make a new sample application, just create a ``.cpp`` file inside the
 ``examples/`` directory and it will be compiled during the next run of ``./waf``::

     cp examples/consumer.cpp examples/my-new-app.cpp
     ... # edit examples/my-new-app.cpp with your preferred editor
     ./waf
     sudo ./waf install
     sudo ldconfig  # on Linux only
     ./build/examples/my-new-app

 Debug symbols
 -------------

 The default compiler flags include debug symbols in binaries. This should provide
 more meaningful debugging information if ndn-cxx or your application crashes.

 If this is undesirable, the default flags can be overridden to disable debug symbols.
 The following example shows how to completely disable debug symbols and configure
 ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.

 ::

     CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
     ./waf
     sudo ./waf install

 Customizing the compiler
 ------------------------

 To build ndn-cxx with a different compiler (rather than the platform default), set the
 ``CXX`` environment variable to point to the compiler binary. For example, to build
 with clang on Linux, use the following::

     CXX=clang++ ./waf configure

 Building the documentation
 --------------------------

 ndn-cxx tutorials and API documentation can be built using the following commands::

     # Full set of documentation (tutorials + API) in build/docs
     ./waf docs

     # Only tutorials in build/docs
     ./waf sphinx

     # Only API docs in build/docs/doxygen
     ./waf doxygen

 If ``sphinx-build`` is detected during ``./waf configure``, manpages will automatically
 be built and installed during the normal build process (i.e., during ``./waf`` and
 ``./waf install``). By default, manpages will be installed into ``${PREFIX}/share/man``
 (the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
 during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
 ``--mandir`` options.

 For further details, please refer to ``./waf --help``.

 .. _Development build:

 Development build
 -----------------

 The following is the suggested build procedure for development builds::

     ./waf configure --debug --with-tests  # on CentOS, add --without-pch
     ./waf
     sudo ./waf install
     sudo ldconfig  # on Linux only

 In a development build, most compiler optimizations will be disabled and all warnings
 will be treated as errors. This default behavior can be overridden by setting the
 ``CXXFLAGS`` environment variable before running ``./waf configure``, for example::

     CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
     ...
	Getting started with ndn-cxx
	============================

	Supported platforms
	-------------------

	ndn-cxx is built against a continuous integration system and has been tested on the
	following platforms:

	- Ubuntu 18.04 (amd64, armhf, i386)
	- Ubuntu 19.10 (amd64)
	- macOS 10.13
	- macOS 10.14
	- macOS 10.15
	- CentOS 8

	ndn-cxx is known to work on the following platforms, although they are not officially
	supported:

	- Debian 10 (Buster)
	- Fedora >= 29
	- Gentoo Linux
	- Raspbian >= 2019-06-20 (Buster)
	- FreeBSD >= 11.3

	Prerequisites
	-------------

	Required
	~~~~~~~~

	- GCC >= 7.4 or clang >= 4.0 (on Linux and FreeBSD)
	- Xcode >= 9.0 (on macOS)
	- Python >= 3.6
	- pkg-config
	- Boost >= 1.65.1
	- OpenSSL >= 1.0.2
	- SQLite 3.x

	To build ndn-cxx from source, one must first install a C++ compiler and all necessary
	development tools and libraries:

	- Ubuntu

	In a terminal, enter::

	sudo apt install g++ pkg-config python3-minimal libboost-all-dev libssl-dev libsqlite3-dev

	- CentOS and Fedora

	In a terminal, enter::

	sudo dnf install gcc-c++ pkgconf-pkg-config python3 boost-devel openssl-devel sqlite-devel

	- macOS

	* Install either Xcode (from the App Store) or the Command Line Tools
	(with ``xcode-select --install``)

	* If using Homebrew (recommended), enter the following in a terminal::

	brew install boost openssl pkg-config

	.. note::

	If a major OS upgrade is performed after installing the dependencies
	with Homebrew, remember to reinstall all packages.

	- FreeBSD

	In a terminal, enter::

	sudo pkg install pkgconf python3 boost-libs openssl sqlite3

	Optional
	~~~~~~~~

	To build tutorials, manpages, and API documentation the following additional dependencies
	need to be installed:

	- doxygen
	- graphviz
	- sphinx
	- sphinxcontrib-doxylink

	The following lists the steps to install these prerequisites on various common platforms.

	- On Ubuntu::

	sudo apt install doxygen graphviz python3-pip
	sudo pip3 install sphinx sphinxcontrib-doxylink

	- On CentOS and Fedora::

	sudo dnf config-manager --enable PowerTools # on CentOS only
	sudo dnf install doxygen graphviz python3-pip
	pip3 install --user sphinx sphinxcontrib-doxylink

	- On macOS::

	brew install doxygen graphviz
	sudo pip install sphinx sphinxcontrib-doxylink

	- On FreeBSD::

	sudo pkg install doxygen graphviz py37-sphinx

	Build
	-----

	.. note::
	These are instructions for regular builds of ndn-cxx (release mode). If you are
	planning to develop the ndn-cxx code itself, you should do a :ref:`Development build`.

	To build in a terminal, change directory to the ndn-cxx root, then enter::

	./waf configure # on CentOS, add --without-pch
	./waf
	sudo ./waf install

	By default, only the shared variant of the ndn-cxx library will be built. To build the
	static library, pass ``--enable-static`` to the ``./waf configure`` command::

	./waf configure --enable-static

	To disable the build of the shared library and build only the static library, use the
	additional ``--disable-shared`` option. Note that at least one variant of the library
	needs to be enabled.

	::

	./waf configure --enable-static --disable-shared

	On Linux, it is necessary to run the following command after the shared library has
	been installed::

	sudo ldconfig

	.. note::
	When the library is installed in a non-standard path (in general: not in ``/usr/lib``
	or ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
	additional actions may be necessary.

	The installation path should be added to ``/etc/ld.so.conf`` (or in
	``/etc/ld.so.conf.d``) before running ``sudo ldconfig``. For example::

	echo /usr/local/lib \| sudo tee /etc/ld.so.conf.d/ndn-cxx.conf

	Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
	the installation directory of the shared library::

	export LD_LIBRARY_PATH=/usr/local/lib

	The ``./waf install`` command installs the following files:

	- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled).
	- ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
	``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on macOS):
	shared NDN C++ library (if enabled).
	- ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all necessary flags to
	build against the library. For example, if the ``pkg-config`` or ``pkgconf-pkg-config``
	package is installed and ``PKG_CONFIG_PATH`` is configured properly (or if
	``<LIBPATH>/pkgconfig`` is a default search path), the command ``pkg-config --cflags
	--libs libndn-cxx`` will return all necessary compile and link flags for the library.
	- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates.
	- ``<BINPATH>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.

	If configured with tests (``./waf configure --with-tests``), the above commands
	will also produce:

	- ``build/unit-tests``: a unit test binary for the library.

	1.5 GB available memory per CPU core is necessary for efficient compilation. On a
	multi-core machine with less than 1.5 GB available memory per CPU core, limit the
	objects being compiled in parallel with ``./waf -jN``, where N is the amount of
	available memory divided by 1.5 GB (e.g., ``./waf -j2`` for 3 GB of memory). This
	should avoid memory thrashing and result in faster compilation.

	Build with examples
	-------------------

	By default, the examples in the ``examples/`` directory will not be built. To enable
	them, pass ``--with-examples`` during the configuration step::

	./waf configure --with-examples # on CentOS, add --without-pch
	./waf
	sudo ./waf install
	sudo ldconfig # on Linux only

	To run the examples::

	# trivial producer app
	./build/examples/producer

	# trivial consumer app
	./build/examples/consumer

	# trivial consumer app with timers
	./build/examples/consumer-with-timer

	If you want to make a new sample application, just create a ``.cpp`` file inside the
	``examples/`` directory and it will be compiled during the next run of ``./waf``::

	cp examples/consumer.cpp examples/my-new-app.cpp
	... # edit examples/my-new-app.cpp with your preferred editor
	./waf
	sudo ./waf install
	sudo ldconfig # on Linux only
	./build/examples/my-new-app

	Debug symbols
	-------------

	The default compiler flags include debug symbols in binaries. This should provide
	more meaningful debugging information if ndn-cxx or your application crashes.

	If this is undesirable, the default flags can be overridden to disable debug symbols.
	The following example shows how to completely disable debug symbols and configure
	ndn-cxx to be installed into ``/usr`` with configuration in the ``/etc`` directory.

	::

	CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
	./waf
	sudo ./waf install

	Customizing the compiler
	------------------------

	To build ndn-cxx with a different compiler (rather than the platform default), set the
	``CXX`` environment variable to point to the compiler binary. For example, to build
	with clang on Linux, use the following::

	CXX=clang++ ./waf configure

	Building the documentation
	--------------------------

	ndn-cxx tutorials and API documentation can be built using the following commands::

	# Full set of documentation (tutorials + API) in build/docs
	./waf docs

	# Only tutorials in build/docs
	./waf sphinx

	# Only API docs in build/docs/doxygen
	./waf doxygen

	If ``sphinx-build`` is detected during ``./waf configure``, manpages will automatically
	be built and installed during the normal build process (i.e., during ``./waf`` and
	``./waf install``). By default, manpages will be installed into ``${PREFIX}/share/man``
	(the default value for ``PREFIX`` is ``/usr/local``). This location can be changed
	during the ``./waf configure`` stage using the ``--prefix``, ``--datarootdir``, or
	``--mandir`` options.

	For further details, please refer to ``./waf --help``.

	.. _Development build:

	Development build
	-----------------

	The following is the suggested build procedure for development builds::

	./waf configure --debug --with-tests # on CentOS, add --without-pch
	./waf
	sudo ./waf install
	sudo ldconfig # on Linux only

	In a development build, most compiler optimizations will be disabled and all warnings
	will be treated as errors. This default behavior can be overridden by setting the
	``CXXFLAGS`` environment variable before running ``./waf configure``, for example::

	CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
	...