ns-3.24: comparison doc/tutorial/source/getting-started.rst

equal deleted inserted replaced

-:a688e3775e21
+:9ef562047d3e
 Building ns-3
 *************
 Building with build.py
 ++++++++++++++++++++++
-The first time you build the |ns3| project you should build using the
+The first time you build the |ns3| project you can build using a
-``allinone`` environment.  This will get the project configured for you
+convenience program found in the
-in the most commonly useful way.
+``allinone`` directory.  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, Waf, to be introduced later in this tutorial.
 Change into the directory you created in the download section above.  If you
 downloaded using Mercurial you should have a directory called
 ``ns-3-allinone`` under your ``~/repos`` directory.  If you downloaded
 using a tarball you should have a directory called something like
-``ns-allinone-3.13`` under your ``~/tarballs`` directory.  Take a deep
+``ns-allinone-3.13`` under your ``~/tarballs`` directory.
-breath and type the following:
+Type the following:
 ::
 ./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.  In the future you can build
+build.py tells it to build them for us.  The program also defaults to
-|ns3| without examples and tests if you wish.
+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 typical compiler output messages displayed as the build
 script builds the various pieces you downloaded.  Eventually you should see the
 following magic words:
 cd ns-3-dev
 Building with Waf
 +++++++++++++++++
-We use Waf to configure and build the |ns3| project.  It's not
+Most users directly use Waf to configure and build the |ns3| project.
+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.  By default you have configured
 your project to build the debug version.  Let's tell the project to
 make an optimized build.  To explain to Waf that it should do optimized
 builds that include the examples and tests, you will need to execute the
-following command,
+following commands,
 ::
+./waf clean
 ./waf -d optimized --enable-examples --enable-tests configure
 This runs Waf out of the local directory (which is provided as a convenience
-for you).  As the build system checks for various dependencies you should see
+for you).  The first command to clean out the previous build is not
+typically strictly necessary but is good practice; it will remove the
+previously built libraries and object files found in directory ``build/``.
+When the project is reconfigured and the build system checks for various
+dependencies, you should see
 output that looks similar to the following,
 ::
 Checking for program g++                 : ok /usr/bin/g++
 Now go ahead and switch back to the debug build that includes the examples and tests.
 ::
+./waf clean
 ./waf -d debug --enable-examples --enable-tests configure
 The build system is now configured and you can build the debug versions of
 the |ns3| programs by simply typing
 ::
 ./waf
+Okay, sorry, I made you build the |ns3| part of the system twice,
+but now you know how to change the configuration and build optimized code.
+Here are a few more introductory tips about Waf.
 Some waf commands are meaningful during the build phase and some commands are valid
 in the configuration phase.  For example, if you wanted to use the emulation
 features of |ns3|, you might want to enable setting the suid bit using
 sudo as described above.  This turns out to be a configuration-time command, and so
 you could reconfigure using the following command that also includes the examples and tests
 ./waf --help
 We'll use some of the testing-related commands in the next section.
-Okay, sorry, I made you build the |ns3| part of the system twice,
+Finally, as an aside, it is possible to specify that waf builds the
-but now you know how to change the configuration and build optimized code.
+project in
+a directory different than the default ``build/`` directory by passing
+the ``-o`` option to configure; e.g.
+::
+./waf -d debug -o build/debug --enable-examples --enable-tests configure
+This allows users to work with multiple builds rather than always
+overwriting the last build.
 Testing ns-3
 ************
 You can run the unit tests of the |ns3| distribution by running the

changeset 7661	9ef562047d3e
parent 7654	62ecccd96cad
child 8837	b769bed02bc2