ci+docs: minor cleanups

Change-Id: I280fd84d89061e34ad4e2aaa00ce63ad21b03565

.jenkins

@@ -2,7 +2,9 @@
 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

.jenkins.d/10-build.sh

@@ -4,15 +4,15 @@ set -ex
 git submodule sync
 git submodule update --init
 
-if has CentOS-8 $NODE_LABELS; then
-    # https://bugzilla.redhat.com/show_bug.cgi?id=1721553
-    PCH="--without-pch"
+if [[ -z $DISABLE_ASAN ]]; then
+    ASAN="--with-sanitizer=address"
 fi
-
 if [[ $JOB_NAME == *"code-coverage" ]]; then
     COVERAGE="--with-coverage"
-elif [[ -z $DISABLE_ASAN ]]; then
-    ASAN="--with-sanitizer=address"
+fi
+if has CentOS-8 $NODE_LABELS; then
+    # https://bugzilla.redhat.com/show_bug.cgi?id=1721553
+    PCH="--without-pch"
 fi
 
 if [[ $JOB_NAME != *"code-coverage" && $JOB_NAME != *"limited-build" ]]; then

.jenkins.d/README.md

@@ -22,4 +22,7 @@
   - `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`: 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 threads used by waf, defaults to 1.

README.md

@@ -11,8 +11,8 @@ used by the following projects:
 * [NFD - NDN Forwarding Daemon](https://github.com/named-data/NFD)
 * [NLSR - Named-data Link-State Routing protocol](https://github.com/named-data/NLSR)
 * [ndn-tools - Essential NDN command-line tools](https://github.com/named-data/ndn-tools)
-* [repo-ng - Next generation of NDN repository](https://github.com/named-data/repo-ng)
-* [ChronoSync - Sync library for multiuser realtime applications](https://github.com/named-data/ChronoSync)
+* [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)
 * [ndn-traffic-generator - Traffic generator for NDN](https://github.com/named-data/ndn-traffic-generator)
 * [NAC - Name-based Access Control](https://github.com/named-data/name-based-access-control)

docs/INSTALL.rst

@@ -1,12 +1,11 @@
-.. _Getting Started with ndn-cxx:
-
 Getting started with ndn-cxx
 ============================
 
 Supported platforms
 -------------------
 
-ndn-cxx uses continuous integration and has been tested on the following platforms:
+ndn-cxx 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)
@@ -28,18 +27,18 @@ supported:
 Prerequisites
 -------------
 
-Required:
-~~~~~~~~~
+Required
+~~~~~~~~
 
--  GCC >= 5.3, or clang >= 3.6
+-  GCC >= 5.3 or clang >= 3.6
 -  Python >= 3.5
--  ``pkg-config``
+-  pkg-config
 -  Boost >= 1.58
 -  OpenSSL >= 1.0.2
 -  SQLite 3.x
 
-Following are the detailed steps for each platform to install the compiler and all necessary
-development tools and libraries that are required to build ndn-cxx from source.
+To build ndn-cxx from source, one must first install a C++ compiler and all necessary
+development tools and libraries:
 
 - Ubuntu
 
@@ -73,16 +72,16 @@ development tools and libraries that are required to build ndn-cxx from source.
 
         sudo pkg install pkgconf python3 boost-libs openssl sqlite3
 
-Optional:
-~~~~~~~~~
+Optional
+~~~~~~~~
 
-To build tutorials, manpages, and API documentation the following
-dependencies need to be installed:
+To build tutorials, manpages, and API documentation the following additional dependencies
+need to be installed:
 
--  ``doxygen``
--  ``graphviz``
--  ``sphinx``
--  ``sphinxcontrib-doxylink``
+-  doxygen
+-  graphviz
+-  sphinx
+-  sphinxcontrib-doxylink
 
 The following lists the steps to install these prerequisites on various common platforms.
 
@@ -106,36 +105,34 @@ The following lists the steps to install these prerequisites on various common p
 
     sudo pkg install doxygen graphviz py37-sphinx
 
-
-.. _build:
-
 Build
 -----
 
 .. note::
-  These are instructions for regular builds of ndn-cxx (release mode).
-  To do development of ndn-cxx code itself, see "Development build" below.
+  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 version of ndn-cxx library is built.  To build the static library,
-use ``--enable-static`` option for ``./waf configure`` command::
+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 build of the shared library and build only the static library, use additional
-``--disable-shared`` option.  Note that at least one version of the library needs to be
-enabled.
+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
 
-After the shared library is installed, on Linux it is also necessary to run::
+On Linux, it is necessary to run the following command after the shared library has
+been installed::
 
     sudo ldconfig
 
@@ -160,38 +157,37 @@ The ``./waf install`` command installs the following files:
 -  ``<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
-   neccessary flags to build against the library. For example, if
-   pkg-config or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
-   configured properly (or ``<LIBPATH>/pkgconfig`` is a default path),
-   ``pkgconfig --libs --clflags libndn-cxx`` will return all necessary
-   compile and link flags for the library.
+-  ``<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:
+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.5GB available memory per CPU core is necessary for efficient compilation.
-On a multi-core machine with less than 1.5GB 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.5GB (eg. ``./waf -j1`` for 1.5GB memory),
-which should usually avoid memory thrashing and result in faster compilation.
+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, examples in ``examples/`` are not built.  To enable them, use the
-``--with-examples`` configure option::
+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
+    ./waf configure --with-examples  # on CentOS, add --without-pch
     ./waf
     sudo ./waf install
     sudo ldconfig  # on Linux only
 
-To run examples::
+To run the examples::
 
     # trivial producer app
     ./build/examples/producer
@@ -202,34 +198,45 @@ To run examples::
     # trivial consumer app with timers
     ./build/examples/consumer-with-timer
 
-If you want to test out a sample application, just create a ``.cpp`` file in ``examples/``
-folder and it will be compiled on the next run on ``./waf``.  For example::
+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-consumer-app.cpp
+    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-consumer-app
+    ./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.
 
-The default compiler flags enable debug symbols to be included in binaries (i.e., ``-g``
-flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``).  This
-potentially allows more meaningful debugging information if 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.
 
-The default build flags can easily be overridden::
+::
 
     CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
     ./waf
     sudo ./waf install
 
+Customizing the compiler
+------------------------
 
-Documentation
--------------
+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::
 
-ndn-cxx tutorials and API documentation can be built using the following
-commands::
+    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
@@ -240,41 +247,30 @@ commands::
     # Only API docs in build/docs/doxygen
     ./waf doxygen
 
-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.
+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 more details, refer to ``./waf --help``.
+For further details, please refer to ``./waf --help``.
 
+.. _Development build:
 
 Development build
 -----------------
 
-The following is the suggested configure command for development builds::
+The following is the suggested build procedure for development builds::
 
-    ./waf configure --debug --with-tests
+    ./waf configure --debug --with-tests  # on CentOS, add --without-pch
     ./waf
     sudo ./waf install
     sudo ldconfig  # on Linux only
 
-In the development build most compiler optimizations are disabled by
-default and all warnings are treated as errors. The default behavior can
-be overridden by setting ``CXXFLAGS`` environment variable before
-running ``./waf configure``::
+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
     ...
-
-
-Customizing the compiler
-------------------------
-
-To choose a custom C++ compiler for building ndn-cxx, 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

docs/conf.py

@@ -12,15 +12,15 @@
 # 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('.'))
 
 
 # -- Project information -----------------------------------------------------
 
 project = u'ndn-cxx: NDN C++ library with eXperimental eXtensions'
-copyright = u'Copyright © 2013-2019 Regents of the University of California.'
+copyright = u'Copyright © 2013-2020 Regents of the University of California.'
 author = u'Named Data Networking Project'
 
 # The short X.Y version
@@ -135,7 +135,7 @@ def addExtensionIfExists(extension):
     ('manpages/ndnsec-set-default',  'ndnsec-set-default',  'change the default NDN identity, key, or certificate for the current user', None, 1),
     ('manpages/ndnsec-sign-req',     'ndnsec-sign-req',     'generate an NDN certificate signing request',  None, 1),
     ('manpages/ndnsec-unlock-tpm',   'ndnsec-unlock-tpm',   'unlock the TPM',                               None, 1),
-    ('manpages/ndn-client.conf',     'ndn-client.conf',     'configuration file for NDN platform',          None, 5),
+    ('manpages/ndn-client.conf',     'ndn-client.conf',     'configuration file for NDN applications',      None, 5),
     ('manpages/ndn-log',             'ndn-log',             'ndn-cxx logging',                              None, 7),
 ]