write README, contributing.txt, reorganize the other documentation files
authorMathieu Lacage <mathieu.lacage@sophia.inria.fr>
Thu, 17 May 2007 11:32:22 +0200
changeset 63571b92dfe5f55
parent 634 7dbf8f0dc819
child 636 331b95a5404a
write README, contributing.txt, reorganize the other documentation files
BUILD
BUILD.WAF
README
RELEASE_NOTES
doc/build-waf.txt
doc/build.txt
doc/contributing.txt
doc/mercurial.txt
     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 +