View source for HOWTO enable a subset of ns-3's modules

{{TOC}}

As with most software projects, ns-3 is ever growing larger in terms of number of modules, lines of code, and memory footprint.  

Users, however, may only use a few of those modules at a time.  Therefore, users may want to explicitly enable only the subset of the possible ns-3 modules that they actually need for their research.

This HOWTO discusses how to enable only the ns-3 modules that you are intersted in using.

== HOWTO enable a subset of ns-3's modules ==

If shared libraries are being built, then enabling a module will cause at least one library to be built:  libns3-modulename.so.  If the module has a test library and test libraries are being built, then libns3-modulename-test.so will be built, too.  Other modules that the module depends on and their test libraries will also be built.  

By default, all modules are built in ns-3.  

There are two ways to enable a subset of ns-3's modules:
# Using waf's --enable-modules option
# Using the ns-3 configuration file

=== Enable modules using waf's --enable-modules option ===

To enable only the core module with example and tests, for example,
try these commands:

  ./waf clean
  ./waf configure --enable-examples --enable-tests --enable-modules=core
  ./waf build
  cd build/debug/
  ls

and the following libraries should be present:

  bindings  libns3-core.so       ns3      scratch  utils
  examples  libns3-core-test.so  samples  src

Running test.py will cause only those tests that depend on module core to be run:
 
  24 of 24 tests passed (24 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)

Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core:

  bindings  libns3-core.so       libns3-network.so       ns3      scratch  utils
  examples  libns3-core-test.so  libns3-network-test.so  samples  src

Running test.py will cause those tests that depend on only the core and network modules to be run:

  31 of 31 tests passed (31 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)

=== Enable modules using the ns-3 configuration file ===

A configuration file, .ns3rc, has been added to ns-3 that allows users to specify which modules are to be included in the build.

When enabling a subset of ns-3 modules, the precedence rules are as follows:

# the --enable-modules configure string overrides any .ns3rc file
# the .ns3rc file in the top level ns-3 directory is next consulted, if present
# the system searches for ~/.ns3rc if the above two are unspecified

If none of the above limits the modules to be built, all modules that waf knows about will be built.

The maintained version of the .ns3rc file in the ns-3-dev repository resides in the ns-3-dev/utils directory.  The reason for this is if it were in the top-level directory, ns-3-dev, it would be prone to accidental checkins from maintainers that enable the modules they want to use.  Therefore, users need to manually copy the .ns3rc from the utils directory to their preferred place (top level directory or their home directory) to enable persistent modular build configuration.

Assuming that you are in the ns-3-dev directory, you can get a copy of the .ns3rc file that is in the utils directory as follows:

    cp utils/.ns3rc .

The .ns3rc file should now be in your ns-3-dev directory, and it contains the following:

  #! /usr/bin/env python
  
  # A list of the modules that will be enabled when ns-3 is run.
  # Modules that depend on the listed modules will be enabled also.
  #
  # All modules can be enabled by choosing 'all_modules'.
  modules_enabled = ['all_modules']
  
  # 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

Use your favorite editor to modify the .ns3rc file to only enable the core module with examples and tests like this:

  #! /usr/bin/env python
  
  # A list of the modules that will be enabled when ns-3 is run.
  # Modules that depend on the listed modules will be enabled also.
  #
  # All modules can be enabled by choosing 'all_modules'.
  modules_enabled = ['core']
  
  # Set this equal to true if you want examples to be run.
  examples_enabled = True
  
  # Set this equal to true if you want tests to be run.
  tests_enabled = True

Only the core module will be enabled now if you try these commands:

  ./waf clean
  ./waf configure
  ./waf build
  cd build/debug/
  ls

and the following libraries should be present:

  bindings  libns3-core.so       ns3      scratch  utils
  examples  libns3-core-test.so  samples  src

Running test.py will cause only those tests that depend on module core to be run:
 
  24 of 24 tests passed (24 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)

Repeat the above steps for the "network" module instead of the "core" module, and the following will be built, since network depends on core:

  bindings  libns3-core.so       libns3-network.so       ns3      scratch  utils
  examples  libns3-core-test.so  libns3-network-test.so  samples  src

Running test.py will cause those tests that depend on only the core and network modules to be run:

  31 of 31 tests passed (31 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)