README-dev.md

Notes for ndn-tools developers

Licensing Requirements

Contributions to ndn-tools must be licensed under the GPL v3 or a compatible license. If you choose the GPL v3, please use the following license boilerplate in all .hpp and .cpp files:

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) [Year(s)], [Copyright Holder(s)].
 *
 * This file is part of ndn-tools (Named Data Networking Essential Tools).
 * See AUTHORS.md for complete list of ndn-tools authors and contributors.
 *
 * ndn-tools is free software: you can redistribute it and/or modify it under the terms
 * of the GNU General Public License as published by the Free Software Foundation,
 * either version 3 of the License, or (at your option) any later version.
 *
 * ndn-tools is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 * PURPOSE.  See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * ndn-tools, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
 */

Directory Structure and Build Script

All tools are placed in subdirectories of the tools directory.

A tool can consist of one or more programs. For instance, a pair of consumer and producer programs that are designed to work together should be considered a single tool, not two separate tools.

Each tool must have a wscript build script in its subdirectory. This script will be invoked automatically if the corresponding tool is selected for the build. It should compile the source code and produce one or more binaries in the build/bin directory (e.g., use target='../../bin/foo').

Shared Modules

Modules shared among multiple tools should be placed in the core directory. They are available for use in all tools.

A header in core/ can be included in a tool like #include "core/foo.hpp".

The wscript of a tool can link a program with modules in core/ with use='core-objects'.

Documentation

A file named README.md in the subdirectory of each tool should provide a brief description.

Manual pages for each program should be written in reStructuredText format and placed in the manpages directory.

Code Guidelines

C++ code should conform to the ndn-cxx code style.

Namespace

Types in each tool should be declared in a sub-namespace inside namespace ndn. For example, a tool in tools/foo directory has namespace ndn::foo. This allows the tool to reference ndn-cxx types with unqualified name lookup. This also prevents name conflicts between ndn-cxx and tools.

Types in core/ should be declared directly inside namespace ndn, or in a sub-namespace if desired.

main Function

The main function of a program should be declared as a static function in the namespace of the corresponding tool. This allows referencing types in ndn-cxx and the tool via unqualified name lookup.

Then, another (non-static) main function must be defined in the global namespace, and from there call the main function in the tool namespace.

These two functions should appear in a file named main.cpp in the tool's subdirectory.

Example:

namespace ndn {
namespace foo {

class Bar
{
public:
  explicit
  Bar(Face& face);

  void
  run();
};

static int
main(int argc, char* argv[])
{
  Face face;
  Bar program(face);
  program.run();
  return 0;
}

} // namespace foo
} // namespace ndn

int
main(int argc, char* argv[])
{
  return ndn::foo::main(argc, argv);
}

Command Line Arguments

Boost.Program_options is strongly preferred over getopt(3) for parsing command line arguments.