--- a/doc/tutorial/source/getting-started.rst Thu May 09 16:17:01 2013 -0700
+++ b/doc/tutorial/source/getting-started.rst Thu May 09 22:38:09 2013 -0700
@@ -27,6 +27,12 @@
to undertake the job of making pre-built libraries and packages for
operating systems, please contact the ns-developers mailing list.
+In the following, we'll look at two ways of downloading and building
+|ns3|. The first is to download and build an official release
+from the main web site. The second is to fetch and build development
+copies of |ns3|. We'll walk through both examples since the tools
+involved are slightly different.
+
Downloading ns-3
****************
@@ -68,6 +74,7 @@
Downloading ns-3 Using a Tarball
++++++++++++++++++++++++++++++++
+
A tarball is a particular format of software archive where multiple
files are bundled together and the archive possibly compressed.
|ns3| software releases are provided via a downloadable tarball.
@@ -98,21 +105,27 @@
You are now ready to build the |ns3| distribution.
-Downloading ns-3 Using Mercurial
-++++++++++++++++++++++++++++++++
-|ns3| can also be fetched from the project's master code repositories
-using a tool called Mercurial.
-One practice is to create a directory called ``repos`` in one's home
+Downloading ns-3 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.
+
+One practice is to create a directory called ``workspace`` 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
+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
following into your Linux shell (assuming you have installed Mercurial):
::
cd
- mkdir repos
- cd repos
+ mkdir workspace
+ cd workspace
hg clone http://code.nsnam.org/bake
As the hg (Mercurial) command executes, you should see something like the
@@ -130,8 +143,7 @@
45 files updated, 0 files merged, 0 files removed, 0 files unresolved
After the clone command completes, you should have a directory called
-``bake``, the contents of which should
-look something like the following:
+``bake``, the contents of which should look something like the following:
::
@@ -143,13 +155,16 @@
will be to use those scripts to download and build the |ns3|
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 |ns3| development team. The repositories of interest to you will
-be prefixed with "ns-3". Official releases of |ns3| will be
-numbered as ``ns-3.<release>.<hotfix>``. For example, a second hotfix to a
-still hypothetical release forty two of |ns3| would be numbered as
-``ns-3.42.2``.
+There are a few configuration targets available:
+
+1. ``ns-3.17``: 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.17``: 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
+ module, but for development code.
The current development snapshot (unreleased) of |ns3| may be found
at http://code.nsnam.org/ns-3-dev/. The
@@ -158,24 +173,37 @@
to consider staying with an official release if you do not need newly-
introduced features.
-Since the release numbers are going to be changing, we 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.17) in the
-text below. You can find the latest version of the
+You can find the latest version of the
code either by inspection of the repository list or by going to the
`"ns-3 Releases"
<http://www.nsnam.org/releases>`_
-web page and clicking on the latest release link.
+web page and clicking on the latest release link. We'll proceed in
+this tutorial example with ``ns-3.17``.
+
+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.
-Go ahead and change into the ``ns-3-allinone`` directory you created when
-you cloned that repository. We are now going to use the bake tool
-to pull down the various pieces of |ns3| you will be using.
-
-Go ahead and type the following into your shell:
+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):
::
- ./bake.py configure -e ns-3.17
+ export BAKE_HOME=`pwd`/bake
+ export PATH=$PATH:$BAKE_HOME
+ export PYTHONPATH=$PYTHONPATH:$BAKE_HOME
+
+However, setting environment variables is not strictly necessary to
+complete this tutorial, so we'll call bake directly by specifying the path
+to it in our shell commands.
+
+Step into the workspace directory and type the following into your shell:
+
+::
+
+ ./bake.py configure -e ns-3-dev
Next, we'l ask bake to check whether we have enough tools to download
various components. Type:
@@ -207,14 +235,14 @@
> Path searched for tools: /usr/lib64/qt-3.3/bin /usr/lib64/ccache /usr/local/bin /bin /usr/bin /usr/local/sbin /usr/sbin /sbin /home/tomh/bin bin
In particular, download tools such as Mercurial, CVS, GIT, and Bazaar
-are our principal concerns at thi spoint, since they allow us to fetch
+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.
Next, try to download the software:
::
- python ./bake.py download
+ ./bake.py download
should yield something like:
@@ -319,7 +347,7 @@
::
- python bake.py build
+ ./bake.py build
and you should see something like:
@@ -329,12 +357,14 @@
>> Building netanim-3.103 - OK
>> Building ns-3.17 - OK
+*Hint: you can also perform both steps, download and build by calling 'bake.py deploy'.*
+
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:
::
- python bake.py show
+ ./bake.py show
This will list out the various dependencies of the packages you are
trying to build.