build+ci: switch to python3
Also in this commit:
* Sync CI scripts with other projects
* Modernize docs/conf.py
* Replace redmine_issue extension with sphinx.ext.extlinks
* Minor updates to docs/doxygen.conf.in
* Cleanup README.md and INSTALL.rst
Refs: #5095
Change-Id: I614e876e6aed73659f4f4cea01813f4604599263
diff --git a/.jenkins b/.jenkins
index 674d751..bc1c847 100755
--- a/.jenkins
+++ b/.jenkins
@@ -1,10 +1,32 @@
#!/usr/bin/env bash
set -e
+source .jenkins.d/util.sh
-DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
+export CACHE_DIR=${CACHE_DIR:-/tmp}
+export WAF_JOBS=${WAF_JOBS:-1}
+[[ $JOB_NAME == *"code-coverage" ]] && export DISABLE_ASAN=yes
-for file in "$DIR"/.jenkins.d/*; do
+nanos() {
+ # Cannot use date(1) because macOS does not support %N format specifier
+ python3 -c 'import time; print(int(time.time() * 1e9))'
+}
+
+for file in .jenkins.d/*; do
[[ -f $file && -x $file ]] || continue
- echo "Run: $file"
+
+ if [[ -n $TRAVIS ]]; then
+ label=$(basename "$file" | sed -E 's/[[:digit:]]+-(.*)\..*/\1/')
+ echo -ne "travis_fold:start:${label}\r"
+ echo -ne "travis_time:start:${label}\r"
+ start=$(nanos)
+ fi
+
+ echo "\$ $file"
"$file"
+
+ if [[ -n $TRAVIS ]]; then
+ finish=$(nanos)
+ echo -ne "travis_time:end:${label}:start=${start},finish=${finish},duration=$((finish-start)),event=${label}\r"
+ echo -ne "travis_fold:end:${label}\r"
+ fi
done
diff --git a/.jenkins.d/00-deps.sh b/.jenkins.d/00-deps.sh
index 84c8ae1..458bbd0 100755
--- a/.jenkins.d/00-deps.sh
+++ b/.jenkins.d/00-deps.sh
@@ -1,31 +1,32 @@
#!/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
+ sudo apt-get -qy install g++ pkg-config python3-minimal \
+ libboost-all-dev libssl-dev libsqlite3-dev
if [[ $JOB_NAME == *"code-coverage" ]]; then
sudo apt-get -qy install gcovr lcov libgd-perl
diff --git a/.jenkins.d/01-ndn-cxx.sh b/.jenkins.d/01-ndn-cxx.sh
index e627627..4e0e154 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*
@@ -42,15 +35,21 @@
pushd ndn-cxx >/dev/null
-./waf configure --color=yes --enable-shared --disable-static --without-osx-keychain
-./waf build --color=yes -j${WAF_JOBS:-1}
-sudo_preserve_env PATH -- ./waf install --color=yes
+if has CentOS-8 $NODE_LABELS; then
+ # https://bugzilla.redhat.com/show_bug.cgi?id=1721553
+ PCH="--without-pch"
+fi
+
+./waf --color=yes configure --disable-static --enable-shared --without-osx-keychain $PCH
+./waf --color=yes build -j$WAF_JOBS
+sudo_preserve_env PATH -- ./waf --color=yes install
popd >/dev/null
popd >/dev/null
+if has CentOS-8 $NODE_LABELS; then
+ sudo tee /etc/ld.so.conf.d/ndn.conf >/dev/null <<< /usr/local/lib64
+fi
if has Linux $NODE_LABELS; then
sudo ldconfig
-elif has FreeBSD10 $NODE_LABELS; then
- sudo ldconfig -m
fi
diff --git a/.jenkins.d/02-chronosync.sh b/.jenkins.d/02-chronosync.sh
index c27aa33..642e469 100755
--- a/.jenkins.d/02-chronosync.sh
+++ b/.jenkins.d/02-chronosync.sh
@@ -1,57 +1,46 @@
#!/usr/bin/env bash
-set -e
+set -ex
-JDIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
-source "$JDIR"/util.sh
+PROJ=ChronoSync
-set -x
-
-pushd "${CACHE_DIR:-/tmp}" >/dev/null
+pushd "$CACHE_DIR" >/dev/null
INSTALLED_VERSION=
NDN_CXX=$(ndnsec version)
-OLD_NDN_CXX=$(cat ndn_cxx_chrono.txt || :)
+OLD_NDN_CXX=$(cat "$PROJ-ndn-cxx.txt" || :)
if [[ $OLD_NDN_CXX != $NDN_CXX ]]; then
- echo "$NDN_CXX" > ndn_cxx_chrono.txt
+ echo "$NDN_CXX" > "$PROJ-ndn-cxx.txt"
INSTALLED_VERSION=NONE
fi
if [[ -z $INSTALLED_VERSION ]]; then
- INSTALLED_VERSION=$(git -C ChronoSync rev-parse HEAD 2>/dev/null || echo NONE)
+ INSTALLED_VERSION=$(git -C "$PROJ" rev-parse HEAD 2>/dev/null || echo NONE)
fi
-sudo rm -Rf ChronoSync-latest
-
-git clone --depth 1 git://github.com/named-data/ChronoSync ChronoSync-latest
-
-LATEST_VERSION=$(git -C ChronoSync-latest rev-parse HEAD 2>/dev/null || echo UNKNOWN)
+sudo rm -rf "$PROJ-latest"
+git clone --depth 1 "https://github.com/named-data/$PROJ.git" "$PROJ-latest"
+LATEST_VERSION=$(git -C "$PROJ-latest" rev-parse HEAD 2>/dev/null || echo UNKNOWN)
if [[ $INSTALLED_VERSION != $LATEST_VERSION ]]; then
- sudo rm -Rf ChronoSync
- mv ChronoSync-latest ChronoSync
+ sudo rm -rf "$PROJ"
+ mv "$PROJ-latest" "$PROJ"
else
- sudo rm -Rf ChronoSync-latest
+ sudo rm -rf "$PROJ-latest"
fi
-sudo rm -fr /usr/local/include/ChronoSync
-sudo rm -f /usr/local/lib{,64}/libChronoSync*
-sudo rm -f /usr/local/lib{,64}/pkgconfig/ChronoSync.pc
+sudo rm -fr /usr/local/include/"$PROJ"
+sudo rm -f /usr/local/lib{,64}/lib"$PROJ"*
+sudo rm -f /usr/local/lib{,64}/pkgconfig/"$PROJ".pc
-pushd ChronoSync >/dev/null
+pushd "$PROJ" >/dev/null
-if has FreeBSD10 $NODE_LABELS; then
- export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/
-fi
-
-./waf configure --color=yes
-./waf build --color=yes -j${WAF_JOBS:-1}
-sudo_preserve_env PATH -- ./waf install --color=yes
+./waf --color=yes configure
+./waf --color=yes build -j$WAF_JOBS
+sudo_preserve_env PATH -- ./waf --color=yes install
popd >/dev/null
popd >/dev/null
if has Linux $NODE_LABELS; then
sudo ldconfig
-elif has FreeBSD10 $NODE_LABELS; then
- sudo ldconfig -m
fi
diff --git a/.jenkins.d/03-psync.sh b/.jenkins.d/03-psync.sh
index 1788a02..c4b88b2 100755
--- a/.jenkins.d/03-psync.sh
+++ b/.jenkins.d/03-psync.sh
@@ -1,57 +1,46 @@
#!/usr/bin/env bash
-set -e
+set -ex
-JDIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
-source "$JDIR"/util.sh
+PROJ=PSync
-set -x
-
-pushd "${CACHE_DIR:-/tmp}" >/dev/null
+pushd "$CACHE_DIR" >/dev/null
INSTALLED_VERSION=
NDN_CXX=$(ndnsec version)
-OLD_NDN_CXX=$(cat ndn_cxx_psync.txt || :)
+OLD_NDN_CXX=$(cat "$PROJ-ndn-cxx.txt" || :)
if [[ $OLD_NDN_CXX != $NDN_CXX ]]; then
- echo "$NDN_CXX" > ndn_cxx_psync.txt
+ echo "$NDN_CXX" > "$PROJ-ndn-cxx.txt"
INSTALLED_VERSION=NONE
fi
if [[ -z $INSTALLED_VERSION ]]; then
- INSTALLED_VERSION=$(git -C PSync rev-parse HEAD 2>/dev/null || echo NONE)
+ INSTALLED_VERSION=$(git -C "$PROJ" rev-parse HEAD 2>/dev/null || echo NONE)
fi
-sudo rm -Rf PSync-latest
-
-git clone --depth 1 git://github.com/named-data/PSync PSync-latest
-
-LATEST_VERSION=$(git -C PSync-latest rev-parse HEAD 2>/dev/null || echo UNKNOWN)
+sudo rm -rf "$PROJ-latest"
+git clone --depth 1 "https://github.com/named-data/$PROJ.git" "$PROJ-latest"
+LATEST_VERSION=$(git -C "$PROJ-latest" rev-parse HEAD 2>/dev/null || echo UNKNOWN)
if [[ $INSTALLED_VERSION != $LATEST_VERSION ]]; then
- sudo rm -Rf PSync
- mv PSync-latest PSync
+ sudo rm -rf "$PROJ"
+ mv "$PROJ-latest" "$PROJ"
else
- sudo rm -Rf PSync-latest
+ sudo rm -rf "$PROJ-latest"
fi
-sudo rm -fr /usr/local/include/PSync
-sudo rm -f /usr/local/lib{,64}/libPSync*
-sudo rm -f /usr/local/lib{,64}/pkgconfig/PSync.pc
+sudo rm -fr /usr/local/include/"$PROJ"
+sudo rm -f /usr/local/lib{,64}/lib"$PROJ"*
+sudo rm -f /usr/local/lib{,64}/pkgconfig/"$PROJ".pc
-pushd PSync >/dev/null
+pushd "$PROJ" >/dev/null
-if has FreeBSD10 $NODE_LABELS; then
- export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/
-fi
-
-./waf configure --color=yes
-./waf build --color=yes -j${WAF_JOBS:-1}
-sudo_preserve_env PATH -- ./waf install --color=yes
+./waf --color=yes configure
+./waf --color=yes build -j$WAF_JOBS
+sudo_preserve_env PATH -- ./waf --color=yes install
popd >/dev/null
popd >/dev/null
if has Linux $NODE_LABELS; then
sudo ldconfig
-elif has FreeBSD10 $NODE_LABELS; then
- sudo ldconfig -m
fi
diff --git a/.jenkins.d/10-build.sh b/.jenkins.d/10-build.sh
index 6faaf55..2a60f0d 100755
--- a/.jenkins.d/10-build.sh
+++ b/.jenkins.d/10-build.sh
@@ -1,45 +1,37 @@
#!/usr/bin/env bash
-set -e
+set -ex
-JDIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
-source "$JDIR"/util.sh
-
-set -x
-
-git submodule init
git submodule sync
-git submodule update
+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" && $JOB_NAME != *"limited-build" ]]; then
- # Configure/build in optimized mode with tests
- ./waf --color=yes configure --with-tests
- ./waf --color=yes build -j${WAF_JOBS:-1}
-
- # Cleanup
- sudo_preserve_env PATH -- ./waf --color=yes distclean
-
- # Configure/build in optimized mode without tests
- ./waf --color=yes configure
- ./waf --color=yes build -j${WAF_JOBS:-1}
-
- # Cleanup
- sudo_preserve_env PATH -- ./waf --color=yes distclean
+if [[ $JOB_NAME == *"code-coverage" ]]; then
+ COVERAGE="--with-coverage"
fi
-# Configure/build in debug mode with tests
-./waf --color=yes configure --debug --with-tests $ASAN $COVERAGE
-./waf --color=yes build -j${WAF_JOBS:-1}
+if [[ $JOB_NAME != *"code-coverage" && $JOB_NAME != *"limited-build" ]]; then
+ # Build in release mode with tests
+ ./waf --color=yes configure --with-tests
+ ./waf --color=yes build -j$WAF_JOBS
-# (tests will be run against debug version)
+ # Cleanup
+ ./waf --color=yes distclean
+
+ # Build in release mode without tests
+ ./waf --color=yes configure
+ ./waf --color=yes build -j$WAF_JOBS
+
+ # Cleanup
+ ./waf --color=yes distclean
+fi
+
+# Build in debug mode with tests
+./waf --color=yes configure --debug --with-tests $ASAN $COVERAGE
+./waf --color=yes build -j$WAF_JOBS
+
+# (tests will be run against the debug version)
# Install
sudo_preserve_env PATH -- ./waf --color=yes install
diff --git a/.jenkins.d/20-tests.sh b/.jenkins.d/20-tests.sh
index 2657aa9..111035f 100755
--- a/.jenkins.d/20-tests.sh
+++ b/.jenkins.d/20-tests.sh
@@ -1,15 +1,10 @@
#!/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
-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
@@ -24,13 +19,14 @@
fi
}
+# https://github.com/google/sanitizers/wiki/AddressSanitizerFlags
ASAN_OPTIONS="color=always"
-ASAN_OPTIONS+=":detect_stack_use_after_return=true"
-ASAN_OPTIONS+=":check_initialization_order=true"
-ASAN_OPTIONS+=":strict_init_order=true"
-ASAN_OPTIONS+=":detect_invalid_pointer_pairs=1"
-ASAN_OPTIONS+=":detect_container_overflow=false"
-ASAN_OPTIONS+=":strict_string_checks=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=2"
+ASAN_OPTIONS+=":detect_container_overflow=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 981bdc0..6f6ee88 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
lcov --quiet \
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/README.md b/README.md
index b9ca240..19dff9c 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,38 @@
-NLSR - Named Data Link State Routing Protocol
-=============================================
+# NLSR: Named Data Link State Routing Protocol
+
+
+[](https://travis-ci.org/named-data/NLSR)
+
For complete documentation and more extensive information,
-please visit the [NLSR homepage](http://named-data.net/doc/NLSR/current/).
+please visit the [NLSR homepage](https://named-data.net/doc/NLSR/current/).
-If you are new to the NDN community of software generally, read the
-[Contributor's Guide](https://github.com/named-data/NFD/blob/master/CONTRIBUTING.md).
+If you are new to the NDN software community, please read the
+[Contributor's Guide](https://github.com/named-data/.github/blob/master/CONTRIBUTING.md)
+to get started.
## Overview
-NLSR is a routing protocol in NDN that populates NDN's Routing Information Base. NLSR
-will continue to evolve alongside the Named Data Networking [protocol](http://named-data.net/doc/ndn-tlv/).
+NLSR is a routing protocol in NDN that populates NDN's Routing Information Base.
+NLSR will continue to evolve alongside the Named Data Networking
+[protocol](https://named-data.net/doc/NDN-packet-spec/current/).
-NLSR is an open and free software package licensed under the GPL 3.0 license and free to all
-Internet users and developers. For more information about the licensing details and
-limitations, refer to [COPYING.md](https://github.com/named-data/NLSR/blob/master/COPYING.md).
+NLSR is an open and free software package licensed under the GPL 3.0 license and free to
+all Internet users and developers. For more information about the licensing details and
+limitations, refer to [`COPYING.md`](COPYING.md).
NLSR is developed by the members of the [NSF-sponsored NDN project team](https://named-data.net/project/participants/).
-For more details, please refer to [AUTHORS.md](https://github.com/named-data/NLSR/blob/master/AUTHORS.md).
-Bug reports and feedback are highly appreciated and can be made through the
-[Redmine site](https://redmine.named-data.net/projects/nlsr).
+For more details, please refer to [`AUTHORS.md`](AUTHORS.md).
+Bug reports and feedback are highly appreciated and can be made through our
+[Redmine site](https://redmine.named-data.net/projects/nlsr/issues).
-The main design goal of NLSR is to provide a routing protocol to populate NDN's FIB.
+The main design goal of NLSR is to provide a routing protocol to populate NDN's RIB.
NLSR calculates the routing table using link-state or hyperbolic routing and produces
multiple faces for each reachable name prefix in a single authoritative domain. NLSR
will continue to evolve over time to include neighbor discovery and to become a full
fledged inter-domain routing protocol for NDN.
-
-Source releases
----------------
+## Source releases
The source code and source-code installation instructions are always available at
the following links:
@@ -38,13 +41,12 @@
- [Getting Started with NLSR](https://named-data.net/doc/NLSR/current/GETTING-STARTED.html)
- [GitHub NLSR repository](https://github.com/named-data/NLSR)
-Additional information
-----------------------
+## Additional information
-- [Contributor's Guide](https://github.com/named-data/NFD/blob/master/CONTRIBUTING.md)
+- [Contributor's Guide](https://github.com/named-data/.github/blob/master/CONTRIBUTING.md)
- [NLSR Wiki](https://redmine.named-data.net/projects/nlsr/wiki/)
- Feature requests and bug reports are welcome on our
- [NLSR on NDN Redmine](https://redmine.named-data.net/projects/nlsr)
+ [NLSR on NDN Redmine](https://redmine.named-data.net/projects/nlsr/issues)
- [NLSR Mailing List Sign Up](https://listserv.memphis.edu/scripts/wa.exe?GETPW1)
- [NLSR Mailing List](https://listserv.memphis.edu/scripts/wa.exe?SUBED1=NLSR-HELP-L&A=1)
- [NLSR Mailing List Archives](https://listserv.memphis.edu/scripts/wa.exe?A0=NLSR-HELP-L)
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index da66e87..f496919 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -7,48 +7,36 @@
Prerequisites
-------------
-- `NFD <https://named-data.net/doc/NFD/>`_ and its requirements:
+- `NFD <https://named-data.net/doc/NFD/>`_ and its dependencies
Refer to `Getting started with NFD <https://named-data.net/doc/NFD/current/INSTALL.html>`_
for detailed installation and running instruction.
-- ChronoSync library:
+- ChronoSync library
-Download the ChronoSync library and build it according to the instructions at the following
-address:
+Download the ChronoSync library and build it according to the instructions available at
+https://github.com/named-data/ChronoSync#build
- ::
+- PSync library
- https://github.com/named-data/ChronoSync#build
-
-- PSync library:
-
-Download the PSync library and build it according to the instructions at the following
-address:
-
- ::
-
- https://github.com/named-data/PSync#build
+Download the PSync library and build it according to the instructions available at
+https://github.com/named-data/PSync#build
Build
-----
-Execute the following commands to build NLSR:
-
-::
+Execute the following commands to build NLSR::
./waf configure
./waf
sudo ./waf install
-Refer to ``./waf –help`` for more options that can be used during the configure stage and
+Refer to ``./waf --help`` for more options that can be used during the configure stage and
how to properly configure NLSR.
If your pkgconfig path is not set properly you can do the following before running ``./waf
-configure``
+configure``::
-::
-
- export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/
- or
+ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
+ # or
export PKG_CONFIG_PATH=/path/to/pkgconfig/on/your/machine
diff --git a/docs/conf.py b/docs/conf.py
index 68de944..050d44c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,37 +1,53 @@
# -*- coding: utf-8 -*-
#
-# NLSR - Named Data Link State Routing Protocol documentation build configuration file, created by
-# sphinx-quickstart on Sun Apr 6 19:58:22 2014.
+# Configuration file for the Sphinx documentation builder.
#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
-import datetime
-import sys
-import os
+# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# 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.
-sys.path.insert(0, os.path.abspath('.'))
+#
+# import os
+import sys
+# sys.path.insert(0, os.path.abspath('.'))
-# -- General configuration ------------------------------------------------
+
+# -- Project information -----------------------------------------------------
+
+project = u'Named Data Link State Routing Protocol (NLSR)'
+copyright = u'Copyright © 2014-2020 Named Data Networking Project.'
+author = u'Named Data Networking Project'
+
+# The short X.Y version
+#version = ''
+
+# The full version, including alpha/beta/rc tags
+#release = ''
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%Y-%m-%d'
+
+
+# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+#
+needs_sphinx = '1.1'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
+ 'sphinx.ext.extlinks',
'sphinx.ext.todo',
- 'redmine_issue'
]
def addExtensionIfExists(extension):
@@ -39,218 +55,88 @@
__import__(extension)
extensions.append(extension)
except ImportError:
- sys.stderr.write("Extension '%s' in not available. "
+ sys.stderr.write("Extension '%s' not found. "
"Some documentation may not build correctly.\n" % extension)
- sys.stderr.write("To install, use \n"
- " sudo pip install %s\n" % extension.replace('.', '-'))
-# sphinxcontrib.googleanalytics is currently not working with the latest version of sphinx
-# if os.getenv('GOOGLE_ANALYTICS', None):
-# addExtensionIfExists('sphinxcontrib.googleanalytics')
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
+addExtensionIfExists('sphinxcontrib.doxylink')
# The master toctree document.
master_doc = 'index'
-# General information about the project.
-project = u'NLSR - Named Data Link State Routing Protocol'
-copyright = u'2014-{}, Named Data Networking Project'.format(datetime.date.today().year)
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
-
-
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-# html_theme = 'default'
+#
html_theme = 'named_data_theme'
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['./']
-
-# The name for this set of Sphinx documents. If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
+html_theme_path = ['.']
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-html_file_suffix = ".html"
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'nlsr-docs'
-
-
-# -- Options for LaTeX output ---------------------------------------------
+# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+ # The paper size ('letterpaper' or 'a4paper').
+ #
+ # 'papersize': 'letterpaper',
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+ # The font size ('10pt', '11pt' or '12pt').
+ #
+ # 'pointsize': '10pt',
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+ # Additional stuff for the LaTeX preamble.
+ #
+ # 'preamble': '',
+
+ # Latex figure (float) alignment
+ #
+ # 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- ('index', 'nlsr-docs.tex', u'NLSR - Named Data Link State Routing Protocol Documentation',
- u'Named Data Networking Project', 'manual'),
+ ('index', 'nlsr-docs.tex', u'Named Data Link State Routing Protocol (NLSR)',
+ author, 'manual'),
]
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output ---------------------------------------
+# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('manpages/nlsr', 'nlsr', u'Named Data Link State Routing Protocol Daemon', None, 1),
- ('manpages/nlsr.conf', 'nlsr.conf', u'Named Data Link State Routing Protocol Daemon config file', None, 5),
- ('manpages/nlsrc', 'nlsrc', u'Command-line utility to interact with and collect statistics from NLSR', None, 1),
+ ('manpages/nlsr', 'nlsr', u'Named Data Link State Routing daemon', None, 1),
+ ('manpages/nlsr.conf', 'nlsr.conf', u'Named Data Link State Routing daemon configuration file', None, 5),
+ ('manpages/nlsrc', 'nlsrc', u'command-line utility to interact with and collect statistics from NLSR', None, 1),
]
-
# If true, show URL addresses after external links.
-#man_show_urls = False
+#man_show_urls = True
-if os.getenv('GOOGLE_ANALYTICS', None):
- googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
- googleanalytics_enabled = True
-redmine_project_url = "https://redmine.named-data.net/"
+# -- Custom options ----------------------------------------------------------
+
+doxylink = {
+ 'nlsr': ('NLSR.tag', 'doxygen/'),
+}
+
+extlinks = {
+ 'issue': ('https://redmine.named-data.net/issues/%s', 'issue #'),
+}
diff --git a/docs/doxygen.conf.in b/docs/doxygen.conf.in
index 2ecc2ad..5f041ce 100644
--- a/docs/doxygen.conf.in
+++ b/docs/doxygen.conf.in
@@ -32,7 +32,7 @@
# title of most generated pages and in a few other places.
# The default value is: My Project.
-PROJECT_NAME = "NLSR - Named Data Link State Routing Protocol"
+PROJECT_NAME = "NLSR: Named Data Link State Routing Protocol"
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
@@ -232,7 +232,7 @@
# members will be omitted, etc.
# The default value is: NO.
-OPTIMIZE_OUTPUT_FOR_C = YES
+OPTIMIZE_OUTPUT_FOR_C = NO
# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
# Python sources only. Doxygen will then generate output that is more tailored
@@ -408,7 +408,7 @@
# scope will be included in the documentation.
# The default value is: NO.
-EXTRACT_PACKAGE = YES
+EXTRACT_PACKAGE = NO
# If the EXTRACT_STATIC tag is set to YES all static members of a file will be
# included in the documentation.
@@ -524,7 +524,7 @@
# name. If set to NO the members will appear in declaration order.
# The default value is: NO.
-SORT_BRIEF_DOCS = NO
+SORT_BRIEF_DOCS = YES
# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
# (brief and detailed) documentation of class members so that constructors and
@@ -536,7 +536,7 @@
# detailed member documentation.
# The default value is: NO.
-SORT_MEMBERS_CTORS_1ST = NO
+SORT_MEMBERS_CTORS_1ST = YES
# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
# of group names into alphabetical order. If set to NO the group names will
@@ -1117,7 +1117,7 @@
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
-HTML_DYNAMIC_SECTIONS = NO
+HTML_DYNAMIC_SECTIONS = YES
# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries
# shown in the various tree structured indices initially; the user can expand
@@ -1355,7 +1355,7 @@
# Minimum value: 0, maximum value: 20, default value: 4.
# This tag requires that the tag GENERATE_HTML is set to YES.
-ENUM_VALUES_PER_LINE = 4
+ENUM_VALUES_PER_LINE = 1
# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used
# to set the initial width (in pixels) of the frame in which the tree is shown.
@@ -1916,18 +1916,14 @@
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-PREDEFINED = DOXYGEN=1 \
+PREDEFINED = DOXYGEN \
INIT_LOGGER(x)= \
- BOOST_STATIC_ASSERT(x)= \
BOOST_CONCEPT_ASSERT(x)= \
BOOST_CONCEPT_REQUIRES(x)= \
- DECL_OVERRIDE=override \
PUBLIC_WITH_TESTS_ELSE_PRIVATE=private \
PUBLIC_WITH_TESTS_ELSE_PROTECTED=protected \
PROTECTED_WITH_TESTS_ELSE_PRIVATE=private \
- VIRTUAL_WITH_TESTS \
- DECL_CLASS_FINAL=final \
- DECL_FINAL=final
+ VIRTUAL_WITH_TESTS=
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
@@ -2264,7 +2260,7 @@
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.
-DOT_MULTI_TARGETS = NO
+DOT_MULTI_TARGETS = YES
# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page
# explaining the meaning of the various boxes and arrows in the dot generated
diff --git a/docs/redmine_issue.py b/docs/redmine_issue.py
deleted file mode 100644
index 0df2b1f..0000000
--- a/docs/redmine_issue.py
+++ /dev/null
@@ -1,70 +0,0 @@
-# -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
-# Based on http://doughellmann.com/2010/05/09/defining-custom-roles-in-sphinx.html
-
-"""Integration of Sphinx with Redmine.
-"""
-
-from docutils import nodes, utils
-from docutils.parsers.rst.roles import set_classes
-
-def redmine_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
- """Link to a Redmine issue.
-
- Returns 2 part tuple containing list of nodes to insert into the
- document and a list of system messages. Both are allowed to be
- empty.
-
- :param name: The role name used in the document.
- :param rawtext: The entire markup snippet, with role.
- :param text: The text marked with the role.
- :param lineno: The line number where rawtext appears in the input.
- :param inliner: The inliner instance that called us.
- :param options: Directive options for customization.
- :param content: The directive content for customization.
- """
- try:
- issue_num = int(text)
- if issue_num <= 0:
- raise ValueError
- except ValueError:
- msg = inliner.reporter.error(
- 'Redmine issue number must be a number greater than or equal to 1; '
- '"%s" is invalid.' % text, line=lineno)
- prb = inliner.problematic(rawtext, rawtext, msg)
- return [prb], [msg]
- app = inliner.document.settings.env.app
- node = make_link_node(rawtext, app, 'issues', str(issue_num), options)
- return [node], []
-
-def make_link_node(rawtext, app, type, slug, options):
- """Create a link to a Redmine resource.
-
- :param rawtext: Text being replaced with link node.
- :param app: Sphinx application context
- :param type: Link type (issue, changeset, etc.)
- :param slug: ID of the thing to link to
- :param options: Options dictionary passed to role func.
- """
- #
- try:
- base = app.config.redmine_project_url
- if not base:
- raise AttributeError
- except AttributeError:
- raise ValueError('redmine_project_url configuration value is not set')
- #
- slash = '/' if base[-1] != '/' else ''
- ref = base + slash + type + '/' + slug + '/'
- set_classes(options)
- node = nodes.reference(rawtext, 'Issue #' + utils.unescape(slug), refuri=ref,
- **options)
- return node
-
-def setup(app):
- """Install the plugin.
-
- :param app: Sphinx application context.
- """
- app.add_role('issue', redmine_role)
- app.add_config_value('redmine_project_url', None, 'env')
- return
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
#