Ns-3.22-build: Difference between revisions

From Nsnam
Jump to navigation Jump to search
(move page)
 
Line 1: Line 1:
{{TOC}}
{{TOC}}


This page summarizes the proposed build system modifications to [[ns-3.22]].  Comments should be directed to the [http://mailman.isi.edu/mailman/listinfo/ns-developers ns-developers] mailing list.
This page has been moved to [[ns-3.23-build]] since the milestone has slipped a release cycle.
 
= 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:
 
  <nowiki> #! /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
  </nowiki>
 
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.
 
  <nowiki> 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"
  ...
  </nowiki>
 
= waf differences =
 
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:
 
  <nowiki> Modules built:
  core                      mobility                  network                 
  propagation              stats                    wifi                   
 
  Modules not built (see ns-3 tutorial for explanation):
  brite                    click                    openflow               
  visualizer
  </nowiki>
 
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.22, 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:
 
  <nowiki> 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)
  </nowiki>
 
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:
 
  <nowiki> Modules requested:
  wifi                      wimax
 
  Modules enabled:
  bridge                    core                      internet               
  mobility                  mpi                      network                 
  point-to-point            propagation              stats                   
  wifi                      wimax
  </nowiki>
 
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).
 
= 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, 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

Latest revision as of 17:20, 26 January 2015

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

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

This page has been moved to ns-3.23-build since the milestone has slipped a release cycle.

Retrieved from "https://www.nsnam.org/mediawiki/index.php?title=Ns-3.22-build&oldid=9265"