Ns-3.22-build

From Nsnam
Revision as of 19:36, 18 November 2014 by Tomh (Talk | contribs) (ns-3.22 build proposal)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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

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

This page summarizes the proposed build system modifications to ns-3.22. Comments should be directed to the ns-developers mailing list.

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.22 directory differences

ns-3.22 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 <ajohnson@example.edu>"
  maintainers="John Doe <jdoe@example.com>"
  current-bugs="552,1979,1980,2022"
  compatible-with="3.21"
  ...
  

waf differences

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 current list omits the list of modules not built because they are not required by the requested modules. There is also no way to incrementally add or delete modules. 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.

For ns-3.22, the proposal is to distinguish between modules requested and modules enabled, and to also allow users to incrementally add or subtract modules.

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 the --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), but the distinction between 'requested' and 'enabled' modules is planned regardless.

bake differences

1) bake will be extended to allow the download target directory of an ns-3 contributed module to land in the ns-3.22/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.22/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.22 will provide the following:

1) source code in a module directory structure, on a publicly available web site (code.nsnam.org, github, bitbucket, etc.). The module should be downloadable into contrib/ directory 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 bakeconf.xml file including any library dependencies

In addition, the release manager will determine the advertised state and maintenance status of each module bundled. 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