docs: Adding installation instructions and configuration tips
README.md and INSTALL.md now redirect to documentation in docs/ folder.
Later we will add links to HTML pages with NFD documentation.
Change-Id: I4f02f3166e7802570b24ed225ac4de8c56c6e64e
Refs: #1446
diff --git a/INSTALL.md b/INSTALL.md
index cf8bfcc..493bd0f 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,86 +1,5 @@
-NFD: NDN Forwarding Daemon
-==========================
+NFD Installation Instructions
+=============================
-## Prerequisites
-
-* [ndn-cpp-dev library](https://github.com/named-data/ndn-cpp-dev) and
- its requirements:
-
- * `libcrypto`
- * `libsqlite3`
- * `libcrypto++`
- * `pkg-config`
- * Boost libraries (>= 1.48)
- * OSX Security framework (on OSX platform only)
-
- Refer to https://github.com/named-data/ndn-cpp-dev/blob/master/INSTALL.md
- for detailed installation instructions.
-
-* `libpcap`
-
- Comes with base on OS X 10.8 and 10.9:
-
- On Ubuntu >= 12.04:
-
- sudo apt-get install libpcap-dev
-
-To build manpages and API documentation:
-
-* `doxygen`
-* `graphviz`
-* `python-sphinx`
-
- On OS X 10.8 and 10.9 with macports:
-
- sudo port install doxygen graphviz py27-sphinx sphinx_select
- sudo port select sphinx py27-sphinx
-
- On Ubuntu >= 12.04:
-
- sudo apt-get install doxygen graphviz python-sphinx
-
-
-## Build
-
-The following commands should be used to build NFD:
-
- ./waf configure
- ./waf
- sudo ./waf install
-
-Refer to `README.md` file for more options that can be used during `configure` stage and
-how to properly configure and run NFD.
-
-In some configurations, configuration step may require small modification. For example,
-on OSX that uses macports (correct the path if macports was not installed in the default
-path `/opt/local`):
-
- export PKG_CONFIG_PATH=/opt/local/lib/pkgconfig:/usr/local/lib/pkgconfig:/usr/lib/pkgconfig:$PKG_CONFIG_PATH
- ./waf configure
- ./waf
- sudo ./waf install
-
-On some Linux distributions (e.g., Fedora 20):
-
- export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/lib/pkgconfig:/usr/lib64/pkgconfig:$PKG_CONFIG_PATH
- ./waf configure
- ./waf
- sudo ./waf install
-
-# Building API documentation
-
-The following commands can be used to build API documentation in `build/docs/doxygen`
-
- ./waf doxygen
-
-Note that 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`.
-
-Additional documentation in `build/docs` can be built using (requires `python-sphinx` package)
-
- ./waf sphinx
+See [`docs/install.rst`](https://github.com/named-data/NFD/blob/master/docs/INSTALL.rst)
+for detailed NFD installation instructions.
diff --git a/README-dev.md b/README-dev.md
index d9cae4a..aab44e9 100644
--- a/README-dev.md
+++ b/README-dev.md
@@ -1,7 +1,10 @@
-Requirements
----------------------
+Notes for NFD developers
+========================
-Include the following header into all `.hpp` and `.cpp` files:
+Requirements
+------------
+
+Include the following license boilerplate into all `.hpp` and `.cpp` files:
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/**
@@ -36,8 +39,8 @@
Recommendations
---------------
-NFD code is subject to the code style, defined here:
-http://redmine.named-data.net/projects/nfd/wiki/CodeStyle
+NFD code is subject to NFD [code style](http://redmine.named-data.net/projects/nfd/wiki/CodeStyle).
+
Running unit-tests
------------------
@@ -49,27 +52,47 @@
The simplest way to run tests, is just to run the compiled binary without any parameters:
- ./build/unit-tests
+ # Run core tests
+ ./build/unit-tests-core
-However, Boost.Test framework is very flexible and allow a number of
-run-time customization of what tests should be run. For example, it
-is possible to choose to run only specific test suite or only a
-specific test case within a suite:
+ # Run NFD daemon tests
+ ./build/unit-tests-daemon
- # Run only skeleton test suite (see tests/test-skeleton.cpp)
- ./build/unit-tests -t TestSkeleton
+ # Run NFD RIB management tests
+ ./build/unit-tests-rib
- # Run only test cast Test1 from skeleton suite
- ./build/unit-tests -t TestSkeleton/Test1
+However, [Boost.Test framework](http://www.boost.org/doc/libs/1_48_0/libs/test/doc/html/)
+is very flexible and allows a number of run-time customization of what tests should be run.
+For example, it is possible to choose to run only a specific test suite, only a specific
+test case within a suite, or specific test cases within specific test suites:
-By default, Boost.Test framework will produce verbose output only when
-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:
+ # Run only TCP Face test suite of NFD daemon tests (see tests/daemon/face/tcp.cpp)
+ ./build/unit-tests-daemon -t FaceTcp
- ./build/unit-tests -l all
+ # Run only test case EndToEnd4 from the same test suite
+ ./build/unit-tests-daemon -t FaceTcp/EndToEnd4
+
+ # Run Basic test case from all core test suites
+ ./build/unit-tests-core -t */Basic
+
+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:
+
+ # Show report all log messages including the passed test notification
+ ./build/unit-tests-daemon -l all
+
+ # Show test suite messages
+ ./build/unit-tests-daemon -l test_suite
+
+ # Show nothing
+ ./build/unit-tests-daemon -l nothing
+
+ # Show progress bar
+ ./build/unit-tests-core -p
There are many more command line options available, information about
-which can be obtained either from the command line using ``--help``
-switch, or online on Boost.Test library website
-(http://www.boost.org/doc/libs/1_48_0/libs/test/doc/html/).
+which can be obtained either from the command line using `--help`
+switch, or online on [Boost.Test library](http://www.boost.org/doc/libs/1_48_0/libs/test/doc/html/)
+website.
diff --git a/README.md b/README.md
index dc46009..2501f3b 100644
--- a/README.md
+++ b/README.md
@@ -1,101 +1,31 @@
NFD - Named Data Networking Forwarding Daemon
==============================================================
-## Default Paths
+NFD is the network forwarder that implements the Named Data Networking (NDN)
+[protocol](http://named-data.net/doc/ndn-tlv/) and evolves together with the NDN protocol.
-This README uses `SYSCONFDIR` when referring to the default locations of
-various NFD configuration files. By default, `SYSCONFDIR` is set to
-`/usr/local/etc`. If you override `PREFIX`, then `SYSCONFDIR` will
-default to `PREFIX/etc`.
+The main design goal of NFD development is to support diverse experimention of NDN
+research. The design emphasizes on modularity and extensibility to allow easy experiments
+with new protocol features, new algorithms, and new applications. We have not optimized
+the code for performance, but it can be achieved within the same framework by trying out
+different data structures and algorithms.
-You may override `SYSCONFDIR` and `PREFIX` by specifying their
-corresponding options during installation:
+NFD is open, free, and developed by a community effort. Although most code of this first
+release was done by the NSF-sponsored NDN project team, it also contains significant
+contributions by people outside the project team. We strongly encourage contributions from
+all interested parties, since broader community support is key to NDN’s success as a new
+Internet architecture. Bug reports and feedbacks can be made through
+[Redmine site](http://redmine.named-data.net/projects/nfd) and the
+[ndn-interest mailing list](http://www.lists.cs.ucla.edu/mailman/listinfo/ndn-interest).
- ./waf configure --prefix <path/for/prefix> --sysconfdir <some/other/path>
+The design and development of NFD benefited from our experiences with CCNx. However NFD
+does not maintain compatibility with [CCNx](http://www.ccnx.org).
-Refer to `INSTALL.md` for more detailed instructions on how to compile
-and install NFD.
+Documentation
+-------------
-## Running and Configuring NFD
+For more information refer to
-NFD's runtime settings may be modified via configuration file. After
-installation, a working sample configuration is provided at
-`SYSCONFDIR/ndn/nfd.conf.sample`. At startup, NFD will attempt to
-read the default configuration file location:
-`SYSCONFDIR/ndn/nfd.conf`.
-
-You may also specify an alternative configuration file location
-by running NFD with:
-
- nfd --config </path/to/nfd.conf>
-
-Once again, note that you may simply copy or rename the provided
-sample configuration and have an **almost** fully configured NFD.
-However, this NFD will be unable to add FIB entries or perform
-other typical operation tasks until you authorize an NDN certificate
-with the appropriate privileges.
-
-## Installing an NDN Certificate for Command Authentication
-
-Many NFD management protocols require signed commands to be processed
-(e.g. FIB modification, Face creation/destructions, etc.). You will
-need an NDN certificate to use any application that issues signed
-commands.
-
-If you do not already have NDN certificate, you can generate one with
-the following commands:
-
-**Generate and install a self-signed identity certificate**:
-
- ndnsec-keygen /`whoami` | ndnsec-install-cert -
-
-Note that the argument to ndnsec-key will be the identity name of the
-new key (in this case, `/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**:
-
-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`).
-
- 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
-
-## Running NFD with 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:
-
-**Ubuntu:**
-
- sudo apt-get install libcap2-bin
-
-**Mac OS X:**
-
- curl https://bugs.wireshark.org/bugzilla/attachment.cgi?id=3373 -o ChmodBPF.tar.gz
- tar zxvf ChmodBPF.tar.gz
- open ChmodBPF/Install\ ChmodBPF.app
-
-or manually:
-
- sudo chgrp admin /dev/bpf*
- sudo chmod g+rw /dev/bpf*
-
-## 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:
-
- sudo setcap cap_net_raw=eip /full/path/nfd
+* [Installation instruction `docs/INSTALL.rst`](https://github.com/named-data/NFD/blob/master/docs/INSTALL.rst),
+* [Hints on configuration `docs/README.rst`](https://github.com/named-data/NFD/blob/master/docs/README.rst)
+* Other documentation in [`docs/`](https://github.com/named-data/NFD/blob/master/docs) folder.
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
new file mode 100644
index 0000000..2c74157
--- /dev/null
+++ b/docs/INSTALL.rst
@@ -0,0 +1,109 @@
+.. _NFD Installation Instructions:
+
+NFD Installation Instructions
+=============================
+
+Prerequisites
+-------------
+
+- `ndn-cpp-dev library <https://github.com/named-data/ndn-cpp-dev>`__
+ and its requirements:
+
+ - ``libcrypto``
+ - ``libsqlite3``
+ - ``libcrypto++``
+ - ``pkg-config``
+ - Boost libraries (>= 1.48)
+ - OSX Security framework (on OSX platform only)
+
+ Refer to https://github.com/named-data/ndn-cpp-dev/blob/master/INSTALL.md for detailed
+ installation instructions.
+
+- ``libpcap``
+
+ Comes with base on OS X 10.8 and 10.9:
+
+ On Ubuntu >= 12.04:
+
+ ::
+
+ sudo apt-get install libpcap-dev
+
+To build manpages and API documentation:
+
+- ``doxygen``
+- ``graphviz``
+- ``python-sphinx``
+
+ On OS X 10.8 and 10.9 with macports:
+
+ ::
+
+ sudo port install doxygen graphviz py27-sphinx sphinx_select
+ sudo port select sphinx py27-sphinx
+
+ On Ubuntu >= 12.04:
+
+ ::
+
+ sudo apt-get install doxygen graphviz python-sphinx
+
+Build
+-----
+
+The following commands should be used to build NFD:
+
+::
+
+ ./waf configure
+ ./waf
+ sudo ./waf install
+
+Refer to :ref:`NFD Configuration Tips` (``README.rst``) for more options that can be used
+during ``configure`` stage and how to properly configure and run NFD.
+
+In some configurations, configuration step may require small modification. For example, on
+OSX that uses macports (correct the path if macports was not installed in the default path
+``/opt/local``):
+
+::
+
+ export PKG_CONFIG_PATH=/opt/local/lib/pkgconfig:/usr/local/lib/pkgconfig:/usr/lib/pkgconfig:$PKG_CONFIG_PATH
+ ./waf configure
+ ./waf
+ sudo ./waf install
+
+On some Linux distributions (e.g., Fedora 20):
+
+::
+
+ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/lib/pkgconfig:/usr/lib64/pkgconfig:$PKG_CONFIG_PATH
+ ./waf configure
+ ./waf
+ sudo ./waf install
+
+Building documentation
+----------------------
+
+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`
+ ./waf sphinx
+
+ # Only API docs in `build/docs/doxygen`
+ ./waf doxgyen
+
+
+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``.
diff --git a/docs/README.rst b/docs/README.rst
new file mode 100644
index 0000000..7788bb5
--- /dev/null
+++ b/docs/README.rst
@@ -0,0 +1,124 @@
+.. _NFD Configuration Tips:
+
+NFD - Named Data Networking Forwarding Daemon
+=============================================
+
+Default Paths
+-------------
+
+This document uses ``SYSCONFDIR`` when referring to the default locations
+of various NFD configuration files. By default, ``SYSCONFDIR`` is set to
+``/usr/local/etc``. If you override ``PREFIX``, then ``SYSCONFDIR`` will
+default to ``PREFIX/etc``.
+
+You may override ``SYSCONFDIR`` and ``PREFIX`` by specifying their
+corresponding options during installation:
+
+::
+
+ ./waf configure --prefix <path/for/prefix> --sysconfdir <some/other/path>
+
+Refer to :ref:`NFD Installation Instructions` for more detailed instructions on how to compile
+and install NFD.
+
+Running and Configuring NFD
+---------------------------
+
+NFD's runtime settings may be modified via configuration file. After
+installation, a working sample configuration is provided at
+``SYSCONFDIR/ndn/nfd.conf.sample``. At startup, NFD will attempt to read
+the default configuration file location: ``SYSCONFDIR/ndn/nfd.conf``.
+
+You may also specify an alternative configuration file location by
+running NFD with:
+
+::
+
+ nfd --config </path/to/nfd.conf>
+
+Once again, note that you may simply copy or rename the provided sample
+configuration and have an **almost** fully configured NFD. However, this
+NFD will be unable to add FIB entries or perform other typical operation
+tasks until you authorize an NDN certificate with the appropriate
+privileges.
+
+Installing an NDN Certificate for Command Authentication
+--------------------------------------------------------
+
+Many NFD management protocols require signed commands to be processed
+(e.g. FIB modification, Face creation/destructions, etc.). You will need
+an NDN certificate to use any application that issues signed commands.
+
+If you do not already have NDN certificate, you can generate one with
+the following commands:
+
+**Generate and install a self-signed identity certificate**:
+
+::
+
+ ndnsec-keygen /`whoami` | ndnsec-install-cert -
+
+Note that the argument to ndnsec-key will be the identity name of the
+new key (in this case, ``/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**:
+
+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``).
+
+::
+
+ 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
+
+Running NFD with 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:
+
+**Ubuntu:**
+
+::
+
+ sudo apt-get install libcap2-bin
+
+**Mac OS X:**
+
+::
+
+ curl https://bugs.wireshark.org/bugzilla/attachment.cgi?id=3373 -o ChmodBPF.tar.gz
+ tar zxvf ChmodBPF.tar.gz
+ open ChmodBPF/Install\ ChmodBPF.app
+
+or manually:
+
+::
+
+ sudo chgrp admin /dev/bpf*
+ sudo chmod g+rw /dev/bpf*
+
+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:
+
+::
+
+ sudo setcap cap_net_raw=eip /full/path/nfd
diff --git a/docs/index.rst b/docs/index.rst
index 6bc1fff..385a657 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,9 +1,11 @@
NFD - Named Data Networking Forwarding Daemon's documentation
=============================================================
-Contents:
-
.. toctree::
release_notes
+ Installation Instruction <INSTALL>
+ NFD Configuration Tips <README>
manpages
- :maxdepth: 2
+ :maxdepth: 1
+
+* `API documentation (doxygen) <doxygen/annotated.html>`_
diff --git a/docs/manpages.rst b/docs/manpages.rst
index ff5630a..9690f11 100644
--- a/docs/manpages.rst
+++ b/docs/manpages.rst
@@ -6,3 +6,4 @@
manpages/nrd
manpages/ndn-autoconfig
manpages/ndn-autoconfig-server
+ :maxdepth: 1
diff --git a/docs/named_data_theme/static/base.css_t b/docs/named_data_theme/static/base.css_t
index 93fa4e1..ea6938e 100644
--- a/docs/named_data_theme/static/base.css_t
+++ b/docs/named_data_theme/static/base.css_t
@@ -17,7 +17,7 @@
/* Page layout */
div.header, div.content, div.footer {
- width: {{ theme_pagewidth }};
+ width: 90%;
margin-left: auto;
margin-right: auto;
}
@@ -159,13 +159,13 @@
}
div.document {
- width: {{ theme_documentwidth }};
+ width: 70%;
float: left;
}
div.body {
padding-right: 2em;
- text-align: {{ theme_textalign }};
+ text-align: left;
}
div.document h1 {
@@ -236,7 +236,7 @@
/* Sidebar */
div.sidebar {
- width: {{ theme_sidebarwidth }};
+ width: 20%;
float: right;
font-size: .9em;
}
@@ -453,3 +453,11 @@
border-top: 1px solid #ac9;
border-bottom: 1px solid #ac9;
}
+
+td.linenos pre {
+ padding: 5px 0px;
+ border: 0;
+ background-color: transparent;
+ color: #aaa;
+ margin-top: -10pt;
+}
\ No newline at end of file
diff --git a/docs/named_data_theme/static/named_data_style.css_t b/docs/named_data_theme/static/named_data_style.css_t
index 0d00020..f37be7f 100644
--- a/docs/named_data_theme/static/named_data_style.css_t
+++ b/docs/named_data_theme/static/named_data_style.css_t
@@ -10,7 +10,7 @@
padding: 10px;
background-color: #fafafa;
color: #222;
- line-height: 1.0em;
+ /* line-height: 1.0em; */
border: 2px solid #C6C9CB;
font-size: 0.9em;
/* margin: 1.5em 0 1.5em 0; */
diff --git a/docs/named_data_theme/theme.conf b/docs/named_data_theme/theme.conf
index 1dab97e..aa5a7ff 100644
--- a/docs/named_data_theme/theme.conf
+++ b/docs/named_data_theme/theme.conf
@@ -6,6 +6,9 @@
theme_bodyfont = "normal 12px Verdana, sans-serif"
theme_bgcolor = "#ccc"
+theme_documentwidth = "100%"
+theme_textalign = "left"
+
[options]
stickysidebar = true
diff --git a/wscript b/wscript
index 1a2bdb3..61bc03f 100644
--- a/wscript
+++ b/wscript
@@ -182,6 +182,10 @@
source=bld.path.ant_glob('docs/manpages/**/*.rst'),
install_path="${MANDIR}/")
+def docs(bld):
+ from waflib import Options
+ Options.commands = ['doxygen', 'sphinx'] + Options.commands
+
def doxygen(bld):
if not bld.env.DOXYGEN:
bld.fatal("ERROR: cannot build documentation (`doxygen' is not found in $PATH)")