doc/build.txt
author Tom Henderson <tomh@tomh.org>
Fri, 18 May 2007 10:27:42 -0700
changeset 657 be551a3b07c6
parent 635 71b92dfe5f55
child 658 32307a281d86
permissions -rw-r--r--
minor changes due to documentation review
     1 If you want to build ns3, you need to install scons (see
     2 http://www.scons.org). scons takes care of building
     3 the whole source tree using your system compiler. scons
     4 0.91.1 and 0.91.96 have been tested and are known to 
     5 work on linux FC5, Mac os X and MinGW.
     6 
     7 To start a build, you can just type 'scons' which
     8 will generate a debug shared build by default, located
     9 in the directory 'build-dir/dbg-shared/bin' and
    10 'build-dir/dbg-shared/lib'.
    11 
    12 All builds are built with debugging symbols. Debugging
    13 builds enable asserts while optimized builds disable them.
    14 On platforms which support it, rpath is used which means that
    15 the executable binaries generated link explicitely against
    16 the right libraries. This saves you the pain of having to
    17 setup environment variables to point to the right libraries.
    18 
    19 (Note:  An experimental, alternative build system is described
    20 in build-waf.txt)
    21 
    22 1) Options
    23 ----------
    24 
    25 - verbose: if you have installed scons 0.91.96 or higher, 
    26   the default build output is terse. To get a more verbose 
    27   output, you need to set the 'verbose' variable to 'y'.
    28 Example: scons verbose=y
    29 - cflags: flags for the C compiler.
    30 Example: scons cflags="-O3 -ffast-math"
    31 - cxxflags: flags for the C++ compiler.
    32 Example: scons cxxflags="-O3 -ffast-math"
    33 - ldflags: flags for the linker:
    34 Example: scons ldflags="-L/foo -L/bar"
    35 - cc: the C compiler to use:
    36 Example: scons cc=gcc-4.0
    37 - cxx: the C++ compiler to use:
    38 Example: scons cxx=g++-4.0
    39 - high-precision-as-double: set to 'y' to make sure that the
    40   high-precision arithmetics performed by the Time class on
    41   behalf of the user will use doubles. By default, the code
    42   uses 128 integers.
    43 Example: scons high-precision-as-double=y
    44 - inheritenv: set to 'y' if you want to make your compiler
    45   execute within the same environment (env vars) as your own
    46   shell. This is typically used to make colorgcc work.
    47 Example: scons inheritenv=y
    48 
    49 2) Targets
    50 ----------
    51 
    52 - doc: build the doxygen documentation.
    53 Example: scons doc
    54 
    55 - dbg-shared: a debug build using shared libraries.
    56   The files are built in 'build-dir/dbg-shared/'.
    57 Example: scons dbg-shared
    58 
    59 - dbg-static: a debug build using static libraries
    60   The files are built in 'build-dir/dbg-static/'.
    61 Example: scons dbg-static
    62 
    63 - opt-shared: an optimized build using shared libraries.
    64   The files are built in 'build-dir/opt-shared/'.
    65 Example: scons opt-shared
    66 
    67 - opt-static: an optimized build using static libraries.
    68   The files are built in 'build-dir/opt-static/'.
    69 Example: scons opt-static
    70 
    71 - dbg: an alias for dbg-shared
    72 Example: scons dbg
    73 
    74 - opt: an alias for opt-shared
    75 Example: scons opt
    76 
    77 - all: alias for dbg-shared, dbg-static, opt-shared 
    78   and opt-static
    79 Example: scons all
    80 
    81 - gcov: code coverage analysis. Build a debugging version of
    82   the code for code coverage analysis in 'build-dir/gcov'. Once
    83   the code has been built, you can run various applications to
    84   exercise the code paths. To generate an html report from
    85   the gcov data, use the lcov-report target
    86 
    87 - lcov-report: generate html report of gcov data. The output
    88   is stored in 'build-dir/lcov-report/'.
    89 
    90 - dist: generate a release tarball and zipfile from the 
    91   source tree. The tarball and zipfile name are generated
    92   according to the version number stored in the SConstruct
    93   file.
    94 Example in SConstruct:
    95 ns3 = Ns3 ()
    96 ns3.name = 'foo'
    97 ns3.version = '0.0.10'
    98 Example command: scons dist
    99 Example output files:
   100 foo-0.0.10.tar.gz
   101 foo-0.0.10.zip
   102 
   103 - distcheck: generate a release tarball and zipfile and 
   104   attempt to run the 'all' target for the release tarball.
   105 Example: scons distcheck
   106 
   107 3) How the build system works
   108 -----------------------------
   109 
   110 The current build system defines what are called "ns3 modules": each module
   111 is a set of source files, normal header files and installable header
   112 files. Each module also depends on a set of other modules. We build
   113 modules automatically in the correct order. That is, we always start
   114 from the module which does not depend on any other module (core) and
   115 proceed with the other modules and make sure that when a module is
   116 built, all the modules it depends upon have already been built.
   117 
   118 To build a module, we:
   119 1) generate the .o files
   120 2) link the .o files together 
   121 3) install the installable headers in the common directory
   122 top_build_dir/include/ns3.
   123 
   124 This means that if you want to use a header from your own module, you
   125 should just include it: #include "foo.h" but if you want to include a
   126 header from another module, you need to include it with #include
   127 "ns3/bar.h". This allows you to make sure that our "public" ns3 headers
   128 do not conflict with existing system-level headers.   For instance,
   129 if you were to define a header called queue.h, you would include
   130 ns3/queue.h rather than queue.h, when including from a separate module,
   131 since many systems provide a queue.h system include file.  
   132 
   133 4) How to add files to a module ?
   134 ---------------------------------
   135 
   136 In the main SConstruct file, you can add source code
   137 to the add_sources method. For example, to add a foo.cc
   138 file to the core module, we coud do this:
   139 core.add_sources ('foo.cc')
   140 Of course, if this file implements public API, its 
   141 header should be installable:
   142 core.add_inst_headers ('foo.h')
   143 
   144 5) How to create a new module ?
   145 -------------------------------
   146 
   147 # create a new module. First arg is the name of
   148 # the new module. Second arg is the directory in
   149 # which all source files for this module reside.
   150 my_module = build.Ns3Module ('my', 'src/my_dir')
   151 # add it to build system
   152 ns3.add (my_module)
   153 # specify module dependencies. Here, depends
   154 # on the 'ipv4' and 'core' modules
   155 my_module.add_deps (['core', 'ipv4']) 
   156 # add source code to build located in 
   157 # src/my_dir
   158 my_module.add_sources ([
   159 	'my_a.cc',
   160 	'my_b.cc',
   161 	'my_c.cc'
   162 ])
   163 my_module.add_sources ([
   164 	'my_d.cc'
   165 ])
   166 # add headers which are not public
   167 my_module.add_headers ([
   168 	'my_a.h',
   169 	'my_c.h'
   170 ])
   171 # add headers which are public
   172 my_module.add_inst_headers ([
   173 	'my_b.h'
   174 ])
   175 my_module.add_inst_headers ([
   176 	'my_d.h'
   177 ])
   178 # if you need to link against an external library,
   179 # you must add 'external' dependencies. Here, the 
   180 # pthread library
   181 my_module.add_external_dep ('pthread')
   182 # by default, a module is conceptually a library. If you
   183 # want to generate an executable from a module you need to:
   184 my_module.set_executable ()
   185