Summary of proposed changes
At a high level, the changes can be summarized in terms of some informal use case goals and perspectives:
For new ns-3 users, the goal is to reduce the scope of the default build, and to make it easier to selectively enable and disable ns-3 modules, so that build times and complexity are reduced. An additional goal for users is to more clearly show the maintenance status of each module.
For ns-3 contributors of new modules, the goal is to allow contributors to publish new ns-3 modules and have them bundled with the allinone release if they have not been completely certified by the main project (e.g. they are in an 'alpha' or 'beta' state), if they are being maintained elsewhere, or if they are considered too specialized for the main ns-3 distribution.
For ns-3 maintainers, the goal is to provide a new category of module, called a 'contributed module', that is maintained outside the main ns-3-dev code tree. This will further federate the maintenance of modules, and reduce growth of the ns-3-dev repository.
ns-3.23 directory differences
ns-3.23 directory structure will have the following differences:
1) the directory structure will contain a separate 'contrib' directory at the top level. The internal layout of the directory will resemble that of 'src'. 'contrib' will not be populated in ns-3-dev, but will contain bundled contributed modules in allinone releases.
2) the top level directory will contain a default .ns3rc file. In previous releases, this file needed to be copied by the user from its location at 'utils/.ns3rc'. The basic functionality and syntax of the file will be the same, although the 'all_modules' will be substituted with a list of selected modules from 'src', such as:
#! /usr/bin/env python # A list of the modules that will be enabled when ns-3 is built. # Modules that depend on the listed modules will be enabled also. # # All modules can be enabled by choosing 'all_modules'. # modules_enabled = ['all_modules'] modules_enabled = ['core', 'network', 'mobility', 'propagation', ... ] # Set this equal to true if you want examples to be run. examples_enabled = False # Set this equal to true if you want tests to be run. tests_enabled = False
and there will be an additional option to enable Python bindings (default True):
# Set this equal to True if you request to enable Python bindings. python_enabled = True
3) The 'create-module.py' will be moved from 'src/' to 'contrib/'
4) a new "module-status.html" file will be present in the top level directory and available on the main web site. It will contain metadata and hyperlinks about each of the modules, similar to http://www.boost.org/doc/libs/1_57_0/ and http://cran.rstudio.com/web/views/
5) each module will contain a metadata file (format TBD) that lists the metadata values for each descriptor; e.g.
name="ethernet-switch" brief="an Ethernet switch model supporting VLAN tagging and RSTP" authors="Alice Johnson <firstname.lastname@example.org>" maintainers="John Doe <email@example.com>" current-bugs="552,1979,1980,2022" compatible-with="3.21" ...
waf will be slightly modified to build also what it finds in contrib (along with src).
waf will be slightly modified to display the currently requested, enabled, and disabled modules.
Currently, using an example to illustrate, if a user configures waf to only use the 'wifi' module (through .ns3rc file or through passing the '--enable-modules=' argument to './waf configure'), './waf list' (among other commands) will show these modules enabled:
Modules built: core mobility network propagation stats wifi Modules not built (see ns-3 tutorial for explanation): brite click openflow visualizer
There are more modules than requested by the user since wifi has additional dependencies. The currently provided list of 'modules not built' omits the list of modules not built because they are not required by the requested modules; it only shows those whose configuration failed for some reason. For ns-3.23, the proposal is to better distinguish between modules requested and modules enabled, and to show all the possibly available modules that are outside of the current configuration.
There is also no way to incrementally add or delete modules from the command line. For instance, if a user wants to add one more module to the existing list of enabled modules, he or she must submit the entire module list again for configuration.
So, for instance, if the user requested "--enable-modules=wifi", he or she would see something like:
Modules requested: wifi Modules enabled: core mobility network propagation stats wifi Modules not enabled: antenna aodv applications bridge brite buildings click config-store csma csma-layout dsdv dsr energy fd-net-device flow-monitor internet lr-wpan lte mesh mpi netanim (no Python) nix-vector-routing olsr openflow point-to-point point-to-point-layout sixlowpan spectrum tap-bridge test (no Python) topology-read uan virtual-net-device visualizer wave wimax (plus whatever is in contrib/ directory)
The user may later decide to add 'wimax', with a command such as:
./waf configure --add-module='wimax'
which will lead to more enabled modules because of the dependency:
Modules requested: wifi wimax Modules enabled: bridge core internet mobility mpi network point-to-point propagation stats wifi wimax
The following would revert the requested configuration to what it was before:
./waf configure --remove-module='wimax'
Note: if something like the above --add-module and --remove-module command line arguments are too cumbersome to add to waf, this goal may be dropped (recommending instead to use the .ns3rc file to maintain the list of requested modules).
1) bake will be extended to allow the download target directory of an ns-3 contributed module to land in the ns-3.23/contrib/ directory.
2) bake will be extended to allow multiple bakeconf.xml files. A future contributor should be able to add support for his or her new module or patch to ns-3 by providing a snippet of XML that can either be dropped into the ns-allinone-3.23/bake/ directory as a separate file, or appended to the existing bakeconf.xml file.
contributed module requirements
All contributed modules to be bundled with ns-allinone-3.23 will provide the following:
1) source code in a module directory structure, on a publicly available web site (code.nsnam.org, github, bitbucket, a tarball, etc.). The module should be downloadable into contrib/ directory (by the bake.py download facility) and buildable by ns-3 waf.
2) metadata about the module, including a version number (which can be the same as ns-3's VERSION, or different)
3) XML for the bakeconf.xml file, including any library dependencies
In addition, the release manager will determine the advertised state and maintenance status of each module. Some possible keywords and examples:
- An essential module such as 'network' can be given the status of 'mainline'. These conform to ns-3 coding style, documentation, testing, and maintenance guidelines, and are part of the default build.
- Other modules that conform to ns-3 guidelines but that aren't essential to the default build could be called 'certified'
- A module that is in development, hoping to become certified or mainline, could be in an 'alpha' or 'beta' state
- Modules could be listed as 'unmaintained' if they are no longer supported. Modules that don't graduate from 'alpha' or 'beta' state would eventually be listed as 'unmaintained'.
Maintenance status labels such as 'maintained', 'unmaintained', and 'third-party' could be used to describe the maintenance status. Basically, this lets users know whether bugs will be addressed by the ns-3 project, by another project, or may be ignored due to lack of maintainers.
strawman proposal for default enabled modules
This list is expected to change based on future discussions; it is just an initial proposal to make a smaller build with core Internet functionality.
applications bridge config-store core csma csma-layout energy fd-net-device flow-monitor internet mobility netanim (no Python) network nix-vector-routing point-to-point point-to-point-layout propagation stats