1.1 --- a/BUILD Thu May 17 07:51:22 2007 +0200
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,182 +0,0 @@
1.4 -If you want to build ns3, you need to install scons (see
1.5 -http://www.scons.org). scons takes care of building
1.6 -the whole source tree using your system compiler. scons
1.7 -0.91.1 and 0.91.96 have been tested and are known to
1.8 -work on linux FC5, Mac os X and MinGW.
1.9 -
1.10 -To start a build, you can just type 'scons' which
1.11 -will generate a debug shared build by default, located
1.12 -in the directory 'build-dir/dbg-shared/bin' and
1.13 -'build-dir/dbg-shared/lib'.
1.14 -
1.15 -All builds are built with debugging symbols. Debugging
1.16 -builds enable asserts while optimized builds disable them.
1.17 -On platforms which support it, rpath is used which means that
1.18 -the executable binaries generated link explicitely against
1.19 -the right libraries. This saves you the pain of having to
1.20 -setup environment variables to point to the right libraries.
1.21 -
1.22 -1) Options
1.23 -----------
1.24 -
1.25 -- verbose: if you have installed scons 0.91.96 or higher,
1.26 - the default build output is terse. To get a more verbose
1.27 - output, you need to set the 'verbose' variable to 'y'.
1.28 -Example: scons verbose=y
1.29 -- cflags: flags for the C compiler.
1.30 -Example: scons cflags="-O3 -ffast-math"
1.31 -- cxxflags: flags for the C++ compiler.
1.32 -Example: scons cxxflags="-O3 -ffast-math"
1.33 -- ldflags: flags for the linker:
1.34 -Example: scons ldflags="-L/foo -L/bar"
1.35 -- cc: the C compiler to use:
1.36 -Example: scons cc=gcc-4.0
1.37 -- cxx: the C++ compiler to use:
1.38 -Example: scons cxx=g++-4.0
1.39 -- high-precision-as-double: set to 'y' to make sure that the
1.40 - high-precision arithmetics performed by the Time class on
1.41 - behalf of the user will use doubles. By default, the code
1.42 - uses 128 integers.
1.43 -Example: scons high-precision-as-double=y
1.44 -- inheritenv: set to 'y' if you want to make your compiler
1.45 - execute within the same environment (env vars) as your own
1.46 - shell. This is typically used to make colorgcc work.
1.47 -Example: scons inheritenv=y
1.48 -
1.49 -2) Targets
1.50 -----------
1.51 -
1.52 -- doc: build the doxygen documentation.
1.53 -Example: scons doc
1.54 -
1.55 -- dbg-shared: a debug build using shared libraries.
1.56 - The files are built in 'build-dir/dbg-shared/'.
1.57 -Example: scons dbg-shared
1.58 -
1.59 -- dbg-static: a debug build using static libraries
1.60 - The files are built in 'build-dir/dbg-static/'.
1.61 -Example: scons dbg-static
1.62 -
1.63 -- opt-shared: an optimized build using shared libraries.
1.64 - The files are built in 'build-dir/opt-shared/'.
1.65 -Example: scons opt-shared
1.66 -
1.67 -- opt-static: an optimized build using static libraries.
1.68 - The files are built in 'build-dir/opt-static/'.
1.69 -Example: scons opt-static
1.70 -
1.71 -- dbg: an alias for dbg-shared
1.72 -Example: scons dbg
1.73 -
1.74 -- opt: an alias for opt-shared
1.75 -Example: scons opt
1.76 -
1.77 -- all: alias for dbg-shared, dbg-static, opt-shared
1.78 - and opt-static
1.79 -Example: scons all
1.80 -
1.81 -- gcov: code coverage analysis. Build a debugging version of
1.82 - the code for code coverage analysis in 'build-dir/gcov'. Once
1.83 - the code has been built, you can run various applications to
1.84 - exercise the code paths. To generate an html report from
1.85 - the gcov data, use the lcov-report target
1.86 -
1.87 -- lcov-report: generate html report of gcov data. The output
1.88 - is stored in 'build-dir/lcov-report/'.
1.89 -
1.90 -- dist: generate a release tarball and zipfile from the
1.91 - source tree. The tarball and zipfile name are generated
1.92 - according to the version number stored in the SConstruct
1.93 - file.
1.94 -Example in SConstruct:
1.95 -ns3 = Ns3 ()
1.96 -ns3.name = 'foo'
1.97 -ns3.version = '0.0.10'
1.98 -Example command: scons dist
1.99 -Example output files:
1.100 -foo-0.0.10.tar.gz
1.101 -foo-0.0.10.zip
1.102 -
1.103 -- distcheck: generate a release tarball and zipfile and
1.104 - attempt to run the 'all' target for the release tarball.
1.105 -Example: scons distcheck
1.106 -
1.107 -3) How the build system works
1.108 ------------------------------
1.109 -
1.110 -The current build system defines what are called "ns3 modules": each module
1.111 -is a set of source files, normal header files and installable header
1.112 -files. Each module also depends on a set of other modules. We build
1.113 -modules automatically in the correct order. That is, we always start
1.114 -from the module which does not depend on any other module (core) and
1.115 -proceed with the other modules and make sure that when a module is
1.116 -built, all the modules it depends upon have already been built.
1.117 -
1.118 -To build a module, we:
1.119 -1) generate the .o files
1.120 -2) link the .o files together
1.121 -3) install the installable headers in the common directory
1.122 -top_build_dir/include/ns3.
1.123 -
1.124 -This means that if you want to use a header from your own module, you
1.125 -should just include it: #include "foo.h" but if you want to include a
1.126 -header from another module, you need to include it with #include
1.127 -"ns3/bar.h". This allows you to make sure that our "public" ns3 headers
1.128 -do not conflict with existing system-level headers. For instance,
1.129 -if you were to define a header called queue.h, you would include
1.130 -ns3/queue.h rather than queue.h, when including from a separate module,
1.131 -since many systems provide a queue.h system include file.
1.132 -
1.133 -4) How to add files to a module ?
1.134 ----------------------------------
1.135 -
1.136 -In the main SConstruct file, you can add source code
1.137 -to the add_sources method. For example, to add a foo.cc
1.138 -file to the core module, we coud do this:
1.139 -core.add_sources ('foo.cc')
1.140 -Of course, if this file implements public API, its
1.141 -header should be installable:
1.142 -core.add_inst_headers ('foo.h')
1.143 -
1.144 -5) How to create a new module ?
1.145 --------------------------------
1.146 -
1.147 -# create a new module. First arg is the name of
1.148 -# the new module. Second arg is the directory in
1.149 -# which all source files for this module reside.
1.150 -my_module = build.Ns3Module ('my', 'src/my_dir')
1.151 -# add it to build system
1.152 -ns3.add (my_module)
1.153 -# specify module dependencies. Here, depends
1.154 -# on the 'ipv4' and 'core' modules
1.155 -my_module.add_deps (['core', 'ipv4'])
1.156 -# add source code to build located in
1.157 -# src/my_dir
1.158 -my_module.add_sources ([
1.159 - 'my_a.cc',
1.160 - 'my_b.cc',
1.161 - 'my_c.cc'
1.162 -])
1.163 -my_module.add_sources ([
1.164 - 'my_d.cc'
1.165 -])
1.166 -# add headers which are not public
1.167 -my_module.add_headers ([
1.168 - 'my_a.h',
1.169 - 'my_c.h'
1.170 -])
1.171 -# add headers which are public
1.172 -my_module.add_inst_headers ([
1.173 - 'my_b.h'
1.174 -])
1.175 -my_module.add_inst_headers ([
1.176 - 'my_d.h'
1.177 -])
1.178 -# if you need to link against an external library,
1.179 -# you must add 'external' dependencies. Here, the
1.180 -# pthread library
1.181 -my_module.add_external_dep ('pthread')
1.182 -# by default, a module is conceptually a library. If you
1.183 -# want to generate an executable from a module you need to:
1.184 -my_module.set_executable ()
1.185 -
2.1 --- a/BUILD.WAF Thu May 17 07:51:22 2007 +0200
2.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
2.3 @@ -1,86 +0,0 @@
2.4 -WAF is an alternative build system, similar to SCons. NS-3 now is
2.5 -able to build with WAF, in parallel to SCons.
2.6 -
2.7 -Note: the WAF build scripts are experimental at this stage.
2.8 -
2.9 -
2.10 -=== Building with WAF ===
2.11 -
2.12 -To build NS-3 with waf type the commands:
2.13 - 1. ./waf configure [options]
2.14 - 2. ./waf
2.15 -
2.16 -[ Note: if ./waf does not exist, see the section "Note for developers" below ]
2.17 -
2.18 -To see valid configure options, type ./waf --help. The most important
2.19 -option is -d <debug level>. Valid debug levels (which are listed in
2.20 -./waf --help) are: ultradebug, debug, release, and optimized.
2.21 -
2.22 -The resulting binaries are placed in build/<debuglevel>/srcpath.
2.23 -
2.24 -Other waf usages include:
2.25 -
2.26 - 1. ./waf check
2.27 - Runs the unit tests
2.28 -
2.29 - 2. ./waf --doxygen
2.30 - Run doxygen to generate documentation
2.31 -
2.32 - 3. ./waf --lcov-report
2.33 - Run code coverage analysis (assuming the project was configured
2.34 -with --enable-gcov)
2.35 -
2.36 -=== Extending NS-3 ===
2.37 -
2.38 -To add new modules:
2.39 - 1. Create the module directory under src (or src/devices, or whatever);
2.40 - 2. Add the source files to it;
2.41 - 3. Add a 'wscript' describing it;
2.42 - 4. Add the module subdirectory name to the all_modules list in src/wscript.
2.43 -
2.44 -A module's wscript file is basically a regular WAF script. A NS-3
2.45 -module is created as a cpp/shlib object, like this:
2.46 -
2.47 -def build(bld):
2.48 - obj = bld.create_obj('cpp', 'shlib')
2.49 -
2.50 - ## set module name; by convention it starts with ns3-
2.51 - obj.name = 'ns3-mymodule'
2.52 - obj.target = obj.name
2.53 -
2.54 - ## list dependencies to other modules
2.55 - obj.uselib_local = ['ns3-core']
2.56 -
2.57 - ## list source files (private or public header files excluded)
2.58 - obj.source = [
2.59 - 'mymodule.cc',
2.60 - ]
2.61 -
2.62 - ## list module public header files
2.63 - headers = bld.create_obj('ns3header')
2.64 - headers.source = [
2.65 - 'mymodule-header.h',
2.66 - ]
2.67 -
2.68 -
2.69 -=== Note for developers ===
2.70 -
2.71 -The NS-3 code repository does not contain the waf script. Instead,
2.72 -developers should check it out from a subversion repository:
2.73 -
2.74 - svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
2.75 -
2.76 -[ note: 'tags/ns3' is a tag that represents the last svn version
2.77 -tested to work correctly with ns3, although 'trunk' will likely work
2.78 - as well ]
2.79 -
2.80 -Then it can be installed system-wide with 'sudo ./waf-light install'.
2.81 -When preparing a distribution, the resulting 'waf' script, which is
2.82 -self contained (no external files needed), can be easily included in
2.83 -the tarball so that users downloading NS-3 can easily build it without
2.84 -having WAF installed (although Python >= 2.3 is still needed).
2.85 -
2.86 -The command 'waf dist' can be used to create a distribution tarball.
2.87 -It includes all files in the source directory, except some particular
2.88 -extensions that are blacklisted, such as back files (ending in ~).
2.89 -
3.1 --- a/README Thu May 17 07:51:22 2007 +0200
3.2 +++ b/README Thu May 17 11:32:22 2007 +0200
3.3 @@ -1,32 +1,129 @@
3.4 -ns-3 uses the Mercurial software revision control system
3.5
3.6 -Mercurial cheat sheet
3.7 + The Network Simulator Version 3
3.8 + -------------------------------
3.9
3.10 -clone this repository:
3.11 -----------------------
3.12 -hg clone http://code.nsnam.org/ns-3-dev
3.13 +Table of Content:
3.14 +-----------------
3.15
3.16 -pull development tree changes to your local repository:
3.17 -------------------------------------------------------
3.18 -hg pull http://code.nsnam.org/ns-3-dev
3.19 -hg update (apply the changes) OR
3.20 -hg merge (if you've made local changes)
3.21 +1) An Open Source project
3.22 +2) An overview of the ns-3 project
3.23 +3) Building ns-3
3.24 +4) Running ns-3
3.25 +5) Working with the development version of ns-3
3.26
3.27 -commit locally:
3.28 ---------------
3.29 -hg status
3.30 -hg add <new files, if any>
3.31 -hg ci -m "message"
3.32
3.33 -push upwards (developers access only):
3.34 ---------------------------------------
3.35 -hg push ssh://code@code.nsnam.org//home/code/repos/ns-3-dev
3.36 +1) An Open Source project
3.37 +-------------------------
3.38
3.39 -view the change log:
3.40 ---------------
3.41 -hg log <file>
3.42 +ns-3 is an Open Source project and we intend to make this
3.43 +project a successful collaborative project: we hope that
3.44 +the missing pieces of the models we have not yet implemented
3.45 +will be contributed by the community in an open collaboration
3.46 +process.
3.47
3.48 -doing a scons make clean:
3.49 -------------------------
3.50 -scons -c
3.51 +Contributing to the ns-3 project is still a very informal
3.52 +process because that process depends heavily on the personality
3.53 +of the people involved, the amount of time they can invest
3.54 +and the type of model they want to work on.
3.55
3.56 +Despite this lack of a formal process, there are a number of
3.57 +steps which naturally stem from the open-source roots of the
3.58 +project. These steps are described in doc/contributing.txt
3.59 +
3.60 +2) An overview of the ns-3 project
3.61 +----------------------------------
3.62 +
3.63 +This package contains the latest version of ns-3 which is aims
3.64 +at being a replacement for ns-2. Currently, ns-3 provides a
3.65 +number of very simple network simulation models:
3.66 + - an ipv4 and udp stack
3.67 + - arp support at the bottom of the stack
3.68 + - point-to-point physical-layer links
3.69 + - OnOff traffic generator
3.70 +
3.71 +However, the framework is there to make adding new models as
3.72 +simple as possible:
3.73 + - an extensive tracing system can be used to connect
3.74 + any number of arbitrary trace sources to any number
3.75 + of trace sinks. This tracing system is decoupled
3.76 + from the act of serializing the trace events to a
3.77 + file: users can and should provide their own
3.78 + trace handling routines.
3.79 +
3.80 + - simple file trace serialization support is included
3.81 + to both text and pcap files.
3.82 +
3.83 + - adding new MAC-level models simply requires subclassing
3.84 + the pair of classes NetDevice and Channel.
3.85 +
3.86 + - adding new traffic generation algorithms is also very
3.87 + simple through the Application and the Socket classes.
3.88 +
3.89 +3) Building ns-3
3.90 +----------------
3.91 +
3.92 +The code for the framework and the default models provided
3.93 +by ns-3 is built as a set of libraries. User simulations
3.94 +are expected to be written as simple programs which make
3.95 +use of these ns-3 libraries.
3.96 +
3.97 +To build the set of default libraries and the example
3.98 +programs included in this package, you need to use the
3.99 +tool 'scons'. Detailed information on how to install
3.100 +and use scons is included in the file doc/build.txt
3.101 +
3.102 +However, the real quick and dirty way to get started is to
3.103 +type the command "scons" the the directory which contains
3.104 +this README file. The files built will be copied in the
3.105 +build-dir/dbg-shared/bin and build-dir/dbg-shared/lib
3.106 +directories. build-dir/dbg-shared/bin will contain
3.107 +one binary for each of the sample code in the 'samples'
3.108 +directory and one binary for each of the detailed examples
3.109 +found in the 'examples' directory.
3.110 +
3.111 +The current codebase is expected to build and run on the
3.112 +following set of platforms:
3.113 + - linux x86 gcc 4.1, gcc 3.4.
3.114 + - MacOS X ppc and x86
3.115 +
3.116 +The current codebase is expected to fail to build on
3.117 +the following platforms:
3.118 + - gcc 3.3 and earlier
3.119 + - optimized builds on linux x86 gcc 4.0
3.120 +
3.121 +Other platforms might or might not work: we welcome
3.122 +patches to improve the portability of the code to these
3.123 +other platforms.
3.124 +
3.125 +4) Running ns-3
3.126 +---------------
3.127 +
3.128 +On Recent Linux systems, once you have built ns-3, it
3.129 +should be easy to run the sample programs with the
3.130 +following command:
3.131 +
3.132 +./build-dir/dbg-shared/bin/simple-p2p
3.133 +
3.134 +or:
3.135 +
3.136 +cd build-dir/dbg-shared/bin
3.137 +./simple-p2p
3.138 +
3.139 +That program should generate a simple-p2p.tr text
3.140 +trace file and a set of simple-p2p-xx-xx.pcap binary
3.141 +pcap trace files.
3.142 +
3.143 +5) Working with the development version of ns-3
3.144 +-----------------------------------------------
3.145 +
3.146 +If you want to download and use the development version
3.147 +of ns-3, you need to use the tool 'mercurial'. A quick and
3.148 +dirty cheat sheet is included in doc/mercurial.txt but
3.149 +reading through the mercurial tutorials included on the
3.150 +mercurial website is usually a good idea if you are not
3.151 +familiar with it.
3.152 +
3.153 +If you have successfully installed mercurial, you can get
3.154 +a copy of the development version with the following
3.155 +command:
3.156 +"hg clone http://code.nsnam.org/ns-3-dev"
3.157 \ No newline at end of file
4.1 --- a/RELEASE_NOTES Thu May 17 07:51:22 2007 +0200
4.2 +++ b/RELEASE_NOTES Thu May 17 11:32:22 2007 +0200
4.3 @@ -3,6 +3,18 @@
4.4
4.5 This file contains ns-3 release notes (most recent releases first).
4.6
4.7 +Release 0.2 (2007/05/XX)
4.8 +========================
4.9 +
4.10 + - Implement a new memory management infrastructure based
4.11 + on reference counting and smart pointers (the latter being
4.12 + optional)
4.13 +
4.14 + - Implement a COM-like framework with support for QueryInterface
4.15 + to provide object extensibility
4.16 +
4.17 + - Add support for a BSD-style socket API for user applications
4.18 +
4.19 Release 0.1 (2007/03/31)
4.20 ========================
4.21
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/doc/build-waf.txt Thu May 17 11:32:22 2007 +0200
5.3 @@ -0,0 +1,86 @@
5.4 +WAF is an alternative build system, similar to SCons. NS-3 now is
5.5 +able to build with WAF, in parallel to SCons.
5.6 +
5.7 +Note: the WAF build scripts are experimental at this stage.
5.8 +
5.9 +
5.10 +=== Building with WAF ===
5.11 +
5.12 +To build NS-3 with waf type the commands:
5.13 + 1. ./waf configure [options]
5.14 + 2. ./waf
5.15 +
5.16 +[ Note: if ./waf does not exist, see the section "Note for developers" below ]
5.17 +
5.18 +To see valid configure options, type ./waf --help. The most important
5.19 +option is -d <debug level>. Valid debug levels (which are listed in
5.20 +./waf --help) are: ultradebug, debug, release, and optimized.
5.21 +
5.22 +The resulting binaries are placed in build/<debuglevel>/srcpath.
5.23 +
5.24 +Other waf usages include:
5.25 +
5.26 + 1. ./waf check
5.27 + Runs the unit tests
5.28 +
5.29 + 2. ./waf --doxygen
5.30 + Run doxygen to generate documentation
5.31 +
5.32 + 3. ./waf --lcov-report
5.33 + Run code coverage analysis (assuming the project was configured
5.34 +with --enable-gcov)
5.35 +
5.36 +=== Extending NS-3 ===
5.37 +
5.38 +To add new modules:
5.39 + 1. Create the module directory under src (or src/devices, or whatever);
5.40 + 2. Add the source files to it;
5.41 + 3. Add a 'wscript' describing it;
5.42 + 4. Add the module subdirectory name to the all_modules list in src/wscript.
5.43 +
5.44 +A module's wscript file is basically a regular WAF script. A NS-3
5.45 +module is created as a cpp/shlib object, like this:
5.46 +
5.47 +def build(bld):
5.48 + obj = bld.create_obj('cpp', 'shlib')
5.49 +
5.50 + ## set module name; by convention it starts with ns3-
5.51 + obj.name = 'ns3-mymodule'
5.52 + obj.target = obj.name
5.53 +
5.54 + ## list dependencies to other modules
5.55 + obj.uselib_local = ['ns3-core']
5.56 +
5.57 + ## list source files (private or public header files excluded)
5.58 + obj.source = [
5.59 + 'mymodule.cc',
5.60 + ]
5.61 +
5.62 + ## list module public header files
5.63 + headers = bld.create_obj('ns3header')
5.64 + headers.source = [
5.65 + 'mymodule-header.h',
5.66 + ]
5.67 +
5.68 +
5.69 +=== Note for developers ===
5.70 +
5.71 +The NS-3 code repository does not contain the waf script. Instead,
5.72 +developers should check it out from a subversion repository:
5.73 +
5.74 + svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
5.75 +
5.76 +[ note: 'tags/ns3' is a tag that represents the last svn version
5.77 +tested to work correctly with ns3, although 'trunk' will likely work
5.78 + as well ]
5.79 +
5.80 +Then it can be installed system-wide with 'sudo ./waf-light install'.
5.81 +When preparing a distribution, the resulting 'waf' script, which is
5.82 +self contained (no external files needed), can be easily included in
5.83 +the tarball so that users downloading NS-3 can easily build it without
5.84 +having WAF installed (although Python >= 2.3 is still needed).
5.85 +
5.86 +The command 'waf dist' can be used to create a distribution tarball.
5.87 +It includes all files in the source directory, except some particular
5.88 +extensions that are blacklisted, such as back files (ending in ~).
5.89 +
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/doc/build.txt Thu May 17 11:32:22 2007 +0200
6.3 @@ -0,0 +1,182 @@
6.4 +If you want to build ns3, you need to install scons (see
6.5 +http://www.scons.org). scons takes care of building
6.6 +the whole source tree using your system compiler. scons
6.7 +0.91.1 and 0.91.96 have been tested and are known to
6.8 +work on linux FC5, Mac os X and MinGW.
6.9 +
6.10 +To start a build, you can just type 'scons' which
6.11 +will generate a debug shared build by default, located
6.12 +in the directory 'build-dir/dbg-shared/bin' and
6.13 +'build-dir/dbg-shared/lib'.
6.14 +
6.15 +All builds are built with debugging symbols. Debugging
6.16 +builds enable asserts while optimized builds disable them.
6.17 +On platforms which support it, rpath is used which means that
6.18 +the executable binaries generated link explicitely against
6.19 +the right libraries. This saves you the pain of having to
6.20 +setup environment variables to point to the right libraries.
6.21 +
6.22 +1) Options
6.23 +----------
6.24 +
6.25 +- verbose: if you have installed scons 0.91.96 or higher,
6.26 + the default build output is terse. To get a more verbose
6.27 + output, you need to set the 'verbose' variable to 'y'.
6.28 +Example: scons verbose=y
6.29 +- cflags: flags for the C compiler.
6.30 +Example: scons cflags="-O3 -ffast-math"
6.31 +- cxxflags: flags for the C++ compiler.
6.32 +Example: scons cxxflags="-O3 -ffast-math"
6.33 +- ldflags: flags for the linker:
6.34 +Example: scons ldflags="-L/foo -L/bar"
6.35 +- cc: the C compiler to use:
6.36 +Example: scons cc=gcc-4.0
6.37 +- cxx: the C++ compiler to use:
6.38 +Example: scons cxx=g++-4.0
6.39 +- high-precision-as-double: set to 'y' to make sure that the
6.40 + high-precision arithmetics performed by the Time class on
6.41 + behalf of the user will use doubles. By default, the code
6.42 + uses 128 integers.
6.43 +Example: scons high-precision-as-double=y
6.44 +- inheritenv: set to 'y' if you want to make your compiler
6.45 + execute within the same environment (env vars) as your own
6.46 + shell. This is typically used to make colorgcc work.
6.47 +Example: scons inheritenv=y
6.48 +
6.49 +2) Targets
6.50 +----------
6.51 +
6.52 +- doc: build the doxygen documentation.
6.53 +Example: scons doc
6.54 +
6.55 +- dbg-shared: a debug build using shared libraries.
6.56 + The files are built in 'build-dir/dbg-shared/'.
6.57 +Example: scons dbg-shared
6.58 +
6.59 +- dbg-static: a debug build using static libraries
6.60 + The files are built in 'build-dir/dbg-static/'.
6.61 +Example: scons dbg-static
6.62 +
6.63 +- opt-shared: an optimized build using shared libraries.
6.64 + The files are built in 'build-dir/opt-shared/'.
6.65 +Example: scons opt-shared
6.66 +
6.67 +- opt-static: an optimized build using static libraries.
6.68 + The files are built in 'build-dir/opt-static/'.
6.69 +Example: scons opt-static
6.70 +
6.71 +- dbg: an alias for dbg-shared
6.72 +Example: scons dbg
6.73 +
6.74 +- opt: an alias for opt-shared
6.75 +Example: scons opt
6.76 +
6.77 +- all: alias for dbg-shared, dbg-static, opt-shared
6.78 + and opt-static
6.79 +Example: scons all
6.80 +
6.81 +- gcov: code coverage analysis. Build a debugging version of
6.82 + the code for code coverage analysis in 'build-dir/gcov'. Once
6.83 + the code has been built, you can run various applications to
6.84 + exercise the code paths. To generate an html report from
6.85 + the gcov data, use the lcov-report target
6.86 +
6.87 +- lcov-report: generate html report of gcov data. The output
6.88 + is stored in 'build-dir/lcov-report/'.
6.89 +
6.90 +- dist: generate a release tarball and zipfile from the
6.91 + source tree. The tarball and zipfile name are generated
6.92 + according to the version number stored in the SConstruct
6.93 + file.
6.94 +Example in SConstruct:
6.95 +ns3 = Ns3 ()
6.96 +ns3.name = 'foo'
6.97 +ns3.version = '0.0.10'
6.98 +Example command: scons dist
6.99 +Example output files:
6.100 +foo-0.0.10.tar.gz
6.101 +foo-0.0.10.zip
6.102 +
6.103 +- distcheck: generate a release tarball and zipfile and
6.104 + attempt to run the 'all' target for the release tarball.
6.105 +Example: scons distcheck
6.106 +
6.107 +3) How the build system works
6.108 +-----------------------------
6.109 +
6.110 +The current build system defines what are called "ns3 modules": each module
6.111 +is a set of source files, normal header files and installable header
6.112 +files. Each module also depends on a set of other modules. We build
6.113 +modules automatically in the correct order. That is, we always start
6.114 +from the module which does not depend on any other module (core) and
6.115 +proceed with the other modules and make sure that when a module is
6.116 +built, all the modules it depends upon have already been built.
6.117 +
6.118 +To build a module, we:
6.119 +1) generate the .o files
6.120 +2) link the .o files together
6.121 +3) install the installable headers in the common directory
6.122 +top_build_dir/include/ns3.
6.123 +
6.124 +This means that if you want to use a header from your own module, you
6.125 +should just include it: #include "foo.h" but if you want to include a
6.126 +header from another module, you need to include it with #include
6.127 +"ns3/bar.h". This allows you to make sure that our "public" ns3 headers
6.128 +do not conflict with existing system-level headers. For instance,
6.129 +if you were to define a header called queue.h, you would include
6.130 +ns3/queue.h rather than queue.h, when including from a separate module,
6.131 +since many systems provide a queue.h system include file.
6.132 +
6.133 +4) How to add files to a module ?
6.134 +---------------------------------
6.135 +
6.136 +In the main SConstruct file, you can add source code
6.137 +to the add_sources method. For example, to add a foo.cc
6.138 +file to the core module, we coud do this:
6.139 +core.add_sources ('foo.cc')
6.140 +Of course, if this file implements public API, its
6.141 +header should be installable:
6.142 +core.add_inst_headers ('foo.h')
6.143 +
6.144 +5) How to create a new module ?
6.145 +-------------------------------
6.146 +
6.147 +# create a new module. First arg is the name of
6.148 +# the new module. Second arg is the directory in
6.149 +# which all source files for this module reside.
6.150 +my_module = build.Ns3Module ('my', 'src/my_dir')
6.151 +# add it to build system
6.152 +ns3.add (my_module)
6.153 +# specify module dependencies. Here, depends
6.154 +# on the 'ipv4' and 'core' modules
6.155 +my_module.add_deps (['core', 'ipv4'])
6.156 +# add source code to build located in
6.157 +# src/my_dir
6.158 +my_module.add_sources ([
6.159 + 'my_a.cc',
6.160 + 'my_b.cc',
6.161 + 'my_c.cc'
6.162 +])
6.163 +my_module.add_sources ([
6.164 + 'my_d.cc'
6.165 +])
6.166 +# add headers which are not public
6.167 +my_module.add_headers ([
6.168 + 'my_a.h',
6.169 + 'my_c.h'
6.170 +])
6.171 +# add headers which are public
6.172 +my_module.add_inst_headers ([
6.173 + 'my_b.h'
6.174 +])
6.175 +my_module.add_inst_headers ([
6.176 + 'my_d.h'
6.177 +])
6.178 +# if you need to link against an external library,
6.179 +# you must add 'external' dependencies. Here, the
6.180 +# pthread library
6.181 +my_module.add_external_dep ('pthread')
6.182 +# by default, a module is conceptually a library. If you
6.183 +# want to generate an executable from a module you need to:
6.184 +my_module.set_executable ()
6.185 +
7.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2 +++ b/doc/contributing.txt Thu May 17 11:32:22 2007 +0200
7.3 @@ -0,0 +1,53 @@
7.4 +
7.5 +Contributing to the ns-3 project
7.6 +--------------------------------
7.7 +
7.8 +Despite the lack of a formal contribution process to the ns-3
7.9 +project, there are a number of steps which we expect every
7.10 +potential contributor to follow. These naturally stem from
7.11 +the open-source roots of the project:
7.12 +
7.13 + - first, you should subscribe to the ns-developers
7.14 + mailing-list (see http://www.nsnam.org/mailing_lists.html)
7.15 +
7.16 + - then, you should send an email there stating your interest
7.17 + in working on a specific part of the models and trying
7.18 + to explain how you would like to implement it, what
7.19 + resources you have, etc.
7.20 +
7.21 + - you should be prepared to work together with the other
7.22 + potential contributors who want to work on the same models.
7.23 +
7.24 + - you should be prepared to go through code reviews with the
7.25 + ns-3 development team prior to integration. The goal of these
7.26 + code reviews is to:
7.27 + - ensure adherence to the coding style of the project
7.28 + (see doc/codingstyle.html)
7.29 + - ensure that the structure of your code has a certain
7.30 + coherence with regard to the rest of the ns-3 codebase
7.31 + - improve the quality of the code: we strongly believe in
7.32 + the old saying: "many eyes make all bugs shallow".
7.33 + - increase code reuse by trying to generalize certain
7.34 + useful pieces of your code to make them available to
7.35 + other models.
7.36 +
7.37 + - you should be prepared to try to integrate as many tests
7.38 + in the codebase as possible: we understand that writing
7.39 + tests is not sexy and that not everyone is convinced that
7.40 + they improve the code-writing poductivity which is why
7.41 + we do not enforce strict rules about testing. However,
7.42 + we expect model authors to answer basic questions about
7.43 + how they plan to test and validate their models.
7.44 +
7.45 + - you should be prepared to maintain your model once it is
7.46 + integrated: while we consider every bug filed against the
7.47 + simulator as being a bug we must deal with and while we
7.48 + will try to fix as many bugs as humanly possible, we
7.49 + also expect model authors to act as responsible maintainers
7.50 + and be reactive to bug reports concerning their models.
7.51 +
7.52 + - you should make sure that you understand that contributed
7.53 + models should be licensed under the GPLv2. You do not have
7.54 + to assign your copyright to the ns-3 project but you must
7.55 + accept the terms of the GPLv2. See the following link:
7.56 + http://www.fsf.org/licensing/licenses/info/GPLv2.html
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/doc/mercurial.txt Thu May 17 11:32:22 2007 +0200
8.3 @@ -0,0 +1,44 @@
8.4 +Introduction
8.5 +------------
8.6 +
8.7 +ns-3 uses the Mercurial software revision control system which
8.8 +is a replacement for tools liks cvs or subversion. Thus, to get
8.9 +access to the developement versions of ns-3, you need to install
8.10 +mercurial first. See http://www.selenic.com/mercurial/wiki/
8.11 +
8.12 +Mercurial cheat sheet
8.13 +---------------------
8.14 +
8.15 +Look at our project history and source code:
8.16 +-------------------------------------------
8.17 +http://code.nsnam.org/ns-3-dev
8.18 +
8.19 +clone this repository:
8.20 +---------------------
8.21 +hg clone http://code.nsnam.org/ns-3-dev
8.22 +
8.23 +commit locally:
8.24 +--------------
8.25 +hg status
8.26 +hg add <new files, if any>
8.27 +hg ci -m "message"
8.28 +
8.29 +pull development tree changes to your local repository:
8.30 +------------------------------------------------------
8.31 +hg ci -m "my local changes are recorded"
8.32 +hg pull http://code.nsnam.org/ns-3-dev
8.33 +hg update (apply the changes) OR
8.34 +hg merge (if you've made local changes)
8.35 +
8.36 +view the change log:
8.37 +-------------------
8.38 +hg log <file>
8.39 +
8.40 +push upwards (developers access only):
8.41 +--------------------------------------
8.42 +To the main repository:
8.43 +hg push ssh://code@code.nsnam.org/repos/ns-3-dev
8.44 +To your private repository:
8.45 +hg push ssh://username@code.nsnam.org//home/username/repositories/username/repository
8.46 +
8.47 +