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

doc: Update documentation for new ns-allinone package

Browse Source
This commit is contained in:
Tom Henderson
2025-05-11 10:22:15 -07:00
parent c55335b075
commit 461547ba4d
8 changed files with 139 additions and 372 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGES.md
View File

@@ -37,6 +37,8 @@ This file is a best-effort approach to solving this issue; we will do our best b
### Changes to build system ### Changes to build system
* The ns-allinone release has been redesigned; it no longer includes ``netanim`` or ``bake`` but instead includes ns-3 plus compatible contributed modules.
### Changed behavior ### Changed behavior
* (docs) Models documentation format guidelines have been updated. * (docs) Models documentation format guidelines have been updated.

57
README.md
View File

@@ -14,6 +14,8 @@ See the LICENSE file for more details.
## Table of Contents ## Table of Contents
* [Overview](#overview-an-open-source-project) * [Overview](#overview-an-open-source-project)
* [Software overview](#software-overview)
* [Getting ns-3](#getting-ns-3)
* [Building ns-3](#building-ns-3) * [Building ns-3](#building-ns-3)
* [Testing ns-3](#testing-ns-3) * [Testing ns-3](#testing-ns-3)
* [Running ns-3](#running-ns-3) * [Running ns-3](#running-ns-3)
@@ -41,13 +43,60 @@ This README excerpts some details from a more extensive
tutorial that is maintained at: tutorial that is maintained at:
<https://www.nsnam.org/documentation/latest/> <https://www.nsnam.org/documentation/latest/>
## Building ns-3 ## Software overview
From a software perspective, ns-3 consists of a number of C++
libraries organized around different topics and technologies.
Programs that actually run simulations can be written in
either C++ or Python; the use of Python is enabled by
[runtime C++/Python bindings](https://cppyy.readthedocs.io/en/latest/). Simulation programs will
typically link or import the ns `core` library and any additional
libraries that they need. ns-3 requires a modern C++ compiler
installation (g++ or clang++) and the [CMake](https://cmake.org) build system.
Most ns-3 programs are single-threaded; there is some limited
support for parallelization using the [MPI](https://www.nsnam.org/docs/models/html/distributed.html) framework.
ns-3 can also run in a real-time emulation mode by binding to an
Ethernet device on the host machine and generating and consuming
packets on an actual network. The ns-3 APIs are documented
using [Doxygen](https://www.doxygen.nl).
The code for the framework and the default models provided The code for the framework and the default models provided
by ns-3 is built as a set of libraries. User simulations by ns-3 is built as a set of libraries. The libraries maintained
are expected to be written as simple programs that make by the open source project can be found in the `src` directory.
use of these ns-3 libraries. Users may extend ns-3 by adding libraries to the build;
third-party libraries can be found on the [ns-3 App Store](https://www.nsnam.org)
or elsewhere in public Git repositories, and are usually added to the `contrib` directory.
## Getting ns-3
ns-3 can be obtained by either downloading a released source
archive, or by cloning the project's
[Git repository](https://gitlab.com/nsnam/ns-3-dev.git).
Starting with ns-3 release version 3.45, there are two versions
of source archives that are published with each release:
1. ns-3.##.tar.bz2
1. ns-allinone-3.##.tar.bz2
The first archive is simply a compressed archive of the same code
that one can obtain by checking out the release tagged code from
the ns-3-dev Git repository. The second archive consists of
ns-3 plus additional contributed modules that are maintained outside
of the main ns-3 open source project but that have been reviewed
by maintainers and lightly tested for compatibility with the
release. The contributed modules included in the `allinone` release
will change over time as new third-party libraries emerge while others
may lose compatibility with the ns-3 mainline (e.g., if they become
unmaintained).
## Building ns-3
As mentioned above, ns-3 uses the CMake build system, but
the project maintains a customized wrapper around CMake
called the `ns3` tool. This tool provides a
[Waf-like](https://waf.io) API
to the underlying CMake build manager.
To build the set of default libraries and the example To build the set of default libraries and the example
programs included in this package, you need to use the programs included in this package, you need to use the
`ns3` tool. This tool provides a Waf-like API to the `ns3` tool. This tool provides a Waf-like API to the

5
RELEASE_NOTES.md
View File

@@ -30,6 +30,11 @@ been tested on Linux. As of this release, the latest known version to work with
The required Doxygen version for documentation generation is now version 1.13. The required Doxygen version for documentation generation is now version 1.13.
Note that the ns-3 allinone archive has been redesigned for this release; the
allinone release no longer contains the `netanim` animator or the `bake` build tools
but instead contains ns-3 plus additional contributed ns-3 modules that are known
to work with the release.
### New user-visible features ### New user-visible features
- (dsr) !2403 - Reformatted documentation and added a new concept figure. - (dsr) !2403 - Reformatted documentation and added a new concept figure.

21
doc/installation/source/quick-start.rst
View File

@@ -80,26 +80,25 @@ Download
There are two main options: There are two main options:
1. Download a release tarball. This will unpack to a directory such as ``ns-allinone-3.44`` #. Download a release tarball. This will unpack to a directory such as ``ns-allinone-3.45``
containing |ns3| and some other programs. Below is a command-line download using ``wget``, or ``ns-3.45``. Below is a command-line download using ``wget``,
but a browser download will also work:: but a browser download will also work::
$ wget https://www.nsnam.org/releases/ns-allinone-3.44.tar.bz2 $ wget https://www.nsnam.org/releases/ns-allinone-3.45.tar.bz2
$ tar xfj ns-allinone-3.44.tar.bz2 $ tar xfj ns-allinone-3.45.tar.bz2
$ cd ns-allinone-3.44/ns-3.44 $ cd ns-3.45
2. Clone |ns3| from the Git repository. The ``ns-3-allinone`` can be cloned, as well as #. Clone |ns3| from the ``ns-3-dev`` Git repository::
``ns-3-dev`` by itself. Below, we illustrate the latter::
$ git clone https://gitlab.com/nsnam/ns-3-dev.git $ git clone https://gitlab.com/nsnam/ns-3-dev.git
$ cd ns-3-dev $ cd ns-3-dev
Note that if you select option 1), your directory name will contain the release number. If Note that if you select option 1), your directory name will contain the release number. If
you clone |ns3|, your directory will be named ``ns-3-dev``. By default, Git will check out you clone |ns3|, your directory will be named ``ns-3-dev``. By default, Git will check out
the |ns3| ``master`` branch, which is a development branch. All |ns3| releases are tagged the |ns3| ``master`` branch, which is a development branch. All |ns3| releases are tagged
in Git, so if you would then like to check out a past release, you can do so as follows:: in Git, so if you would then like to check out a past release, you can do so as follows::
$ git checkout -b ns-3.44-release ns-3.44 $ git checkout -b ns-3.45-release ns-3.45
In this quick-start, we are omitting download and build instructions for optional |ns3| modules, In this quick-start, we are omitting download and build instructions for optional |ns3| modules,
the ``NetAnim`` animator, Python bindings, and ``NetSimulyzer``. The the ``NetAnim`` animator, Python bindings, and ``NetSimulyzer``. The

6
doc/manual/source/python.rst
View File

@@ -173,9 +173,9 @@ Here is some example code that is written in Python and that runs |ns3|, which i
Running Python Scripts Running Python Scripts
********************** **********************
For users that want to change upstream modules in C++ and got a copy of For users who want to change upstream modules in C++ and who obtained a copy of
ns-3 by Git cloning the ns-3-dev repository, or downloaded the ns-3 by Git cloning the ns-3-dev repository, or by downloading a released
ns3-allinone package, or is using bake, continue to the next section. source archive, continue to the next section.
`Note: models implemented in Python are not available from C++. If you want `Note: models implemented in Python are not available from C++. If you want
your model to be available for both C++ and Python users, you must implement your model to be available for both C++ and Python users, you must implement

81
doc/release_steps.txt
View File

@@ -1,14 +1,22 @@
Steps in doing an ns-3 release Steps in doing an ns-3 release
We typically post release candidates for testing at the following URL: Starting with ns-3.45, there are two release versions-- the "mainline"
https://www.nsnam.org/release/ns-allinone-3.X.rcX.tar.bz2 release (ns-3-dev by itself) and the "allinone" release (ns-3 plus
compatible app store modules).
This overview covers the following release stages: We typically post release candidates for testing at the following URLs:
(mainline): https://www.nsnam.org/release/ns-3.X.rcX.tar.bz2
(allinone): https://www.nsnam.org/release/ns-allinone-3.X.rcX.tar.bz2
This overview covers the following release stages for the mainline release:
1) new feature additions and bug fixing 1) new feature additions and bug fixing
2) preparing release candidates for testing 2) preparing release candidates for testing
3) making the actual release 3) making the actual release
4) maintaining the release 4) maintaining the release
Some additional notes for the allinone release are also included.
1) new feature additions and bug fixing 1) new feature additions and bug fixing
--------------------------------------- ---------------------------------------
@@ -26,48 +34,41 @@ when the release is imminent.
------------------------------------------- -------------------------------------------
This step presumes that you have a reasonably solid ns-3-dev that you This step presumes that you have a reasonably solid ns-3-dev that you
and/or the buildbots have been testing and/or the CI have been testing
- building static, optimized, and debug versions - building static, optimized, and debug versions
- try Python visualizer (not tested by buildbots) - try Python visualizer (not tested by buildbots)
-- ./ns3 run src/flow-monitor/examples/wifi-olsr-flowmon.py --vis -- ./ns3 run src/flow-monitor/examples/wifi-olsr-flowmon.py --vis
- ensure that tests pass (./test.py -g) and make sure that the buildbots - ensure that tests pass (./test.py -g) and make sure that the CI scripts
are reporting 'pass' state, based on the tip of the repository are reporting 'pass' state, based on the tip of the repository
- revise and check in AUTHORS, RELEASE_NOTES.md, and CHANGES.html - revise and check in AUTHORS, RELEASE_NOTES.md, and CHANGES.html
- required versions for related libraries (netanim, cppyy) - required versions for related libraries (netanim, cppyy)
are correct are correct
- confirm that Doxygen builds cleanly (./ns3 doxygen), - confirm that Doxygen builds cleanly (./ns3 doxygen),
- confirm that the new bake configurations for the release work correctly
- confirm all documents build: './ns3 docs' and check outputs - confirm all documents build: './ns3 docs' and check outputs
2.1) Update the tutorial "Getting Started" and "Quick Start" pages to use the new release number. 2.1) Update the tutorial "Getting Started" and "Quick Start" pages to use the new release number.
An example commit (July 14, 2021) to review is 9df8ef4b2. An example commit (July 14, 2021) to review is 9df8ef4b2.
2.2) Prepare some bakeconf.xml updates for the new release. Note that the 2.2) Check out a clean ns-3-dev somewhere using ns-3-allinone
new release 'ns-3.x' will not be yet available as a tagged release, so
the 'ns-3.x' module may need some indirection to fetch ns-3-dev in its place.
2.3) Check out a clean ns-3-dev somewhere using ns-3-allinone
- git clone https://gitlab.com/nsnam/ns-3-allinone.git - git clone https://gitlab.com/nsnam/ns-3-allinone.git
- cd ns-3-allinone - cd ns-3-allinone
- ./download.py - git clone https://gitlab.com/nsnam/ns-3-dev.git
- cd ns-3-dev - cd ns-3-dev
- edit VERSION such as "ns-3.31.rc1" (DO NOT commit this change to ns-3-dev) - edit VERSION such as "ns-3.45.rc1" (DO NOT commit this change to ns-3-dev)
- generate a version.cache file via './ns3 configure --enable-build-version' - generate a version.cache file via './ns3 configure --enable-build-version'
- remove other files generated by the previous step ('./ns3 clean') - remove other files generated by the previous step ('./ns3 clean')
- cd ../bake
- copy over the modified bakeconf.xml that is being tested
- cd .. - cd ..
- ./dist.py - ./dist.py
This should yield a compressed tarfile, such as: ns-allinone-3.31.rc1.tar.bz2 This should yield a compressed tarfile, such as: ns-3.45.rc1.tar.bz2
Test this, and when satisfied, upload it to Test this, and when satisfied, upload it to
www.nsnam.org:/var/www/html/releases/ (with apache:apache file ownership) www.nsnam.org:/var/www/html/releases/ (with apache:apache file ownership)
Release candidates from previous releases can be deleted at this point. Release candidates from previous releases can be deleted at this point.
Announce the release candidate to ns-developers as: Announce the release candidate to ns-developers as:
https://www.nsnam.org/release/ns-allinone-3.31.rc1.tar.bz2 https://www.nsnam.org/release/ns-3.45.rc1.tar.bz2
Iterate the above as needed during the release testing phase. Iterate the above as needed during the release testing phase.
@@ -95,31 +96,25 @@ The desired outcome is to have a git commit history looking like this:
$ git log --graph --decorate --oneline --all $ git log --graph --decorate --oneline --all
* 4b27025 (master) Update release files to start next release * 4b27025 (master) Update release files to start next release
* fd075f6 Merge ns-3.34-release branch * fd075f6 Merge ns-3.45-release branch
|\ |\
| * 3fab3cf (HEAD, tag: ns-3.34) Update availability in RELEASE_NOTES | * 3fab3cf (HEAD, tag: ns-3.45) Update availability in RELEASE_NOTES
| * c50aaf7 Update VERSION and documentation tags for ns-3.34 release | * c50aaf7 Update VERSION and documentation tags for ns-3.45 release
|/ |/
* 9df8ef4 doc: Update ns-3 version in tutorial examples * 9df8ef4 doc: Update ns-3 version in tutorial examples
* 9319cdd (origin/master, origin/HEAD) Update CHANGES.html and RELEASE_NOTES * 9319cdd (origin/master, origin/HEAD) Update CHANGES.html and RELEASE_NOTES
2. Create a final bakeconf.xml and commit it. 2. Create a final distribution tarball (here, 'nn' stands for the version number):
Now that the ns-3.34 tagged release is available, a final bakeconf.xml with
final release components can be committed. For a sample commit, view
bake commit ba47854c (July 14, 2021).
3. Create a final distribution tarball
- git clone https://gitlab.com/nsnam/ns-3-allinone.git - git clone https://gitlab.com/nsnam/ns-3-allinone.git
- cd ns-3-allinone - cd ns-3-allinone
- ./download.py - ./download.py
- cd ns-3-dev - cd ns-3-dev
- git checkout -b 'ns-3.x-release' ns-3.x - git checkout -b 'ns-3.nn-release' ns-3.nn
- ./ns3 configure --enable-build-version - ./ns3 configure --enable-build-version
- ./ns3 clean - ./ns3 clean
- cd ../ - cd ../
- ./dist.py (notice we did not build here) - ./dist.py (notice we did not build here)
- this will create an ns-allinone-3.x.tar.bz2 tarball - this will create an ns-3.nn.tar.bz2 tarball
Make sure that the version.cache file included in the source archive looks Make sure that the version.cache file included in the source archive looks
something like the below example: something like the below example:
@@ -135,32 +130,28 @@ VERSION_TAG = '"ns-3.37"'
VERSION_TAG_DISTANCE = '0' VERSION_TAG_DISTANCE = '0'
VERSION_BUILD_PROFILE = 'default' VERSION_BUILD_PROFILE = 'default'
4. Test this tarball on at least one system 4. Test this tarball works on at least one system
- check that ns-3-allinone build.py works
- check that bake ns-3.x and ns-allinone-3.x targets work
5. upload "ns-allinone-3.x.tar.bz2" to the /var/www/html/releases/ directory on 5. upload "ns-3.nn.tar.bz2" to the /var/www/html/releases/ directory on
the www.nsnam.org server the www.nsnam.org server
- scp ns-allinone-3.x.tar.bz2 www.nsnam.org:~ - scp ns-3.nn.tar.bz2 www.nsnam.org:~
- ssh www.nsnam.org - ssh www.nsnam.org
- sudo cp ns-allinone-3.x.tar.bz2 /var/www/html/releases - sudo cp ns-3.nn.tar.bz2 /var/www/html/releases
- cd !$ - cd !$
6. give it 644 file permissions, and user/group = apache if it is not already 6. give it 644 file permissions, and user/group = apache if it is not already
- sudo chown apache:apache ns-allinone-3.x.tar.bz2 - sudo chown apache:apache ns-3.nn.tar.bz2
- sudo chmod 644 ns-allinone-3.x.tar.bz2 - sudo chmod 644 ns-3.nn.tar.bz2
7. Create a patch file for the releases/patches directory, and upload it 7. Create a patch file for the releases/patches directory, and upload it
to the server. The main idea is to extract the previous release's to the server. The main idea is to extract the previous release's
ns-3.(x-1) directory and the new ns-3.x directory, and run a diff over it. ns-3.(nn-1) directory and the new ns-3.nn directory, and run a diff over it.
- mkdir patchdir && cd patchdir - mkdir patchdir && cd patchdir
- wget https://www.nsnam.org/releases/ns-allinone-3.(x-1).tar.bz2 - wget https://www.nsnam.org/releases/ns-3.(nn-1).tar.bz2
- tar xjf ns-allinone-3.(x-1).tar.bz2 - tar xjf ns-3.(nn-1).tar.bz2
- mv ns-allinone-3.(x-1)/ns-3.(x-1) . - wget https://www.nsnam.org/releases/ns-3.nn.tar.bz2
- wget https://www.nsnam.org/releases/ns-allinone-3.x.tar.bz2 - tar xjf ns-3.nn.tar.bz2
- tar xjf ns-allinone-3.x.tar.bz2 - diff -Naur -x '*.dia' -x '*.pcap' -x '*.png' ns-3.(nn-1) ns-3.nn > ns-3.(nn-1)-to-ns-3.nn.patch
- mv ns-allinone-3.x/ns-3.x .
- diff -Naur -x '*.dia' -x '*.pcap' -x '*.png' ns-3.(x-1) ns-3.x > ns-3.(x-1)-to-ns-3.x.patch
preparing the documentation preparing the documentation
---------------------------- ----------------------------

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

