Skip to content

Commit 461547b

Browse files
committed
doc: Update documentation for new ns-allinone package
1 parent c55335b commit 461547b

File tree

8 files changed

+139
-372
lines changed

8 files changed

+139
-372
lines changed

CHANGES.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ This file is a best-effort approach to solving this issue; we will do our best b
3737

3838
### Changes to build system
3939

40+
* The ns-allinone release has been redesigned; it no longer includes ``netanim`` or ``bake`` but instead includes ns-3 plus compatible contributed modules.
41+
4042
### Changed behavior
4143

4244
* (docs) Models documentation format guidelines have been updated.

README.md

Lines changed: 53 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ See the LICENSE file for more details.
1414
## Table of Contents
1515

1616
* [Overview](#overview-an-open-source-project)
17+
* [Software overview](#software-overview)
18+
* [Getting ns-3](#getting-ns-3)
1719
* [Building ns-3](#building-ns-3)
1820
* [Testing ns-3](#testing-ns-3)
1921
* [Running ns-3](#running-ns-3)
@@ -41,13 +43,60 @@ This README excerpts some details from a more extensive
4143
tutorial that is maintained at:
4244
<https://www.nsnam.org/documentation/latest/>
4345

44-
## Building ns-3
46+
## Software overview
47+
48+
From a software perspective, ns-3 consists of a number of C++
49+
libraries organized around different topics and technologies.
50+
Programs that actually run simulations can be written in
51+
either C++ or Python; the use of Python is enabled by
52+
[runtime C++/Python bindings](https://cppyy.readthedocs.io/en/latest/). Simulation programs will
53+
typically link or import the ns `core` library and any additional
54+
libraries that they need. ns-3 requires a modern C++ compiler
55+
installation (g++ or clang++) and the [CMake](https://cmake.org) build system.
56+
Most ns-3 programs are single-threaded; there is some limited
57+
support for parallelization using the [MPI](https://www.nsnam.org/docs/models/html/distributed.html) framework.
58+
ns-3 can also run in a real-time emulation mode by binding to an
59+
Ethernet device on the host machine and generating and consuming
60+
packets on an actual network. The ns-3 APIs are documented
61+
using [Doxygen](https://www.doxygen.nl).
4562

4663
The code for the framework and the default models provided
47-
by ns-3 is built as a set of libraries. User simulations
48-
are expected to be written as simple programs that make
49-
use of these ns-3 libraries.
64+
by ns-3 is built as a set of libraries. The libraries maintained
65+
by the open source project can be found in the `src` directory.
66+
Users may extend ns-3 by adding libraries to the build;
67+
third-party libraries can be found on the [ns-3 App Store](https://www.nsnam.org)
68+
or elsewhere in public Git repositories, and are usually added to the `contrib` directory.
69+
70+
## Getting ns-3
71+
72+
ns-3 can be obtained by either downloading a released source
73+
archive, or by cloning the project's
74+
[Git repository](https://gitlab.com/nsnam/ns-3-dev.git).
75+
76+
Starting with ns-3 release version 3.45, there are two versions
77+
of source archives that are published with each release:
78+
79+
1. ns-3.##.tar.bz2
80+
1. ns-allinone-3.##.tar.bz2
81+
82+
The first archive is simply a compressed archive of the same code
83+
that one can obtain by checking out the release tagged code from
84+
the ns-3-dev Git repository. The second archive consists of
85+
ns-3 plus additional contributed modules that are maintained outside
86+
of the main ns-3 open source project but that have been reviewed
87+
by maintainers and lightly tested for compatibility with the
88+
release. The contributed modules included in the `allinone` release
89+
will change over time as new third-party libraries emerge while others
90+
may lose compatibility with the ns-3 mainline (e.g., if they become
91+
unmaintained).
92+
93+
## Building ns-3
5094

95+
As mentioned above, ns-3 uses the CMake build system, but
96+
the project maintains a customized wrapper around CMake
97+
called the `ns3` tool. This tool provides a
98+
[Waf-like](https://waf.io) API
99+
to the underlying CMake build manager.
51100
To build the set of default libraries and the example
52101
programs included in this package, you need to use the
53102
`ns3` tool. This tool provides a Waf-like API to the

RELEASE_NOTES.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,11 @@ been tested on Linux. As of this release, the latest known version to work with
3030

3131
The required Doxygen version for documentation generation is now version 1.13.
3232

33+
Note that the ns-3 allinone archive has been redesigned for this release; the
34+
allinone release no longer contains the `netanim` animator or the `bake` build tools
35+
but instead contains ns-3 plus additional contributed ns-3 modules that are known
36+
to work with the release.
37+
3338
### New user-visible features
3439

3540
- (dsr) !2403 - Reformatted documentation and added a new concept figure.

doc/installation/source/quick-start.rst

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -80,26 +80,25 @@ Download
8080

8181
There are two main options:
8282

83-
1. Download a release tarball. This will unpack to a directory such as ``ns-allinone-3.44``
84-
containing |ns3| and some other programs. Below is a command-line download using ``wget``,
85-
but a browser download will also work::
83+
#. Download a release tarball. This will unpack to a directory such as ``ns-allinone-3.45``
84+
or ``ns-3.45``. Below is a command-line download using ``wget``,
85+
but a browser download will also work::
8686

87-
$ wget https://www.nsnam.org/releases/ns-allinone-3.44.tar.bz2
88-
$ tar xfj ns-allinone-3.44.tar.bz2
89-
$ cd ns-allinone-3.44/ns-3.44
87+
$ wget https://www.nsnam.org/releases/ns-allinone-3.45.tar.bz2
88+
$ tar xfj ns-allinone-3.45.tar.bz2
89+
$ cd ns-3.45
9090

91-
2. Clone |ns3| from the Git repository. The ``ns-3-allinone`` can be cloned, as well as
92-
``ns-3-dev`` by itself. Below, we illustrate the latter::
91+
#. Clone |ns3| from the ``ns-3-dev`` Git repository::
9392

94-
$ git clone https://gitlab.com/nsnam/ns-3-dev.git
95-
$ cd ns-3-dev
93+
$ git clone https://gitlab.com/nsnam/ns-3-dev.git
94+
$ cd ns-3-dev
9695

9796
Note that if you select option 1), your directory name will contain the release number. If
9897
you clone |ns3|, your directory will be named ``ns-3-dev``. By default, Git will check out
9998
the |ns3| ``master`` branch, which is a development branch. All |ns3| releases are tagged
10099
in Git, so if you would then like to check out a past release, you can do so as follows::
101100

102-
$ git checkout -b ns-3.44-release ns-3.44
101+
$ git checkout -b ns-3.45-release ns-3.45
103102

104103
In this quick-start, we are omitting download and build instructions for optional |ns3| modules,
105104
the ``NetAnim`` animator, Python bindings, and ``NetSimulyzer``. The

doc/manual/source/python.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -173,9 +173,9 @@ Here is some example code that is written in Python and that runs |ns3|, which i
173173
Running Python Scripts
174174
**********************
175175

176-
For users that want to change upstream modules in C++ and got a copy of
177-
ns-3 by Git cloning the ns-3-dev repository, or downloaded the
178-
ns3-allinone package, or is using bake, continue to the next section.
176+
For users who want to change upstream modules in C++ and who obtained a copy of
177+
ns-3 by Git cloning the ns-3-dev repository, or by downloading a released
178+
source archive, continue to the next section.
179179

180180
`Note: models implemented in Python are not available from C++. If you want
181181
your model to be available for both C++ and Python users, you must implement

doc/release_steps.txt

Lines changed: 36 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,22 @@
11
Steps in doing an ns-3 release
22

3-
We typically post release candidates for testing at the following URL:
4-
https://www.nsnam.org/release/ns-allinone-3.X.rcX.tar.bz2
3+
Starting with ns-3.45, there are two release versions-- the "mainline"
4+
release (ns-3-dev by itself) and the "allinone" release (ns-3 plus
5+
compatible app store modules).
56

6-
This overview covers the following release stages:
7+
We typically post release candidates for testing at the following URLs:
8+
9+
(mainline): https://www.nsnam.org/release/ns-3.X.rcX.tar.bz2
10+
(allinone): https://www.nsnam.org/release/ns-allinone-3.X.rcX.tar.bz2
11+
12+
This overview covers the following release stages for the mainline release:
713
1) new feature additions and bug fixing
814
2) preparing release candidates for testing
915
3) making the actual release
1016
4) maintaining the release
1117

18+
Some additional notes for the allinone release are also included.
19+
1220
1) new feature additions and bug fixing
1321
---------------------------------------
1422

@@ -26,48 +34,41 @@ when the release is imminent.
2634
-------------------------------------------
2735

2836
This step presumes that you have a reasonably solid ns-3-dev that you
29-
and/or the buildbots have been testing
37+
and/or the CI have been testing
3038
- building static, optimized, and debug versions
3139
- try Python visualizer (not tested by buildbots)
3240
-- ./ns3 run src/flow-monitor/examples/wifi-olsr-flowmon.py --vis
33-
- ensure that tests pass (./test.py -g) and make sure that the buildbots
41+
- ensure that tests pass (./test.py -g) and make sure that the CI scripts
3442
are reporting 'pass' state, based on the tip of the repository
3543
- revise and check in AUTHORS, RELEASE_NOTES.md, and CHANGES.html
3644
- required versions for related libraries (netanim, cppyy)
3745
are correct
3846
- confirm that Doxygen builds cleanly (./ns3 doxygen),
39-
- confirm that the new bake configurations for the release work correctly
4047
- confirm all documents build: './ns3 docs' and check outputs
4148

4249
2.1) Update the tutorial "Getting Started" and "Quick Start" pages to use the new release number.
4350

4451
An example commit (July 14, 2021) to review is 9df8ef4b2.
4552

46-
2.2) Prepare some bakeconf.xml updates for the new release. Note that the
47-
new release 'ns-3.x' will not be yet available as a tagged release, so
48-
the 'ns-3.x' module may need some indirection to fetch ns-3-dev in its place.
49-
50-
2.3) Check out a clean ns-3-dev somewhere using ns-3-allinone
53+
2.2) Check out a clean ns-3-dev somewhere using ns-3-allinone
5154
- git clone https://gitlab.com/nsnam/ns-3-allinone.git
5255
- cd ns-3-allinone
53-
- ./download.py
56+
- git clone https://gitlab.com/nsnam/ns-3-dev.git
5457
- cd ns-3-dev
55-
- edit VERSION such as "ns-3.31.rc1" (DO NOT commit this change to ns-3-dev)
58+
- edit VERSION such as "ns-3.45.rc1" (DO NOT commit this change to ns-3-dev)
5659
- generate a version.cache file via './ns3 configure --enable-build-version'
5760
- remove other files generated by the previous step ('./ns3 clean')
58-
- cd ../bake
59-
- copy over the modified bakeconf.xml that is being tested
6061
- cd ..
6162
- ./dist.py
6263

63-
This should yield a compressed tarfile, such as: ns-allinone-3.31.rc1.tar.bz2
64+
This should yield a compressed tarfile, such as: ns-3.45.rc1.tar.bz2
6465
Test this, and when satisfied, upload it to
6566
www.nsnam.org:/var/www/html/releases/ (with apache:apache file ownership)
6667

6768
Release candidates from previous releases can be deleted at this point.
6869

6970
Announce the release candidate to ns-developers as:
70-
https://www.nsnam.org/release/ns-allinone-3.31.rc1.tar.bz2
71+
https://www.nsnam.org/release/ns-3.45.rc1.tar.bz2
7172

7273
Iterate the above as needed during the release testing phase.
7374

@@ -95,31 +96,25 @@ The desired outcome is to have a git commit history looking like this:
9596

9697
$ git log --graph --decorate --oneline --all
9798
* 4b27025 (master) Update release files to start next release
98-
* fd075f6 Merge ns-3.34-release branch
99+
* fd075f6 Merge ns-3.45-release branch
99100
|\
100-
| * 3fab3cf (HEAD, tag: ns-3.34) Update availability in RELEASE_NOTES
101-
| * c50aaf7 Update VERSION and documentation tags for ns-3.34 release
101+
| * 3fab3cf (HEAD, tag: ns-3.45) Update availability in RELEASE_NOTES
102+
| * c50aaf7 Update VERSION and documentation tags for ns-3.45 release
102103
|/
103104
* 9df8ef4 doc: Update ns-3 version in tutorial examples
104105
* 9319cdd (origin/master, origin/HEAD) Update CHANGES.html and RELEASE_NOTES
105106

106-
2. Create a final bakeconf.xml and commit it.
107-
108-
Now that the ns-3.34 tagged release is available, a final bakeconf.xml with
109-
final release components can be committed. For a sample commit, view
110-
bake commit ba47854c (July 14, 2021).
111-
112-
3. Create a final distribution tarball
107+
2. Create a final distribution tarball (here, 'nn' stands for the version number):
113108
- git clone https://gitlab.com/nsnam/ns-3-allinone.git
114109
- cd ns-3-allinone
115110
- ./download.py
116111
- cd ns-3-dev
117-
- git checkout -b 'ns-3.x-release' ns-3.x
112+
- git checkout -b 'ns-3.nn-release' ns-3.nn
118113
- ./ns3 configure --enable-build-version
119114
- ./ns3 clean
120115
- cd ../
121116
- ./dist.py (notice we did not build here)
122-
- this will create an ns-allinone-3.x.tar.bz2 tarball
117+
- this will create an ns-3.nn.tar.bz2 tarball
123118

124119
Make sure that the version.cache file included in the source archive looks
125120
something like the below example:
@@ -135,32 +130,28 @@ VERSION_TAG = '"ns-3.37"'
135130
VERSION_TAG_DISTANCE = '0'
136131
VERSION_BUILD_PROFILE = 'default'
137132

138-
4. Test this tarball on at least one system
139-
- check that ns-3-allinone build.py works
140-
- check that bake ns-3.x and ns-allinone-3.x targets work
133+
4. Test this tarball works on at least one system
141134

142-
5. upload "ns-allinone-3.x.tar.bz2" to the /var/www/html/releases/ directory on
135+
5. upload "ns-3.nn.tar.bz2" to the /var/www/html/releases/ directory on
143136
the www.nsnam.org server
144-
- scp ns-allinone-3.x.tar.bz2 www.nsnam.org:~
137+
- scp ns-3.nn.tar.bz2 www.nsnam.org:~
145138
- ssh www.nsnam.org
146-
- sudo cp ns-allinone-3.x.tar.bz2 /var/www/html/releases
139+
- sudo cp ns-3.nn.tar.bz2 /var/www/html/releases
147140
- cd !$
148141

149142
6. give it 644 file permissions, and user/group = apache if it is not already
150-
- sudo chown apache:apache ns-allinone-3.x.tar.bz2
151-
- sudo chmod 644 ns-allinone-3.x.tar.bz2
143+
- sudo chown apache:apache ns-3.nn.tar.bz2
144+
- sudo chmod 644 ns-3.nn.tar.bz2
152145

153146
7. Create a patch file for the releases/patches directory, and upload it
154147
to the server. The main idea is to extract the previous release's
155-
ns-3.(x-1) directory and the new ns-3.x directory, and run a diff over it.
148+
ns-3.(nn-1) directory and the new ns-3.nn directory, and run a diff over it.
156149
- mkdir patchdir && cd patchdir
157-
- wget https://www.nsnam.org/releases/ns-allinone-3.(x-1).tar.bz2
158-
- tar xjf ns-allinone-3.(x-1).tar.bz2
159-
- mv ns-allinone-3.(x-1)/ns-3.(x-1) .
160-
- wget https://www.nsnam.org/releases/ns-allinone-3.x.tar.bz2
161-
- tar xjf ns-allinone-3.x.tar.bz2
162-
- mv ns-allinone-3.x/ns-3.x .
163-
- diff -Naur -x '*.dia' -x '*.pcap' -x '*.png' ns-3.(x-1) ns-3.x > ns-3.(x-1)-to-ns-3.x.patch
150+
- wget https://www.nsnam.org/releases/ns-3.(nn-1).tar.bz2
151+
- tar xjf ns-3.(nn-1).tar.bz2
152+
- wget https://www.nsnam.org/releases/ns-3.nn.tar.bz2
153+
- tar xjf ns-3.nn.tar.bz2
154+
- diff -Naur -x '*.dia' -x '*.pcap' -x '*.png' ns-3.(nn-1) ns-3.nn > ns-3.(nn-1)-to-ns-3.nn.patch
164155

165156
preparing the documentation
166157
----------------------------

0 commit comments

Comments
 (0)