changes for 3.0.4 release
authorTom Henderson <tomh@tomh.org>
Mon, 16 Jul 2007 21:41:19 -0700
changeset 9299394956b7fc4
parent 928 218063b19458
child 930 5701e60bf01a
changes for 3.0.4 release
RELEASE_NOTES
SConstruct
VERSION
doc/build.txt
     1.1 --- a/RELEASE_NOTES	Sun Jul 15 13:04:47 2007 +0100
     1.2 +++ b/RELEASE_NOTES	Mon Jul 16 21:41:19 2007 -0700
     1.3 @@ -3,6 +3,14 @@
     1.4  
     1.5  This file contains ns-3 release notes (most recent releases first).
     1.6  
     1.7 +Release 3.0.4 (2007/07/15)
     1.8 +========================
     1.9 +
    1.10 +  - Enable waf as the default build system.
    1.11 +  - Per-packet metadata:  a system to track which headers and trailers 
    1.12 +    are added to a packet
    1.13 +  - Simplifications to point-to-point devices and channel
    1.14 +
    1.15  Release 3.0.3 (2007/06/15)
    1.16  ========================
    1.17  
     2.1 --- a/SConstruct	Sun Jul 15 13:04:47 2007 +0100
     2.2 +++ b/SConstruct	Mon Jul 16 21:41:19 2007 -0700
     2.3 @@ -24,7 +24,6 @@
     2.4  ns3.add_extra_dist ('AUTHORS')
     2.5  ns3.add_extra_dist ('VERSION')
     2.6  
     2.7 -ns3.add_extra_dist('doc/build-waf.txt')
     2.8  ns3.add_extra_dist('ns3/_placeholder_')
     2.9  for wscript in [
    2.10      "src/core/wscript",
    2.11 @@ -41,7 +40,6 @@
    2.12      "wscript",
    2.13      ]:
    2.14      ns3.add_extra_dist(wscript)
    2.15 -ns3.add_extra_dist('waf')
    2.16  ns3.add_extra_dist('waf.bat')
    2.17  
    2.18  
     3.1 --- a/VERSION	Sun Jul 15 13:04:47 2007 +0100
     3.2 +++ b/VERSION	Mon Jul 16 21:41:19 2007 -0700
     3.3 @@ -1,1 +1,1 @@
     3.4 -3.0.3
     3.5 +3.0.4
     4.1 --- a/doc/build.txt	Sun Jul 15 13:04:47 2007 +0100
     4.2 +++ b/doc/build.txt	Mon Jul 16 21:41:19 2007 -0700
     4.3 @@ -1,186 +1,106 @@
     4.4 -If you want to build ns3, you need to install scons (see
     4.5 -http://www.scons.org). scons takes care of building
     4.6 -the whole source tree using your system compiler. scons
     4.7 -0.91.1 and 0.91.96 have been tested and are known to 
     4.8 -work on linux FC5, Mac os X and MinGW.
     4.9 +The Waf build system is used to build ns-3.  Waf is a Python-based
    4.10 +build system (http://www.freehackers.org/~tnagy/waf.html)
    4.11  
    4.12 -To start a build, you can just type 'scons' which
    4.13 -will generate a debug shared build by default, located
    4.14 -in the directory 'build-dir/dbg-shared/bin' and
    4.15 -'build-dir/dbg-shared/lib'.
    4.16 +=== Installing Waf ===
    4.17  
    4.18 -All builds are built with debugging symbols. Debugging
    4.19 -builds enable asserts while optimized builds disable them.
    4.20 -On platforms which support it, rpath is used which means that
    4.21 -the executable binaries generated link explicitely against
    4.22 -the right libraries. This saves you the pain of having to
    4.23 -setup environment variables to point to the right libraries.
    4.24 +If this file is part of a development release tarball, the top-level 
    4.25 +ns-3 directory should contain a current waf script.
    4.26  
    4.27 -(Note:  An alternative build system (Waf) is being
    4.28 -evaluated in the development branch of ns-3-dev on our server
    4.29 -only (i.e., not in the release tarballs)-- see doc/build-waf.txt)
    4.30 +However, the ns-3 Mercurial code repository does not contain the waf 
    4.31 +script.  Instead, developers should check it out from a subversion 
    4.32 +repository:
    4.33  
    4.34 -1) Options
    4.35 -----------
    4.36 +  svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
    4.37  
    4.38 -- verbose: if you have installed scons 0.91.96 or higher, 
    4.39 -  the default build output is terse. To get a more verbose 
    4.40 -  output, you need to set the 'verbose' variable to 'y'.
    4.41 -Example: scons verbose=y
    4.42 -- cflags: flags for the C compiler.
    4.43 -Example: scons cflags="-O3 -ffast-math"
    4.44 -- cxxflags: flags for the C++ compiler.
    4.45 -Example: scons cxxflags="-O3 -ffast-math"
    4.46 -- ldflags: flags for the linker:
    4.47 -Example: scons ldflags="-L/foo -L/bar"
    4.48 -- cc: the C compiler to use:
    4.49 -Example: scons cc=gcc-4.0
    4.50 -- cxx: the C++ compiler to use:
    4.51 -Example: scons cxx=g++-4.0
    4.52 -- high-precision-as-double: set to 'y' to make sure that the
    4.53 -  high-precision arithmetics performed by the Time class on
    4.54 -  behalf of the user will use doubles. By default, the code
    4.55 -  uses 128 integers.
    4.56 -Example: scons high-precision-as-double=y
    4.57 -- inheritenv: set to 'y' if you want to make your compiler
    4.58 -  execute within the same environment (env vars) as your own
    4.59 -  shell. This is typically used to make colorgcc work.
    4.60 -Example: scons inheritenv=y
    4.61 +[ note: 'tags/ns3' is a tag that represents the last svn version
    4.62 +tested to work correctly with ns3, although 'trunk' will likely work
    4.63 + as well ]
    4.64  
    4.65 -2) Targets
    4.66 -----------
    4.67 +Then it can be installed system-wide with 'sudo waf-light install'.
    4.68 +When preparing a distribution, the resulting 'waf' script, which is
    4.69 +self contained (no external files needed), can be easily included in
    4.70 +the tarball so that users downloading ns-3 can easily build it without
    4.71 +having Waf installed (although Python >= 2.3 is still needed).
    4.72  
    4.73 -- doc: build the doxygen documentation.
    4.74 -Example: scons doc
    4.75 +=== Building with Waf ===
    4.76  
    4.77 -- dbg-shared: a debug build using shared libraries.
    4.78 -  The files are built in 'build-dir/dbg-shared/'.
    4.79 -Example: scons dbg-shared
    4.80 +To build ns-3 with waf type the commands:
    4.81 + 1. waf configure [options]
    4.82 + 2. waf
    4.83  
    4.84 -- dbg-static: a debug build using static libraries
    4.85 -  The files are built in 'build-dir/dbg-static/'.
    4.86 -Example: scons dbg-static
    4.87 +To see valid configure options, type waf --help.  The most important
    4.88 +option is -d <debug level>.  Valid debug levels (which are listed in
    4.89 +waf --help) are: ultradebug, debug, release, and optimized.  It is
    4.90 +also possible to change the flags used for compilation with (e.g.):
    4.91 +CXXFLAGS="-O3" waf configure.
    4.92  
    4.93 -- opt-shared: an optimized build using shared libraries.
    4.94 -  The files are built in 'build-dir/opt-shared/'.
    4.95 -Example: scons opt-shared
    4.96 +[ Note:  Unlike some other build tools, to change the build target,
    4.97 +the option must be supplied during the configure stage rather than
    4.98 +the build stage (i.e., "waf -d optimized" will not work; instead, do
    4.99 +"waf -d optimized configure; waf" ]
   4.100  
   4.101 -- opt-static: an optimized build using static libraries.
   4.102 -  The files are built in 'build-dir/opt-static/'.
   4.103 -Example: scons opt-static
   4.104 +The resulting binaries are placed in build/<debuglevel>/srcpath.
   4.105  
   4.106 -- dbg: an alias for dbg-shared
   4.107 -Example: scons dbg
   4.108 +Other waf usages include:
   4.109  
   4.110 -- opt: an alias for opt-shared
   4.111 -Example: scons opt
   4.112 + 1. waf check
   4.113 +    Runs the unit tests
   4.114  
   4.115 -- all: alias for dbg-shared, dbg-static, opt-shared 
   4.116 -  and opt-static
   4.117 -Example: scons all
   4.118 + 2. waf --doxygen
   4.119 +    Run doxygen to generate documentation
   4.120  
   4.121 -- gcov: code coverage analysis. Build a debugging version of
   4.122 -  the code for code coverage analysis in 'build-dir/gcov'. Once
   4.123 -  the code has been built, you can run various applications to
   4.124 -  exercise the code paths. To generate an html report from
   4.125 -  the gcov data, use the lcov-report target
   4.126 + 3. waf --lcov-report
   4.127 +    Run code coverage analysis (assuming the project was configured
   4.128 +with --enable-gcov)
   4.129  
   4.130 -- lcov-report: generate html report of gcov data. The output
   4.131 -  is stored in 'build-dir/lcov-report/'.
   4.132 + 4. waf --run "program [args]"
   4.133 +    Run a ns3 program, given its target name, with the given
   4.134 +    arguments.  This takes care of automatically modifying the the
   4.135 +    path for finding the ns3 dynamic libraries in the environment
   4.136 +    before running the program.  Note: the "program [args]" string is
   4.137 +    parsed using POSIX shell rules.
   4.138  
   4.139 -- dist: generate a release tarball and zipfile from the 
   4.140 -  source tree. The tarball and zipfile name are generated
   4.141 -  according to the version number stored in the SConstruct
   4.142 -  file.
   4.143 -Example in SConstruct:
   4.144 -ns3 = Ns3 ()
   4.145 -ns3.name = 'foo'
   4.146 -ns3.version = '0.0.10'
   4.147 -Example command: scons dist
   4.148 -Example output files:
   4.149 -foo-0.0.10.tar.gz
   4.150 -foo-0.0.10.zip
   4.151 + 5. waf --shell
   4.152 +    Starts a nested system shell with modified environment to run ns3 programs.
   4.153  
   4.154 -- distcheck: generate a release tarball and zipfile and 
   4.155 -  attempt to run the 'all' target for the release tarball.
   4.156 -Example: scons distcheck
   4.157 + 6. waf distclean
   4.158 +    Cleans out the entire build/ directory
   4.159  
   4.160 -3) How the build system works
   4.161 ------------------------------
   4.162 + 7. waf dist
   4.163 +    The command 'waf dist' can be used to create a distribution tarball.
   4.164 +    It includes all files in the source directory, except some particular
   4.165 +    extensions that are blacklisted, such as back files (ending in ~).
   4.166  
   4.167 -The current build system defines what are called "ns3 modules": each module
   4.168 -is a set of source files, normal header files and installable header
   4.169 -files. Each module also depends on a set of other modules. We build
   4.170 -modules automatically in the correct order. That is, we always start
   4.171 -from the module which does not depend on any other module (core) and
   4.172 -proceed with the other modules and make sure that when a module is
   4.173 -built, all the modules it depends upon have already been built.
   4.174  
   4.175 -To build a module, we:
   4.176 -1) generate the .o files
   4.177 -2) link the .o files together 
   4.178 -3) install the installable headers in the common directory
   4.179 -top_build_dir/include/ns3.
   4.180 +=== Extending ns-3 ===
   4.181  
   4.182 -This means that if you want to use a header from your own module, you
   4.183 -should just include it: #include "foo.h" but if you want to include a
   4.184 -header from another module, you need to include it with #include
   4.185 -"ns3/bar.h". This allows you to make sure that our "public" ns3 headers
   4.186 -do not conflict with existing system-level headers.   For instance,
   4.187 -if you were to define a header called queue.h, you would include
   4.188 -ns3/queue.h rather than queue.h, when including from a separate module,
   4.189 -since many systems provide a queue.h system include file.  
   4.190 +To add new modules:
   4.191 +  1. Create the module directory under src (or src/devices, or whatever);
   4.192 +  2. Add the source files to it;
   4.193 +  3. Add a 'wscript' describing it;
   4.194 +  4. Add the module subdirectory name to the all_modules list in src/wscript.
   4.195  
   4.196 -4) How to add files to a module ?
   4.197 ----------------------------------
   4.198 +A module's wscript file is basically a regular Waf script.  A ns-3
   4.199 +module is created as a cpp/shlib object, like this:
   4.200  
   4.201 -In the main SConstruct file, you can add source code
   4.202 -to the add_sources method. For example, to add a foo.cc
   4.203 -file to the core module, we coud do this:
   4.204 -core.add_sources ('foo.cc')
   4.205 -Of course, if this file implements public API, its 
   4.206 -header should be installable:
   4.207 -core.add_inst_headers ('foo.h')
   4.208 +def build(bld):
   4.209 +    obj = bld.create_obj('cpp', 'shlib')
   4.210  
   4.211 -5) How to create a new module ?
   4.212 --------------------------------
   4.213 +    ## set module name; by convention it starts with ns3-
   4.214 +    obj.name = 'ns3-mymodule'
   4.215 +    obj.target = obj.name 
   4.216  
   4.217 -# create a new module. First arg is the name of
   4.218 -# the new module. Second arg is the directory in
   4.219 -# which all source files for this module reside.
   4.220 -my_module = build.Ns3Module ('my', 'src/my_dir')
   4.221 -# add it to build system
   4.222 -ns3.add (my_module)
   4.223 -# specify module dependencies. Here, depends
   4.224 -# on the 'ipv4' and 'core' modules
   4.225 -my_module.add_deps (['core', 'ipv4']) 
   4.226 -# add source code to build located in 
   4.227 -# src/my_dir
   4.228 -my_module.add_sources ([
   4.229 -	'my_a.cc',
   4.230 -	'my_b.cc',
   4.231 -	'my_c.cc'
   4.232 -])
   4.233 -my_module.add_sources ([
   4.234 -	'my_d.cc'
   4.235 -])
   4.236 -# add headers which are not public
   4.237 -my_module.add_headers ([
   4.238 -	'my_a.h',
   4.239 -	'my_c.h'
   4.240 -])
   4.241 -# add headers which are public
   4.242 -my_module.add_inst_headers ([
   4.243 -	'my_b.h'
   4.244 -])
   4.245 -my_module.add_inst_headers ([
   4.246 -	'my_d.h'
   4.247 -])
   4.248 -# if you need to link against an external library,
   4.249 -# you must add 'external' dependencies. Here, the 
   4.250 -# pthread library
   4.251 -my_module.add_external_dep ('pthread')
   4.252 -# by default, a module is conceptually a library. If you
   4.253 -# want to generate an executable from a module you need to:
   4.254 -my_module.set_executable ()
   4.255 +    ## list dependencies to other modules
   4.256 +    obj.uselib_local = ['ns3-core'] 
   4.257  
   4.258 +    ## list source files (private or public header files excluded)
   4.259 +    obj.source = [
   4.260 +        'mymodule.cc',
   4.261 +    ]
   4.262 +
   4.263 +    ## list module public header files
   4.264 +    headers = bld.create_obj('ns3header')
   4.265 +    headers.source = [
   4.266 +        'mymodule-header.h',
   4.267 +    ]
   4.268 +