docs: refresh installation instructions and general cleanup
Change-Id: Ibfe945887e5cad979c1f9a78fd5a3062bb20a8b5
diff --git a/.jenkins.d/10-build.sh b/.jenkins.d/10-build.sh
index 09b09e3..66ec27f 100755
--- a/.jenkins.d/10-build.sh
+++ b/.jenkins.d/10-build.sh
@@ -51,6 +51,4 @@
if has Linux $NODE_LABELS; then
sudo ldconfig
-elif has FreeBSD $NODE_LABELS; then
- sudo ldconfig -a
fi
diff --git a/.jenkins.d/README.md b/.jenkins.d/README.md
index aeb94b0..7c78349 100644
--- a/.jenkins.d/README.md
+++ b/.jenkins.d/README.md
@@ -15,11 +15,11 @@
* `[DISTRO_TYPE]`: `Ubuntu`
* `[DISTRO_VERSION]`: `Ubuntu-16.04`, `Ubuntu-18.04`
- Possible values for OS X / macOS:
+ Possible values for macOS:
* `[OS_TYPE]`: `OSX`
* `[DISTRO_TYPE]`: `OSX` (can be absent)
- * `[DISTRO_VERSION]`: `OSX-10.11`, `OSX-10.12`, `OSX-10.13`
+ * `[DISTRO_VERSION]`: `OSX-10.12`, `OSX-10.13`, `OSX-10.14`
- `JOB_NAME`: optional variable to define type of the job. Depending on the defined job type,
the build scripts can perform different tasks.
diff --git a/README-dev.md b/README-dev.md
index 6bd7644..0b31401 100644
--- a/README-dev.md
+++ b/README-dev.md
@@ -49,17 +49,17 @@
Running unit tests
------------------
-To run unit tests, ndn-cxx needs to be configured, build with unit test support, and installed
+To run the unit tests, ndn-cxx needs to be built with unit test support and installed
into the configured location. For example:
- ./waf configure --with-tests
+ ./waf configure --with-tests # --debug is also recommended while developing
./waf
sudo ./waf install
-**Note**: On Linux platform you also need to run `sudo ldconfig` to reconfigure dynamic loader
-run-time bindings. On FreeBSD, use `sudo ldconfig -a` instead.
+**Note**: On Linux you also need to run `sudo ldconfig` to reconfigure dynamic loader
+run-time bindings.
-The simplest way to run tests, is just to run the compiled binary without any parameters:
+The simplest way to run the tests is to launch the compiled binary without any parameters:
./build/unit-tests
@@ -79,8 +79,8 @@
By default, Boost.Test framework will produce verbose output only when a test case fails.
If it is desired to see verbose output (result of each test assertion), add `-l all`
-option to `./build/unit-tests` command. To see test progress, you can use `-l test_suite`
-or `-p` to show progress bar:
+option to `./build/unit-tests` command. To see test progress, you can use `-l test_suite`,
+or `-p` to show a progress bar:
# Show report all log messages including the passed test notification
./build/unit-tests -l all
diff --git a/client.conf.sample b/client.conf.sample
index abed4ff..9eae16e 100644
--- a/client.conf.sample
+++ b/client.conf.sample
@@ -1,25 +1,24 @@
; "transport" specifies Face's default transport connection.
-; The value is a unix or tcp4 scheme Face URI.
+; The value can be a "unix:" or "tcp4:" Face URI.
;
; For example:
-;
; unix:///var/run/nfd.sock
; tcp://192.0.2.1
; tcp4://example.com:6363
-
+;
transport=unix:///var/run/nfd.sock
; "pib" determines which Public Info Base (PIB) should used by default in applications.
-; If "pib" is not specified, the default PIB will be used.
-; Note that default PIB could be different on different system.
+; If "pib" is not specified, a platform-dependent default will be used.
; If "pib" is specified, it may have a value of:
; pib-sqlite3
-; pib=pib-sqlite3
+;
+;pib=pib-sqlite3
; "tpm" determines which Trusted Platform Module (TPM) should used by default in applications.
-; If "tpm" is not specified, the default TPM will be used.
-; Note that default TPM could be different on different system.
+; If "tpm" is not specified, a platform-dependent default will be used.
; If "tpm" is specified, it may have a value of:
-; tpm-osxkeychain (default in OS X)
-; tpm-file (default in operating systems other than OS X)
-; tpm=tpm-file
\ No newline at end of file
+; tpm-osxkeychain (default on macOS)
+; tpm-file (default in operating systems other than macOS)
+;
+;tpm=tpm-file
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index 428c064..864bb10 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -11,9 +11,9 @@
- Ubuntu 16.04 (amd64, armhf, i386)
- Ubuntu 18.04 (amd64)
-- OS X 10.11
- macOS 10.12
- macOS 10.13
+- macOS 10.14
ndn-cxx is known to work on the following platforms, although they are not officially
supported:
@@ -22,6 +22,9 @@
- Fedora >= 24
- Gentoo Linux
- Raspbian >= 2017-08-16
+- OS X 10.11
+- FreeBSD 11.2
+
Prerequisites
-------------
@@ -31,48 +34,46 @@
- GCC >= 5.3, or clang >= 3.6
- ``python2`` >= 2.7, or ``python3`` >= 3.4
-- ``libsqlite3``
-- OpenSSL >= 1.0.2
-- ``pkg-config``
- Boost libraries >= 1.58
-- OSX Security framework (on OSX/macOS platform only)
+- ``pkg-config``
+- SQLite 3.x
+- OpenSSL >= 1.0.2
+- Apple Security framework (on macOS only)
Following are the detailed steps for each platform to install the compiler, all necessary
development tools and libraries, and ndn-cxx prerequisites.
-- OS X / macOS
+- macOS
- Install Xcode from AppStore or at least Command Line Tools (``xcode-select --install``)
+ * Install Xcode from the App Store, or at least the Command Line Tools
+ (``xcode-select --install``)
- * When using MacPorts
+ * If using Homebrew (recommended), enter the following in a terminal::
- In a terminal, enter::
+ brew install boost openssl pkg-config
- sudo port install pkgconfig boost sqlite3 openssl
+ .. note::
- * When using Homebrew
+ If a major OS upgrade is performed after installing the dependencies
+ with Homebrew, remember to reinstall all packages.
- In a terminal, enter::
-
- brew install boost openssl pkg-config
-
- .. note::
-
- If a major OS upgrade is performed after installing dependencies with
- MacPorts or Homebrew, remember to reinstall all packages.
-
-- Ubuntu
+- Ubuntu
In a terminal, enter::
- sudo apt-get install build-essential libsqlite3-dev libboost-all-dev libssl-dev
+ sudo apt install build-essential libsqlite3-dev libboost-all-dev libssl-dev
- Fedora
In a terminal, enter::
- sudo yum install gcc-g++ git
- sudo yum install sqlite-devel boost-devel openssl-devel
+ sudo yum install gcc-g++ sqlite-devel boost-devel openssl-devel
+
+- FreeBSD
+
+ In a terminal, enter::
+
+ sudo pkg install python pkgconf sqlite3 boost-libs
Optional:
~~~~~~~~~
@@ -82,49 +83,48 @@
- ``doxygen``
- ``graphviz``
-- ``python-sphinx`` and sphinx extensions ``sphinxcontrib-doxylink``,
- ``sphinxcontrib-googleanalytics``
+- ``python-sphinx``
+- ``sphinxcontrib-doxylink``
The following lists steps for common platforms to install these prerequisites:
-- On OS X / macOS with MacPorts::
+- On macOS with Homebrew and pip::
- sudo port install doxygen graphviz py27-sphinx sphinx_select
- sudo port select sphinx py27-sphinx
+ brew install doxygen graphviz
+ sudo pip install sphinx sphinxcontrib-doxylink
- # Install sphinx extensions
- sudo port install py27-pip
- sudo port select pip pip27
- sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
+- On Ubuntu::
-- On Ubuntu::
+ sudo apt install doxygen graphviz python3-pip
+ sudo pip3 install sphinx sphinxcontrib-doxylink
- sudo apt-get install doxygen graphviz python-sphinx python-pip
- sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
+- On Fedora::
-- On Fedora::
+ sudo yum install doxygen graphviz python-sphinx
+ sudo pip install sphinxcontrib-doxylink
- sudo yum install doxygen graphviz python-sphinx
- sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
+- On FreeBSD::
+
+ sudo pkg install doxygen graphviz py27-sphinx
+
.. _build:
Build
-----
-(These are instructions to build ndn-cxx. To do development of ndn-cxx
-code and update the build system, see Development.)
+.. note::
+ These are instructions for regular builds of ndn-cxx (release mode).
+ To do development of ndn-cxx code itself, see "Development build" below.
-To build in a terminal, change directory to the ndn-cxx root. Enter:
-
-::
+To build in a terminal, change directory to the ndn-cxx root, then enter::
./waf configure
./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. For example::
+use ``--enable-static`` option for ``./waf configure`` command::
./waf configure --enable-static
@@ -136,83 +136,63 @@
./waf configure --enable-static --disable-shared
+After the shared library is installed, on Linux it is also necessary to run::
-After the shared library is built and installed, some systems require additional actions.
+ sudo ldconfig
- - on Linux::
+.. 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.
- sudo ldconfig
+ The installation path should be added to ``/etc/ld.so.conf`` (or in
+ ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
- - on FreeBSD::
+ echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
- sudo ldconfig -m
+ Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
+ the installation directory of the shared library::
- .. note::
- When 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.
+ export LD_LIBRARY_PATH=/usr/local/lib
- The installation path should be added to ``/etc/ld.so.conf`` (or in
- ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
+The ``./waf install`` command installs the following files:
- echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
-
- Alternatively, ``LD_LIBRARY_PATH`` environment variable should be set to the location of
- the library::
-
- export LD_LIBRARY_PATH=/usr/local/lib
-
-This builds and installs the following items:
-
-- ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled)
+- ``<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 OS X):
- shared NDN C++ library (if enabled)
+ ``<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
- pkgconfig or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
+ 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.
-- ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates
-- ``<BINPATH>/ndnsec-*``: convenience scripts for ``ndnsec`` tools
+- ``<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
+If configured with tests (``./waf configure --with-tests``), the above
commands will also produce:
-- ``build/unit-tests``: A unit test binary for the library
+- ``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 could usually avoid memory thrashing and result in faster compilation.
+which should usually avoid memory thrashing and result in faster compilation.
Build with examples
-------------------
-By default, examples in ``examples/`` are not build. To enable them, use
-``--with-examples`` configure option:
-
-::
+By default, examples in ``examples/`` are not built. To enable them, use the
+``--with-examples`` configure option::
./waf configure --with-examples
./waf
sudo ./waf install
+ sudo ldconfig # (on Linux only)
-:ref:`Additional step <build>`:
-
- - on Linux::
-
- sudo ldconfig
-
- - on FreeBSD::
-
- sudo ldconfig -m
-
-To run examples:
-
-::
+To run examples::
# trivial producer app
./build/examples/producer
@@ -224,16 +204,14 @@
./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:
-
-::
+folder and it will be compiled on the next run on ``./waf``. For example::
cp examples/consumer.cpp examples/my-new-consumer-app.cpp
./waf
sudo ./waf install
+ sudo ldconfig # (on Linux only)
./build/examples/my-new-consumer-app
-
Debug symbols
~~~~~~~~~~~~~
@@ -241,31 +219,18 @@
flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``). This
potentially allows more meaningful debugging information if your application crashes.
-If it is undesirable, default flags can be easily overridden:
-
-::
+The default build flags can easily be overridden::
CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
./waf
sudo ./waf install
-:ref:`Additional step <build>`:
-
- - on Linux::
-
- sudo ldconfig
-
- - on FreeBSD::
-
- sudo ldconfig -m
Documentation
-------------
ndn-cxx tutorials and API documentation can be built using the following
-commands:
-
-::
+commands::
# Full set of documentation (tutorials + API) in build/docs
./waf docs
@@ -286,44 +251,31 @@
For more details, refer to ``./waf --help``.
-Development Build
+
+Development build
-----------------
-The following is the suggested configure commands for development build.
-
-::
+The following is the suggested configure command for development builds::
./waf configure --debug --with-tests
./waf
sudo ./waf install
+ sudo ldconfig # (on Linux only)
-:ref:`Additional step <build>`:
-
- - on Linux::
-
- sudo ldconfig
-
- - on FreeBSD::
-
- sudo ldconfig -m
-
-In the development build all compiler optimizations are disabled by
-default and all warnings are treated as error. The default behavior can
+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``:
-
-::
+running ``./waf configure``::
CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
...
-Customize Compiler
-------------------
-To choose a custom C++ compiler for building ndn-cxx, set ``CXX`` environment
+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:
-
-::
+Linux, use the following::
CXX=clang++ ./waf configure
diff --git a/docs/manpages/ndn-client.conf.rst b/docs/manpages/ndn-client.conf.rst
index d267c14..62f42ca 100644
--- a/docs/manpages/ndn-client.conf.rst
+++ b/docs/manpages/ndn-client.conf.rst
@@ -5,8 +5,8 @@
The configuration file ``client.conf`` is looked up in several directories in the following order:
-- ``$HOME/.ndn/``: user-specific settings
-- ``@SYSCONFDIR@/ndn/`` (``/usr/local/etc/ndn``, ``/opt/local/etc/ndn``, or other, depending how the
+- ``$HOME/.ndn``: user-specific settings
+- ``@SYSCONFDIR@/ndn`` (``/usr/local/etc/ndn``, ``/opt/local/etc/ndn``, or other, depending how the
library is configured): system-wide settings
- ``/etc/ndn``: default system-wide settings
@@ -24,9 +24,10 @@
By default, ``unix:///var/run/nfd.sock`` is used.
- ..note::
+ .. note::
This value can be overridden using the ``NDN_CLIENT_TRANSPORT`` environment variable.
+
Key Management
--------------
@@ -55,10 +56,10 @@
rm -rf ~/.ndn/ndnsec-*
- It's not recommended to share the same directory between machines, e.g. via NFS.
+ It is not recommended to share the same directory between machines, e.g. via NFS.
Simultaneous access from multiple machines may cause errors.
- ..note::
+ .. note::
This value can be overridden using the ``NDN_CLIENT_PIB`` environment variable.
tpm
@@ -69,15 +70,15 @@
Possible values for ``[scheme]``:
- * ``tpm-osx-keychain`` (default on OS X platform): secure storage of private keys in OS X
+ * ``tpm-osx-keychain`` (default on macOS): secure storage of private keys in the macOS
Keychain with OS-provided access restrictions.
``[location]`` parameter is ignored.
- May not work for daemon applications, as user interaction may be required to access OS X
- Keychain.
+ May not work for daemon applications, as user interaction may be required to access the
+ macOS Keychain.
- * ``tpm-file`` (default on all other platforms): file-based storage of private keys
+ * ``tpm-file`` (default on all other platforms): file-based storage of private keys.
Possible values for ``[location]``:
@@ -90,11 +91,11 @@
tpm=tpm-file
- **Change of ``tpm`` setting is only possible together with ``pib`` setting. Otherwise, an
- error will be generated during PIB/TPM access**
+ **Changing the ``tpm`` setting is only possible together with ``pib`` setting. Otherwise,
+ an error will be generated during PIB/TPM access.**
- It's not recommended to share the same directory between machines, e.g. via NFS.
+ It is not recommended to share the same directory between machines, e.g. via NFS.
Simultaneous access from multiple machines may cause errors.
- ..note::
+ .. note::
This value can be overridden using the ``NDN_CLIENT_TPM`` environment variable.
diff --git a/ndn-cxx/security/tpm/key-handle-osx.hpp b/ndn-cxx/security/tpm/key-handle-osx.hpp
index d4c73af..0171d0c 100644
--- a/ndn-cxx/security/tpm/key-handle-osx.hpp
+++ b/ndn-cxx/security/tpm/key-handle-osx.hpp
@@ -35,7 +35,7 @@
namespace tpm {
/**
- * @brief Abstraction of TPM key handle used by the TPM based on OS X Keychain Service.
+ * @brief Abstraction of TPM key handle used by the TPM based on macOS Keychain Services.
*/
class KeyHandleOsx : public KeyHandle
{
diff --git a/ndn-cxx/util/time.cpp b/ndn-cxx/util/time.cpp
index a7a0cdb..170cb78 100644
--- a/ndn-cxx/util/time.cpp
+++ b/ndn-cxx/util/time.cpp
@@ -69,11 +69,11 @@
/////////////////////////////////////////////////////////////////////////////////////////////
#ifdef __APPLE__
- // Note that on OS X platform boost::steady_clock is not truly monotonic, so we use
- // system_clock instead. Refer to https://svn.boost.org/trac/boost/ticket/7719)
- typedef boost::chrono::system_clock base_steady_clock;
+// Note that on macOS platform boost::steady_clock is not truly monotonic, so we use
+// system_clock instead. Refer to https://svn.boost.org/trac/boost/ticket/7719)
+typedef boost::chrono::system_clock base_steady_clock;
#else
- typedef boost::chrono::steady_clock base_steady_clock;
+typedef boost::chrono::steady_clock base_steady_clock;
#endif
steady_clock::time_point
diff --git a/tests/unit/security/config-file-readme.txt b/tests/unit/security/config-file-readme.txt
deleted file mode 100644
index 44e5f61..0000000
--- a/tests/unit/security/config-file-readme.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-In test, we set a test-specific "HOME", which cause OS X keychain look for the
-default keychain of a "different" user. If the default keychain does not exist,
-all subsequent calls to OS X keychain will fail. User interaction (such as
-specifying password) is required to create a keychain. However, user interaction
-is not feasible in automated tests.
-
-This problem is caused by the OS X system assumption that one user must have a
-login keychain, which is also the user's default keychain, because a user
-account is always created with a login keychain as default. Thus OS X system
-infers a user according to the HOME env, and did not expect user to change the
-HOME env in normal use.
diff --git a/tests/unit/security/config-file.README.txt b/tests/unit/security/config-file.README.txt
new file mode 100644
index 0000000..f77cf65
--- /dev/null
+++ b/tests/unit/security/config-file.README.txt
@@ -0,0 +1,11 @@
+In tests, we set a test-specific HOME, which causes macOS Keychain to look for
+the default keychain of a "different" user. If the default keychain does not
+exist, all subsequent calls to macOS Keychain will fail. User interaction
+(such as entering the password) is required to create a keychain. However,
+user interaction is not feasible in automated tests.
+
+This problem is caused by macOS's assumption that a user must have a login
+keychain, which is also the user's default keychain, because a user account is
+always created with a login keychain by default. Thus, macOS infers the user
+according to the HOME env, and does not expect the user to change the HOME env
+during normal use.