|
|
| (4 intermediate revisions by the same user not shown) |
| 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 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 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:
| + | |
| − | | + | |
| − | <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 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
| + | |