@@ -91,7 +91,7 @@ of the parent directories contains a space in the directory name:
.. sourcecode:: console .. sourcecode:: console
$ pwd $ pwd
/home/user/5G simulations/ns-3-allinone/ns-3-dev /home/user/5G simulations/ns-3-dev
Downloading a release of ns-3 as a source archive Downloading a release of ns-3 as a source archive
+++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++
@@ -116,22 +116,14 @@ get a copy of a release by typing the following into your Linux shell
$ cd $ cd
$ mkdir workspace $ mkdir workspace
$ cd workspace $ cd workspace
$ wget https://www.nsnam.org/release/ns-allinone-3.44.tar.bz2 $ wget https://www.nsnam.org/release/ns-allinone-3.45.tar.bz2
$ tar xjf ns-allinone-3.44.tar.bz2 $ tar xjf ns-allinone-3.45.tar.bz2
Notice the use above of the ``wget`` utility, which is a command-line 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, tool to fetch objects from the web; if you do not have this installed,
you can use a browser for this step. you can use a browser for this step.
Following these steps, if you change into the directory Following these steps, you should change into the directory ``ns-3.45``.
``ns-allinone-3.44``, you should see a number of files and directories
.. sourcecode:: text
$ cd ns-allinone-3.44
$ ls
bake build.py constants.py netanim-3.109 ns-3.44 README.md util.py
You are now ready to build the base |ns3| distribution and may skip ahead You are now ready to build the base |ns3| distribution and may skip ahead
to the section on building |ns3|. to the section on building |ns3|.
@@ -143,9 +135,8 @@ at https://gitlab.com/nsnam/. The group name ``nsnam`` organizes the
various repositories used by the open source project. various repositories used by the open source project.
The simplest way to get started using Git repositories is to fork or clone 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 the ``ns-3-dev`` repository.
downloading and building of the most commonly used subsystems of |ns3| If you are new to Git, the terminology of ``fork`` and ``clone``
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`` 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 (create your own replica) of the repository found on GitLab.com, as
follows: follows:
@@ -155,301 +146,24 @@ follows:
$ cd $ cd
$ mkdir workspace $ mkdir workspace
$ cd workspace $ cd workspace
$ git clone https://gitlab.com/nsnam/ns-3-allinone.git $ git clone https://gitlab.com/nsnam/ns-3-dev.git
$ cd ns-3-allinone $ cd ns-3-dev
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:: console
$ ls
build.py constants.py download.py README.md 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:: console
$ python3 download.py
or to specify a release of |ns3|, using the ``-n`` flag to specify a
release number:
.. sourcecode:: console
$ python3 download.py -n ns-3.44
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 animations). 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
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.30`` 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`` 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 Git)::
$ cd
$ mkdir workspace
$ cd workspace
$ git clone https://gitlab.com/nsnam/bake.git
As the git command executes, you should see something like the
following displayed:
.. sourcecode:: console
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:
.. sourcecode:: console
$ cd bake
$ ls
bake bakeconf.xml bake.py doc examples generate-binary.py test TODO
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.44``: the code corresponding to the release
2. ``ns-3-dev``: a similar module but using the development code tree
3. ``ns-allinone-3.44``: the module that includes other optional features
such as bake build system, netanim animator, and pybindgen
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
and cloned from 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.
You can find the latest version of the
code either by inspection of the repository list or by going to the
`"ns-3 Releases"
<https://www.nsnam.org/releases>`_
web page and clicking on the latest release link. We'll proceed in
this tutorial example with ``ns-3.44``.
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.
Bake works by downloading source packages into a source directory,
and installing libraries into a build directory. bake can be run
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:
.. sourcecode:: console
$ export BAKE_HOME=`pwd`
$ export PATH=$PATH:$BAKE_HOME/build/bin
$ export PYTHONPATH=$BAKE_HOME/build/lib
$ export LD_LIBRARY_PATH=$BAKE_HOME/build/lib
This will put the bake.py program into the shell's path, and will allow
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:
.. sourcecode:: console
$ ./bake.py configure -e ns-allinone-3.44
Next, we'll ask bake to check whether we have enough tools to download
various components. Type:
.. sourcecode:: console
$ ./bake.py check
You should see something like the following:
.. sourcecode:: text
> Python - OK
> GNU C++ compiler - 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 ...
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:
.. sourcecode:: console
$ ./bake.py download
should yield something like:
.. sourcecode:: text
>> Searching for system dependency libxml2-dev - OK
>> Searching for system dependency gi-cairo - OK
>> Searching for system dependency gir-bindings - OK
>> Searching for system dependency pygobject - OK
>> Searching for system dependency pygraphviz - OK
>> Searching for system dependency python3-dev - OK
>> Searching for system dependency qt - OK
>> Searching for system dependency g++ - OK
>> Searching for system dependency cmake - OK
>> Downloading netanim-3.109 - OK
>> Downloading click-ns-3.37 - OK
>> Downloading BRITE - OK
>> Downloading openflow-dev - OK
>> Downloading ns-3.44 (target directory:ns-3.44) - OK
The above suggests that three sources have been downloaded. Check the
``source`` directory now and type ``ls``; one should see:
.. sourcecode:: console
$ cd source
$ ls
BRITE click-ns-3.37 netanim-3.109 ns-3.44 openflow-dev
You are now ready to build the |ns3| distribution.
Building ns-3 Building ns-3
************* *************
As with downloading |ns3|, there are a few ways to build |ns3|. The main |ns3| is built with
thing that we wish to emphasize is the following. |ns3| is built with
a build tool called ``CMake``, described below. Most users will end up a build tool called ``CMake``, described below. Most users will end up
working most directly with the ns3 command-line wrapper for CMake, for the sake working most directly with the ns3 command-line wrapper for CMake, for the sake
of convenience. Therefore, please have a look at ``build.py`` and building of convenience.
with ``bake``, before reading about CMake and the ns3 wrapper below.
Building with ``build.py``
++++++++++++++++++++++++++
**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
native |ns3| build system, CMake, to be introduced later in this tutorial.
If you downloaded
using a tarball you should have a directory called something like
``ns-allinone-3.44`` under your ``~/workspace`` directory.
Type the following:
.. sourcecode:: console
$ ./build.py --enable-examples --enable-tests
Because we are working with examples and tests in this tutorial, and
because they are not built by default in |ns3|, the arguments for
build.py tells it to build them for us. The program also defaults to
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 compiler output messages displayed as the build
script builds the various pieces you downloaded. First, the script will
attempt to build the netanim animator, and then |ns3|.
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:: console
$ ./bake.py build
and you should see something like:
.. sourcecode:: text
>> Building netanim-3.109 - OK
>> Building ns-3.44 - OK
There may be failures to build all components, but the build will proceed
anyway if the component is optional.
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:: console
$ ./bake.py show
This will list out the various dependencies of the packages you are
trying to build.
Building with the ns3 CMake wrapper Building with the ns3 CMake wrapper
+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++
Up to this point, we have used either the `build.py` script, or the The build process consists of two steps: a configuration stage, and then the
`bake` tool, to get started with building |ns3|. These tools are useful actual compilation. The configuration stage is used to enable and disable
for building |ns3| and supporting libraries, and they call into compiler optimizations and other options and to control the scope of the build.
the |ns3| directory to call the CMake build tool to do the actual building. The project will be configured
CMake needs to be installed before building |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. The project will be configured
by default using the ``default`` build profile, which is an optimized by default using the ``default`` build profile, which is an optimized
build with debug information (CMAKE_BUILD_TYPE=relwithdebinfo) version. build with debug information (CMAKE_BUILD_TYPE=relwithdebinfo) version.
Let's tell the project to make an optimized build. Let's tell the project to make an optimized build.

