diff --git a/doc/tutorial/source/conceptual-overview.rst b/doc/tutorial/source/conceptual-overview.rst
index 0d49102bd..a295dc15d 100644
--- a/doc/tutorial/source/conceptual-overview.rst
+++ b/doc/tutorial/source/conceptual-overview.rst
@@ -869,7 +869,7 @@ Ns-3 Source Code
Now that you have used some of the |ns3| helpers you may want to
have a look at some of the source code that implements that functionality.
The most recent code can be browsed on our web server at the following link:
-http://code.nsnam.org/ns-3-dev. There, you will see the Mercurial
+https://gitlab.com/nsnam/ns-3-dev.git. There, you will see the Mercurial
summary page for our |ns3| development tree.
At the top of the page, you will see a number of links,
diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst
index 82beff6c9..4956aa9c8 100644
--- a/doc/tutorial/source/getting-started.rst
+++ b/doc/tutorial/source/getting-started.rst
@@ -27,153 +27,237 @@ code around to rebuild the libraries is useful. If someone would like
to undertake the job of making pre-built libraries and packages for
operating systems, please contact the ns-developers mailing list.
-In the following, we'll look at two ways of downloading and building
+In the following, we'll look at three ways of downloading and building
|ns3|. The first is to download and build an official release
from the main web site. The second is to fetch and build development
-copies of |ns3|. We'll walk through both examples since the tools
-involved are slightly different.
+copies of a basic |ns3| installation. The third is to use an additional
+build tool to download more extensions for |ns3|. We'll walk through each
+since the tools involved are slightly different.
-Downloading |ns3|
-*****************
+Experienced Linux users may wonder at this point why |ns3| is not provided
+like most other libraries using a package management tool? Although there
+exist some binary packages for various Linux distributions (e.g. Debian),
+most users end up editing and having to rebuild the |ns3| libraries
+themselves, so having the source code available is more convenient.
+We will therefore focus on a source installation in this tutorial.
-The |ns3| system as a whole is a fairly complex system and has a
-number of dependencies on other components. Along with the systems you will
-most likely deal with every day (the GNU toolchain, Mercurial, a text
-editor) you will need to ensure that a number of additional libraries are
-present on your system before proceeding. |ns3| provides a wiki
-page that includes pages with many useful hints and tips.
-One such page is the "Installation" page,
-http://www.nsnam.org/wiki/Installation.
+For most uses of |ns3|, root permissions are not needed, and the use of
+a non-privileged user account is recommended.
+
+Prerequisites
+*************
+
+The entire set of available |ns3| libraries has a number of dependencies
+on third-party libraries, but most of |ns3| can be built and used with
+support for a few common (often installed by default) components: a
+C++ compiler, an installation of Python, a source code editor (such as vim,
+emacs, or Eclipse) and, if using the development repositories, an
+installation of Git source code control system. Most beginning users
+need not concern themselves if their configuration reports some missing
+optional features of |ns3|, but for those wishing a full installation,
+the project provides a wiki that includes pages with many useful hints
+and tips. One such page is the "Installation" page, with install instructions
+for various systems, available at
+https://www.nsnam.org/wiki/Installation.
The "Prerequisites" section of this wiki page explains which packages are
required to support common |ns3| options, and also provides the
-commands used to install them for common Linux variants. Cygwin users will
-have to use the Cygwin installer (if you are a Cygwin user, you used it to
-install Cygwin).
+commands used to install them for common Linux or macOS variants.
You may want to take this opportunity to explore the |ns3| wiki
-a bit since there really is a wealth of information there.
+a bit, or the main web site at https://www.nsnam.org, since there is a
+wealth of information there.
+
+As of the most recent |ns3| release (ns-3.29), the following tools
+are needed to get started with |ns3|:
+
+============ ===========================================================
+Prerequisite Package/version
+============ ===========================================================
+C++ compiler ``clang++`` or ``g++`` (g++ version 4.9 or greater)
+Python ``python2`` version >= 2.7.10, or ``python3`` version >=3.4
+Git any recent version (to access |ns3| from `GitLab.com `_)
+tar any recent version (to unpack an `ns-3 release `_)
+bunzip2 any recent version (to uncompress an |ns3| release)
+============ ===========================================================
+
+To check the default version of Python, type ``python -V``. To check
+the default version of g++, type ``g++ -v``. If your installation is
+missing or too old, please consult the |ns3| installation wiki for guidance.
From this point forward, we are going to assume that the reader is working in
-Linux or a Linux emulation environment (Linux, Cygwin, etc.) and has the GNU
-toolchain installed and verified along with the prerequisites mentioned
-above. We are also going to assume that you have Mercurial and Waf installed
-and running on the target system.
+Linux, macOS, or a Linux emulation environment, and has at least the above
+prerequisites.
-The |ns3| code is available in Mercurial repositories on the server
-http://code.nsnam.org. You can also download a tarball release at
-http://www.nsnam.org/release/, or you can work with repositories
-using Mercurial. We recommend using Mercurial unless there's a good reason
-not to. See the end of this section for instructions on how to get a tarball
-release.
-
-The simplest way to get started using Mercurial repositories is to use the
-``ns-3-allinone`` environment. This is a set of scripts that manages the
-downloading and building of various subsystems of |ns3| for you. We
-recommend that you begin your |ns3| work in this environment.
-
-One practice is to create a directory called ``workspace`` in one's home
-directory under which one can keep local Mercurial repositories.
-Any directory name will do, but we'll assume that ``workspace`` is used
-herein (note: ``repos`` may also be used in some documentation as
-an example directory name).
-
-Downloading |ns3| Using a Tarball
-+++++++++++++++++++++++++++++++++
+Downloading a release of ns-3 as a source archive
++++++++++++++++++++++++++++++++++++++++++++++++++
+This option is for the new user who wishes to download and experiment with
+the most recently released and packaged version of |ns3|.
+|ns3| publishes its releases as compressed source archives, sometimes
+referred to as a tarball.
A tarball is a particular format of software archive where multiple
-files are bundled together and the archive possibly compressed.
-|ns3| software releases are provided via a downloadable tarball.
+files are bundled together and the archive is usually compressed.
The process for downloading |ns3| via tarball is simple; you just
-have to pick a release, download it and decompress it.
+have to pick a release, download it and uncompress it.
Let's assume that you, as a user, wish to build |ns3| in a local
directory called ``workspace``.
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)::
+(substitute the appropriate version numbers, of course)
+
+.. sourcecode:: bash
$ cd
$ mkdir workspace
$ cd workspace
- $ wget http://www.nsnam.org/release/ns-allinone-3.28.tar.bz2
- $ tar xjf ns-allinone-3.28.tar.bz2
+ $ wget https://www.nsnam.org/release/ns-allinone-3.29.tar.bz2
+ $ tar xjf ns-allinone-3.29.tar.bz2
-If you change into the directory ``ns-allinone-3.28`` you should see a
-number of files and directories::
+Notice the use above of the ``wget`` utility, which is a command-line
+tool to fetch objects from the web; if you do not have this installed,
+you can use a browser for this step.
+
+Following these steps, if you change into the directory
+``ns-allinone-3.29``, you should see a number of files and directories
+.. sourcecode:: text
+
+ $ cd ns-allinone-3.29
$ ls
- bake constants.py ns-3.28 README
+ bake constants.py ns-3.29 README
build.py netanim-3.108 pybindgen-0.17.0.post58+ngcf00cc0 util.py
You are now ready to build the base |ns3| distribution and may skip ahead
to the section on building |ns3|.
-Downloading |ns3| Using Bake
-++++++++++++++++++++++++++++
+Downloading ns-3 using Git
+**************************
-Bake is a tool for distributed integration and building,
+The |ns3| code is available in Git repositories on the GitLab.com service
+at https://gitlab.com/nsnam/. The group name ``nsnam`` organizes the
+various repositories used by the open source project.
+
+The simplest way to get started using Git repositories is to fork or clone
+the ``ns-3-allinone`` environment. This is a set of scripts that manages the
+downloading and building of the most commonly used subsystems of |ns3|
+for you. If you are new to Git, the terminology of ``fork`` and ``clone``
+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
+
+ $ cd
+ $ mkdir workspace
+ $ cd workspace
+ $ git clone https://gitlab.com/nsnam/ns-3-allinone.git
+ $ cd ns-3-allinone
+
+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
+
+ $ ls
+ build.py constants.py download.py README util.py
+
+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
+
+ $ python download.py
+
+or to specify a release of |ns3|, using the ``-n`` flag to specify a
+release number:
+
+.. sourcecode:: bash
+
+ $ python download.py -n ns-3.29
+
+After this step, the additional repositories of |ns3|, bake, pybindgen,
+and netanim will be downloaded to the ``ns-3-allinone`` directory.
+
+Downloading ns-3 Using Bake
++++++++++++++++++++++++++++
+
+The above two techniques (source archive, or ns-3-allinone repository
+via Git) are useful to get the most basic installation of |ns3| with a
+few addons (pybindgen for generating Python bindings, and netanim
+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
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
-others.
+various |ns3| "apps". If you envision that your |ns3| installation may
+use advanced or optional features, you may wish to follow this installation
+path.
In recent |ns3| releases, Bake has been included in the release
tarball. The configuration file included in the released version
will allow one to download any software that was current at the
time of the release. That is, for example, the version of Bake that
-is distributed with the ``ns-3.21`` release can be used to fetch components
+is distributed with the ``ns-3.29`` release can be used to fetch components
for that |ns3| release or earlier, but can't be used to fetch components
-for later releases (unless the ``bakeconf.xml`` file is updated).
+for later releases (unless the ``bakeconf.xml`` package description file
+is updated).
You can also get the most recent copy of ``bake`` by typing the
-following into your Linux shell (assuming you have installed Mercurial)::
+following into your Linux shell (assuming you have installed Git)::
$ cd
$ mkdir workspace
$ cd workspace
- $ hg clone http://code.nsnam.org/bake
+ $ git clone https://gitlab.com/nsnam/bake.git
-As the hg (Mercurial) command executes, you should see something like the
-following displayed::
+As the git command executes, you should see something like the
+following displayed:
- ...
- destination directory: bake
- requesting all changes
- adding changesets
- adding manifests
- adding file changes
- added 339 changesets with 796 changes to 63 files
- updating to branch default
- 45 files updated, 0 files merged, 0 files removed, 0 files unresolved
+.. sourcecode:: bash
+
+ Cloning into 'bake'...
+ remote: Enumerating objects: 2086, done.
+ remote: Counting objects: 100% (2086/2086), done.
+ remote: Compressing objects: 100% (649/649), done.
+ remote: Total 2086 (delta 1404), reused 2078 (delta 1399)
+ Receiving objects: 100% (2086/2086), 2.68 MiB | 3.82 MiB/s, done.
+ Resolving deltas: 100% (1404/1404), done.
After the clone command completes, you should have a directory called
-``bake``, the contents of which should look something like the following::
+``bake``, the contents of which should look something like the following:
+.. sourcecode:: bash
+
+ $ cd bake
$ ls
- bake bakeconf.xml doc generate-binary.py TODO
- bake.py examples test
+ bake bakeconf.xml bake.py doc examples generate-binary.py test TODO
-Notice that you really just downloaded some Python scripts and a Python
-module called ``bake``. The next step
+Notice that you have downloaded some Python scripts, a Python
+module called ``bake``, and an XML configuration file. The next step
will be to use those scripts to download and build the |ns3|
distribution of your choice.
There are a few configuration targets available:
-1. ``ns-3.28``: the module corresponding to the release; it will download
+1. ``ns-3.29``: the module corresponding to the release; it will download
components similar to the release tarball.
2. ``ns-3-dev``: a similar module but using the development code tree
-3. ``ns-allinone-3.28``: the module that includes other optional features
- such as click routing, openflow for |ns3|, and the Network Simulation
+3. ``ns-allinone-3.29``: the module that includes other optional features
+ such as Click routing, Openflow for |ns3|, and the Network Simulation
Cradle
4. ``ns-3-allinone``: similar to the released version of the allinone
module, but for development code.
The current development snapshot (unreleased) of |ns3| may be found
-at http://code.nsnam.org/ns-3-dev/. The
-developers attempt to keep these repository in consistent, working states but
+at https://gitlab.com/nsnam/ns-3-dev.git. The
+developers attempt to keep these repositories in consistent, working states but
they are in a development area with unreleased code present, so you may want
to consider staying with an official release if you do not need newly-
introduced features.
@@ -181,9 +265,9 @@ introduced features.
You can find the latest version of the
code either by inspection of the repository list or by going to the
`"ns-3 Releases"
-`_
+`_
web page and clicking on the latest release link. We'll proceed in
-this tutorial example with ``ns-3.28``.
+this tutorial example with ``ns-3.29``.
We are now going to use the bake tool to pull down the various pieces of
|ns3| you will be using. First, we'll say a word about running bake.
@@ -194,8 +278,10 @@ by referencing the binary, but if one chooses to run bake from
outside of the directory it was downloaded into, it is advisable
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::
-
+environment variables:
+
+.. sourcecode:: bash
+
$ export BAKE_HOME=`pwd`
$ export PATH=$PATH:$BAKE_HOME:$BAKE_HOME/build/bin
$ export PYTHONPATH=$PYTHONPATH:$BAKE_HOME:$BAKE_HOME/build/lib
@@ -205,85 +291,93 @@ other programs to find executables and libraries created by bake. Although
several bake use cases do not require setting PATH and PYTHONPATH as above,
full builds of ns-3-allinone (with the optional packages) typically do.
-Step into the workspace directory and type the following into your shell::
+Step into the workspace directory and type the following into your shell:
- $ ./bake.py configure -e ns-3.28
+.. sourcecode:: bash
+
+ $ ./bake.py configure -e ns-3.29
Next, we'll ask bake to check whether we have enough tools to download
-various components. Type::
+various components. Type:
+
+.. sourcecode:: bash
$ ./bake.py check
-You should see something like the following::
+You should see something like the following:
- > Python - OK
- > GNU C++ compiler - OK
- > Mercurial - OK
- > CVS - OK
- > GIT - OK
- > Bazaar - OK
- > Tar tool - OK
- > Unzip tool - OK
- > Unrar tool - is missing
- > 7z data compression utility - OK
- > XZ data compression utility - OK
- > Make - OK
- > cMake - OK
- > patch tool - OK
- > autoreconf tool - OK
+.. sourcecode:: text
- > Path searched for tools: /usr/lib64/qt-3.3/bin /usr/lib64/ccache
- /usr/local/bin /bin /usr/bin /usr/local/sbin /usr/sbin /sbin bin
+ > Python - OK
+ > GNU C++ compiler - OK
+ > Mercurial - OK
+ > Git - OK
+ > Tar tool - OK
+ > Unzip tool - OK
+ > Make - OK
+ > cMake - OK
+ > patch tool - OK
+ > Path searched for tools: /usr/local/sbin /usr/local/bin /usr/sbin /usr/bin /sbin /bin ...
-In particular, download tools such as Mercurial, CVS, GIT, and Bazaar
+In particular, download tools such as Mercurial, CVS, Git, and Bazaar
are our principal concerns at this point, since they allow us to fetch
the code. Please install missing tools at this stage, in the usual
way for your system (if you are able to), or contact your system
administrator as needed to install these tools.
-Next, try to download the software::
+Next, try to download the software:
+
+.. sourcecode:: bash
$ ./bake.py download
-should yield something like::
+should yield something like:
- >> Searching for system dependency setuptools - OK
- >> Searching for system dependency pygoocanvas - OK
- >> Searching for system dependency pygraphviz - OK
- >> Searching for system dependency python-dev - OK
- >> Searching for system dependency libxml2-dev - OK
- >> Searching for system dependency clang-dev - OK
- >> Downloading click-ns-3.25 - OK
- >> Downloading BRITE - OK
- >> Searching for system dependency qt4 - OK
- >> Downloading nsc-0.5.3 - OK
- >> Searching for system dependency g++ - OK
- >> Downloading castxml - OK
- >> Downloading openflow-ns-3.25 - OK
- >> Downloading netanim-3.108 - OK
- >> Downloading pygccxml-1.9.1 - OK
- >> Downloading pygccxml - OK
- >> Downloading pybindgen-ns3.27-castxml (target directory:pybindgen) - OK
- >> Downloading ns-3.28 - OK
+.. sourcecode:: text
-The above suggests that seven sources have been downloaded. Check the
-``source`` directory now and type ``ls``; one should see::
+ >> Searching for system dependency setuptools - OK
+ >> Searching for system dependency libgoocanvas2 - OK
+ >> Searching for system dependency gi-cairo - OK
+ >> Searching for system dependency pygobject - OK
+ >> Searching for system dependency pygraphviz - OK
+ >> Searching for system dependency python-dev - OK
+ >> Searching for system dependency qt - OK
+ >> Searching for system dependency g++ - OK
+ >> Downloading pybindgen-0.19.0.post4+ng823d8b2 (target directory:pybindgen) - OK
+ >> Downloading netanim-3.108 - OK
+ >> Downloading ns-3.29 - OK
+The above suggests that three sources have been downloaded. Check the
+``source`` directory now and type ``ls``; one should see:
+
+.. sourcecode:: bash
+
+ $ cd source
$ ls
- BRITE netanim-3.108 openflow-ns-3.25 pygccxml-1.9.1
- castxml ns-3.28 pybindgen v1.9.1.tar.gz
- click-ns-3.25 nsc-0.5.3 pygccxml
+ netanim-3.108 ns-3.29 pybindgen
You are now ready to build the |ns3| distribution.
-Building |ns3|
-**************
+Building ns-3
+*************
+
+As with downloading |ns3|, there are a few ways to build |ns3|. The main
+thing that we wish to emphasize is the following. |ns3| is built with
+a build tool called ``Waf``, described below. Most users will end up
+working most directly with Waf, but there are some convenience scripts
+to get you started or to orchestrate more complicated builds. Therefore,
+please have a look at ``build.py`` and building with ``bake``, before
+reading about Waf below.
Building with ``build.py``
++++++++++++++++++++++++++
-When working from a released tarball, the first time you build the
-|ns3| project you can build using a convenience program found in the
-``allinone`` directory. This program is called ``build.py``. This
+
+**Note:** This build step is only available from a source archive release
+described above; not from downloading via git or bake.
+
+When working from a released tarball, a convenience script available as
+part of ``ns-3-allinone`` can orchestrate a simple build of components.
+This program is called ``build.py``. This
program will get the project configured for you
in the most commonly useful way. However, please note that more advanced
configuration and work with |ns3| will typically involve using the
@@ -291,8 +385,10 @@ native |ns3| build system, Waf, to be introduced later in this tutorial.
If you downloaded
using a tarball you should have a directory called something like
-``ns-allinone-3.28`` under your ``~/workspace`` directory.
-Type the following::
+``ns-allinone-3.29`` under your ``~/workspace`` directory.
+Type the following:
+
+.. sourcecode:: bash
$ ./build.py --enable-examples --enable-tests
@@ -303,31 +399,34 @@ building all available modules. Later, you can build
|ns3| without examples and tests, or eliminate the modules that
are not necessary for your work, if you wish.
-You will see lots of typical compiler output messages displayed as the build
-script builds the various pieces you downloaded. Eventually you should see the
-following::
+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.28/ns-3.28/build'
+ Waf: Leaving directory '/path/to/workspace/ns-allinone-3.29/ns-3.29/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 openflow (no Python) 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
-
+ 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
+ brite click openflow
+
+ Leaving directory ./ns-3.29
Regarding the portion about modules not built::
@@ -340,11 +439,257 @@ 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.
+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
+
+ $ ./bake.py build
+
+and you should see something like:
+
+.. sourcecode:: text
+
+ >> Building pybindgen-0.19.0.post4+ng823d8b2 - OK
+ >> Building netanim-3.108 - OK
+ >> Building ns-3.29 - OK
+
+*Hint: you can also perform both steps, download and build, by calling ``bake.py deploy``.*
+
+There may be failures to build all components, but the build will proceed
+anyway if the component is optional. For example, a recent portability issue
+has been that castxml may not build via the bake build tool on all
+platforms; in this case, the line will show something like::
+
+ >> Building castxml - Problem
+ > Problem: Optional dependency, module "castxml" failed
+ This may reduce the functionality of the final build.
+ However, bake will continue since "castxml" is not an essential dependency.
+ For more information call bake with -v or -vvv, for full verbose mode.
+
+However, castxml is only needed if one wants to generate updated Python
+bindings, and most users do not need to do so (or to do so until they are
+more involved with ns-3 changes), so such warnings might be safely ignored
+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
+
+ $ ./bake.py show
+
+This will list out the various dependencies of the packages you are
+trying to build.
+
+Building with Waf
++++++++++++++++++
+
+Up to this point, we have used either the `build.py` script, or the
+`bake` tool, to get started with building |ns3|. These tools are useful
+for building |ns3| and supporting libraries, and they call into
+the |ns3| directory to call the Waf build tool to do the actual building.
+An installation of Waf is bundled with the |ns3| source code.
+Most users quickly transition to using Waf directly to configure and
+build |ns3|. So, to proceed, please change your working directory to
+the |ns3| directory that you have initially built.
+
+It's not
+strictly required at this point, but it will be valuable to take a slight
+detour and look at how to make changes to the configuration of the project.
+Probably the most useful configuration change you can make will be to
+build the optimized version of the code. By default you have configured
+your project to build the debug version. Let's tell the project to
+make an optimized build. To explain to Waf that it should do optimized
+builds that include the examples and tests, you will need to execute the
+following commands:
+
+.. sourcecode:: bash
+
+ $ ./waf clean
+ $ ./waf configure --build-profile=optimized --enable-examples --enable-tests
+
+This runs Waf out of the local directory (which is provided as a convenience
+for you). The first command to clean out the previous build is not
+typically strictly necessary but is good practice (but see `Build Profiles`_,
+below); it will remove the
+previously built libraries and object files found in directory ``build/``.
+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.19.0.post4+g823d8b2
+ Checking for pybindgen version : 0.19.0.post4+g823d8b2
+ 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 NSC location : not found
+ 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:
+ 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)
+ Gcrypt library : not enabled (libgcrypt not found: you can use libgcrypt-config to find its location.)
+ 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)
+ Network Simulation Cradle : not enabled (NSC not found (see option --with-nsc))
+ PlanetLab FdNetDevice : not enabled (PlanetLab operating system not detected (see option --force-planetlab))
+ 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)
+
+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
+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."
+Finally, to reprint this summary of which optional features are enabled, use
+the ``--check-config`` option to waf.
+
+Now go ahead and switch back to the debug build that includes the examples and tests.
+
+.. sourcecode:: bash
+
+ $ ./waf clean
+ $ ./waf configure --build-profile=debug --enable-examples --enable-tests
+
+The build system is now configured and you can build the debug versions of
+the |ns3| programs by simply typing:
+
+.. sourcecode:: bash
+
+ $ ./waf
+
+Although the above steps made you build the |ns3| part of the system twice,
+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
+
+ $ ./waf --check-profile
+ Waf: Entering directory \`/path/to/ns-3-allinone/ns-3.29/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 waf options; for example, this will not work:
+
+.. sourcecode:: bash
+
+ $ ./build.py --disable-python
+
+will result in:
+
+.. sourcecode:: bash
+
+ build.py: error: no such option: --disable-python
+
+However, the special operator ``--`` can be used to pass additional
+options through to waf, so instead of the above, the following will work:
+
+.. sourcecode:: bash
+
+ $ ./build.py -- --disable-python
+
+as it generates the underlying command ``./waf configure --disable-python``.
+
+Here are a few more introductory tips about Waf.
+
Handling build errors
-+++++++++++++++++++++
+=====================
|ns3| releases are tested against the most recent C++ compilers available
-in the mainstream Linux and MacOS distributions at the time of the release.
+in the mainstream Linux and macOS distributions at the time of the release.
However, over time, newer distributions are released, with newer compilers,
and these newer compilers tend to be more pedantic about warnings. |ns3|
configures its build to treat all warnings as errors, so it is sometimes
@@ -361,217 +706,12 @@ on Fedora 28, when Gtk2+ is installed, will result in an error such as::
In releases starting with ns-3.28.1, an option is available in Waf to work
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.::
+used at configure time; e.g.:
+
+.. sourcecode:: bash
./waf configure --disable-werror --enable-examples --enable-tests
-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
-
-::
-
- $ ./bake.py build
-
-and you should see something like::
-
- >> Building BRITE - OK
- >> Building nsc-0.5.3 - OK
- >> Building click-ns-3.25 - OK
- ...
- >> Building ns-3.28 - OK
-
-*Hint: you can also perform both steps, download and build, by calling ``bake.py deploy``.*
-
-There may be failures to build all components, but the build will proceed
-anyway if the component is optional. For example, a common issue at the
-moment is that castxml may not build via the bake build tool on all
-platforms; in this case, the line will show::
-
- >> Building castxml - Problem
- > Problem: Optional dependency, module "castxml" failed
- This may reduce the functionality of the final build.
- However, bake will continue since "castxml" is not an essential dependency.
- For more information call bake with -v or -vvv, for full verbose mode.
-
-However, castxml is only needed if one wants to generate updated Python
-bindings, and most users do not need to do so (or to do so until they are
-more involved with ns-3 changes), so such warnings might be safely ignored
-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::
-
- $ ./bake.py show
-
-This will list out the various dependencies of the packages you are
-trying to build.
-
-Building with Waf
-+++++++++++++++++
-
-Up to this point, we have used either the `build.py` script, or the
-`bake` tool, to get started with building |ns3|. These tools are useful
-for building |ns3| and supporting libraries, and they call into
-the |ns3| directory to call the Waf build tool to do the actual building.
-Most users quickly transition to using Waf directly to configure and
-build |ns3|. So, to proceed, please change your working directory to
-the |ns3| directory that you have initially built.
-
-It's not
-strictly required at this point, but it will be valuable to take a slight
-detour and look at how to make changes to the configuration of the project.
-Probably the most useful configuration change you can make will be to
-build the optimized version of the code. By default you have configured
-your project to build the debug version. Let's tell the project to
-make an optimized build. To explain to Waf that it should do optimized
-builds that include the examples and tests, you will need to execute the
-following commands::
-
- $ ./waf clean
- $ ./waf configure --build-profile=optimized --enable-examples --enable-tests
-
-This runs Waf out of the local directory (which is provided as a convenience
-for you). The first command to clean out the previous build is not
-typically strictly necessary but is good practice (but see `Build Profiles`_,
-below); it will remove the
-previously built libraries and object files found in directory ``build/``.
-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 : .
- Setting out to : build
- Checking for 'gcc' (c compiler) : /usr/bin/gcc
- Checking for cc version : 4.2.1
- Checking for 'g++' (c++ compiler) : /usr/bin/g++
- Checking boost includes : 1_46_1
- Checking boost libs : ok
- Checking for boost linkage : ok
- Checking for click location : not found
- Checking for program pkg-config : /sw/bin/pkg-config
- Checking for 'gtk+-2.0' >= 2.12 : yes
- Checking for 'libxml-2.0' >= 2.7 : yes
- Checking for type uint128_t : not found
- Checking for type __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 : not found
- Checking for header netpacket/packet.h : not found
- Checking for header sys/ioctl.h : yes
- Checking for header net/if.h : not found
- Checking for header net/ethernet.h : yes
- Checking for header linux/if_tun.h : not found
- Checking for header netpacket/packet.h : not found
- Checking for NSC location : not found
- Checking for 'mpic++' : yes
- Checking for 'sqlite3' : yes
- Checking for header linux/if_tun.h : not found
- Checking for program sudo : /usr/bin/sudo
- Checking for program valgrind : /sw/bin/valgrind
- Checking for 'gsl' : yes
- Checking for compilation flag -Wno-error=deprecated-d... support : ok
- Checking for compilation flag -Wno-error=deprecated-d... support : ok
- 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/local/bin/doxygen
- ---- Summary of optional NS-3 features:
- Build profile : debug
- BRITE Integration : not enabled (BRITE not enabled (see option --with-brite))
- Build directory : build
- Build examples : enabled
- Build tests : enabled
- Emulated Net Device : enabled ( include not detected)
- Emulation FdNetDevice : not enabled (needs netpacket/packet.h)
- File descriptor NetDevice : enabled
- GNU Scientific Library (GSL) : enabled
- GtkConfigStore : enabled
- MPI Support : enabled
- NS-3 Click Integration : not enabled (nsclick not enabled (see option --with-nsclick))
- NS-3 OpenFlow Integration : not enabled (Required boost libraries not found, missing: system, signals, filesystem)
- Network Simulation Cradle : not enabled (NSC not found (see option --with-nsc))
- PlanetLab FdNetDevice : not enabled (PlanetLab operating system not detected (see option --force-planetlab))
- PyViz visualizer : enabled
- Python Bindings : enabled
- Real Time Simulator : enabled (librt is not available)
- SQlite stats data output : enabled
- Tap Bridge : not enabled ( include not detected)
- Tap FdNetDevice : not enabled (needs linux/if_tun.h)
- Threading Primitives : enabled
- Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
- XmlIo : enabled
- 'configure' finished successfully (1.944s)
-
-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
-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."
-Finally, to reprint this summary of which optional features are enabled, use
-the ``--check-config`` option to waf.
-
-Now go ahead and switch back to the debug build that includes the examples and tests.
-
-::
-
- $ ./waf clean
- $ ./waf configure --build-profile=debug --enable-examples --enable-tests
-
-The build system is now configured and you can build the debug versions of
-the |ns3| programs by simply typing
-
-::
-
- $ ./waf
-
-Okay, sorry, I made you build the |ns3| part of the system twice,
-but 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::
-
- $ ./waf --check-profile
- Waf: Entering directory \`/path/to/ns-3-allinone/ns-3.28/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 waf options; for example, this will not work:
-
- $ ./build.py --disable-python
-
-will result in
-
-::
-
- build.py: error: no such option: --disable-python
-
-However, the special operator ``--`` can be used to pass additional
-options through to waf, so instead of the above, the following will work::
-
- $ ./build.py -- --disable-python
-
-as it generates the underlying command ``./waf configure --disable-python``.
-
-Here are a few more introductory tips about Waf.
-
Configure vs. Build
===================
@@ -581,7 +721,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
$ ./waf configure --enable-sudo --enable-examples --enable-tests
@@ -589,7 +729,9 @@ If you do this, Waf will have run sudo to change the socket creator programs of
emulation code to run as root.
There are many other configure- and build-time options
-available in Waf. To explore these options, type::
+available in Waf. To explore these options, type:
+
+.. sourcecode:: bash
$ ./waf --help
@@ -598,7 +740,9 @@ We'll use some of the testing-related commands in the next section.
Build Profiles
==============
-We already saw how you can configure Waf for ``debug`` or ``optimized`` builds::
+We already saw how you can configure Waf for ``debug`` or ``optimized`` builds:
+
+.. sourcecode:: bash
$ ./waf --build-profile=debug
@@ -641,12 +785,14 @@ By default Waf puts the build artifacts in the ``build`` directory.
You can specify a different output directory with the ``--out``
option, e.g.
-::
+.. sourcecode:: bash
- $ ./waf configure --out=foo
+ $ ./waf configure --out=my-build-dir
Combining this with build profiles lets you switch between the different
-compile options in a clean way::
+compile options in a clean way:
+
+.. sourcecode:: bash
$ ./waf configure --build-profile=debug --out=build/debug
$ ./waf build
@@ -661,7 +807,9 @@ what it has to, instead of recompiling everything.
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::
+to define some environment variables to help you avoid mistakes:
+
+.. sourcecode:: bash
$ export NS3CONFIG="--enable-examples --enable-tests"
$ export NS3DEBUG="--build-profile=debug --out=build/debug"
@@ -681,20 +829,22 @@ building |ns3|. However, it's possible to change the C++ compiler used by Waf
by defining the ``CXX`` environment variable.
For example, to use the Clang C++ compiler, ``clang++``,
-::
+.. sourcecode:: bash
$ CXX="clang++" ./waf configure
$ ./waf build
One can also set up Waf to do distributed compilation with ``distcc`` in
-a similar way::
+a similar way:
+
+.. sourcecode:: bash
$ CXX="distcc g++" ./waf configure
$ ./waf build
More info on ``distcc`` and distributed compilation can be found on it's
`project page
-`_
+`_
under Documentation section.
To add compiler flags, use the ``CXXFLAGS_EXTRA`` environment variable when
@@ -744,23 +894,21 @@ One Waf
There is only one Waf script, at the top level of the |ns3| source tree.
As you work, you may find yourself spending a lot of time in ``scratch/``,
or deep in ``src/...``, and needing to invoke Waf. You could just
-remember where you are, and invoke Waf like this::
+remember where you are, and invoke Waf like this:
+
+.. sourcecode:: bash
$ ../../../waf ...
but that gets tedious, and error prone, and there are better solutions.
-If you have the full |ns3| repository this little gem is a start::
+One common way when using a text-based editor such as emacs or vim is to
+open two terminal sessions and use one to build |ns3| and one to
+edit source code.
- $ cd $(hg root) && ./waf ...
+If you only have the tarball, an environment variable can help:
-Even better is to define this as a shell function::
-
- $ function waff { cd $(hg root) && ./waf $* ; }
-
- $ waff build
-
-If you only have the tarball, an environment variable can help::
+.. sourcecode:: bash
$ export NS3DIR="$PWD"
$ function waff { cd $NS3DIR && ./waf $* ; }
@@ -770,26 +918,30 @@ If you only have the tarball, an environment variable can help::
It might be tempting in a module directory to add a trivial ``waf``
script along the lines of ``exec ../../waf``. Please don't. It's
-confusing to new-comers, and when done poorly it leads to subtle build
+confusing to newcomers, and when done poorly it leads to subtle build
errors. The solutions above are the way to go.
-Testing |ns3|
-*************
+Testing ns-3
+************
You can run the unit tests of the |ns3| distribution by running the
-``./test.py -c core`` script::
+``./test.py`` script:
- $ ./test.py -c core
+.. sourcecode:: bash
+
+ $ ./test.py
These tests are run in parallel by Waf. You should eventually
see a report saying that
-::
+.. sourcecode:: text
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)
-This is the important message.
+This is the important message to check for; failures, crashes, or valgrind
+errors indicate problems with the code or incompatibilities between the
+tools and the code.
You will also see the summary output from Waf and the test runner
executing each test, which will actually look something like::
@@ -827,6 +979,9 @@ This command is typically run by users to quickly verify that an
lines can vary, which is okay. What's important is that the summary line at
the end report that all tests passed; none failed or crashed.)
+Both Waf and ``test.py`` will split up the job on the available CPU cores
+of the machine, in parallel.
+
Running a Script
****************
@@ -834,7 +989,9 @@ We typically run scripts under the control of Waf. This allows the build
system to ensure that the shared library paths are set correctly and that
the libraries are available at run time. To run a program, simply use the
``--run`` option in Waf. Let's run the |ns3| equivalent of the
-ubiquitous hello world program by typing the following::
+ubiquitous hello world program by typing the following:
+
+.. sourcecode:: bash
$ ./waf --run hello-simulator
@@ -842,7 +999,7 @@ Waf first checks to make sure that the program is built correctly and
executes a build if required. Waf then executes the program, which
produces the following output.
-::
+.. sourcecode:: text
Hello Simulator
@@ -859,7 +1016,9 @@ special |ns3| logging component that is useful for printing
user messages to the console. Output from this component is
automatically disabled when you compile optimized code -- it is
"optimized out." If you don't see the "Hello Simulator" output,
-type the following::
+type the following:
+
+.. sourcecode:: bash
$ ./waf configure --build-profile=debug --enable-examples --enable-tests
@@ -867,7 +1026,7 @@ to tell Waf 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
$ ./waf
@@ -877,7 +1036,9 @@ expected output.
Program Arguments
+++++++++++++++++
-To feed command line arguments to an |ns3| program use this pattern::
+To feed command line arguments to an |ns3| program use this pattern:
+
+.. sourcecode:: bash
$ ./waf --run --command-template="%s "
@@ -888,19 +1049,30 @@ to execute the program. Waf checks that the build is complete,
sets the shared library paths, then invokes the executable
using the provided command line template,
inserting the program name for the ``%s`` placeholder.
-(I admit this is a bit awkward, but that's the way it is. Patches welcome!)
+
+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
+
+ $ ./waf --run ' --arg1=value1 --arg2=value2 ...'
Another particularly useful example is to run a test suite by itself.
Let's assume that a ``mytest`` test suite exists (it doesn't).
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::
+``test-runner``. To invoke ``test-runner`` directly for a single test:
+
+.. sourcecode:: bash
$ ./waf --run test-runner --command-template="%s --suite=mytest --verbose"
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::
+To print the available ``test-runner`` options:
+
+.. sourcecode:: bash
$ ./waf --run test-runner --command-template="%s --help"
@@ -912,7 +1084,9 @@ a debugger (*e.g.* ``gdb``) or memory checker (*e.g.* ``valgrind``),
you use a similar ``--command-template="..."`` form.
For example, to run your |ns3| program ``hello-simulator`` with the arguments
-```` under the ``gdb`` debugger::
+```` under the ``gdb`` debugger:
+
+.. sourcecode:: bash
$ ./waf --run=hello-simulator --command-template="gdb %s --args "
@@ -925,7 +1099,9 @@ omit the program arguments from the ``--command-template``,
and use the ``gdb`` command ``set args``.)
We can combine this recipe and the previous one to run a test under the
-debugger::
+debugger:
+
+.. sourcecode:: bash
$ ./waf --run test-runner --command-template="gdb %s --args --suite=mytest --verbose"
@@ -934,13 +1110,17 @@ Working Directory
Waf needs to run from its location at the top of the |ns3| tree.
This becomes the working directory where output files will be written.
-But what if you want to keep those ouf to the |ns3| source tree? Use
-the ``--cwd`` argument::
+But what if you want to keep those files out of the |ns3| source tree? Use
+the ``--cwd`` argument:
+
+.. sourcecode:: bash
$ ./waf --cwd=...
It may be more convenient to start with your working directory where
-you want the output files, in which case a little indirection can help::
+you want the output files, in which case a little indirection can help:
+
+.. sourcecode:: bash
$ function waff {
CWD="$PWD"
@@ -953,3 +1133,6 @@ This embellishment of the previous version saves the current working directory,
``cd``'s to the Waf directory, then instructs Waf to change the working
directory *back* to the saved current working directory before running the
program.
+
+We mention this ``--cwd`` command for completeness; most users will simply
+run Waf from the top-level directory and generate the output data files there.
diff --git a/doc/tutorial/source/introduction.rst b/doc/tutorial/source/introduction.rst
index cab42eea6..fd160b223 100644
--- a/doc/tutorial/source/introduction.rst
+++ b/doc/tutorial/source/introduction.rst
@@ -27,13 +27,10 @@ A few key points are worth noting at the onset:
* |ns3| is not a backwards-compatible extension of `ns-2
`_;
it is a new simulator. The two simulators are both written in C++ but
- |ns3| is a new simulator that does not support the |ns2| APIs. Some
- models from |ns2| have already been ported from |ns2| to |ns3|. The
- project will continue to maintain |ns2| while |ns3| is being built,
- and will study transition and integration mechanisms.
+ |ns3| is a new simulator that does not support the |ns2| APIs.
-About |ns3|
-***********
+About ns-3
+**********
|ns3| has been developed to provide an open, extensible network simulation
platform, for networking research and education. In brief, |ns3| provides
@@ -58,16 +55,17 @@ a few distinguishing features of |ns3| in contrast to other tools.
data analysis and visualization tools can be used with |ns3|. However,
users should expect to work at the command line and with C++ and/or
Python software development tools.
-* |ns3| is primarily used on Linux systems, although support exists
- for FreeBSD, Cygwin (for Windows), and native Windows Visual Studio
- support is in the process of being developed.
+* |ns3| is primarily used on Linux or macOS systems, although support exists
+ for BSD systems and also for Windows frameworks that can build Linux code,
+ such as Windows Subsystem for Linux, or Cygwin. Native Windows
+ Visual Studio is not presently supported although a developer is working
+ on future support. Windows users may also use a Linux virtual machine.
* |ns3| is not an officially supported software product of any company.
Support for |ns3| is done on a best-effort basis on the
- ns-3-users mailing list.
+ ns-3-users forum (ns-3-users@googlegroups.com).
-
-For |ns2| Users
-***************
+For ns-2 Users
+**************
For those familiar with |ns2| (a popular tool that preceded |ns3|),
the most visible outward change when moving to
@@ -135,20 +133,23 @@ contribute to |ns3| like they have for |ns2|:
* Open source licensing based on GNU GPLv2 compatibility
* `wiki
- `_
+ `_
* `Contributed Code
- `_ page, similar to |ns2|'s popular Contributed Code
+ `_ page, similar to |ns2|'s popular Contributed Code
`page
`_
-* Open `bug tracker
- `_
+* Use of GitLab.com including issue tracker
+ `_
We realize that if you are reading this document, contributing back to
the project is probably not your foremost concern at this point, but
we want you to be aware that contributing is in the spirit of the project and
that even the act of dropping us a note about your early experience
with |ns3| (e.g. "this tutorial section was not clear..."),
-reports of stale documentation, etc. are much appreciated.
+reports of stale documentation or comments in the code, etc. are much
+appreciated. The preferred way to submit patches is either to fork
+our project on GitLab.com and generate a Merge Request, or to open
+an issue on our issue tracker and append a patch.
Tutorial Organization
*********************
diff --git a/doc/tutorial/source/resources.rst b/doc/tutorial/source/resources.rst
index c2b61c5c0..3463ae515 100644
--- a/doc/tutorial/source/resources.rst
+++ b/doc/tutorial/source/resources.rst
@@ -7,45 +7,36 @@ The Web
*******
There are several important resources of which any |ns3| user must be
-aware. The main web site is located at http://www.nsnam.org and
+aware. The main web site is located at https://www.nsnam.org and
provides access to basic information about the |ns3| system. Detailed
documentation is available through the main web site at
-http://www.nsnam.org/documentation/. You can also find documents
+https://www.nsnam.org/documentation/. You can also find documents
relating to the system architecture from this page.
There is a Wiki that complements the main |ns3| web site which you will
-find at http://www.nsnam.org/wiki/. You will find user and developer
+find at https://www.nsnam.org/wiki/. You will find user and developer
FAQs there, as well as troubleshooting guides, third-party contributed code,
papers, etc.
-The source code may be found and browsed at http://code.nsnam.org/.
+The source code may be found and browsed at GitLab.com:
+https://gitlab.com/nsnam/.
There you will find the current development tree in the repository named
``ns-3-dev``. Past releases and experimental repositories of the core
-developers may also be found there.
+developers may also be found at the project's old Mercurial site at
+http://code.nsnam.org.
-Mercurial
-*********
+Git
+***
Complex software systems need some way to manage the organization and
changes to the underlying code and documentation. There are many ways to
perform this feat, and you may have heard of some of the systems that are
-currently used to do this. The Concurrent Version System (CVS) is probably
-the most well known.
-
-The |ns3| project uses Mercurial as its source code management system.
-Although you do not need to know much about Mercurial in order to complete
-this tutorial, we recommend becoming familiar with Mercurial and using it
-to access the source code. Mercurial has a web site at
-http://www.selenic.com/mercurial/,
-from which you can get binary or source releases of this Software
-Configuration Management (SCM) system. Selenic (the developer of Mercurial)
-also provides a tutorial at
-http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial/,
-and a QuickStart guide at
-http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart/.
-
-You can also find vital information about using Mercurial and |ns3|
-on the main |ns3| web site.
+currently used to do this. Until recently, the |ns3| project used Mercurial
+as its source code management system, but in December 2018, switch to
+using Git. Although you do not need to know much about Git in order to
+complete this tutorial, we recommend becoming familiar with Git and using it
+to access the source code. GitLab.com provides resources to get started
+at: https://docs.gitlab.com/ee/gitlab-basics/.
Waf
***
@@ -63,8 +54,8 @@ The build system Waf is used on the |ns3| project. It is one
of the new generation of Python-based build systems. You will not need to
understand any Python to build the existing |ns3| system.
-For those interested in the gory details of Waf, the main web site can be
-found at http://code.google.com/p/waf/.
+For those interested in the gory details of Waf, the Waf book is available
+at https://waf.io/book/ and the current code at https://gitlab.com/ita1024/waf/.
Development Environment
***********************
@@ -76,8 +67,8 @@ knowledge of C++ and object-oriented concepts is assumed in this document.
We will take some time to review some of the more advanced concepts or
possibly unfamiliar language features, idioms and design patterns as they
appear. We don't want this tutorial to devolve into a C++ tutorial, though,
-so we do expect a basic command of the language. There are an almost
-unimaginable number of sources of information on C++ available on the web or
+so we do expect a basic command of the language. There are a wide
+number of sources of information on C++ available on the web or
in print.
If you are new to C++, you may want to find a tutorial- or cookbook-based
@@ -85,7 +76,7 @@ book or web site and work through at least the basic features of the language
before proceeding. For instance, `this tutorial
`_.
-The |ns3| system uses several components of the GNU "toolchain"
+On Linux, the |ns3| system uses several components of the GNU "toolchain"
for development. A
software toolchain is the set of programming tools available in the given
environment. For a quick review of what is included in the GNU toolchain see,
@@ -93,8 +84,13 @@ http://en.wikipedia.org/wiki/GNU_toolchain. |ns3| uses gcc,
GNU binutils, and gdb. However, we do not use the GNU build system tools,
neither make nor autotools. We use Waf for these functions.
-Typically an |ns3| author will work in Linux or a Linux-like
-environment. For those running under Windows, there do exist environments
+On macOS, the toolchain used is Xcode. |ns3| users on a Mac are strongly
+encouraged to install Xcode and the command-line tools packages from the
+Apple App Store, and to look at the |ns3| installation wiki for more
+information (https://www.nsnam.org/wiki/Installation).
+
+Typically an |ns3| author will work in Linux or a Unix-like environment.
+For those running under Windows, there do exist environments
which simulate the Linux environment to various degrees. The |ns3|
project has in the past (but not presently) supported development in the Cygwin environment for
these users. See http://www.cygwin.com/
@@ -110,7 +106,7 @@ We will assume a basic facility with the Berkeley Sockets API in the examples
used in this tutorial. If you are new to sockets, we recommend reviewing the
API and some common usage cases. For a good overview of programming TCP/IP
sockets we recommend `TCP/IP Sockets in C, Donahoo and Calvert
-`_.
+`_.
There is an associated web site that includes source for the examples in the
book, which you can find at:
@@ -121,6 +117,6 @@ not have access to a copy of the book, the echo clients and servers shown in
the website above) you will be in good shape to understand the tutorial.
There is a similar book on Multicast Sockets,
`Multicast Sockets, Makofske and Almeroth
-`_.
+`_.
that covers material you may need to understand if you look at the multicast
examples in the distribution.