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