25
doc/tutorial/source/quick-start.rst
View File

@@ -60,21 +60,28 @@ Downloading the Latest Release
1) Download the latest release from https://www.nsnam.org/releases/latest 1) Download the latest release from https://www.nsnam.org/releases/latest
2) Unpack it in a working directory of your choice. The latest release is available in two versions, as |ns3| by itself (as
maintained by the open source project) or an ``allinone`` archive that
contains |ns3| and additional third-party contributed modules. Note that
the main |ns3| release can always be later extended by adding contributing
modules of your choice
2) Unpack either archive version in a working directory of your choice.
:: ::
$ tar xjf ns-allinone-3.44.tar.bz2 $ tar xjf ns-3.45.tar.bz2
or
::
$ tar xjf ns-allinone-3.45.tar.bz2
3) Change into the |ns3| directory directly; e.g. 3) Change into the |ns3| directory directly; e.g.
:: ::
$ cd ns-allinone-3.44/ns-3.44 $ cd ns-3.45
The ns-allinone directory has some additional components but we are skipping
over them here; one can work directly from the |ns3| source code directory.
The rest of the tutorial describes the additional components.
Cloning ns-3 from GitLab.com Cloning ns-3 from GitLab.com
++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++
@@ -92,12 +99,12 @@ only to `cd` into ns-3-dev; the `master` branch is checked out by default.
$ cd ns-3-dev $ cd ns-3-dev
If instead you want to try the most recent release (version 3.44 as of this If instead you want to try the most recent release (version 3.45 as of this
writing), you can checkout a branch corresponding to that git tag: writing), you can checkout a branch corresponding to that git tag:
:: ::
$ git checkout -b ns-3.44-branch ns-3.44 $ git checkout -b ns-3.45-branch ns-3.45
Building and testing ns-3 Building and testing ns-3
************************* *************************