diff --git a/CHANGES.md b/CHANGES.md index 93072f69c..3a6d59d2c 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -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 +* 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 * (docs) Models documentation format guidelines have been updated. diff --git a/README.md b/README.md index 03ad7a227..e21bc7c70 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ See the LICENSE file for more details. ## Table of Contents * [Overview](#overview-an-open-source-project) +* [Software overview](#software-overview) +* [Getting ns-3](#getting-ns-3) * [Building ns-3](#building-ns-3) * [Testing ns-3](#testing-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: -## 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 -by ns-3 is built as a set of libraries. User simulations -are expected to be written as simple programs that make -use of these ns-3 libraries. +by ns-3 is built as a set of libraries. The libraries maintained +by the open source project can be found in the `src` directory. +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 programs included in this package, you need to use the `ns3` tool. This tool provides a Waf-like API to the diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 625c112a9..a41c140c0 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -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. +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 - (dsr) !2403 - Reformatted documentation and added a new concept figure. diff --git a/doc/installation/source/quick-start.rst b/doc/installation/source/quick-start.rst index 75f622034..591f35804 100644 --- a/doc/installation/source/quick-start.rst +++ b/doc/installation/source/quick-start.rst @@ -80,26 +80,25 @@ Download There are two main options: -1. Download a release tarball. This will unpack to a directory such as ``ns-allinone-3.44`` -containing |ns3| and some other programs. Below is a command-line download using ``wget``, -but a browser download will also work:: +#. Download a release tarball. This will unpack to a directory such as ``ns-allinone-3.45`` + or ``ns-3.45``. Below is a command-line download using ``wget``, + but a browser download will also work:: - $ wget https://www.nsnam.org/releases/ns-allinone-3.44.tar.bz2 - $ tar xfj ns-allinone-3.44.tar.bz2 - $ cd ns-allinone-3.44/ns-3.44 + $ wget https://www.nsnam.org/releases/ns-allinone-3.45.tar.bz2 + $ tar xfj ns-allinone-3.45.tar.bz2 + $ cd ns-3.45 -2. Clone |ns3| from the Git repository. The ``ns-3-allinone`` can be cloned, as well as -``ns-3-dev`` by itself. Below, we illustrate the latter:: +#. Clone |ns3| from the ``ns-3-dev`` Git repository:: - $ git clone https://gitlab.com/nsnam/ns-3-dev.git - $ cd ns-3-dev + $ git clone https://gitlab.com/nsnam/ns-3-dev.git + $ cd ns-3-dev 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 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:: - $ 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, the ``NetAnim`` animator, Python bindings, and ``NetSimulyzer``. The diff --git a/doc/manual/source/python.rst b/doc/manual/source/python.rst index cf006bd1a..fe99a1741 100644 --- a/doc/manual/source/python.rst +++ b/doc/manual/source/python.rst @@ -173,9 +173,9 @@ Here is some example code that is written in Python and that runs |ns3|, which i Running Python Scripts ********************** -For users that want to change upstream modules in C++ and got a copy of -ns-3 by Git cloning the ns-3-dev repository, or downloaded the -ns3-allinone package, or is using bake, continue to the next section. +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 by downloading a released +source archive, continue to the next section. `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 diff --git a/doc/release_steps.txt b/doc/release_steps.txt index 43ecc9d73..c5445e318 100644 --- a/doc/release_steps.txt +++ b/doc/release_steps.txt @@ -1,14 +1,22 @@ Steps in doing an ns-3 release -We typically post release candidates for testing at the following URL: -https://www.nsnam.org/release/ns-allinone-3.X.rcX.tar.bz2 +Starting with ns-3.45, there are two release versions-- the "mainline" +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 2) preparing release candidates for testing 3) making the actual release 4) maintaining the release +Some additional notes for the allinone release are also included. + 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 -and/or the buildbots have been testing +and/or the CI have been testing - building static, optimized, and debug versions - try Python visualizer (not tested by buildbots) -- ./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 - revise and check in AUTHORS, RELEASE_NOTES.md, and CHANGES.html - required versions for related libraries (netanim, cppyy) are correct - 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 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. -2.2) Prepare some bakeconf.xml updates for the new release. Note that the -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 +2.2) Check out a clean ns-3-dev somewhere using ns-3-allinone - git clone https://gitlab.com/nsnam/ns-3-allinone.git - cd ns-3-allinone - - ./download.py + - git clone https://gitlab.com/nsnam/ns-3-dev.git - 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' - remove other files generated by the previous step ('./ns3 clean') - - cd ../bake - - copy over the modified bakeconf.xml that is being tested - cd .. - ./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 www.nsnam.org:/var/www/html/releases/ (with apache:apache file ownership) Release candidates from previous releases can be deleted at this point. 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. @@ -95,31 +96,25 @@ The desired outcome is to have a git commit history looking like this: $ git log --graph --decorate --oneline --all * 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 -| * c50aaf7 Update VERSION and documentation tags for ns-3.34 release +| * 3fab3cf (HEAD, tag: ns-3.45) Update availability in RELEASE_NOTES +| * c50aaf7 Update VERSION and documentation tags for ns-3.45 release |/ * 9df8ef4 doc: Update ns-3 version in tutorial examples * 9319cdd (origin/master, origin/HEAD) Update CHANGES.html and RELEASE_NOTES -2. Create a final bakeconf.xml and commit it. - -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 +2. Create a final distribution tarball (here, 'nn' stands for the version number): - git clone https://gitlab.com/nsnam/ns-3-allinone.git - cd ns-3-allinone - ./download.py - 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 clean - cd ../ - ./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 something like the below example: @@ -135,32 +130,28 @@ VERSION_TAG = '"ns-3.37"' VERSION_TAG_DISTANCE = '0' VERSION_BUILD_PROFILE = 'default' -4. Test this tarball 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 +4. Test this tarball works on at least one system -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 - - scp ns-allinone-3.x.tar.bz2 www.nsnam.org:~ + - scp ns-3.nn.tar.bz2 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 !$ 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 chmod 644 ns-allinone-3.x.tar.bz2 + - sudo chown apache:apache ns-3.nn.tar.bz2 + - sudo chmod 644 ns-3.nn.tar.bz2 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 - 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 - - wget https://www.nsnam.org/releases/ns-allinone-3.(x-1).tar.bz2 - - tar xjf ns-allinone-3.(x-1).tar.bz2 - - mv ns-allinone-3.(x-1)/ns-3.(x-1) . - - wget https://www.nsnam.org/releases/ns-allinone-3.x.tar.bz2 - - tar xjf ns-allinone-3.x.tar.bz2 - - 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 + - wget https://www.nsnam.org/releases/ns-3.(nn-1).tar.bz2 + - tar xjf ns-3.(nn-1).tar.bz2 + - wget https://www.nsnam.org/releases/ns-3.nn.tar.bz2 + - tar xjf ns-3.nn.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 preparing the documentation ---------------------------- diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst index 75586ab70..5cad8524d 100644 --- a/doc/tutorial/source/getting-started.rst +++ b/doc/tutorial/source/getting-started.rst @@ -91,7 +91,7 @@ of the parent directories contains a space in the directory name: .. sourcecode:: console $ 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 +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -116,22 +116,14 @@ get a copy of a release by typing the following into your Linux shell $ cd $ mkdir workspace $ cd workspace - $ wget https://www.nsnam.org/release/ns-allinone-3.44.tar.bz2 - $ tar xjf ns-allinone-3.44.tar.bz2 + $ wget https://www.nsnam.org/release/ns-allinone-3.45.tar.bz2 + $ tar xjf ns-allinone-3.45.tar.bz2 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.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 - +Following these steps, you should change into the directory ``ns-3.45``. You are now ready to build the base |ns3| distribution and may skip ahead 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. 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`` +the ``ns-3-dev`` repository. +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: @@ -155,301 +146,24 @@ follows: $ 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:: 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" -`_ -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. + $ git clone https://gitlab.com/nsnam/ns-3-dev.git + $ cd ns-3-dev 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 +|ns3| is built with 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 -of convenience. Therefore, please have a look at ``build.py`` and building -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. +of convenience. Building with the ns3 CMake wrapper +++++++++++++++++++++++++++++++++++ -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 CMake build tool to do the actual building. -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 +The build process consists of two steps: a configuration stage, and then the +actual compilation. The configuration stage is used to enable and disable +compiler optimizations and other options and to control the scope of the build. +The project will be configured by default using the ``default`` build profile, which is an optimized build with debug information (CMAKE_BUILD_TYPE=relwithdebinfo) version. Let's tell the project to make an optimized build. diff --git a/doc/tutorial/source/quick-start.rst b/doc/tutorial/source/quick-start.rst index b1d94322b..86795ab1c 100644 --- a/doc/tutorial/source/quick-start.rst +++ b/doc/tutorial/source/quick-start.rst @@ -60,21 +60,28 @@ Downloading the Latest Release 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. :: - $ cd ns-allinone-3.44/ns-3.44 - -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. + $ cd ns-3.45 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 -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: :: - $ 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 *************************