build+docs: switch to python3, refresh FAQ and INSTALL documents
Refs: #5095
Change-Id: Icdc0e9463b28c07783edbe392a9bc47136947e3b
diff --git a/.jenkins b/.jenkins
index ea8834d..bc1c847 100755
--- a/.jenkins
+++ b/.jenkins
@@ -1,11 +1,14 @@
#!/usr/bin/env bash
set -e
+source .jenkins.d/util.sh
+export CACHE_DIR=${CACHE_DIR:-/tmp}
export WAF_JOBS=${WAF_JOBS:-1}
+[[ $JOB_NAME == *"code-coverage" ]] && export DISABLE_ASAN=yes
nanos() {
# Cannot use date(1) because macOS does not support %N format specifier
- python -c 'import time; print(int(time.time() * 1e9))'
+ python3 -c 'import time; print(int(time.time() * 1e9))'
}
for file in .jenkins.d/*; do
diff --git a/.jenkins.d/00-deps.sh b/.jenkins.d/00-deps.sh
index f73079a..633c56f 100755
--- a/.jenkins.d/00-deps.sh
+++ b/.jenkins.d/00-deps.sh
@@ -1,38 +1,39 @@
#!/usr/bin/env bash
-set -e
-
-JDIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
-source "$JDIR"/util.sh
-
-set -x
+set -ex
if has OSX $NODE_LABELS; then
FORMULAE=(boost openssl pkg-config)
- brew update
- if [[ -n $TRAVIS ]]; then
- # Travis images come with a large number of brew packages
- # pre-installed, don't waste time upgrading all of them
- for FORMULA in "${FORMULAE[@]}"; do
- brew outdated $FORMULA || brew upgrade $FORMULA
- done
- else
- brew upgrade
+ if has OSX-10.13 $NODE_LABELS || has OSX-10.14 $NODE_LABELS; then
+ FORMULAE+=(python)
fi
- brew install "${FORMULAE[@]}"
- brew cleanup
-fi
-if has Ubuntu $NODE_LABELS; then
+ if [[ -n $TRAVIS ]]; then
+ # Travis images come with a large number of pre-installed
+ # brew packages, don't waste time upgrading all of them
+ brew list --versions "${FORMULAE[@]}" || brew update
+ for FORMULA in "${FORMULAE[@]}"; do
+ brew list --versions "$FORMULA" || brew install "$FORMULA"
+ done
+ # Ensure /usr/local/opt/openssl exists
+ brew reinstall openssl
+ else
+ brew update
+ brew upgrade
+ brew install "${FORMULAE[@]}"
+ brew cleanup
+ fi
+
+elif has Ubuntu $NODE_LABELS; then
sudo apt-get -qq update
- sudo apt-get -qy install build-essential pkg-config libboost-all-dev \
- libsqlite3-dev libssl-dev libpcap-dev libsystemd-dev
+ sudo apt-get -qy install g++ pkg-config python3-minimal \
+ libboost-all-dev libssl-dev libsqlite3-dev \
+ libpcap-dev libsystemd-dev
if [[ $JOB_NAME == *"code-coverage" ]]; then
sudo apt-get -qy install gcovr lcov libgd-perl
fi
-fi
-if has CentOS-7 $NODE_LABELS; then
+elif has CentOS-7 $NODE_LABELS; then
sudo yum -y install yum-utils pkgconfig \
openssl-devel libtranslit-icu \
python-devel sqlite-devel \
diff --git a/.jenkins.d/01-ndn-cxx.sh b/.jenkins.d/01-ndn-cxx.sh
index 0ae5022..4f19833 100755
--- a/.jenkins.d/01-ndn-cxx.sh
+++ b/.jenkins.d/01-ndn-cxx.sh
@@ -1,12 +1,7 @@
#!/usr/bin/env bash
-set -e
+set -ex
-JDIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
-source "$JDIR"/util.sh
-
-set -x
-
-pushd "${CACHE_DIR:-/tmp}" >/dev/null
+pushd "$CACHE_DIR" >/dev/null
INSTALLED_VERSION=
if has OSX $NODE_LABELS; then
@@ -22,17 +17,15 @@
INSTALLED_VERSION=$(git -C ndn-cxx rev-parse HEAD 2>/dev/null || echo NONE)
fi
-sudo rm -Rf ndn-cxx-latest
-
-git clone --depth 1 git://github.com/named-data/ndn-cxx ndn-cxx-latest
-
+sudo rm -rf ndn-cxx-latest
+git clone --depth 1 https://github.com/named-data/ndn-cxx.git ndn-cxx-latest
LATEST_VERSION=$(git -C ndn-cxx-latest rev-parse HEAD 2>/dev/null || echo UNKNOWN)
if [[ $INSTALLED_VERSION != $LATEST_VERSION ]]; then
- sudo rm -Rf ndn-cxx
+ sudo rm -rf ndn-cxx
mv ndn-cxx-latest ndn-cxx
else
- sudo rm -Rf ndn-cxx-latest
+ sudo rm -rf ndn-cxx-latest
fi
sudo rm -f /usr/local/bin/ndnsec*
diff --git a/.jenkins.d/10-build.sh b/.jenkins.d/10-build.sh
index 3879bb4..854c4ed 100755
--- a/.jenkins.d/10-build.sh
+++ b/.jenkins.d/10-build.sh
@@ -1,22 +1,15 @@
#!/usr/bin/env bash
-set -e
-
-JDIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
-source "$JDIR"/util.sh
-
-set -x
+set -ex
git submodule sync
git submodule update --init
-if [[ $JOB_NAME == *"code-coverage" ]]; then
- COVERAGE="--with-coverage"
-elif [[ -z $DISABLE_ASAN ]]; then
+if [[ -z $DISABLE_ASAN ]]; then
ASAN="--with-sanitizer=address"
fi
-
-# Cleanup
-sudo_preserve_env PATH -- ./waf --color=yes distclean
+if [[ $JOB_NAME == *"code-coverage" ]]; then
+ COVERAGE="--with-coverage"
+fi
if [[ $JOB_NAME != *"code-coverage" && $JOB_NAME != *"limited-build" ]]; then
# Build in release mode with tests and without precompiled headers
@@ -24,14 +17,14 @@
./waf --color=yes build -j$WAF_JOBS
# Cleanup
- sudo_preserve_env PATH -- ./waf --color=yes distclean
+ ./waf --color=yes distclean
# Build in release mode without tests, but with "other tests"
./waf --color=yes configure --with-other-tests
./waf --color=yes build -j$WAF_JOBS
# Cleanup
- sudo_preserve_env PATH -- ./waf --color=yes distclean
+ ./waf --color=yes distclean
fi
# Build in debug mode with tests
diff --git a/.jenkins.d/20-tests.sh b/.jenkins.d/20-tests.sh
index cf1156e..286e95a 100755
--- a/.jenkins.d/20-tests.sh
+++ b/.jenkins.d/20-tests.sh
@@ -1,13 +1,8 @@
#!/usr/bin/env bash
-set -e
-
-JDIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
-source "$JDIR"/util.sh
-
-set -x
+set -ex
# Prepare environment
-rm -Rf ~/.ndn
+rm -rf ~/.ndn
if has OSX $NODE_LABELS; then
security unlock-keychain -p named-data
@@ -15,7 +10,7 @@
ndnsec-keygen "/tmp/jenkins/$NODE_NAME" | ndnsec-install-cert -
-BOOST_VERSION=$(python -c "import sys; sys.path.append('build/c4che'); import _cache; print(_cache.BOOST_VERSION_NUMBER);")
+BOOST_VERSION=$(python3 -c "import sys; sys.path.append('build/c4che'); import _cache; print(_cache.BOOST_VERSION_NUMBER);")
ut_log_args() {
if (( BOOST_VERSION >= 106200 )); then
@@ -30,14 +25,15 @@
fi
}
+# https://github.com/google/sanitizers/wiki/AddressSanitizerFlags
ASAN_OPTIONS="color=always"
-ASAN_OPTIONS+=":detect_leaks=false"
-ASAN_OPTIONS+=":detect_stack_use_after_return=true"
-ASAN_OPTIONS+=":check_initialization_order=true"
-ASAN_OPTIONS+=":strict_init_order=true"
+ASAN_OPTIONS+=":check_initialization_order=1"
+ASAN_OPTIONS+=":detect_stack_use_after_return=1"
+ASAN_OPTIONS+=":strict_init_order=1"
+ASAN_OPTIONS+=":strict_string_checks=1"
ASAN_OPTIONS+=":detect_invalid_pointer_pairs=1"
-ASAN_OPTIONS+=":detect_container_overflow=false"
-ASAN_OPTIONS+=":strict_string_checks=true"
+ASAN_OPTIONS+=":detect_container_overflow=0"
+ASAN_OPTIONS+=":detect_leaks=0"
ASAN_OPTIONS+=":strip_path_prefix=${PWD}/"
export ASAN_OPTIONS
diff --git a/.jenkins.d/30-coverage.sh b/.jenkins.d/30-coverage.sh
index 0dbb03a..380366e 100755
--- a/.jenkins.d/30-coverage.sh
+++ b/.jenkins.d/30-coverage.sh
@@ -1,10 +1,5 @@
#!/usr/bin/env bash
-set -e
-
-JDIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
-source "$JDIR"/util.sh
-
-set -x
+set -ex
if [[ $JOB_NAME == *"code-coverage" ]]; then
gcovr --object-directory=build \
diff --git a/.jenkins.d/README.md b/.jenkins.d/README.md
index 5813349..e8dbf37 100644
--- a/.jenkins.d/README.md
+++ b/.jenkins.d/README.md
@@ -1,36 +1,28 @@
-CONTINUOUS INTEGRATION SCRIPTS
-==============================
+# CONTINUOUS INTEGRATION SCRIPTS
-Environment Variables Used in Build Scripts
--------------------------------------------
+## Environment Variables Used in Build Scripts
-- `NODE_LABELS`: the variable defines a list of OS properties. The set values are used by the
- build scripts to select proper behavior for different OS.
+- `NODE_LABELS`: space-separated list of platform properties. The included values are used by
+ the build scripts to select the proper behavior for different operating systems and versions.
- The list should include at least `[OS_TYPE]`, `[DISTRO_TYPE]`, and `[DISTRO_VERSION]`.
+ The list should normally contain `[OS_TYPE]`, `[DISTRO_TYPE]`, and `[DISTRO_VERSION]`.
- Possible values for Linux:
+ Example values:
- * `[OS_TYPE]`: `Linux`
- * `[DISTRO_TYPE]`: `Ubuntu`
- * `[DISTRO_VERSION]`: `Ubuntu-16.04`, `Ubuntu-18.04`
+ - `[OS_TYPE]`: `Linux`, `OSX`
+ - `[DISTRO_TYPE]`: `Ubuntu`, `CentOS`
+ - `[DISTRO_VERSION]`: `Ubuntu-16.04`, `Ubuntu-18.04`, `CentOS-8`, `OSX-10.14`, `OSX-10.15`
- Possible values for OS X / macOS:
-
- * `[OS_TYPE]`: `OSX`
- * `[DISTRO_TYPE]`: `OSX` (can be absent)
- * `[DISTRO_VERSION]`: `OSX-10.11`, `OSX-10.12`, `OSX-10.13`
-
-- `JOB_NAME`: optional variable to define type of the job. Depending on the defined job type,
+- `JOB_NAME`: optional variable that defines the type of build job. Depending on the job type,
the build scripts can perform different tasks.
Possible values:
- * empty: default build process
- * `code-coverage` (Ubuntu Linux is assumed): debug build with tests and code coverage analysis
- * `limited-build`: only a single debug build with tests
+ - empty: default build task
+ - `code-coverage`: debug build with tests and code coverage analysis (Ubuntu Linux is assumed)
+ - `limited-build`: only a single debug build with tests
-- `CACHE_DIR`: the variable defines a path to folder containing cached files from previous builds,
- e.g., a compiled version of ndn-cxx library. If not set, `/tmp` is used.
+- `CACHE_DIR`: directory containing cached files from previous builds, e.g., a compiled version
+ of ndn-cxx. If not set, `/tmp` is used.
-- `WAF_JOBS`: number of parallel build jobs used by waf, defaults to 1.
+- `WAF_JOBS`: number of parallel build threads used by waf, defaults to 1.
diff --git a/.jenkins.d/util.sh b/.jenkins.d/util.sh
index 8ddc4ba..8077a74 100644
--- a/.jenkins.d/util.sh
+++ b/.jenkins.d/util.sh
@@ -16,6 +16,7 @@
set ${saved_xtrace}
return ${ret}
}
+export -f has
sudo_preserve_env() {
local saved_xtrace
@@ -35,3 +36,4 @@
set ${saved_xtrace}
sudo env "${vars[@]}" "$@"
}
+export -f sudo_preserve_env
diff --git a/.travis.yml b/.travis.yml
index b99ea35..16eb7b6 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -93,12 +93,7 @@
export DISABLE_ASAN=yes
;;
esac
- if [[ ${TRAVIS_OS_NAME} == osx ]]; then
- # Do not waste time upgrading useless packages
- brew pin cgal gdal postgis sfcgal || true
- # Ensure /usr/local/opt/openssl exists
- brew reinstall openssl || true
- elif [[ ${TRAVIS_OS_NAME} == linux ]]; then
+ if [[ ${TRAVIS_OS_NAME} == linux ]]; then
sudo sysctl -e -w net.ipv6.conf.all.disable_ipv6=0
fi
- ${CXX:-c++} --version
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 842a45b..2be26bf 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -1,41 +1,39 @@
FAQ
===
-How to change the default paths?
---------------------------------
+How do I change the default installation paths?
+-----------------------------------------------
-Paths to where NFD is installed can be configured during ``./waf
-configure``:
+Paths to where NFD is installed can be configured during ``./waf configure``:
-- Installation prefix (default ``/usr/local``):
+- Installation prefix (default ``/usr/local``)::
- ::
+ ./waf configure --prefix=/usr
- ./waf configure --prefix=/usr
+- Location of NFD configuration file (default: ``${prefix}/etc``)::
-- Location of NFD configuration file (default: ``${prefix}/etc``):
+ ./waf configure --prefix=/usr --sysconfdir=/etc
- ::
+- Location of manpages (default: ``${prefix}/share/man``)::
- ./waf configure --prefix=/usr --sysconfdir=/etc
+ ./waf configure --prefix=/usr --sysconfdir=/etc --mandir=/usr/share/man
-- Location of manpages (default: ``${prefix}/share/man``)
+See ``./waf configure --help`` for the full list of options.
- ::
+How do I use the NDN PPA repository on Ubuntu Linux?
+----------------------------------------------------
- ./waf configure --prefix=/usr --sysconfdir=/etc --mandir=/usr/share/man
+Please see :ref:`Install NFD on Ubuntu Linux using the NDN PPA repository`.
-How to run NFD as non-root user?
---------------------------------
+How do I run NFD as a non-root user?
+------------------------------------
-How to configure automatic dropping of privileges?
-++++++++++++++++++++++++++++++++++++++++++++++++++
+How do I configure automatic privilege dropping?
+++++++++++++++++++++++++++++++++++++++++++++++++
NFD can be configured to drop privileges whenever possible. You can specify a user and/or
group for NFD to change its *effective* user/group ID to in the ``general`` section of the
-configuration file. For example:
-
-::
+configuration file. For example::
general
{
@@ -54,26 +52,21 @@
root). However, reducing privileges may limit any damage caused by well intentioned,
but buggy, code.
-How to enable Ethernet Face Support?
-++++++++++++++++++++++++++++++++++++
+How do I enable Ethernet face support?
+++++++++++++++++++++++++++++++++++++++
The ``ether`` configuration file section contains settings for Ethernet faces and
-channels. These settings will **NOT** work without root or setting the appropriate
-permissions:
-
-::
-
- sudo setcap cap_net_raw,cap_net_admin=eip /full/path/nfd
-
-You may need to install a package to use setcap:
+channels. These settings will **NOT** work without root or without setting the
+appropriate permissions.
**Ubuntu:**
::
- sudo apt-get install libcap2-bin
+ sudo apt install libcap2-bin
+ sudo setcap cap_net_raw,cap_net_admin=eip /path/to/nfd
-**Mac OS X:**
+**macOS:**
::
@@ -81,44 +74,40 @@
tar zxvf ChmodBPF.tar.gz
open ChmodBPF/Install\ ChmodBPF.app
-or manually:
-
-::
+or manually::
sudo chgrp admin /dev/bpf*
sudo chmod g+rw /dev/bpf*
-How to enable UDP multicast support in multi-homed Linux machines
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+How do I enable UDP multicast support in multi-homed Linux machines?
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-The UDP configuration file section contains settings for unicast and multicast UDP
-faces. If the Linux box is equipped with multiple network interfaces with multicast
-capabilities, the settings for multicast faces will **NOT** work without root
-or setting the appropriate permissions:
+The ``udp`` configuration file section contains settings for unicast and multicast UDP
+faces. If the Linux machine is equipped with multiple network interfaces with multicast
+capabilities, the settings for multicast faces will **NOT** work without root or without
+setting the appropriate permissions::
-::
+ sudo setcap cap_net_raw=eip /path/to/nfd
- sudo setcap cap_net_raw=eip /full/path/nfd
+.. _How do I configure NFD security:
-.. _How to configure NFD security:
+How do I configure NFD security?
+--------------------------------
-How to configure NFD security?
-------------------------------
+.. note:: The sample configuration file for NFD allows any user to manage faces, FIB, RIB,
+ CS, and strategy choices of the local NFD instance. The following procedure can be used
+ to restrict certain operations to certain users.
-.. note:: The sample configuration file of NFD allow any user to manage faces, FIB, RIB, and
- StrategyChoice of the local NFD. The following description can be used to restrict certain
- operations to certain users.
+ More extensive documentation on the security mechanisms in NFD, as well as the available
+ options to configure its trust model, is currently in preparation.
- More extensive documentation about NFD's security and options to configure trust model for
- NFD is currently in preparation.
-
-Many NFD management protocols use commands Interests (e.g., FIB modification, Face
-creation/destructions, etc.), which require an NDN certificate (either self-signed for local
+Many management components in NFD use *Command Interests* (e.g., FIB modification, face
+creation/destruction, etc.), which require an NDN certificate (either self-signed for local
trust or delegated from a trusted authority).
-If you do not already have NDN certificate, you can generate one with the following commands:
+If you do not already have an NDN certificate, you can generate one using the following procedure.
-**Generate and install a self-signed identity certificate**:
+**Generating and installing a self-signed identity certificate**:
::
@@ -128,21 +117,13 @@
``/your-username``). Identity names are hierarchical NDN names and may have multiple components
(e.g. ``/ndn/ucla/edu/alice``). You may create additional keys and identities as you see fit.
-**Dump the NDN certificate to a file**:
+**Exporting the NDN certificate to a file**:
-The following commands assume that you have not modified ``PREFIX`` or ``SYSCONFDIR`` If you
-have, please substitute ``/usr/local/etc`` for the appropriate value (the overriden
-``SYSCONFDIR`` or ``PREFIX/etc`` if you changed ``PREFIX``).
+The following commands assume that you have not modified ``PREFIX`` or ``SYSCONFDIR``.
+If you have, please substitute the appropriate path in place of ``/usr/local/etc``.
::
sudo mkdir -p /usr/local/etc/ndn/keys
ndnsec-cert-dump -i /`whoami` > default.ndncert
sudo mv default.ndncert /usr/local/etc/ndn/keys/default.ndncert
-
-.. _How to start using NDN PPA repository on Ubuntu Linux:
-
-How to start using NDN PPA repository on Ubuntu Linux?
-------------------------------------------------------
-
-Please see :ref:`Install NFD Using the NDN PPA Repository on Ubuntu Linux`.
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index a4b4984..4ee93c6 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -1,147 +1,139 @@
Getting Started with NFD
========================
-.. _Install NFD Using the NDN PPA Repository on Ubuntu Linux:
+Supported platforms
+-------------------
-Install NFD Using the NDN PPA Repository on Ubuntu Linux
+NFD is built against a continuous integration system and has been tested on the
+following platforms:
+
+- Ubuntu 16.04 (amd64)
+- Ubuntu 18.04 (amd64, armhf, i386)
+- Ubuntu 19.10 (amd64)
+- macOS 10.13
+- macOS 10.14
+- macOS 10.15
+
+NFD is known to work on the following platforms, although they are not officially
+supported:
+
+- Debian >= 9
+- Gentoo Linux
+- Raspbian >= 2017-08-16
+
+.. _Install NFD on Ubuntu Linux using the NDN PPA repository:
+
+Install NFD on Ubuntu Linux using the NDN PPA repository
--------------------------------------------------------
-NFD binaries and related tools for the latest versions of Ubuntu Linux can be installed using PPA
-packages from named-data repository. First, you will need to add ``named-data/ppa``
-repository to binary package sources and update list of available packages.
+NFD binaries and related tools for supported versions of Ubuntu can be installed using
+PPA packages from the **named-data** repository. First, you will need to add the
+``named-data/ppa`` repository to the binary package sources and update the list of
+available packages.
Preliminary steps if you have not used PPA packages before
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To simplify adding new PPA repositories, Ubuntu provides ``add-apt-repository`` tool,
+To simplify adding new PPA repositories, Ubuntu provides the ``add-apt-repository`` tool,
which is not installed by default on some systems.
::
- sudo apt-get install software-properties-common
+ sudo apt install software-properties-common
-Adding NDN PPA
-~~~~~~~~~~~~~~
+Adding the NDN PPA
+~~~~~~~~~~~~~~~~~~
-After installing ``add-apt-repository``, run the following command to add `NDN PPA
-repository`_.
-
-::
+After installing ``add-apt-repository``, run the following commands to add the `NDN PPA
+repository`_::
sudo add-apt-repository ppa:named-data/ppa
- sudo apt-get update
+ sudo apt update
Installing NFD and other NDN packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-After you have added `NDN PPA repository`_, NFD and other NDN packages can be easily
-installed in a standard way, i.e., either using ``apt-get`` as shown below or using any
-other package manager, such as Synaptic Package Manager:
+After you have added the `NDN PPA repository`_, NFD and other NDN packages can be easily
+installed either using ``apt``, as shown below, or any other compatible package manager.
::
- sudo apt-get install nfd
+ sudo apt install nfd
-For the list of available packages, refer to `NDN PPA repository`_ homepage.
+For the list of available packages, refer to the `NDN PPA repository`_ page.
.. _NDN PPA repository: https://launchpad.net/~named-data/+archive/ppa
-Building from Source
+Building from source
--------------------
-Downloading from Git
+Downloading from git
~~~~~~~~~~~~~~~~~~~~
-The first step is to obtain the source code for ``NFD`` and, its main dependency, the
-``ndn-cxx`` library. If you are not planning to work with the bleeding edge code, make
-sure you checkout the correct release tag (e.g., ``*-0.7.0``) for both repositories:
+The first step is to obtain the source code for NFD and its main dependency, the
+*ndn-cxx* library. If you do not want a development version of NFD, make sure you
+checkout the correct release tag (e.g., ``*-0.7.0``) from both repositories.
::
# Download ndn-cxx
- git clone https://github.com/named-data/ndn-cxx
+ git clone https://github.com/named-data/ndn-cxx.git
# Download NFD
- git clone --recursive https://github.com/named-data/NFD
+ git clone --recursive https://github.com/named-data/NFD.git
.. note::
- While we strive to ensure that the latest version (master branch) of NFD and ndn-cxx
- always properly compiles and works, sometimes there could be problems. In these cases, use
- the latest released version.
+ While we strive to ensure that the latest version (git master branch) of NFD and ndn-cxx
+ always compiles and works properly, we cannot guarantee that there will be no issues.
+ If this is discovered to be the case, please use matching released versions (git tag or
+ tarball) of NFD and ndn-cxx instead.
Prerequisites
~~~~~~~~~~~~~
-Install the `ndn-cxx library <https://named-data.net/doc/ndn-cxx/current/INSTALL.html>`__ and its requirements
+Install the `ndn-cxx library <https://named-data.net/doc/ndn-cxx/current/INSTALL.html>`__
+and its prerequisites.
-- On macOS with Homebrew:
+On Linux, NFD needs the following dependencies to enable optional features:
- ::
+- On Ubuntu::
- brew install boost openssl pkg-config
-
-- On Ubuntu:
-
- ::
-
- sudo apt-get install build-essential pkg-config libboost-all-dev \
- libsqlite3-dev libssl-dev libpcap-dev
-
-To build manpages and API documentation:
-
-- On macOS with Homebrew:
-
- ::
-
- brew install doxygen graphviz
- sudo easy_install pip
- sudo pip Sphinx
-
-- On Ubuntu:
-
- ::
-
- sudo apt-get install doxygen graphviz python-sphinx
+ sudo apt install libpcap-dev libsystemd-dev
Build
~~~~~
-The following basic commands should be used to build NFD on Ubuntu and macOS with Homebrew:
-
-::
+The following commands can be used to build and install NFD from source::
./waf configure
./waf
sudo ./waf install
-If you have installed ``ndn-cxx`` library and/or other dependencies into a non-standard path, you
-may need to modify ``PKG_CONFIG_PATH`` environment variable before running ``./waf configure``.
-For example,
+If you have installed ndn-cxx and/or any other dependencies into a non-standard path,
+you may need to modify the ``PKG_CONFIG_PATH`` environment variable before running
+``./waf configure``. For example::
-::
-
- export PKG_CONFIG_PATH=/custom/lib/pkgconfig:$PKG_CONFIG_PATH
+ export PKG_CONFIG_PATH="/custom/lib/pkgconfig:$PKG_CONFIG_PATH"
./waf configure
./waf
sudo ./waf install
-Refer to ``./waf --help`` for more options that can be used during ``configure`` stage and
-how to properly configure and run NFD.
+Refer to ``./waf --help`` for more options that can be used during the ``configure`` stage.
.. note::
- If you are working on a source repository that has been compiled before, and you have
- upgraded one of the dependencies, please execute ``./waf distclean`` to clear object files
- and start over.
+ If you are working on a source repository that has been compiled before, and you have
+ upgraded one of the dependencies, please execute ``./waf distclean`` to clear object files
+ and start over.
Debug symbols
~~~~~~~~~~~~~
-The default compiler flags enable debug symbols to be included in binaries. This
-potentially allows more meaningful debugging if NFD or other tools happen to crash.
+The default compiler flags enable debug symbols to be included in binaries. This should
+provide more meaningful debugging information if NFD or other tools happen to crash.
-If it is undesirable, default flags can be easily overridden. The following example shows
-how to completely disable debug symbols and configure NFD to be installed into ``/usr``
-with configuration in ``/etc`` folder.
+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 NFD
+to be installed into ``/usr`` with configuration in the ``/etc`` directory.
::
@@ -149,61 +141,52 @@
./waf
sudo ./waf install
-.. note::
- For Ubuntu PPA packages debug symbols are available in ``*-dbg`` packages.
+For Ubuntu PPA packages, debug symbols are available in ``*-dbg`` packages.
-Customize Compiler
-~~~~~~~~~~~~~~~~~~
+Customizing the compiler
+~~~~~~~~~~~~~~~~~~~~~~~~
-To choose a custom C++ compiler for building NFD, set the ``CXX`` environment variable
-to point to the compiler binary. For example, to select the clang compiler on a Linux
-system, use the following:
-
-::
+To build NFD 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 documentation
-~~~~~~~~~~~~~~~~~~~~~~
+Building the documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
-NFD tutorials and API documentation can be built using the following commands:
-
-::
+NFD 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`
+ # Only tutorials in build/docs
./waf sphinx
- # Only API docs in `build/docs/doxygen`
- ./waf doxgyen
+ # Only API docs in build/docs/doxygen
+ ./waf doxygen
+If ``sphinx-build`` is detected during ``./waf configure``, manpages are automatically
+built and installed during the normal build process (i.e., during ``./waf`` and ``./waf
+install``). By default, manpages are 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.
-Manpages are automatically created and installed during the normal build process (e.g.,
-during ``./waf`` and ``./waf install``), if ``python-sphinx`` module is detected during
-``./waf configure`` stage. By default, manpages are installed into
-``${PREFIX}/share/man`` (where default value for ``PREFIX`` is ``/usr/local``). This
-location can be changed during ``./waf configure`` stage using ``--prefix``,
-``--datarootdir``, or ``--mandir`` options.
-
-For more details, refer to ``./waf --help``.
+For more details, please refer to ``./waf --help``.
Initial configuration
---------------------
.. note::
If you have installed NFD from binary packages, the package manager has already
- installed initial configuration and you can safely skip this section.
+ installed a working configuration and you can safely skip this section.
General
~~~~~~~
-After installing NFD from source, you need to create a proper config file. If default
-location for ``./waf configure`` was used, this can be accomplished by simply copying the
-sample configuration file:
-
-::
+After installing NFD from source, you need to create a proper configuration file.
+If the default installation directories were used with ``./waf configure``, this
+can be accomplished by simply copying the sample configuration file as follows::
sudo cp /usr/local/etc/ndn/nfd.conf.sample /usr/local/etc/ndn/nfd.conf
@@ -211,15 +194,17 @@
~~~~~~~~~~~~
NFD provides mechanisms to enable strict authorization for all management commands. In
-particular, one can authorize only specific public keys to create new Faces or change the
+particular, one can authorize only specific public keys to create new faces or change the
forwarding strategy for specific namespaces. For more information about how to generate
-private/public key pair, generate self-signed certificate, and use this self-signed
-certificate to authorize NFD management commands, refer to :ref:`How to configure NFD
-security` FAQ question.
+public/private key pairs, generate self-signed certificates, and use them to authorize
+NFD management commands, refer to the :ref:`How do I configure NFD security` FAQ question.
-In the sample configuration file, all authorizations are disabled, effectively allowing
-anybody on the local machine to issue NFD management commands. **The sample file is
-intended only for demo purposes and MUST NOT be used in a production environment.**
+In the sample configuration file, all security mechanisms are disabled for local clients,
+effectively allowing anybody on the local machine to issue NFD management commands.
+
+.. note::
+ The sample configuration file is intended only for demo purposes and should NOT be
+ used in production environments.
Running
-------
@@ -227,81 +212,63 @@
Starting
~~~~~~~~
-If you have installed NFD from source code, it is recommended to start NFD with the
-``nfd-start`` script:
-
-::
+If you have installed NFD from source, it is recommended to start NFD with the
+``nfd-start`` script::
nfd-start
-On macOS it may ask for your keychain password or ask ``nfd wants to sign using key in
-your keychain``. Enter your keychain password and click "Always Allow".
+On macOS, this command may ask for your keychain password or ask "nfd wants to sign using
+key [xyz] in your keychain". Enter your keychain password and click "Always Allow".
Later, you can stop NFD with ``nfd-stop`` or by simply killing the ``nfd`` process.
If you have installed NFD using a package manager, you can start and stop NFD using the
-operating system's service manager (such as systemd or launchd) or using
-"Automatically start NFD" option in NDN Control Center app.
+operating system's service manager, such as ``systemctl`` or ``launchctl``.
-Connecting to remote NFDs
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Connecting to remote forwarders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To create a UDP tunnel to a remote NFD, execute the following command in terminal:
+To create a UDP tunnel to a remote instance of NFD, execute the following command
+in a terminal::
-::
+ nfdc face create udp://<other-host>
- nfdc face create udp://<other host>
-
-where ``<other host>`` is the name or IP address of the other host (e.g.,
-``udp://spurs.cs.ucla.edu``). This outputs:
-
-::
+where ``<other-host>`` is the name or IP address of the other host (e.g.,
+``udp://ndn.example.net``). If successful, this will print something like::
face-created id=308 local=udp4://10.0.2.15:6363 remote=udp4://131.179.196.46:6363 persistency=persistent
-To add a route ``/ndn`` toward the remote NFD, execute the following command in terminal:
+To add a route ``/ndn`` toward this remote forwarder, execute the following command
+in a terminal::
-::
+ nfdc route add /ndn udp://<other-host>
- nfdc route add /ndn udp://<other host>
-
-This outputs:
-
-::
+This will print::
route-add-accepted prefix=/ndn nexthop=308 origin=static cost=0 flags=child-inherit expires=never
-The ``/ndn`` means that NFD will forward all Interests that start with ``/ndn`` through the
-face to the other host. If you only want to forward Interests with a certain prefix, use it
-instead of ``/ndn``. This only forwards Interests to the other host, but there is no "back
-route" for the other host to forward Interests to you. For that, you can rely on automatic
-prefix propagation feature of NFD or go to the other host and use ``nfdc`` to add the route.
+This indicates that NFD will forward all Interests that start with ``/ndn`` through the
+face to the other host. This forwards Interests to the other host, but does not provide
+a "back route" for the other host to forward Interests to you. For this, you can rely on
+the "automatic prefix propagation" feature of NFD or use the ``nfdc`` command on the other
+host to add the route.
Playing with NFD
----------------
-After you haved installed, configured, and started NFD, you can try to install and play
-with the following:
+After you have installed, configured, and started NFD, you can demonstrate the features
+of NDN using the following applications and libraries.
Sample applications:
-- `Simple examples in ndn-cxx library <https://named-data.net/doc/ndn-cxx/current/examples.html>`_
-
- If you have installed ndn-cxx from source, you already have compiled these:
-
- + examples/producer
- + examples/consumer
- + examples/consumer-with-timer
-
-- `Introductory examples of NDN-CCL
- <https://redmine.named-data.net/projects/application-development-documentation-guides/wiki/Step-By-Step_-_Common_Client_Libraries>`_
+ + `Simple examples using the ndn-cxx library <https://named-data.net/doc/ndn-cxx/current/examples.html>`_
+ + `Introductory examples of NDN-CCL
+ <https://redmine.named-data.net/projects/application-development-documentation-guides/wiki/Step-By-Step_-_Common_Client_Libraries>`_
Real applications and libraries:
- + `ndn-tools - NDN Essential Tools <https://github.com/named-data/ndn-tools>`_
- + `ndn-traffic-generator - Traffic Generator For NDN
- <https://github.com/named-data/ndn-traffic-generator>`_
- + `repo-ng - Next generation of NDN repository <https://github.com/named-data/repo-ng>`_
- + `ChronoChat - Multi-user NDN chat application <https://github.com/named-data/ChronoChat>`_
- + `ChronoSync - Sync library for multiuser realtime applications for NDN
- <https://github.com/named-data/ChronoSync>`_
+ + `ndn-tools - Essential NDN command-line tools <https://github.com/named-data/ndn-tools>`_
+ + `ndn-traffic-generator - Traffic generator for NDN <https://github.com/named-data/ndn-traffic-generator>`_
+ + `repo-ng - Next generation NDN repository <https://github.com/named-data/repo-ng>`_
+ + `ChronoSync - Sync library for multi-user real-time applications <https://github.com/named-data/ChronoSync>`_
+ + `PSync - Partial and full synchronization library <https://github.com/named-data/PSync>`_
diff --git a/docs/conf.py b/docs/conf.py
index 60dd74f..f95dbcd 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,7 +12,7 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
-import os
+# import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
@@ -20,7 +20,7 @@
# -- Project information -----------------------------------------------------
project = u'Named Data Networking Forwarding Daemon (NFD)'
-copyright = u'Copyright © 2014-2019 Named Data Networking Project.'
+copyright = u'Copyright © 2014-2020 Named Data Networking Project.'
author = u'Named Data Networking Project'
# The short X.Y version
@@ -58,12 +58,7 @@
sys.stderr.write("Extension '%s' not found. "
"Some documentation may not build correctly.\n" % extension)
-if sys.version_info[0] >= 3:
- addExtensionIfExists('sphinxcontrib.doxylink')
-
-# sphinxcontrib.googleanalytics is currently not working with the latest version of Sphinx
-# if os.getenv('GOOGLE_ANALYTICS', None):
-# addExtensionIfExists('sphinxcontrib.googleanalytics')
+addExtensionIfExists('sphinxcontrib.doxylink')
# The master toctree document.
master_doc = 'index'
@@ -156,7 +151,3 @@
extlinks = {
'issue': ('https://redmine.named-data.net/issues/%s', 'issue #'),
}
-
-if os.getenv('GOOGLE_ANALYTICS', None):
- googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
- googleanalytics_enabled = True
diff --git a/nfd.conf.sample.in b/nfd.conf.sample.in
index 4cd4e26..a17423f 100644
--- a/nfd.conf.sample.in
+++ b/nfd.conf.sample.in
@@ -177,7 +177,7 @@
;
; **Ubuntu:**
;
- ; sudo apt-get install libcap2-bin
+ ; sudo apt install libcap2-bin
;
; **Mac OS X:**
;
diff --git a/waf b/waf
index 7ceee16..a1c5c96 100755
--- a/waf
+++ b/waf
@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
# encoding: latin-1
# Thomas Nagy, 2005-2018
#