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