From 2b005b32caef379a3f806b67e5cffd2925cf9b1b Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Thu, 5 Feb 2015 11:54:48 -0800 Subject: [PATCH] tutorial updates for ns-3.22 --- doc/tutorial/source/getting-started.rst | 93 ++++++++++++++----------- 1 file changed, 53 insertions(+), 40 deletions(-) diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst index 571f4ae11..e3449a125 100644 --- a/doc/tutorial/source/getting-started.rst +++ b/doc/tutorial/source/getting-started.rst @@ -72,6 +72,12 @@ The simplest way to get started using Mercurial repositories is to use 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 +++++++++++++++++++++++++++++++++ @@ -90,32 +96,37 @@ get a copy of a release by typing the following into your Linux shell $ cd $ mkdir workspace $ cd workspace - $ wget http://www.nsnam.org/release/ns-allinone-3.20.tar.bz2 - $ tar xjf ns-allinone-3.20.tar.bz2 + $ wget http://www.nsnam.org/release/ns-allinone-3.22.tar.bz2 + $ tar xjf ns-allinone-3.22.tar.bz2 -If you change into the directory ``ns-allinone-3.20`` you should see a +If you change into the directory ``ns-allinone-3.22`` you should see a number of files:: $ ls - bake constants.py ns-3.20 README - build.py netanim-3.103 pybindgen-0.16.0.825 util.py + bake constants.py ns-3.22 README + build.py netanim-3.105 pybindgen-0.16.0.886 util.py -You are now ready to build the |ns3| distribution. +You are now ready to build the base |ns3| distribution. Downloading |ns3| Using Bake ++++++++++++++++++++++++++++ Bake is a tool for distributed integration and building, -developed for the |ns3| project.  First of all, Bake is -developed in Python, and should be fetched from the project's -master code repositories using a tool called Mercurial, so to -run Bake one must have Python and mercurial on one's machine. +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. -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). You can get a copy of ``bake`` by typing the +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 +for that |ns3| release or earlier, but can't be used to fetch components +for later releases (unless the ``bakeconf.xml`` 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):: $ cd @@ -134,7 +145,7 @@ following displayed, adding changesets adding manifests adding file changes - added 252 changesets with 661 changes to 62 files + 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 @@ -152,10 +163,10 @@ distribution of your choice. There are a few configuration targets available: -1. ``ns-3.20``: the module corresponding to the release; it will download +1. ``ns-3.22``: 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.20``: the module that includes other optional features +3. ``ns-allinone-3.22``: 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 @@ -173,7 +184,7 @@ 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.20``. +this tutorial example with ``ns-3.22``. 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. @@ -199,7 +210,7 @@ full builds of ns-3-allinone (with the optional packages) typically do. Step into the workspace directory and type the following into your shell:: - $ ./bake.py configure -e ns-3.20 + $ ./bake.py configure -e ns-3.22 Next, we'l ask bake to check whether we have enough tools to download various components. Type:: @@ -232,7 +243,9 @@ You should see something like the following, 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 if you are able to. +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:: @@ -243,17 +256,17 @@ should yield something like:: >> Searching for system dependency pygoocanvas - OK >> Searching for system dependency python-dev - OK >> Searching for system dependency pygraphviz - OK - >> Downloading pybindgen-0.16.0.825 - OK + >> Downloading pybindgen-0.16.0.886 - OK >> Searching for system dependency g++ - OK >> Searching for system dependency qt4 - OK - >> Downloading netanim-3.103 - OK - >> Downloading ns-3.20 - OK + >> Downloading netanim-3.105 - OK + >> Downloading ns-3.22 - OK The above suggests that three sources have been downloaded. Check the ``source`` directory now and type ``ls``; one should see:: $ ls - netanim-3.103 ns-3.20 pybindgen-0.16.0.825 + netanim-3.105 ns-3.22 pybindgen-0.16.0.886 You are now ready to build the |ns3| distribution. @@ -272,7 +285,7 @@ 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.20`` under your ``~/workspace`` directory. +``ns-allinone-3.22`` under your ``~/workspace`` directory. Type the following:: $ ./build.py --enable-examples --enable-tests @@ -286,31 +299,31 @@ 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 magic words:: +following:: - Waf: Leaving directory `/path/to/workspace/ns-allinone-3.20/ns-3.20/build' + Waf: Leaving directory `/path/to/workspace/ns-allinone-3.22/ns-3.22/build' 'build' finished successfully (6m25.032s) Modules built: antenna aodv applications bridge buildings config-store core csma csma-layout - dsdv dsr emu - energy fd-net-device flow-monitor - internet lte mesh + dsdv dsr energy + fd-net-device flow-monitor internet + lr-wpan lte mesh mobility mpi netanim (no Python) network nix-vector-routing olsr point-to-point point-to-point-layout propagation - spectrum stats tap-bridge - test (no Python) tools topology-read - uan virtual-net-device wifi - wimax - + sixlowpan spectrum stats + tap-bridge test (no Python) topology-read + uan virtual-net-device visualizer + wifi wimax + Modules not built (see ns-3 tutorial for explanation): brite click openflow visualizer - Leaving directory `./ns-3.20' + Leaving directory `./ns-3.22' Regarding the portion about modules not built:: @@ -336,9 +349,9 @@ may continue to use it to build |ns3|. Type and you should see something like:: - >> Building pybindgen-0.16.0.825 - OK - >> Building netanim-3.103 - OK - >> Building ns-3.20 - OK + >> Building pybindgen-0.16.0.886 - OK + >> Building netanim-3.105 - OK + >> Building ns-3.22 - OK *Hint: you can also perform both steps, download and build by calling 'bake.py deploy'.*