docs: update README and add RELEASE NOTES
Change-Id: Ifb79bda4d8cddc8002e244a090723c284c49a2c9
Refs: #1439
diff --git a/.waf-tools/sphinx_build.py b/.waf-tools/sphinx_build.py
index 09f67f8..bd3905b 100644
--- a/.waf-tools/sphinx_build.py
+++ b/.waf-tools/sphinx_build.py
@@ -1,13 +1,14 @@
#!/usr/bin/env python
# encoding: utf-8
-# Hans-Martin von Gaudecker, 2012
+
+# inspired by code by Hans-Martin von Gaudecker, 2012
import os
from waflib import Node, Task, TaskGen, Errors, Logs, Build, Utils
class sphinx_build(Task.Task):
color = 'BLUE'
- run_str = '${SPHINX_BUILD} -q -b ${BUILDERNAME} -d ${DOCTREEDIR} ${SRCDIR} ${OUTDIR}'
+ run_str = '${SPHINX_BUILD} -D ${VERSION} -D ${RELEASE} -q -b ${BUILDERNAME} -d ${DOCTREEDIR} ${SRCDIR} ${OUTDIR}'
def __str__(self):
env = self.env
@@ -52,6 +53,8 @@
task.env['SRCDIR'] = srcdir
task.env['DOCTREEDIR'] = doctreedir
task.env['OUTDIR'] = outdir.abspath()
+ task.env['VERSION'] = "version=%s" % self.VERSION
+ task.env['RELEASE'] = "release=%s" % self.VERSION
import imp
confData = imp.load_source('sphinx_conf', conf.abspath())
diff --git a/README.md b/README.md
index 2501f3b..ecc1d72 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,50 @@
NFD - Named Data Networking Forwarding Daemon
-==============================================================
+=============================================
-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.
+NFD is a network forwarder that implements and evolves together with the Named Data
+Networking (NDN) [protocol](http://named-data.net/doc/ndn-tlv/). After the initial
+release, NFD will become a core component of the
+[NDN Platform](http://named-data.net/codebase/platform/) and will follow the same release
+cycle.
-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.
+NFD is an open and free software package licensed under GPL 3.0 license and is the
+centerpiece of our committement to making NDN's core technology open and free to all
+Internet users and developers. For more information about the licensing details and
+limitation, refer to
+[`COPYING.md`](https://github.com/named-data/NFD/blob/master/COPYING.md).
-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
+NFD is developed by a community effort. Although the first release was mostly done by the
+members of [NSF-sponsored NDN project team](http://named-data.net/project/participants/),
+it already contains significant contributions from people outside the project team (for
+more details, refer to [`AUTHORS.md`](https://github.com/named-data/NFD/blob/master/AUTHORS.md)).
+We strongly encourage participation from all interested parties, since broader community
+support is key for NDN to succeed as a new Internet architecture. Bug reports and
+feedback are highly appreciated and 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).
-The design and development of NFD benefited from our experiences with CCNx. However NFD
-does not maintain compatibility with [CCNx](http://www.ccnx.org).
+The main design goal of NFD is to support diverse experimentation of NDN technology. The
+design emphasizes *modularity* and *extensibility* to allow easy experiments with new
+protocol features, algorithms, new applications. We have not fully optimized the code for
+performance. The intention is that performance optimizations are one type of experiments
+that developers can conduct by trying out different data structures and different
+algorithms; over time, better implementations may emerge within the same design framework.
+
+NFD will keep evolving in three aspects: improvement of the modularity framework, keeping
+up with the NDN protocol spec, and addition of other new features. We hope to keep the
+modular framework stable and lean, allowing researchers to implement and experiment
+with various features, some of which may eventually work into the protocol spec.
+
+The design and development of NFD benefited from our earlier experience with
+[CCNx](http://www.ccnx.org) software package. However, NFD is not in any part derived from
+CCNx codebase and does not maintain compatibility with CCNx.
Documentation
-------------
For more information refer to
-* [Installation instruction `docs/INSTALL.rst`](https://github.com/named-data/NFD/blob/master/docs/INSTALL.rst),
+* [Release notes `docs/RELEASE_NOTES.rst`](https://github.com/named-data/NFD/blob/master/docs/RELEASE_NOTES.rst)
+* [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.
+* Other documentation in [`docs/`](https://github.com/named-data/NFD/blob/master/docs) folder
diff --git a/docs/RELEASE_NOTES.rst b/docs/RELEASE_NOTES.rst
new file mode 100644
index 0000000..1f3f282
--- /dev/null
+++ b/docs/RELEASE_NOTES.rst
@@ -0,0 +1,144 @@
+.. _NFD v0.1.0 Release Notes:
+
+NFD v0.1.0 Release Notes
+========================
+
+Major Modules of NFD
+--------------------
+
+NFD has the following major modules:
+
+- Core
+ Provides various common services shared between different NFD modules. These include
+ hash computation routines, DNS resolver, config file, face monitoring, and
+ several other modules.
+
+- Faces
+ Implements the NDN face abstraction on top of different lower level transport
+ mechanisms.
+
+- Tables
+ Implements the Content Store (CS), the Pending Interest Table (PIT), the Forwarding
+ Information Base (FIB), and other data structures to support forwarding of NDN Data
+ and Interest packets.
+
+- Forwarding
+ Implements basic packet processing pathways, which interact with Faces, Tables,
+ and Strategies.
+
+ + **Strategy Support**, a major part of the forwarding module
+ Implements a framework to support different forwarding strategies. It includes
+ StrategyChoice, Measurements, Strategies, and hooks in the forwarding pipelines. The
+ StrategyChoice records the choice of the strategy for a namespace, and Measurement
+ records are used by strategies to store past performance results for namespaces.
+
+- Management
+ Implements the `NFD Management Protocol
+ <http://redmine.named-data.net/projects/nfd/wiki/Management>`_, which allows
+ applications to configure NFD and set/query NFD's internal states. Protocol interaction
+ is done via NDN's Interest/Data exchange between applications and NFD.
+
+- RIB Management
+ Manages the routing information base (RIB). The RIB may be updated by different parties
+ in different ways, including various routing protocols, application's prefix
+ registrations, and command-line manipulation by sysadmins. The RIB management module
+ processes all these requests to generate a consistent forwarding table, and then syncs
+ it up with the NFD's FIB, which contains only the minimal information needed for
+ forwarding decisions. Strictly speaking RIB management is part of the NFD management
+ module. However, due to its importance to the overall operations and its more complex
+ processing, we make it a separate module.
+
+Features in Version 0.1.0
+-------------------------
+
+This is an incomplete list of features that are implemented in NFD version 0.1.0.
+
+- Packet Format
+
+ + `NDN-TLV <http://named-data.net/doc/ndn-tlv/>`_
+ + LocalControlHeader, to allow apps to set outgoing face and learn incoming face.
+
+- Faces
+
+ + Unix stream socket
+ + UDP unicast
+ + UDP multicast
+ + TCP
+ + Ethernet, currently without fragmentation.
+
+ .. note::
+ Ethernet support will not work properly on Linux kernels with TPACKET_V3 flexible
+ buffer implementation (>= 3.2.0) and libpcap >= 1.5.0 (e.g., Ubuntu Linux 14.04).
+ Refer to `Issue 1551 <http://redmine.named-data.net/issues/1511>`_ for more
+ detail and implementation progress.
+
+- Management
+
+ + Use of signed Interests as commands, with authentication and authorization.
+ + Face management
+ + FIB management
+ + Per-namespace strategy selection
+ + NFD status publishing
+ + Notification to authorized apps of internal events, including Face creation and destruction.
+
+- Tables and forwarding pipelines support most Interest/Data processing, including
+ selectors.
+
+- RIB Management that runs as a separate process, ``nrd``. It supports basic prefix
+ registration by applications, but no flags yet.
+
+- Strategies
+
+ + ``broadcast``
+ + ``best-route``
+ + ``ncc``: based on ccnx 0.7 for experimentation
+ + ``client-control``: authorized application can directly control Interest forwarding
+
+- Name-based scoping
+
+ + ``/localhost``: communication only within localhost using "local" Faces
+ (UnixStreamFace, LocalTcpFace). NFD will strictly enforce this scope for Interests
+ and Data packets
+ + ``/localhop``: one-hop communication (e.g., if at least one incoming or outgoing Face
+ in PIT entry is non-local, the Interest cannot be forwarded to any non-local Face)
+
+- Support configuration file, which is in the Boost INFO format.
+
+- Applications
+
+ + Tools to discover hubs on NDN testbed.
+ + peek/poke and traffic generators for testing and debugging.
+ + ``nfdc``, a command-line tool to configure NFD.
+ + ``nfd-status``, a command-line tool to query NFD status.
+ + ``nfd-status-http-server``, which reads the NFD status and publishes over HTTP.
+
+
+Planned Functions and Features for Next Releases
+------------------------------------------------
+
+- NACK
+ A packet sent back by a producer or a router to signal the unavailability of a requested
+ Data packet. The protocol specification for NACK is in progress.
+
+- New strategies
+ Additional strategies, including self-learning that populates the FIB by observing
+ Interest and Data exchange.
+
+- Hop-by-hop Interest limit mechanism for congestion control.
+
+- Face enhancements
+ Add fragmentation support for Ethernet face, may add support for new types such as
+ WiFi direct and WebSockets.
+
+- Tables
+ Experiment and evaluate different data structures and algorithms.
+
+- RIB management
+ Move to more scalable data structures and support all flags in prefix registrations.
+
+- Tunnel management
+ For hub nodes to authenticate incoming tunnel requests and maintain the tunnels.
+
+- Extensible name-based scoping
+
+ + configurable organization-based scoping
diff --git a/docs/conf.py b/docs/conf.py
index 849997c..4a4ab93 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -51,11 +51,6 @@
# 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 short X.Y version.
-version = '0.1.0'
-# The full version, including alpha/beta/rc tags.
-release = '0.1.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/doxygen.conf b/docs/doxygen.conf.in
similarity index 99%
rename from docs/doxygen.conf
rename to docs/doxygen.conf.in
index a6a9a38..49a9994 100644
--- a/docs/doxygen.conf
+++ b/docs/doxygen.conf.in
@@ -32,13 +32,13 @@
# title of most generated pages and in a few other places.
# The default value is: My Project.
-PROJECT_NAME = "NFD: Named Data Network Forwarding Daemon"
+PROJECT_NAME = "NFD - Named Data Networking Forwarding Daemon"
# 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
# control system is used.
-PROJECT_NUMBER =
+PROJECT_NUMBER = @VERSION@
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
diff --git a/docs/index.rst b/docs/index.rst
index 385a657..0f76bcb 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,11 +1,80 @@
-NFD - Named Data Networking Forwarding Daemon's documentation
-=============================================================
+NFD - Named Data Networking Forwarding Daemon
+=============================================
+
+NFD is a network forwarder that implements and evolves together with the Named Data
+Networking (NDN) `protocol <http://named-data.net/doc/ndn-tlv/>`__. After the initial
+release, NFD will become a core component of the `NDN Platform
+<http://named-data.net/codebase/platform/>`__ and will follow the same release cycle.
+
+NFD is developed by a community effort. Although the first release was mostly done by the
+members of `NSF-sponsored NDN project team
+<http://named-data.net/project/participants/>`__, it already contains significant
+contributions from people outside the project team (for more details, refer to `AUTHORS.md
+<https://github.com/named-data/NFD/blob/master/AUTHORS.md>`__). We strongly encourage
+participation from all interested parties, since broader community support is key for NDN
+to succeed as a new Internet architecture. Bug reports and feedback are highly
+appreciated and 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>`__.
+
+The main design goal of NFD is to support diverse experimentation of NDN technology. The
+design emphasizes *modularity* and *extensibility* to allow easy experiments with new
+protocol features, algorithms, and applications. We have not fully optimized the code for
+performance. The intention is that performance optimizations are one type of experiments
+that developers can conduct by trying out different data structures and different
+algorithms; over time, better implementations may emerge within the same design framework.
+
+NFD will keep evolving in three aspects: improvement of the modularity framework, keeping
+up with the NDN protocol spec, and addition of other new features. We hope to keep the
+modular framework stable and lean, allowing researchers to implement and experiment
+with various features, some of which may eventually work into the protocol spec.
+
+The design and development of NFD benefited from our earlier experience with `CCNx
+<http://www.ccnx.org>`__ software package. However, NFD is not in any part derived from
+CCNx codebase and does not maintain compatibility with CCNx.
+
+Downloading
+-----------
+
+NFD code can be downloaded from `GitHub git repository <https://github.com/named-data/NFD>`_.
+
+Refer to :ref:`NFD Installation Instructions` for detailed guide on how to install NFD
+from source.
+
+NFD Documentation
+-----------------
.. toctree::
- release_notes
+ :hidden:
+ :maxdepth: 2
+
+ RELEASE_NOTES
Installation Instruction <INSTALL>
NFD Configuration Tips <README>
manpages
- :maxdepth: 1
+
+
+
+* :ref:`NFD v0.1.0 Release Notes`
+
+* :ref:`NFD Installation Instructions`
+
+* :ref:`NFD Configuration Tips`
+
+* :ref:`Manpages`
+
+* `NFD Wiki <http://redmine.named-data.net/projects/nfd/wiki>`_
+
+ + `NFD Management protocol <http://redmine.named-data.net/projects/nfd/wiki/Management>`_
+ + `NFD Configuration file format <http://redmine.named-data.net/projects/nfd/wiki/ConfigFileFormat>`_
* `API documentation (doxygen) <doxygen/annotated.html>`_
+
+
+License
+-------
+
+NFD is an open and free software package licensed under GPL 3.0 license and is the
+centerpiece of our committement to making NDN's core technology open and free to all
+Internet users and developers. For more information about the licensing details and
+limitation, refer to `COPYING.md <https://github.com/named-data/NFD/blob/master/COPYING.md>`_.
diff --git a/docs/manpages.rst b/docs/manpages.rst
index 5e1530b..3b8a496 100644
--- a/docs/manpages.rst
+++ b/docs/manpages.rst
@@ -1,5 +1,7 @@
-NFD Manpages
-============
+.. _Manpages:
+
+Manpages
+========
.. toctree::
manpages/nfd
diff --git a/docs/named_data_theme/layout.html b/docs/named_data_theme/layout.html
index 0dc8b44..520b853 100644
--- a/docs/named_data_theme/layout.html
+++ b/docs/named_data_theme/layout.html
@@ -36,7 +36,13 @@
<div class="sidebar">
{%- block sidebartoc %}
<h3>{{ _('Table Of Contents') }}</h3>
- {{ toctree() }}
+ {{ toctree(includehidden=True) }}
+
+ <h3>{{ _('Additional documenation') }}</h3>
+ <ul>
+ <li class="toctree-l1"><a class="reference external" href="http://redmine.named-data.net/projects/nfd/wiki">NFD Wiki</a></li>
+ <li class="toctree-l1"><a class="reference internal" href="doxygen/annotated.html">API documentation (doxygen)</a></li>
+ </ul>
{%- endblock %}
{%- block sidebarsearch %}
<h3 style="margin-top: 1.5em;">{{ _('Search') }}</h3>
diff --git a/docs/named_data_theme/named_data_header.html b/docs/named_data_theme/named_data_header.html
index d9cb50b..97b2932 100644
--- a/docs/named_data_theme/named_data_header.html
+++ b/docs/named_data_theme/named_data_header.html
@@ -32,7 +32,7 @@
<!--top menu-->
<div class="nine columns" id="menu_container" >
- <h1><a href="#">$projectname documentation</a></h1>
+ <h1><a href="http://named-data.net/doc/NFD/$projectnumber/">$projectname $projectnumber documentation</a></h1>
</div>
</div>
</div><!--header container end-->
diff --git a/docs/named_data_theme/static/base.css_t b/docs/named_data_theme/static/base.css_t
index ea6938e..eed3973 100644
--- a/docs/named_data_theme/static/base.css_t
+++ b/docs/named_data_theme/static/base.css_t
@@ -173,7 +173,7 @@
}
div.document ul {
- margin: 1.5em;
+ margin-left: 1.5em;
list-style-type: square;
}
@@ -224,10 +224,6 @@
padding: 0px;
}
-div.document blockquote {
- margin: 1em;
-}
-
div.document ol {
margin: 1.5em;
}
diff --git a/docs/named_data_theme/static/foundation.css b/docs/named_data_theme/static/foundation.css
index 91ad40c..ff1330e 100644
--- a/docs/named_data_theme/static/foundation.css
+++ b/docs/named_data_theme/static/foundation.css
@@ -123,10 +123,10 @@
ol li ul, ol li ol { margin-left: 20px; margin-bottom: 0; }
/* Blockquotes ---------------------- */
-blockquote, blockquote p { line-height: 1.5; color: #6f6f6f; }
+blockquote, blockquote p { line-height: 1.5; }
-blockquote { margin: 0 0 17px; padding: 9px 20px 0 19px; border-left: 1px solid #ddd; }
-blockquote cite { display: block; font-size: 13px; color: #555555; }
+blockquote { margin: 0 0 17px; padding: 9px 20px 0 19px; }
+blockquote cite { display: block; font-size: 13pt; color: #555555; }
blockquote cite:before { content: "\2014 \0020"; }
blockquote cite a, blockquote cite a:visited { color: #555555; }
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 f37be7f..c1f02f9 100644
--- a/docs/named_data_theme/static/named_data_style.css_t
+++ b/docs/named_data_theme/static/named_data_style.css_t
@@ -66,7 +66,7 @@
}
p {
- padding: 0 0 0.5em;
+ padding: 0;
line-height:1.6em;
}
ul {
@@ -124,7 +124,6 @@
color: #555;
}
blockquote {
- font-style: italic;
padding: 0 3em;
}
blockquote cite,
@@ -803,3 +802,12 @@
margin-left:auto;
margin-right:auto;
}
+
+
+table {
+ border-collapse:collapse;
+}
+table, th, td {
+ border: 1px solid black;
+ padding: 5px;
+}
\ No newline at end of file
diff --git a/docs/release_notes.rst b/docs/release_notes.rst
deleted file mode 100644
index 6cc8005..0000000
--- a/docs/release_notes.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-Release Notes
-=============
diff --git a/wscript b/wscript
index 6aa342d..5b37759 100644
--- a/wscript
+++ b/wscript
@@ -23,7 +23,10 @@
NFD, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
"""
-VERSION = '0.1.0'
+import re
+
+VERSION = re.search('^#define NFD_VERSION_STRING\\s+"(.*)"',
+ open("version.hpp").read(), re.M).group(1)
APPNAME = "nfd"
BUGREPORT = "http://redmine.named-data.net/projects/nfd"
URL = "https://github.com/named-data/NFD"
@@ -54,15 +57,10 @@
dest='with_other_tests', help='''Build other tests''')
def configure(conf):
- conf.load("compiler_cxx boost gnu_dirs sphinx_build")
-
- try: conf.load("doxygen")
- except: pass
-
- try: conf.load("sphinx_build")
- except: pass
-
- conf.load('default-compiler-flags')
+ conf.load(['compiler_cxx', 'gnu_dirs',
+ 'default-compiler-flags',
+ 'boost', 'dependency-checker',
+ 'doxygen', 'sphinx_build'])
conf.check_cfg(package='libndn-cxx', args=['--cflags', '--libs'],
uselib_store='NDN_CXX', mandatory=True)
@@ -180,7 +178,8 @@
outdir="docs/manpages",
config="docs/conf.py",
source=bld.path.ant_glob('docs/manpages/**/*.rst'),
- install_path="${MANDIR}/")
+ install_path="${MANDIR}/",
+ VERSION=VERSION)
for script in bld.path.ant_glob('tools/*.sh'):
bld(features='subst',
@@ -195,14 +194,25 @@
def doxygen(bld):
if not bld.env.DOXYGEN:
- bld.fatal("ERROR: cannot build documentation (`doxygen' is not found in $PATH)")
- bld(features="doxygen",
- doxyfile='docs/doxygen.conf',
- install_path=None)
+ Logs.error("ERROR: cannot build documentation (`doxygen' is not found in $PATH)")
+ else:
+ bld(features="subst",
+ name="doxygen-conf",
+ source="docs/doxygen.conf.in",
+ target="docs/doxygen.conf",
+ VERSION=VERSION,
+ )
+
+ bld(features="doxygen",
+ doxyfile='docs/doxygen.conf',
+ use="doxygen-conf")
def sphinx(bld):
- bld(features="sphinx",
- outdir="docs",
- source=bld.path.ant_glob('docs/**/*.rst'),
- config="docs/conf.py",
- install_path=None)
+ if not bld.env.SPHINX_BUILD:
+ bld.fatal("ERROR: cannot build documentation (`sphinx-build' is not found in $PATH)")
+ else:
+ bld(features="sphinx",
+ outdir="docs",
+ source=bld.path.ant_glob('docs/**/*.rst'),
+ config="docs/conf.py",
+ VERSION=VERSION)