| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ns-3 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, you programmer
editor) you will need to ensure that a number of additional libraries are
present on your system before proceeding. ns-3 provides a wiki
for your reading pleasure that includes pages with many useful hints and tips.
One such page is the “Installation” page,
http://www.nsnam.org/wiki/index.php/Installation.
The “Prerequisites” section of this wiki page explains which packages are
required to support common ns-3 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).
You may want to take this opportunity to explore the ns-3 wiki
a bit since there really is a wealth of information there.
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 as described in the “Getting Started” section
of the ns-3 web site:
http://www.nsnam.org/getting_started.html.
The ns-3 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/releases/, 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 ns-3 for you. We
recommend that you begin your ns-3 adventures in this environment
as it can really simplify your life at this point.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
One practice is to create a directory called repos in one’s home
directory under which one can keep local Mercurial repositories.
Hint: we will assume you do this later in the tutorial. If you adopt
that approach, you can get a copy of ns-3-allinone by typing the
following into your Linux shell (assuming you have installed Mercurial):
cd mkdir repos cd repos hg clone http://code.nsnam.org/ns-3-allinone
As the hg (Mercurial) command executes, you should see something like the following displayed,
destination directory: ns-3-allinone requesting all changes adding changesets adding manifests adding file changes added 31 changesets with 45 changes to 7 files 7 files updated, 0 files merged, 0 files removed, 0 files unresolved
After the clone command completes, you should have a directory called
ns-3-allinone under your ~/repos directory, the contents of which should
look something like the following:
build.py* constants.py dist.py* download.py* README util.py
Notice that you really just downloaded some Python scripts. The next step
will be to use those scripts to download and build the ns-3
distribution of your choice.
If you go to the following link: http://code.nsnam.org/,
you will see a number of repositories. Many are the private repositories of
the ns-3 development team. The repositories of interest to you will
be prefixed with “ns-3”. Official releases of ns-3 will be
numbered as ns-3.<release>.<hotfix>. For example, a second hotfix to a
still hypothetical release nine of ns-3 would be numbered as
ns-3.9.2.
We have had a regression testing framework in place since the first release.
For each release, a set of output files that define “good behavior” are saved.
These known good output files are called reference traces and are associated
with a given release by name. For example, in http://code.nsnam.org/
you will find a repository named ns-3.1 which is the first stable release
of ns-3. You will also find a separate repository named
ns-3.1-ref-traces that holds the reference traces for the ns-3.1
release. It is crucial to keep these files consistent if you want to do any
regression testing of your repository. This is a good idea to do at least once
to verify everything has built correctly.
The current development snapshot (unreleased) of ns-3 may be found
at http://code.nsnam.org/ns-3-dev/ and the associated reference traces
may be found at http://code.nsnam.org/ns-3-dev-ref-traces/. The
developers attempt to keep these repository 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.
Since the release numbers are going to be changing, I will stick with the more constant ns-3-dev here in the tutorial, but you can replace the string “ns-3-dev” with your choice of release (e.g., ns-3.6 and ns-3.6-ref-traces) in the text below. You can find the latest version of the code either by inspection of the repository list or by going to the “Getting Started” web page and looking for the latest release identifier.
Go ahead and change into the ns-3-allinone directory you created when
you cloned that repository. We are now going to use the download.py
script to pull down the various pieces of ns-3 you will be using.
Go ahead and type the following into your shell (remember you can substitute
the name of your chosen release number instead of ns-3-dev – like
"ns-3.6" and "ns-3.6-ref-traces" if you want to work with a
stable release).
./download.py -n ns-3-dev -r ns-3-dev-ref-traces
Note that the default for the -n option is ns-3-dev and the
default for the -r option is ns-3-dev-ref-traces and so the
above is actually redundant. We provide this example to illustrate how to
specify alternate repositories. In order to download ns-3-dev you
can actually use the defaults and simply type,
./download.py
As the hg (Mercurial) command executes, you should see something like the following,
#
# Get NS-3
#
Cloning ns-3 branch
=> hg clone http://code.nsnam.org/ns-3-dev ns-3-dev
requesting all changes
adding changesets
adding manifests
adding file changes
added 4634 changesets with 16500 changes to 1762 files
870 files updated, 0 files merged, 0 files removed, 0 files unresolved
This is output by the download script as it fetches the actual ns-3
code from the repository. Next, you should see something like,
#
# Get the regression traces
#
Synchronizing reference traces using Mercurial.
=> hg clone http://code.nsnam.org/ns-3-dev-ref-traces ns-3-dev-ref-traces
requesting all changes
adding changesets
adding manifests
adding file changes
added 86 changesets with 1178 changes to 259 files
208 files updated, 0 files merged, 0 files removed, 0 files unresolved
This is the download script fetching the reference trace files for you. The download script is smart enough to know that on some platforms various pieces of ns-3 are not supported. On your platform you may not see some of these pieces come down. However, on most platforms, the process should continue with something like,
#
# Get PyBindGen
#
Required pybindgen version: 0.10.0.640
Trying to fetch pybindgen; this will fail if no network connection is available. Hit Ctrl-C to skip.
=> bzr checkout -rrevno:640 https://launchpad.net/pybindgen pybindgen
Fetch was successful.
This was the download script getting the Python bindings generator for you. Note that you will need bazaar (bzr), a version control system, to download PyBindGen. Next you should see (modulo platform variations) something along the lines of,
#
# Get NSC
#
Required NSC version: nsc-0.5.0
Retrieving nsc from https://secure.wand.net.nz/mercurial/nsc
=> hg clone https://secure.wand.net.nz/mercurial/nsc nsc
requesting all changes
adding changesets
adding manifests
adding file changes
added 273 changesets with 17565 changes to 15175 files
10622 files updated, 0 files merged, 0 files removed, 0 files unresolved
This part of the process is the script downloading the Network Simulation Cradle for you. Note that NSC is not supported on OSX or Cygwin and works best with gcc-3.4 or gcc-4.2 or greater series.
After the clone command completes, you should have several new directories
under ~/repos/ns-3-allinone:
build.py* constants.pyc download.py* ns-3-dev-ref-traces/ pybindgen/ util.py constants.py dist.py* ns-3-dev/ nsc/ README util.pyc
Go ahead and change into ns-3-dev under your ~/repos/ns-3-allinone
directory. You should see something like the following there:
AUTHORS examples/ regression/ scratch/ waf* bindings/ LICENSE regression.py src/ waf.bat* CHANGES.html ns3/ RELEASE_NOTES utils/ wscript doc/ README samples/ VERSION wutils.py
You are now ready to build the ns-3 distribution.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The process for downloading ns-3 via tarball is simpler than the
Mercurial process since all of the pieces are pre-packaged for you. You just
have to pick a release, download it and decompress it.
As mentioned above, one practice is to create a directory called repos
in one’s home directory under which one can keep local Mercurial repositories.
One could also keep a tarballs directory. Hint: the tutorial
will assume you downloaded into a repos directory, so remember the
placekeeper. If you adopt the tarballs 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):
cd mkdir tarballs cd tarballs wget http://www.nsnam.org/releases/ns-allinone-3.6.tar.bz2 tar xjf ns-allinone-3.6.tar.bz2
If you change into the directory ns-allinone-3.6 you should see a
number of files:
build.py* ns-3.6/ nsc-0.5.1/ README constants.py ns-3.6-ref-traces/ pybindgen-0.12.0.700/ util.py
You are now ready to build the ns-3 distribution.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated on August 20, 2010 using texi2html 1.82.