Difference between revisions of "App Store Technical Requirements"

From Nsnam
Jump to: navigation, search
(API and work flow)
(update app store requirements)
 
(44 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{TOC}}
 
{{TOC}}
  
 +
= Background =
 +
 +
The goal is to support modularization of the ns-3 code base and federation of development activities.  To date, the main path to distributing extensions to ns-3 has been to request a code review for merge to the mainline tree.  The future goal is to shrink the ns-3 core, and to better facilitate modules that are independently developed and maintained.  As a concrete example, the [https://www.r-project.org/ R statistical framework] does not integrate every extension to its main release; instead, it allows users to [https://cran.cnr.berkeley.edu/web/packages/available_packages_by_date.html fetch the packages of interest] and add to their installation.  Communities-of-interest have even arisen to allow researchers to organize and curate sets of R extensions (e.g. [https://www.bioconductor.org/ bioinformatic packages]).  We envision the same for ns-3.
 +
 +
In the ns-3.27 release, the bake build orchestration tool was extended to allow third party contributed code modules to be added to ns-3, and to be downloaded, built, and installed with the main ns-3 release.  This allows modules to be hosted elsewhere and integrated with the ns-3-allinone framework.  Consider this to be the back-end support for modularization.  We have not gone further since that time.
 +
 +
For example, the sift routing code contribution has been added as a module.  Please review how users are expected to add sift to their ns-3.27 release [[BakeIntegration | on this wiki page]].
 +
 +
There are two main components:
 +
 +
1) '''front end''' The ns-3 app store (https://apps.nsnam.org) is largely operational and will be put into actual use for ns-3.29.  The app store can be used to directly download contributed modules, and to post information about the module.
 +
 +
2) '''back end''' The back end will be the [https://www.nsnam.org/docs/bake/tutorial/html/bake-over.html bake build orchestration tool].
 +
 +
= Workflows =
 +
 +
We envision three types of users:
 +
 +
#. '''End user:'''  The normal user will browse to the app store to learn about available apps, learn about resources (user forums, documentation) about each app, and possibly leave feedback on a review board.  The normal user will obtain the necessary information to fetch and install each app from this page.
 +
#. '''Developer:'''  Developers will not be able to create new apps on the app store, but will be able to edit the app page that he or she owns. To make an app available on the store, it has to go through an ns-3 review process.
 +
#. '''Maintainer:''' ns-3 maintainers will create a new page for an accepted app, and create a developer account for the author. Then the developer will be able to edit the page to suit their app.
 +
 
 
= Requirements =
 
= Requirements =
 +
The following requirements were used to develop the app store (https://apps.nsnam.org).
 +
 +
#. The front page should be clean, consisting of categories, newest releases, and popular downloads.
 +
#. Each "app" will be an ns-3 module, with a description page including:  Description, screenshots (optional),  download tab, resources tab, etc.
 +
#. Clear documentation must be posted on how to use the app store, and how to submit a new app to the app store
 +
#. The "Download" tab will fetch a source archive, and the user will download to a location of their choice.  The user is responsible for moving or copying the package to their ns-3 development directory, and then the ns-3 build tools (invoked at command line by users in the normal way) will do the rest.
 +
#. XML for the bake configuration will also be maintained for each module, allowing module contributors to post new releases of their module.
 +
 +
= Enhancements =
 +
 +
Once the basic capability is deployed, enhancements are possible.  Some of these extensions may involve modifying the app store installation, but some will involve modifying ns-3 build scripts, documentation, and other scripts (e.g. Jenkins scripts).
 +
 +
== Integration with bake ==
 +
 +
Bake uses XML to describe modules.  It would be nice to have a standardized XML schema that describes an ns-3 module, and make it usable from both the app store and from bake.  For instance, there could be an "authors" field in the XML description that can be displayed by bake at the command line and can also be parsed and shown as the Authors in the app store description.
 +
 +
== User feedback and comments ==
 +
 +
We probably want to explore and tailor the capability for users to provide feedback and hints about apps.  We do not want the capability to be abused by spammers (e.g. a captcha?).
 +
 +
== Documentation and module creation scripts ==
 +
 +
* Doxygen and Sphinx scripts should be modified to allow building on a per-module basis; ns-3 web site should still integrate all of these module documentations coherently
 +
* The create-module.py program should be updated
 +
* The ns-3 tutorial must be updated
 +
 +
== Regression testing ==
 +
 +
We need to write some new [https://ns-buildmaster.ee.washington.edu:8010/ Jenkins scripts] to test the known modules for regressions.
 +
 +
== Versioning ==
 +
 +
Managing the version numbers of different apps will be necessary.  We want users to be able to declare that apps are compatible with specific ns-3 versions.
 +
 +
== Patch management ==
 +
 +
Apps may fall out of date (become unmaintained) but it may be the case that some simple patches could be applied on top of them to make them workable again with the latest ns-3.  The framework should support the ability to declare that a module installation consists of downloading an archive and then patching it with a file fetched from elsewhere.  A module may also require patching of ns-3 core itself; the framework should support this.
 +
 +
== Dependency management ==
 +
 +
If some modules depend on other modules or system dependencies, that needs to be expressed and handled by the tools.  This is mainly a bake build issue, but it probably requires also some documentation in the app store that the module depends, for example, on a system library such as Boost.
 +
 +
== Module grouping ==
 +
 +
We will probably want support for groups of modules.  Users should be able to specify, for example, "Ad hoc routing" and fetch modules for several protocols, which may be hosted at different sites.
 +
 +
= contrib module requirements for ns-3.29 =
 +
 +
== Goals ==
 +
 +
1. The source code layout of a module is the same as a module found in the <code>src</code> directory of ns-3:
 +
 +
  bindings doc examples helper model test wscript
 +
 +
2.  Additionally, the module must contain two version files.  <code>VERSION</code> is the version number of the module, and should be a conventional sequence-based identifier (such as '1.0.0') allowing users to easily interpret older and newer versions.  <code>NS3-VERSION</code> is a recommended or known-good version of ns-3 with which the module is compatible, and should just be a single line.
 +
 +
  release <release tag number>
 +
 +
or
 +
 +
  changeset <mercurial changeset hash>
 +
 +
Examples:
 +
 +
  release ns-3.28
 +
 +
  changeset 13418:82d130348a36
 +
 +
The build system will use the NS3-VERSION to warn of possible incompatibilities.
 +
 +
3.  The source code must be provided from a hosting provider such as GitHub or Bitbucket, or as an source archive downloadable from the web.  The module should be provided such that it can be cloned directly (or untarred) into the contrib directory without cloning also the upstream ns-3-dev repository.
 +
 +
For example:
 +
 +
  $ cd ns-3-allinone/ns-3-dev/contrib
 +
  $ git clone https://github.com/sampleuser/sample-module
 +
  $ ls sample-module
 +
  bindings doc examples helper model NS3-VERSION test VERSION
 +
 +
4.  The module should be named in lowercase with hyphen separation of words, similar to ns-3 <code>src</code> directory conventions.
 +
 +
5.  All module C++ source code should be put into a separate C++ namespace within ns3 namespace, corresponding to the module name, similar to how ns-3's aodv and olsr are structured.
 +
 +
5.  ns-3's <code>create-module.py</code> should be moved to the contrib/ directory, and documentation updated to describe this change.
 +
 +
== Non-goals ==
 +
 +
The below are non-goals for ns-3.29 release, although they may be worked on for future releases.
 +
 +
1.  provide build scripts so that each module can be built, tested, and installed as a completely standalone library without invoking ns-3's Waf, although this will not be precluded if a user wishes to provide some build scripts to do so.
  
Devise a new source code organization, build system, and package management (metadata and scripts) system that provides the following.
+
2.  provide build scripts to build the module Doxygen separately from the rest of ns-3 (perhaps this could be supported in ns-3.29 if someone can work on it).  
  
The top level goals are as follows:
+
3.  support modules that require patching of the mainline ns-3 release to function.  We could experiment with including a <code>patches</code> directory that can store patches for the mainline that must be applied by bake.
  
* '''Modular build,''' with capability to enable/disable models from the build
+
= Packaging for ns-3.29 release =
* '''Package management system,''' to allow users to manage model packages that are provided by ns-3 as well as those that may be provided by third parties
+
* Uniform way to handle and '''manage (non-system) external libraries''' used with ns-3
+
  
Beyond modularity, there is a need to distinguish the maintenance status of models:
+
The <code>ns-allinone-3.29</code> release tarball will contain all modules (the universe) supported for ns-3.29 and found in the app storeHowever, the default build of ns-3.29 will exclude the contributed modules.   
* ns-3-dev continues to contain the core models, test suites, and documentation that are actively maintained by the project and built by all users
+
* ns-3-models contains additional models that can be added to the build with user-friendly build instructions. There will be two classifications:
+
** ''maintained:'' These contain models that are actively maintained by the projectAll models in this directory are checked for each release, and bugs in tracker are responded to
+
** ''unmaintained:'' These contain models that conform to the package metadata system, but the project does not do any testing or maintenance of them. They may fall out of date over time.  They may be revived in the future and added to the maintained status.
+
* models can also be stored at external web sites; such models will typically have "unmaintained" statusNote that "unmaintained" means unmaintained by the project; someone may be actively maintaining them behind the scenes.
+
  
The basic idea of the ns-3 app store would be to store on a server a set of user-submitted metadata which describes various source code packages. Typical metadata would include:
+
We may decide to later release subsets of the universe of modules (such as the so-called 'spins' of Linux desktop distros), but for simplicity's sake for ns-3.29, we will just include all.
* unique name
+
* version number
+
* last known good ns-3 version (tested against)
+
* description
+
* download url
+
* untar/unzip command
+
* configure command
+
* build command
+
* system prerequisites (if user needs to apt-get install other libraries)
+
* list of ns-3 package dependencies (other ns-3 packages which this package depends upon)
+
  
There are a few metadata systems to be considered, such as Debian spec files and jhbuild.
+
We may decide to migrate some relatively unused existing ns-3 modules from <code>src</code> to <code>contrib</code> at release time, to shrink the default build.
  
= API and work flow =
+
Proposed API:
  
There are separate tasks that people will want to do on a per-module basis, and perhaps on a top-level repository with specific components enabled/disabled:
+
  # by default, will exclude contrib modules:
* download code
+
  $ ./waf configure --enable-examples --enable-tests 
* update code
+
  # selectively include sample-module in the usual way:
* configure; enable/disable them from the build
+
  $ ./waf configure --enable-examples --enable-tests --enable-modules=core,network,lte,sample-module
* enable optimized/debug
+
  # include all src and contrib modules meeting dependency requirements:
* build, compile, and link model code
+
  $ ./waf configure --enable-examples --enable-tests --enable-modules=all
* install: copy exported .so binaries, .h to an "install" location (maybe specified during configure)
+
* build examples:  compile and link examples
+
* build tests:  compile and link etsts
+
* run tests
+
* generate documentation
+
  
One idea is to have a workflow like this:
+
= Development workflow for contrib modules =
  hg clone http://code.nsnam.org/build
+
  cd build
+
  ./build.py module-list.xml download
+
  ./build.py module-list.xml configure
+
  ./build.py module-list.xml build
+
  ./build.py module-list.xml install
+
  
module-list.xml would describe the list of modules to build, for each
+
The usual way for people to work on a new feature has been to fork ns-3-dev and either edit existing modules or create new modules in <code>src</code>.  This results in a parallel repository to ns-3-dev, completely stand-alone from ns-3-dev.
module the list of commands for each task.
+
  
= Plan =
+
In the new model, authors will create standalone module repositories and will need to place them within the contrib/ folder of ns-3 to work on them.
  
It probably makes sense to first consider how to factor out an existing model into a new library, and how we want the build system to handle that case (such as what we used to do a long time ago with separate simulator, core, common, etc. libraries). Then, we could talk about how to maintain such separate model libraries as packages.
+
Will [https://gist.github.com/gitaarik/8735255 Git submodules] be the preferred recommended way for people to set up a contrib development environment? Someone should investigate this or propose alternatives.

Latest revision as of 15:21, 19 April 2018

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

Background

The goal is to support modularization of the ns-3 code base and federation of development activities. To date, the main path to distributing extensions to ns-3 has been to request a code review for merge to the mainline tree. The future goal is to shrink the ns-3 core, and to better facilitate modules that are independently developed and maintained. As a concrete example, the R statistical framework does not integrate every extension to its main release; instead, it allows users to fetch the packages of interest and add to their installation. Communities-of-interest have even arisen to allow researchers to organize and curate sets of R extensions (e.g. bioinformatic packages). We envision the same for ns-3.

In the ns-3.27 release, the bake build orchestration tool was extended to allow third party contributed code modules to be added to ns-3, and to be downloaded, built, and installed with the main ns-3 release. This allows modules to be hosted elsewhere and integrated with the ns-3-allinone framework. Consider this to be the back-end support for modularization. We have not gone further since that time.

For example, the sift routing code contribution has been added as a module. Please review how users are expected to add sift to their ns-3.27 release on this wiki page.

There are two main components:

1) front end The ns-3 app store (https://apps.nsnam.org) is largely operational and will be put into actual use for ns-3.29. The app store can be used to directly download contributed modules, and to post information about the module.

2) back end The back end will be the bake build orchestration tool.

Workflows

We envision three types of users:

  1. . End user: The normal user will browse to the app store to learn about available apps, learn about resources (user forums, documentation) about each app, and possibly leave feedback on a review board. The normal user will obtain the necessary information to fetch and install each app from this page.
  2. . Developer: Developers will not be able to create new apps on the app store, but will be able to edit the app page that he or she owns. To make an app available on the store, it has to go through an ns-3 review process.
  3. . Maintainer: ns-3 maintainers will create a new page for an accepted app, and create a developer account for the author. Then the developer will be able to edit the page to suit their app.

Requirements

The following requirements were used to develop the app store (https://apps.nsnam.org).

  1. . The front page should be clean, consisting of categories, newest releases, and popular downloads.
  2. . Each "app" will be an ns-3 module, with a description page including: Description, screenshots (optional), download tab, resources tab, etc.
  3. . Clear documentation must be posted on how to use the app store, and how to submit a new app to the app store
  4. . The "Download" tab will fetch a source archive, and the user will download to a location of their choice. The user is responsible for moving or copying the package to their ns-3 development directory, and then the ns-3 build tools (invoked at command line by users in the normal way) will do the rest.
  5. . XML for the bake configuration will also be maintained for each module, allowing module contributors to post new releases of their module.

Enhancements

Once the basic capability is deployed, enhancements are possible. Some of these extensions may involve modifying the app store installation, but some will involve modifying ns-3 build scripts, documentation, and other scripts (e.g. Jenkins scripts).

Integration with bake

Bake uses XML to describe modules. It would be nice to have a standardized XML schema that describes an ns-3 module, and make it usable from both the app store and from bake. For instance, there could be an "authors" field in the XML description that can be displayed by bake at the command line and can also be parsed and shown as the Authors in the app store description.

User feedback and comments

We probably want to explore and tailor the capability for users to provide feedback and hints about apps. We do not want the capability to be abused by spammers (e.g. a captcha?).

Documentation and module creation scripts

  • Doxygen and Sphinx scripts should be modified to allow building on a per-module basis; ns-3 web site should still integrate all of these module documentations coherently
  • The create-module.py program should be updated
  • The ns-3 tutorial must be updated

Regression testing

We need to write some new Jenkins scripts to test the known modules for regressions.

Versioning

Managing the version numbers of different apps will be necessary. We want users to be able to declare that apps are compatible with specific ns-3 versions.

Patch management

Apps may fall out of date (become unmaintained) but it may be the case that some simple patches could be applied on top of them to make them workable again with the latest ns-3. The framework should support the ability to declare that a module installation consists of downloading an archive and then patching it with a file fetched from elsewhere. A module may also require patching of ns-3 core itself; the framework should support this.

Dependency management

If some modules depend on other modules or system dependencies, that needs to be expressed and handled by the tools. This is mainly a bake build issue, but it probably requires also some documentation in the app store that the module depends, for example, on a system library such as Boost.

Module grouping

We will probably want support for groups of modules. Users should be able to specify, for example, "Ad hoc routing" and fetch modules for several protocols, which may be hosted at different sites.

contrib module requirements for ns-3.29

Goals

1. The source code layout of a module is the same as a module found in the src directory of ns-3:

 bindings doc examples helper model test wscript

2. Additionally, the module must contain two version files. VERSION is the version number of the module, and should be a conventional sequence-based identifier (such as '1.0.0') allowing users to easily interpret older and newer versions. NS3-VERSION is a recommended or known-good version of ns-3 with which the module is compatible, and should just be a single line.

 release <release tag number>

or

 changeset <mercurial changeset hash>

Examples:

 release ns-3.28
 changeset 13418:82d130348a36

The build system will use the NS3-VERSION to warn of possible incompatibilities.

3. The source code must be provided from a hosting provider such as GitHub or Bitbucket, or as an source archive downloadable from the web. The module should be provided such that it can be cloned directly (or untarred) into the contrib directory without cloning also the upstream ns-3-dev repository.

For example:

 $ cd ns-3-allinone/ns-3-dev/contrib
 $ git clone https://github.com/sampleuser/sample-module
 $ ls sample-module
 bindings doc examples helper model NS3-VERSION test VERSION

4. The module should be named in lowercase with hyphen separation of words, similar to ns-3 src directory conventions.

5. All module C++ source code should be put into a separate C++ namespace within ns3 namespace, corresponding to the module name, similar to how ns-3's aodv and olsr are structured.

5. ns-3's create-module.py should be moved to the contrib/ directory, and documentation updated to describe this change.

Non-goals

The below are non-goals for ns-3.29 release, although they may be worked on for future releases.

1. provide build scripts so that each module can be built, tested, and installed as a completely standalone library without invoking ns-3's Waf, although this will not be precluded if a user wishes to provide some build scripts to do so.

2. provide build scripts to build the module Doxygen separately from the rest of ns-3 (perhaps this could be supported in ns-3.29 if someone can work on it).

3. support modules that require patching of the mainline ns-3 release to function. We could experiment with including a patches directory that can store patches for the mainline that must be applied by bake.

Packaging for ns-3.29 release

The ns-allinone-3.29 release tarball will contain all modules (the universe) supported for ns-3.29 and found in the app store. However, the default build of ns-3.29 will exclude the contributed modules.

We may decide to later release subsets of the universe of modules (such as the so-called 'spins' of Linux desktop distros), but for simplicity's sake for ns-3.29, we will just include all.

We may decide to migrate some relatively unused existing ns-3 modules from src to contrib at release time, to shrink the default build.

Proposed API:

 # by default, will exclude contrib modules:
 $ ./waf configure --enable-examples --enable-tests  
 # selectively include sample-module in the usual way:
 $ ./waf configure --enable-examples --enable-tests --enable-modules=core,network,lte,sample-module
 # include all src and contrib modules meeting dependency requirements:
 $ ./waf configure --enable-examples --enable-tests --enable-modules=all

Development workflow for contrib modules

The usual way for people to work on a new feature has been to fork ns-3-dev and either edit existing modules or create new modules in src. This results in a parallel repository to ns-3-dev, completely stand-alone from ns-3-dev.

In the new model, authors will create standalone module repositories and will need to place them within the contrib/ folder of ns-3 to work on them.

Will Git submodules be the preferred recommended way for people to set up a contrib development environment? Someone should investigate this or propose alternatives.