Broad functional goals
1. Enable a more distributed package environment for ns-3 third-party developers.
1.1 Split out some of existing ns-3-dev into a smaller "core" and additional "extensions". This should reduce build time for users.
1.2 Provide straightforward way for a third-party developer to maintain their own ns-3 extension and make it available to ns-3 users.
2. Provide a tool for developers to manage multiple builds.
3. Start to provide access to INRIA's Direct Code Execution (DCE) environment
Below are proposed goals for ns-3.16.
1. bake.py provides existing download.py and build.py with no change of functionality
1.1 For ns-3-dev (after merge):
hg clone http://code.nsnam.org/ns-3-allinone cd ns-3-allinone ./bake.py configure -e ns-3-dev ./bake.py download ./bake.py build
alternative: the "install" command will "download" then "build"
hg clone http://code.nsnam.org/ns-3-allinone cd ns-3-allinone ./bake.py configure -e ns-3-dev ./bake.py install
1.2 For ns-3.16:
tar xjf ns-allinone-3.16.tar.bz2 cd ns-allinone-3.16 ./bake.py configure -e ns-3.16 ./bake.py build
1.3 existing download.py and build.py
We keep existing download.py and build.py files, but they print out a backward-compatibility warning and call the equivalent bake commands; e.g.
cd ns-allinone-3.16 ./build.py "Warning: build.py is deprecated, please use './bake.py configure -e ns-3.16 && ./bake.py build' instead.
2. different levels of verbosity show different amount of build information
yields something sparse, such as
>> Downloading ns-3-dev >> Download ns-3-dev - OK >> Building ns-3-dev >> Built ns-3-dev - OK
./bake.py install -vv
yields the full build output (full waf configure and build information).
3. Managing ns-3 versions
4. Managing debug, optimized, and static builds
5. Passing configure options to bake, especially ns-3 ones such as --disable-python
6. cleaning the directory
'./bake.py clean' will remove the build/ directory and any build artifacts and configuration information; './bake.py distclean' will perform a clean and also remove source/
7. Configuration manipulation
-d and -e behavior
8. Show behavior
bake.py shows available packages, whether they are enabled, and their dependencies; e.g.:
./bake.py show --enabled module: click (enabled) No dependencies! module: openflow-ns3 (enabled) No dependencies! module: gccxml-ns3 (enabled) No dependencies! module: nsc (enabled) No dependencies! module: qt4 (enabled) No dependencies! module: pygccxml (enabled) depends on: gccxml-ns3 (optional:True) module: net_anim (enabled) depends on: qt4 (optional:True) module: pybindgen (enabled) depends on: pygccxml (optional:True) module: ns-3-dev (enabled) depends on: net_anim (optional:True) nsc (optional:True) pybindgen (optional:True) click (optional:True) openflow-ns3 (optional:True)
In the example above, the gccxml-ns3 dependency is shown for pygccxml. It is out of scope for bake.py to manage package dependencies for some of these (e.g. showing "scons" as a dependency for nsc). However, it would be nice if, during the course of the build, if a package configure bails out, that "bake.py build" reports this to a user in a nice way so the user can try to find/install the missing package.
The user can check the missing dependencies by calling:
./bake.py check > Python - Ok > Mercurial - Ok > CVS - Ok > Bazaar - Ok > Tar tool - Ok > Unzip tool - Ok > Unrar tool - Ok > GIT - is missing > Make - Ok > cMake - Ok > path tool - Ok > Autotools - Ok
Perhaps an enhancement to the above would be to show the "build" and "install" status of each.
Users should be able to disable (in a sticky way) a package they are not interested in; e.g.:
./bake.py configure -d netanim
would result in netanim being "(disabled)". Either of the following would restore netanim:
./bake.py reconfigure (or some other way to get back to defaults) ./bake.py configure -e netanim
9. Other behavior
- bake.py does not rebuild things unnecessarily - bake.py handles control-C to abort the build
10. bake.py handling of ns-3 enabled_modules
bake.py provides access to ns-3 DCE with at least one well-documented example (iperf? quagga?) of how to use real application code within an ns-3 program. Perhaps we focus on user-mode applications for ns-3.16 and kernel-mode for the next release.
12. external module
(defer) bake.py allows at least one "external" ns-3-based module to be downloaded and built with ns-3. For example, assume there is an external routing protocol module (ns-3-bgp); we may need to make one of these up for the sake of providing an example.
For ns-3-bgp to build, it needs to link to ns-3 libraries. So, there needs to be some install step in bake to install to a well-known place in the allinone directory, or in the system.
For a user program in ns-3.16/scratch to use ns-3-bgp, it needs to be able to find the library and headers. So, the install step on ns-3-bgp should leave the installation in a well-known place by ns-3's waf.
So, the goal here would be:
./bake.py configure -e ns-3-bgp ./bake.py download ./bake.py build # builds ns-3, then builds ns-3-bgp ./bake.py install # installs both (does install have to happen before ns-3-bgp build?)
Then, user program in ns-3.16/scratch/ can include the module without specifying the full path to ns-3-bgp; i.e., waf may need to become smarter to find these headers and libraries.
To be determined.