F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: CMake docs

Browse Source
This commit is contained in:
Gabriel Ferreira
2021-12-22 17:16:47 -03:00
parent d368877d92
commit 42e320d676
7 changed files with 2555 additions and 315 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/manual/Makefile
View File

@@ -45,6 +45,7 @@ SOURCES = \
source/tracing.rst \
source/troubleshoot.rst \
source/utilities.rst \
source/working-with-cmake.rst \
${SRC}/stats/doc/data-collection.rst \
${SRC}/stats/doc/data-collection-overview.rst \
${SRC}/stats/doc/statistics.rst \

1
doc/manual/source/develop.rst
View File

@@ -9,6 +9,7 @@ This chapter describes the development ecosystem generaly used to create new mod
:maxdepth: 2
working-with-git
working-with-cmake
logging
tests
new-models

267
doc/manual/source/new-modules.rst
View File

@@ -1,6 +1,9 @@
.. include:: replace.txt
.. highlight:: cpp
.. _Adding a New Module to ns3:
Adding a New Module to |ns3|
----------------------------
@@ -31,12 +34,12 @@ required files:
bindings/
doc/
examples/
wscript
CMakeLists.txt
helper/
model/
test/
examples-to-run.py
wscript
CMakeLists.txt
Not all directories will be present in each module.
@@ -67,10 +70,10 @@ Let's assume we've created our new module in ``src``.
$ cd new-module
$ ls
doc examples helper model test wscript
doc examples helper model test CMakeLists.txt
In more detail, the ``create-module.py`` script will create the
directories as well as initial skeleton ``wscript``, ``.h``, ``.cc``
directories as well as initial skeleton ``CMakeLists.txt``, ``.h``, ``.cc``
and ``.rst`` files. The complete module with skeleton files looks like this:
.. sourcecode:: text
@@ -81,7 +84,7 @@ and ``.rst`` files. The complete module with skeleton files looks like this:
new-module.rst
examples/
new-module-example.cc
wscript
CMakeLists.txt
helper/
new-module-helper.cc
new-module-helper.h
@@ -90,7 +93,7 @@ and ``.rst`` files. The complete module with skeleton files looks like this:
new-module.h
test/
new-module-test-suite.cc
wscript
CMakeLists.txt
(If required the ``bindings/`` directory listed in
:ref:`Step-0 <Step-0>` will be created automatically during
@@ -98,28 +101,45 @@ the build.)
We next walk through how to customize this module. Informing ``ns3``
about the files which make up your module is done by editing the two
``wscript`` files. We will walk through the main steps in this chapter.
``CMakeLists.txt`` files. We will walk through the main steps in this chapter.
All |ns3| modules depend on the ``core`` module and usually on
other modules. This dependency is specified in the ``wscript`` file
(at the top level of the module, not the separate ``wscript`` file
in the ``examples`` directory!). In the skeleton ``wscript``
other modules. This dependency is specified in the ``CMakeLists.txt`` file
(at the top level of the module, not the separate ``CMakeLists.txt`` file
in the ``examples`` directory!). In the skeleton ``CMakeLists.txt``
the call that will declare your new module to ``ns3`` will look
like this (before editing):
.. sourcecode:: python
.. sourcecode:: cmake
def build(bld):
module = bld.create_ns3_module('new-module', ['core'])
build_lib(
LIBNAME new-module
SOURCE_FILES helper/new-module-helper.cc
model/new-module.cc
HEADER_FILES helper/new-module-helper.h
model/new-module.h
LIBRARIES_TO_LINK ${libcore}
TEST_SOURCES test/new-module-test-suite.cc
)
Let's assume that ``new-module`` depends on the ``internet``,
``mobility``, and ``aodv`` modules. After editing it the ``wscript`` file
``mobility``, and ``aodv`` modules. After editing it the ``CMakeLists.txt`` file
should look like:
.. sourcecode:: python
.. sourcecode:: cmake
def build(bld):
module = bld.create_ns3_module('new-module', ['internet', 'mobility', 'aodv'])
build_lib(
LIBNAME new-module
SOURCE_FILES helper/new-module-helper.cc
model/new-module.cc
HEADER_FILES helper/new-module-helper.h
model/new-module.h
LIBRARIES_TO_LINK
${libinternet}
${libmobility}
${libaodv}
TEST_SOURCES test/new-module-test-suite.cc
)
Note that only first level module dependencies should be listed, which
is why we removed ``core``; the ``internet`` module in turn depends on
@@ -151,31 +171,49 @@ Step 3 - Declare Source Files
*****************************
The public header and source code files for your new module
should be specified in the ``wscript`` file by modifying it with
should be specified in the ``CMakeLists.txt`` file by modifying it with
your text editor.
As an example, after declaring the ``spectrum`` module,
the ``src/spectrum/wscript`` specifies the source code files
with the following list:
the ``src/spectrum/CMakeLists.txt`` specifies the source code files
with the following:
.. sourcecode:: python
.. sourcecode:: cmake
def build(bld):
set(source_files
helper/adhoc-aloha-noack-ideal-phy-helper.cc
helper/spectrum-analyzer-helper.cc
helper/spectrum-helper.cc
...
)
module = bld.create_ns3_module('spectrum', ['internet', 'propagation', 'antenna', 'applications'])
set(header_files
helper/adhoc-aloha-noack-ideal-phy-helper.h
helper/spectrum-analyzer-helper.h
helper/spectrum-helper.h
...
)
module.source = [
'model/spectrum-model.cc',
'model/spectrum-value.cc',
.
.
.
'model/microwave-oven-spectrum-value-helper.cc',
'helper/spectrum-helper.cc',
'helper/adhoc-aloha-noack-ideal-phy-helper.cc',
'helper/waveform-generator-helper.cc',
'helper/spectrum-analyzer-helper.cc',
]
build_lib(
LIBNAME spectrum
SOURCE_FILES ${source_files}
HEADER_FILES ${header_files}
LIBRARIES_TO_LINK ${libpropagation}
${libantenna}
TEST_SOURCES
test/spectrum-ideal-phy-test.cc
test/spectrum-interference-test.cc
test/spectrum-value-test.cc
test/spectrum-waveform-generator-test.cc
test/three-gpp-channel-test-suite.cc
test/tv-helper-distribution-test.cc
test/tv-spectrum-transmitter-test.cc
)
Note: the ``source_files`` and ``header_files`` lists are not necessary.
They are used keep the ``build_lib`` macro readable for modules with many
source files.
The objects resulting from compiling these sources will be assembled
into a link library, which will be linked to any programs relying on this
@@ -187,31 +225,48 @@ Step 4 - Declare Public Header Files
************************************
The header files defining the public API of your model and helpers
also should be specified in the ``wscript`` file.
also should be specified in the ``CMakeLists.txt`` file.
Continuing with the ``spectrum`` model illustration,
the public header files are specified with the following stanza.
(Note that the argument to the ``bld`` function tells
``ns3`` to install this module's headers with the other |ns3| headers):
(Note that the variable ``header_files`` tells
``CMake`` to install this module's headers with the other |ns3| headers):
.. sourcecode:: python
.. sourcecode:: cmake
headers = bld(features='ns3header')
set(header_files
helper/adhoc-aloha-noack-ideal-phy-helper.h
helper/spectrum-analyzer-helper.h
...
model/tv-spectrum-transmitter.h
model/waveform-generator.h
model/wifi-spectrum-value-helper.h
)
headers.module = 'spectrum'
build_lib(
LIBNAME spectrum
...
HEADER_FILES ${header_files}
...
)
headers.source = [
'model/spectrum-model.h',
'model/spectrum-value.h',
.
.
.
'model/microwave-oven-spectrum-value-helper.h',
'helper/spectrum-helper.h',
'helper/adhoc-aloha-noack-ideal-phy-helper.h',
'helper/waveform-generator-helper.h',
'helper/spectrum-analyzer-helper.h',
]
If the list of headers is short, use the following instead:
.. sourcecode:: cmake
build_lib(
LIBNAME spectrum
...
HEADER_FILES
helper/adhoc-aloha-noack-ideal-phy-helper.h
helper/spectrum-analyzer-helper.h
...
model/tv-spectrum-transmitter.h
model/waveform-generator.h
model/wifi-spectrum-value-helper.h
...
)
Headers made public in this way will be accessible to users of your model
with include statements like
@@ -233,18 +288,24 @@ Step 5 - Declare Tests
**********************
If your new module has tests, then they must be specified in your
``wscript`` file by modifying it with your text editor.
``CMakeLists.txt`` file by modifying it with your text editor.
The ``spectrum`` model tests are specified with the following stanza:
.. sourcecode:: python
.. sourcecode:: cmake
module_test = bld.create_ns3_module_test_library('spectrum')
module_test.source = [
'test/spectrum-interference-test.cc',
'test/spectrum-value-test.cc',
]
build_lib(
LIBNAME spectrum
...
TEST_SOURCES
test/spectrum-ideal-phy-test.cc
test/spectrum-interference-test.cc
test/spectrum-value-test.cc
test/spectrum-waveform-generator-test.cc
test/three-gpp-channel-test-suite.cc
test/tv-helper-distribution-test.cc
test/tv-spectrum-transmitter-test.cc
)
See :doc:`Tests <tests>` for more information on how to write test cases.
@@ -252,43 +313,46 @@ Step 6 - Declare Examples
*************************
If your new module has examples, then they must be specified in your
``examples/wscript`` file. (The skeleton top-level ``wscript`` will
recursively include ``examples/wscript`` only if the examples were
``examples/CMakeLists.txt`` file. (The skeleton top-level ``CMakeLists.txt`` will
recursively include ``examples/CMakeLists.txt`` only if the examples were
enabled at configure time.)
The ``spectrum`` model defines it's first example in
``src/spectrum/examples/wscript`` with
``src/spectrum/examples/CMakeLists.txt`` with
.. sourcecode:: python
.. sourcecode:: cmake
def build(bld):
obj = bld.create_ns3_program('adhoc-aloha-ideal-phy',
['spectrum', 'mobility'])
obj.source = 'adhoc-aloha-ideal-phy.cc'
build_lib_example(
NAME adhoc-aloha-ideal-phy
SOURCE_FILES adhoc-aloha-ideal-phy.cc
LIBRARIES_TO_LINK
${libspectrum}
${libmobility}
${libinternet}
${libapplications}
)
Note that the second argument to the function ``create_ns3_program()``
is the list of modules that the program being created depends on; again,
don't forget to include ``new-module`` in the list. It's best practice
to list only the direct module dependencies, and let ``ns3`` deduce
the full dependency tree.
Note that the variable ``libraries_to_link`` is the list of modules that
the program being created depends on; again, don't forget to include
``new-module`` in the list. It's best practice to list only the direct
module dependencies, and let ``CMake`` deduce the full dependency tree.
Occasionally, for clarity, you may want to split the implementation
for your example among several source files. In this case, just
include those files as additional explicit sources of the example:
.. sourcecode:: python
obj = bld.create_ns3_program('new-module-example', [new-module])
obj.source = ['new-module-example.cc', 'new-module-example-part.cc']
Python examples are specified using the following
function call. Note that the second argument for the function
``register_ns3_script()`` is the list of modules that the Python example
depends on:
.. sourcecode:: python
bld.register_ns3_script('new-module-example.py', ['new-module'])
.. sourcecode:: cmake
build_lib_example(
NAME new-module-example
SOURCE_FILES new-module-example.cc
LIBRARIES_TO_LINK
${libspectrum}
${libmobility}
${libinternet}
${libapplications}
)
Step 7 - Examples Run as Tests
******************************
@@ -330,11 +394,11 @@ two lists of C++ and Python examples:
As indicated in the comment, each entry in the C++ list of examples to run
contains the tuple ``(example_name, do_run, do_valgrind_run)``, where
* ``example_name`` is the executable to be run,
* ``do_run`` is a condition under which to run the example, and
* ``do_valgrind_run`` is a condition under which to run the example
under valgrind. (This is needed because NSC causes illegal instruction
crashes with some tests when they are run under valgrind.)
* ``example_name`` is the executable to be run,
* ``do_run`` is a condition under which to run the example, and
* ``do_valgrind_run`` is a condition under which to run the example
under valgrind. (This is needed because NSC causes illegal instruction
crashes with some tests when they are run under valgrind.)
Note that the two conditions are Python statements that
can depend on ``ns3`` configuration variables. For example, using the
@@ -347,8 +411,8 @@ NSC_ENABLED variable that was defined up until ns-3.35:
Each entry in the Python list of examples to run contains the tuple
``(example_name, do_run)``, where, as for the C++ examples,
* ``example_name`` is the Python script to be run, and
* ``do_run`` is a condition under which to run the example.
* ``example_name`` is the Python script to be run, and
* ``do_run`` is a condition under which to run the example.
Again, the condition is a Python statement that can
depend on ``ns3`` configuration variables. For example,
@@ -363,7 +427,7 @@ Step 8 - Configure and Build
You can now configure, build and test your module as normal.
You must reconfigure the project as a first step so that ``ns3``
caches the new information in your ``wscript`` files,
caches the new information in your ``CMakeLists.txt`` files,
or else your new module will not be included in the build.
.. sourcecode:: bash
@@ -379,15 +443,10 @@ if your module has any enabled) in the test output.
Step 9 - Python Bindings
************************
Adding Python bindings to your module is optional, and the step is
commented out by default in the ``create-module.py`` script.
.. sourcecode:: python
# bld.ns3_python_bindings()
Adding Python bindings to your module is optional.
If you want to include Python bindings (needed only if you want
to write Python ns-3 programs instead of C++ ns-3 programs), you
should uncomment the above and install the Python API scanning
system (covered elsewhere in this manual) and scan your module to
generate new bindings.
should scan your module to generate new bindings for the Python
API (covered elsewhere in this manual), and they will be used
if NS3_PYTHON_BINDINGS is set to ON.

2135
doc/manual/source/working-with-cmake.rst Normal file
View File

File diff suppressed because it is too large Load Diff

2
doc/manual/source/working-with-git.rst
View File

@@ -42,6 +42,8 @@ Setup of a personal repository
We will provide two ways, one anonymous (but will impede the creation of merge requests) and the other, preferred, that include forking the repository through the GitLab.com web interface.
.. _Directly cloning ns-3-dev:
Directly cloning ns-3-dev
+++++++++++++++++++++++++

447
doc/tutorial/source/getting-started.rst
View File

@@ -1,5 +1,5 @@
.. include:: replace.txt
.. highlight:: bash
.. highlight:: console
.. _Getting Started:
@@ -96,7 +96,7 @@ prerequisites.
For example, do not use a directory path such as the below, because one
of the parent directories contains a space in the directory name:
.. sourcecode:: bash
.. sourcecode:: console
$ pwd
/home/user/5G simulations/ns-3-allinone/ns-3-dev
@@ -119,7 +119,7 @@ If you adopt the ``workspace`` directory approach, you can
get a copy of a release by typing the following into your Linux shell
(substitute the appropriate version numbers, of course)
.. sourcecode:: bash
.. sourcecode:: console
$ cd
$ mkdir workspace
@@ -159,7 +159,7 @@ may be foreign to you; if so, we recommend that you simply ``clone``
(create your own replica) of the repository found on GitLab.com, as
follows:
.. sourcecode:: bash
.. sourcecode:: console
$ cd
$ mkdir workspace
@@ -171,7 +171,7 @@ At this point, your view of the ns-3-allinone directory is slightly
different than described above with a release archive; it should look
something like this:
.. sourcecode:: bash
.. sourcecode:: console
$ ls
build.py constants.py download.py README util.py
@@ -180,14 +180,14 @@ Note the presence of the ``download.py`` script, which will further fetch
the |ns3| and related sourcecode. At this point, you have a choice, to
either download the most recent development snapshot of |ns3|:
.. sourcecode:: bash
.. sourcecode:: console
$ python3 download.py
or to specify a release of |ns3|, using the ``-n`` flag to specify a
release number:
.. sourcecode:: bash
.. sourcecode:: console
$ python3 download.py -n ns-3.35
@@ -204,7 +204,7 @@ for network animiations). The third repository provided by default in
ns-3-allinone is called ``bake``.
Bake is a tool for coordinated software building from multiple repositories,
developed for the |ns3| project.  Bake can be used to fetch development
developed for the |ns3| project. Bake can be used to fetch development
versions of the |ns3| software, and to download and build extensions to the
base |ns3| distribution, such as the Direct Code Execution environment,
Network Simulation Cradle, ability to create new Python bindings, and
@@ -232,7 +232,7 @@ following into your Linux shell (assuming you have installed Git)::
As the git command executes, you should see something like the
following displayed:
.. sourcecode:: bash
.. sourcecode:: console
Cloning into 'bake'...
remote: Enumerating objects: 2086, done.
@@ -245,7 +245,7 @@ following displayed:
After the clone command completes, you should have a directory called
``bake``, the contents of which should look something like the following:
.. sourcecode:: bash
.. sourcecode:: console
$ cd bake
$ ls
@@ -291,7 +291,7 @@ to put bake into your path, such as follows (Linux bash shell example).
First, change into the 'bake' directory, and then set the following
environment variables:
.. sourcecode:: bash
.. sourcecode:: console
$ export BAKE_HOME=`pwd`
$ export PATH=$PATH:$BAKE_HOME:$BAKE_HOME/build/bin
@@ -304,14 +304,14 @@ full builds of ns-3-allinone (with the optional packages) typically do.
Step into the workspace directory and type the following into your shell:
.. sourcecode:: bash
.. sourcecode:: console
$ ./bake.py configure -e ns-3.35
Next, we'll ask bake to check whether we have enough tools to download
various components. Type:
.. sourcecode:: bash
.. sourcecode:: console
$ ./bake.py check
@@ -338,7 +338,7 @@ administrator as needed to install these tools. You can also
Next, try to download the software:
.. sourcecode:: bash
.. sourcecode:: console
$ ./bake.py download
@@ -367,7 +367,7 @@ should yield something like:
The above suggests that three sources have been downloaded. Check the
``source`` directory now and type ``ls``; one should see:
.. sourcecode:: bash
.. sourcecode:: console
$ cd source
$ ls
@@ -404,7 +404,7 @@ using a tarball you should have a directory called something like
``ns-allinone-3.35`` under your ``~/workspace`` directory.
Type the following:
.. sourcecode:: bash
.. sourcecode:: console
$ ./build.py --enable-examples --enable-tests
@@ -418,42 +418,7 @@ are not necessary for your work, if you wish.
You will see lots of compiler output messages displayed as the build
script builds the various pieces you downloaded. First, the script will
attempt to build the netanim animator, then the pybindgen bindings generator,
and finally |ns3|. Eventually you should see the following::
Waf: Leaving directory '/path/to/workspace/ns-allinone-3.35/ns-3.35/build'
'build' finished successfully (6m25.032s)
Modules built:
antenna aodv applications
bridge buildings config-store
core csma csma-layout
dsdv dsr energy
fd-net-device flow-monitor internet
internet-apps lr-wpan lte
mesh mobility mpi
netanim (no Python) network nix-vector-routing
olsr point-to-point point-to-point-layout
propagation sixlowpan spectrum
stats tap-bridge test (no Python)
topology-read traffic-control uan
virtual-net-device visualizer wave
wifi wimax
Modules not built (see ns-3 tutorial for explanation):
brite click openflow
Leaving directory ./ns-3.35
Regarding the portion about modules not built::
Modules not built (see ns-3 tutorial for explanation):
brite click
This just means that some |ns3| modules that have dependencies on
outside libraries may not have been built, or that the configuration
specifically asked not to build them. It does not mean that the
simulator did not build successfully or that it will provide wrong
results for the modules listed as being built.
and finally |ns3|.
Building with bake
++++++++++++++++++
@@ -461,7 +426,7 @@ Building with bake
If you used bake above to fetch source code from project repositories, you
may continue to use it to build |ns3|. Type:
.. sourcecode:: bash
.. sourcecode:: console
$ ./bake.py build
@@ -492,7 +457,7 @@ for now.
If there happens to be a failure, please have a look at what the following
command tells you; it may give a hint as to a missing dependency:
.. sourcecode:: bash
.. sourcecode:: console
$ ./bake.py show
@@ -523,7 +488,7 @@ wrapper script for CMake, |ns3|. To tell |ns3| that it should do optimized
builds that include the examples and tests, you will need to execute the
following commands:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 clean
$ ./ns3 configure --build-profile=optimized --enable-examples --enable-tests
@@ -537,109 +502,192 @@ When the project is reconfigured and the build system checks for various
dependencies, you should see
output that looks similar to the following::
Setting top to : /home/ns3user/workspace/bake/source/ns-3-dev
Setting out to : /home/ns3user/workspace/bake/source/ns-3-dev/build
Checking for 'gcc' (C compiler) : /usr/bin/gcc
Checking for cc version : 7.3.0
Checking for 'g++' (C++ compiler) : /usr/bin/g++
Checking for compilation flag -march=native support : ok
Checking for compilation flag -Wl,--soname=foo support : ok
Checking for compilation flag -std=c++11 support : ok
Checking boost includes : headers not found, please provide a --boost-includes argument (see help)
Checking boost includes : headers not found, please provide a --boost-includes argument (see help)
Checking for program 'python' : /usr/bin/python
Checking for python version >= 2.3 : 2.7.15
python-config : /usr/bin/python-config
Asking python-config for pyembed '--cflags --libs --ldflags' flags : yes
Testing pyembed configuration : yes
Asking python-config for pyext '--cflags --libs --ldflags' flags : yes
Testing pyext configuration : yes
Checking for compilation flag -fvisibility=hidden support : ok
Checking for compilation flag -Wno-array-bounds support : ok
Checking for pybindgen location : ../pybindgen (guessed)
Checking for python module 'pybindgen' : 0.21.0
Checking for pybindgen version : 0.21.0
Checking for code snippet : yes
Checking for types uint64_t and unsigned long equivalence : no
Checking for code snippet : no
Checking for types uint64_t and unsigned long long equivalence : yes
Checking for the apidefs that can be used for Python bindings : gcc-LP64
Checking for internal GCC cxxabi : complete
Checking for python module 'pygccxml' : not found
Checking for click location : not found
Checking for program 'pkg-config' : /usr/bin/pkg-config
Checking for 'gtk+-3.0' : not found
Checking for 'libxml-2.0' : yes
checking for uint128_t : not found
checking for __uint128_t : yes
Checking high precision implementation : 128-bit integer (default)
Checking for header stdint.h : yes
Checking for header inttypes.h : yes
Checking for header sys/inttypes.h : not found
Checking for header sys/types.h : yes
Checking for header sys/stat.h : yes
Checking for header dirent.h : yes
Checking for header stdlib.h : yes
Checking for header signal.h : yes
Checking for header pthread.h : yes
Checking for header stdint.h : yes
Checking for header inttypes.h : yes
Checking for header sys/inttypes.h : not found
Checking for library rt : yes
Checking for header sys/ioctl.h : yes
Checking for header net/if.h : yes
Checking for header net/ethernet.h : yes
Checking for header linux/if_tun.h : yes
Checking for header netpacket/packet.h : yes
Checking for 'sqlite3' : not found
Checking for header linux/if_tun.h : yes
Checking for python module 'gi' : 3.26.1
Checking for python module 'gi.repository.GObject' : ok
Checking for python module 'cairo' : ok
Checking for python module 'pygraphviz' : 1.4rc1
Checking for python module 'gi.repository.Gtk' : ok
Checking for python module 'gi.repository.Gdk' : ok
Checking for python module 'gi.repository.Pango' : ok
Checking for python module 'gi.repository.GooCanvas' : ok
Checking for program 'sudo' : /usr/bin/sudo
Checking for program 'valgrind' : not found
Checking for 'gsl' : not found
python-config : not found
Checking for compilation flag -fstrict-aliasing support : ok
Checking for compilation flag -fstrict-aliasing support : ok
Checking for compilation flag -Wstrict-aliasing support : ok
Checking for compilation flag -Wstrict-aliasing support : ok
Checking for program 'doxygen' : /usr/bin/doxygen
---- Summary of optional NS-3 features:
.. sourcecode:: console
-- CCache is enabled. Precompiled headers are disabled by default.
-- The CXX compiler identification is GNU 11.2.0
-- The C compiler identification is GNU 11.2.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Using default output directory /mnt/dev/tools/source/ns-3-dev/build
-- Found GTK3_GTK: /usr/lib/x86_64-linux-gnu/libgtk-3.so
-- GTK3 was found.
-- LibXML2 was found.
-- LibRT was found.
-- Visualizer requires Python bindings
-- Found Boost: /usr/lib/x86_64-linux-gnu/cmake/Boost-1.74.0/BoostConfig.cmake (found version "1.74.0")
-- Found PkgConfig: /usr/bin/pkg-config (found version "0.29.2")
-- GSL was found.
-- Found Sphinx: /usr/bin/sphinx-build
-- Looking for sys/types.h
-- Looking for sys/types.h - found
-- Looking for stdint.h
-- Looking for stdint.h - found
-- Looking for stddef.h
-- Looking for stddef.h - found
-- Check size of long long
-- Check size of long long - done
-- Check size of int128_t
-- Check size of int128_t - failed
-- Check size of __int128_t
-- Check size of __int128_t - done
-- Performing Test has_hash___int128_t
-- Performing Test has_hash___int128_t - Success
-- Check size of unsigned long long
-- Check size of unsigned long long - done
-- Check size of uint128_t
-- Check size of uint128_t - failed
-- Check size of __uint128_t
-- Check size of __uint128_t - done
-- Performing Test has_hash___uint128_t
-- Performing Test has_hash___uint128_t - Success
-- Looking for C++ include inttypes.h
-- Looking for C++ include inttypes.h - found
-- Looking for C++ include stat.h
-- Looking for C++ include stat.h - not found
-- Looking for C++ include dirent.h
-- Looking for C++ include dirent.h - found
-- Looking for C++ include stdlib.h
-- Looking for C++ include stdlib.h - found
-- Looking for C++ include signal.h
-- Looking for C++ include signal.h - found
-- Looking for C++ include netpacket/packet.h
-- Looking for C++ include netpacket/packet.h - found
-- Looking for C++ include semaphore.h
-- Looking for C++ include semaphore.h - found
-- Looking for getenv
-- Looking for getenv - found
-- Processing src/antenna
-- Processing src/aodv
-- Processing src/applications
-- Processing src/bridge
-- Processing src/brite
-- Brite was not found
-- Processing src/buildings
-- Processing src/click
-- Click was not found
-- Processing src/config-store
-- Processing src/core
-- Looking for C++ include boost/units/quantity.hpp
-- Looking for C++ include boost/units/quantity.hpp - found
-- Looking for C++ include boost/units/systems/si.hpp
-- Looking for C++ include boost/units/systems/si.hpp - found
-- Boost Units have been found.
-- Processing src/csma
-- Processing src/csma-layout
-- Processing src/dsdv
-- Processing src/dsr
-- Processing src/energy
-- Processing src/fd-net-device
-- Looking for C++ include net/ethernet.h
-- Looking for C++ include net/ethernet.h - found
-- Looking for C++ include netpacket/packet.h
-- Looking for C++ include netpacket/packet.h - found
-- Looking for C++ include net/if.h
-- Looking for C++ include net/if.h - found
-- Looking for C++ include linux/if_tun.h
-- Looking for C++ include linux/if_tun.h - found
-- Looking for C++ include net/netmap_user.h
-- Looking for C++ include net/netmap_user.h - not found
-- Looking for C++ include sys/ioctl.h
-- Looking for C++ include sys/ioctl.h - found
-- Checking for module 'libdpdk'
-- No package 'libdpdk' found
-- Processing src/flow-monitor
-- Processing src/internet
-- Processing src/internet-apps
-- Processing src/lr-wpan
-- Processing src/lte
-- Processing src/mesh
-- Processing src/mobility
-- Processing src/netanim
-- Processing src/network
-- Processing src/nix-vector-routing
-- Processing src/olsr
-- Processing src/openflow
-- Openflow was not found
-- Processing src/point-to-point
-- Processing src/point-to-point-layout
-- Processing src/propagation
-- Processing src/sixlowpan
-- Processing src/spectrum
-- Processing src/stats
-- Processing src/tap-bridge
-- Processing src/test
-- Processing src/topology-read
-- Processing src/traffic-control
-- Processing src/uan
-- Processing src/virtual-net-device
-- Processing src/wave
-- Processing src/wifi
-- Processing src/wimax
-- ---- Summary of optional NS-3 features:
Build profile : optimized
Build directory :
BRITE Integration : not enabled (BRITE not enabled (see option --with-brite))
DES Metrics event collection : not enabled (defaults to disabled)
Emulation FdNetDevice : enabled
Examples : enabled
File descriptor NetDevice : enabled
GNU Scientific Library (GSL) : not enabled (GSL not found)
GtkConfigStore : not enabled (library 'gtk+-3.0 >= 3.0' not found)
MPI Support : not enabled (option --enable-mpi not selected)
NS-3 Click Integration : not enabled (nsclick not enabled (see option --with-nsclick))
NS-3 OpenFlow Integration : not enabled (Required boost libraries not found)
PyViz visualizer : enabled
Python API Scanning Support : not enabled (Missing 'pygccxml' Python module)
Python Bindings : enabled
Real Time Simulator : enabled
SQlite stats data output : not enabled (library 'sqlite3' not found)
Tap Bridge : enabled
Tap FdNetDevice : enabled
Tests : enabled
Threading Primitives : enabled
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
XmlIo : enabled
'configure' finished successfully (6.387s)
Build directory : /mnt/dev/tools/source/ns-3-dev/build
BRITE Integration : OFF (missing dependency)
DES Metrics event collection : OFF (not requested)
DPDK NetDevice : OFF (missing dependency)
Emulation FdNetDevice : ON
Examples : ON
File descriptor NetDevice : ON
GNU Scientific Library (GSL) : ON
GtkConfigStore : ON
MPI Support : OFF (not requested)
NS-3 Click Integration : OFF (missing dependency)
NS-3 OpenFlow Integration : OFF (missing dependency)
Netmap emulation FdNetDevice : OFF (missing dependency)
PyViz visualizer : OFF (missing dependency)
Python Bindings : OFF (not requested)
Real Time Simulator : ON
SQLite stats support : ON
Tap Bridge : ON
Tap FdNetDevice : ON
Tests : ON
Threading Primitives : ON
Modules configured to be built:
antenna aodv applications
bridge buildings config-store
core csma csma-layout
dsdv dsr energy
fd-net-device flow-monitor internet
internet-apps lr-wpan lte
mesh mobility netanim
network nix-vector-routing olsr
point-to-point point-to-point-layout propagation
sixlowpan spectrum stats
tap-bridge test topology-read
traffic-control uan virtual-net-device
wave wifi wimax
Modules that cannot be built:
brite click mpi
openflow visualizer
-- Configuring done
-- Generating done
-- Build files have been written to: /mnt/dev/tools/source/ns-3-dev/cmake_cache
Finished executing the following commands:
mkdir cmake_cache
cd cmake_cache; /usr/bin/cmake -DCMAKE_BUILD_TYPE=release -DNS3_NATIVE_OPTIMIZATIONS=ON -DNS3_EXAMPLES=ON -DNS3_TESTS=ON -G Unix Makefiles .. ; cd ..
Note the last part of the above output. Some |ns3| options are not enabled by
default or require support from the underlying system to work properly.
For instance, to enable XmlTo, the library libxml-2.0 must be found on the
system. If this library were not found, the corresponding |ns3| feature
default or require support from the underlying system to work properly (``OFF (not requested)``).
Other options might depend on third-party libraries, which if not found will be disabled
(``OFF(missing dependency)``).
If this library were not found, the corresponding |ns3| feature
would not be enabled and a message would be displayed. Note further that there is
a feature to use the program ``sudo`` to set the suid bit of certain programs.
This is not enabled by default and so this feature is reported as "not enabled."
@@ -648,7 +696,7 @@ the ``--check-config`` option to ns3.
Now go ahead and switch back to the debug build that includes the examples and tests.
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 clean
$ ./ns3 configure --build-profile=debug --enable-examples --enable-tests
@@ -656,7 +704,7 @@ Now go ahead and switch back to the debug build that includes the examples and t
The build system is now configured and you can build the debug versions of
the |ns3| programs by simply typing:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 build
@@ -666,30 +714,29 @@ now you know how to change the configuration and build optimized code.
A command exists for checking which profile is currently active
for an already configured project:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 --check-profile
Waf: Entering directory \`/path/to/ns-allinone-3.35/ns-3.35/build\'
Build profile: debug
The build.py script discussed above supports also the ``--enable-examples``
and ``enable-tests`` arguments, but in general, does not directly support
other ns3 options; for example, this will not work:
.. sourcecode:: bash
.. sourcecode:: console
$ ./build.py --disable-python
will result in:
.. sourcecode:: bash
.. sourcecode:: console
build.py: error: no such option: --disable-python
However, the special operator ``--`` can be used to pass additional
options through to ns3, so instead of the above, the following will work:
.. sourcecode:: bash
.. sourcecode:: console
$ ./build.py -- --disable-python
@@ -720,7 +767,7 @@ around these issues. The option disables the inclusion of the '-Werror'
flag to g++ and clang++. The option is '--disable-werror' and must be
used at configure time; e.g.:
.. sourcecode:: bash
.. sourcecode:: console
./ns3 configure --disable-werror --enable-examples --enable-tests
@@ -733,7 +780,7 @@ features of |ns3|, you might want to enable setting the suid bit using
sudo as described above. This turns out to be a configuration-time command, and so
you could reconfigure using the following command that also includes the examples and tests.
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 configure --enable-sudo --enable-examples --enable-tests
@@ -743,7 +790,7 @@ emulation code to run as root.
There are many other configure- and build-time options
available in ns3. To explore these options, type:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 --help
@@ -754,7 +801,7 @@ Build Profiles
We already saw how you can configure CMake for ``debug`` or ``optimized`` builds:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 configure --build-profile=debug
@@ -782,6 +829,7 @@ The build profile controls the use of logging, assertions, and compiler optimiza
| Compiler | ``-O0 -ggdb -g3`` | ``-O3 -g0`` | ``-O3 -g`` |
| Flags | | ``-fomit-frame-pointer`` | ``-fstrict-overflow`` |
| | | | ``-march=native`` |
| | | | ``-mtune=native`` |
+----------+---------------------------------+-------------------------------+---------------------------------+
As you can see, logging and assertions are only configured
@@ -805,14 +853,14 @@ By default ns3 puts the build artifacts in the ``build`` directory.
You can specify a different output directory with the ``--out``
option, e.g.
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 configure --out=my-build-dir
Combining this with build profiles lets you switch between the different
compile options in a clean way:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 configure --build-profile=debug --out=build/debug
$ ./ns3 build
@@ -829,7 +877,7 @@ When you do switch build profiles like this, you have to be careful
to give the same configuration parameters each time. It may be convenient
to define some environment variables to help you avoid mistakes:
.. sourcecode:: bash
.. sourcecode:: console
$ export NS3CONFIG="--enable-examples --enable-tests"
$ export NS3DEBUG="--build-profile=debug --out=build/debug"
@@ -849,7 +897,7 @@ building |ns3|. However, it's possible to change the C++ compiler used by CMake
by defining the ``CXX`` environment variable.
For example, to use the Clang C++ compiler, ``clang++``,
.. sourcecode:: bash
.. sourcecode:: console
$ CXX="clang++" ./ns3 configure
$ ./ns3 build
@@ -857,7 +905,7 @@ For example, to use the Clang C++ compiler, ``clang++``,
One can also set up ns3 to do distributed compilation with ``distcc`` in
a similar way:
.. sourcecode:: bash
.. sourcecode:: console
$ CXX="distcc g++" ./ns3 configure
$ ./ns3 build
@@ -916,7 +964,7 @@ As you work, you may find yourself spending a lot of time in ``scratch/``,
or deep in ``src/...``, and needing to invoke ns3. You could just
remember where you are, and invoke ns3 like this:
.. sourcecode:: bash
.. sourcecode:: console
$ ../../../ns3 ...
@@ -928,7 +976,7 @@ edit source code.
If you only have the tarball, an environment variable can help:
.. sourcecode:: bash
.. sourcecode:: console
$ export NS3DIR="$PWD"
$ function ns3f { cd $NS3DIR && ./ns3 $* ; }
@@ -955,13 +1003,13 @@ Here is are a few examples showing why we suggest the use of the ns3 wrapper scr
Configuration command
=====================
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 configure --enable-tests --enable-examples -d optimized
Corresponds to
.. sourcecode:: bash
.. sourcecode:: console
$ cd /ns-3-dev/cmake_cache/
$ cmake -DCMAKE_BUILD_TYPE=release -DNS3_NATIVE_OPTIMIZATIONS=ON -DNS3_ASSERT=OFF -DNS3_LOG=OFF -DNS3_TESTS=ON -DNS3_EXAMPLES=ON ..
@@ -971,13 +1019,13 @@ Build command
To build a specific target such as ``test-runner`` we use the following ns3 command:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 build test-runner
Which corresponds to the following commands:
.. sourcecode:: bash
.. sourcecode:: console
$ cd /ns-3-dev/cmake_cache/
$ cmake --build . -j 16 --target test-runner # This command builds the test-runner target with the underlying build system
@@ -985,13 +1033,13 @@ Which corresponds to the following commands:
To build all targets such as modules, examples and tests, we use the following ns3 command:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 build
Which corresponds to:
.. sourcecode:: bash
.. sourcecode:: console
$ cd /ns-3-dev/cmake_cache/
$ cmake --build . -j 16 # This command builds all the targets with the underlying build system
@@ -999,13 +1047,13 @@ Which corresponds to:
Run command
===========
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run test-runner
Corresponds to:
.. sourcecode:: bash
.. sourcecode:: console
$ cd /ns-3-dev/cmake_cache/
$ cmake --build . -j 16 --target test-runner # This command builds the test-runner target calling the underlying build system
@@ -1107,7 +1155,7 @@ Code::Blocks does not support CMake project natively, but we can use the corresp
generator to generate a project in order to use it. The generator name depends on the operating
system and underlying build system. https://cmake.org/cmake/help/latest/generator/CodeBlocks.html
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 configure -G"CodeBlocks - Ninja" --enable-examples
@@ -1163,7 +1211,7 @@ XCode does not support CMake project natively, but we can use the corresponding
generator to generate a project in order to use it. The generator name depends on the operating
system and underlying build system. https://cmake.org/cmake/help/latest/generator/Xcode.html
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 configure -GXcode --enable-examples
@@ -1212,9 +1260,9 @@ Testing ns-3
You can run the unit tests of the |ns3| distribution by running the
``./test.py`` script:
.. sourcecode:: bash
.. sourcecode:: console
$ ./test.py
$ ./test.py --no-build
These tests are run in parallel by ns3. You should eventually
see a report saying that
@@ -1230,7 +1278,7 @@ tools and the code.
You will also see the summary output from ns3 and the test runner
executing each test, which will actually look something like:
.. sourcecode:: bash
.. sourcecode:: console
-- CCache is enabled
-- The CXX compiler identification is GNU 11.2.0
@@ -1285,7 +1333,7 @@ the libraries are available at run time. To run a program, simply use the
``--run`` option in ns3. Let's run the |ns3| equivalent of the
ubiquitous hello world program by typing the following:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run hello-simulator
@@ -1312,7 +1360,7 @@ automatically disabled when you compile optimized code -- it is
"optimized out." If you don't see the "Hello Simulator" output,
type the following:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 configure --build-profile=debug --enable-examples --enable-tests
@@ -1320,7 +1368,7 @@ to tell ns3 to build the debug versions of the |ns3|
programs that includes the examples and tests. You must still build
the actual debug version of the code by typing
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3
@@ -1332,7 +1380,7 @@ Program Arguments
To feed command line arguments to an |ns3| program use this pattern:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run <ns3-program> --command-template="%s <args>"
@@ -1348,7 +1396,7 @@ If you find the above to be syntactically complicated, a simpler variant
exists, which is to include the |ns3| program and its arguments enclosed
by single quotes, such as:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run '<ns3-program> --arg1=value1 --arg2=value2 ...'
@@ -1358,7 +1406,7 @@ Above, we used the ``./test.py`` script to run a whole slew of
tests in parallel, by repeatedly invoking the real testing program,
``test-runner``. To invoke ``test-runner`` directly for a single test:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run test-runner --command-template="%s --suite=mytest --verbose"
@@ -1366,7 +1414,7 @@ This passes the arguments to the ``test-runner`` program.
Since ``mytest`` does not exist, an error message will be generated.
To print the available ``test-runner`` options:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run test-runner --command-template="%s --help"
@@ -1380,7 +1428,7 @@ you use a similar ``--command-template="..."`` form.
For example, to run your |ns3| program ``hello-simulator`` with the arguments
``<args>`` under the ``gdb`` debugger:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run=hello-simulator --command-template="gdb %s --args <args>"
@@ -1395,7 +1443,7 @@ and use the ``gdb`` command ``set args``.)
We can combine this recipe and the previous one to run a test under the
debugger:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run test-runner --command-template="gdb %s --args --suite=mytest --verbose"
@@ -1407,7 +1455,7 @@ This becomes the working directory where output files will be written.
But what if you want to keep those files out of the |ns3| source tree? Use
the ``--cwd`` argument:
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run program-name --cwd=...
@@ -1424,7 +1472,7 @@ through a shell script, or when demonstrating program execution.
The option ``--no-build`` modifies the ``run`` option,
skipping the build steps of the program and required ns-3 libraries.
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 run '<ns3-program> --arg1=value1 --arg2=value2 ...' --no-build
@@ -1451,7 +1499,7 @@ When these prerequisites are met and ns-3 is configured with the
``--enable-build-version`` option, the ns3 command ``--check-version`` can be
used to query the local git repository and display the current version metadata.
.. sourcecode:: bash
.. sourcecode:: console
$ ./ns3 --check-version
@@ -1548,7 +1596,6 @@ option which will print the full build version and exit.
.. sourcecode:: text
./ns3 run "command-line-example --version" --no-build
Waf: Entering directory `/g/g14/mdb/gitlab/mdb/ns-3-dev/build/debug'
ns-3.33+249@g80e0dd0-dirty-debug
If the ``--enable-build-version`` option was not configured, ``--version``
@@ -1566,7 +1613,7 @@ with a patch of any changes to that revision if the repository is dirty.
The resulting text file can then be saved with any corresponding
|ns3| simulation results.
.. sourcecode:: bash
.. sourcecode:: console
echo `git describe` > version.txt
gitDiff=`git diff`