187 lines
6.2 KiB
Plaintext
187 lines
6.2 KiB
Plaintext
If you want to build ns3, you need to install scons (see
|
|
http://www.scons.org). scons takes care of building
|
|
the whole source tree using your system compiler. scons
|
|
0.91.1 and 0.91.96 have been tested and are known to
|
|
work on linux FC5, Mac os X and MinGW.
|
|
|
|
To start a build, you can just type 'scons' which
|
|
will generate a debug shared build by default, located
|
|
in the directory 'build-dir/dbg-shared/bin' and
|
|
'build-dir/dbg-shared/lib'.
|
|
|
|
All builds are built with debugging symbols. Debugging
|
|
builds enable asserts while optimized builds disable them.
|
|
On platforms which support it, rpath is used which means that
|
|
the executable binaries generated link explicitely against
|
|
the right libraries. This saves you the pain of having to
|
|
setup environment variables to point to the right libraries.
|
|
|
|
(Note: An alternative build system (Waf) is being
|
|
evaluated in the development branch of ns-3-dev on our server
|
|
only (i.e., not in the release tarballs)-- see doc/build-waf.txt)
|
|
|
|
1) Options
|
|
----------
|
|
|
|
- verbose: if you have installed scons 0.91.96 or higher,
|
|
the default build output is terse. To get a more verbose
|
|
output, you need to set the 'verbose' variable to 'y'.
|
|
Example: scons verbose=y
|
|
- cflags: flags for the C compiler.
|
|
Example: scons cflags="-O3 -ffast-math"
|
|
- cxxflags: flags for the C++ compiler.
|
|
Example: scons cxxflags="-O3 -ffast-math"
|
|
- ldflags: flags for the linker:
|
|
Example: scons ldflags="-L/foo -L/bar"
|
|
- cc: the C compiler to use:
|
|
Example: scons cc=gcc-4.0
|
|
- cxx: the C++ compiler to use:
|
|
Example: scons cxx=g++-4.0
|
|
- high-precision-as-double: set to 'y' to make sure that the
|
|
high-precision arithmetics performed by the Time class on
|
|
behalf of the user will use doubles. By default, the code
|
|
uses 128 integers.
|
|
Example: scons high-precision-as-double=y
|
|
- inheritenv: set to 'y' if you want to make your compiler
|
|
execute within the same environment (env vars) as your own
|
|
shell. This is typically used to make colorgcc work.
|
|
Example: scons inheritenv=y
|
|
|
|
2) Targets
|
|
----------
|
|
|
|
- doc: build the doxygen documentation.
|
|
Example: scons doc
|
|
|
|
- dbg-shared: a debug build using shared libraries.
|
|
The files are built in 'build-dir/dbg-shared/'.
|
|
Example: scons dbg-shared
|
|
|
|
- dbg-static: a debug build using static libraries
|
|
The files are built in 'build-dir/dbg-static/'.
|
|
Example: scons dbg-static
|
|
|
|
- opt-shared: an optimized build using shared libraries.
|
|
The files are built in 'build-dir/opt-shared/'.
|
|
Example: scons opt-shared
|
|
|
|
- opt-static: an optimized build using static libraries.
|
|
The files are built in 'build-dir/opt-static/'.
|
|
Example: scons opt-static
|
|
|
|
- dbg: an alias for dbg-shared
|
|
Example: scons dbg
|
|
|
|
- opt: an alias for opt-shared
|
|
Example: scons opt
|
|
|
|
- all: alias for dbg-shared, dbg-static, opt-shared
|
|
and opt-static
|
|
Example: scons all
|
|
|
|
- gcov: code coverage analysis. Build a debugging version of
|
|
the code for code coverage analysis in 'build-dir/gcov'. Once
|
|
the code has been built, you can run various applications to
|
|
exercise the code paths. To generate an html report from
|
|
the gcov data, use the lcov-report target
|
|
|
|
- lcov-report: generate html report of gcov data. The output
|
|
is stored in 'build-dir/lcov-report/'.
|
|
|
|
- dist: generate a release tarball and zipfile from the
|
|
source tree. The tarball and zipfile name are generated
|
|
according to the version number stored in the SConstruct
|
|
file.
|
|
Example in SConstruct:
|
|
ns3 = Ns3 ()
|
|
ns3.name = 'foo'
|
|
ns3.version = '0.0.10'
|
|
Example command: scons dist
|
|
Example output files:
|
|
foo-0.0.10.tar.gz
|
|
foo-0.0.10.zip
|
|
|
|
- distcheck: generate a release tarball and zipfile and
|
|
attempt to run the 'all' target for the release tarball.
|
|
Example: scons distcheck
|
|
|
|
3) How the build system works
|
|
-----------------------------
|
|
|
|
The current build system defines what are called "ns3 modules": each module
|
|
is a set of source files, normal header files and installable header
|
|
files. Each module also depends on a set of other modules. We build
|
|
modules automatically in the correct order. That is, we always start
|
|
from the module which does not depend on any other module (core) and
|
|
proceed with the other modules and make sure that when a module is
|
|
built, all the modules it depends upon have already been built.
|
|
|
|
To build a module, we:
|
|
1) generate the .o files
|
|
2) link the .o files together
|
|
3) install the installable headers in the common directory
|
|
top_build_dir/include/ns3.
|
|
|
|
This means that if you want to use a header from your own module, you
|
|
should just include it: #include "foo.h" but if you want to include a
|
|
header from another module, you need to include it with #include
|
|
"ns3/bar.h". This allows you to make sure that our "public" ns3 headers
|
|
do not conflict with existing system-level headers. For instance,
|
|
if you were to define a header called queue.h, you would include
|
|
ns3/queue.h rather than queue.h, when including from a separate module,
|
|
since many systems provide a queue.h system include file.
|
|
|
|
4) How to add files to a module ?
|
|
---------------------------------
|
|
|
|
In the main SConstruct file, you can add source code
|
|
to the add_sources method. For example, to add a foo.cc
|
|
file to the core module, we coud do this:
|
|
core.add_sources ('foo.cc')
|
|
Of course, if this file implements public API, its
|
|
header should be installable:
|
|
core.add_inst_headers ('foo.h')
|
|
|
|
5) How to create a new module ?
|
|
-------------------------------
|
|
|
|
# create a new module. First arg is the name of
|
|
# the new module. Second arg is the directory in
|
|
# which all source files for this module reside.
|
|
my_module = build.Ns3Module ('my', 'src/my_dir')
|
|
# add it to build system
|
|
ns3.add (my_module)
|
|
# specify module dependencies. Here, depends
|
|
# on the 'ipv4' and 'core' modules
|
|
my_module.add_deps (['core', 'ipv4'])
|
|
# add source code to build located in
|
|
# src/my_dir
|
|
my_module.add_sources ([
|
|
'my_a.cc',
|
|
'my_b.cc',
|
|
'my_c.cc'
|
|
])
|
|
my_module.add_sources ([
|
|
'my_d.cc'
|
|
])
|
|
# add headers which are not public
|
|
my_module.add_headers ([
|
|
'my_a.h',
|
|
'my_c.h'
|
|
])
|
|
# add headers which are public
|
|
my_module.add_inst_headers ([
|
|
'my_b.h'
|
|
])
|
|
my_module.add_inst_headers ([
|
|
'my_d.h'
|
|
])
|
|
# if you need to link against an external library,
|
|
# you must add 'external' dependencies. Here, the
|
|
# pthread library
|
|
my_module.add_external_dep ('pthread')
|
|
# by default, a module is conceptually a library. If you
|
|
# want to generate an executable from a module you need to:
|
|
my_module.set_executable ()
|
|
|