From 03aaf53d3d99134fb1b07cf0fdb95bc5351fee69 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Tue, 27 Dec 2011 14:13:26 -0800 Subject: [PATCH] some clarifications to the use of build.py in the tutorial --- doc/tutorial/source/getting-started.rst | 50 +++++++++++++++++++------ 1 file changed, 38 insertions(+), 12 deletions(-) diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst index 36f05edc7..e318f5f1e 100644 --- a/doc/tutorial/source/getting-started.rst +++ b/doc/tutorial/source/getting-started.rst @@ -248,16 +248,20 @@ Building ns-3 Building with build.py ++++++++++++++++++++++ -The first time you build the |ns3| project you should build using the -``allinone`` environment. This will get the project configured for you -in the most commonly useful way. +The first time you build the |ns3| project you can build using a +convenience program found in the +``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 -breath and type the following: +``ns-allinone-3.13`` under your ``~/tarballs`` directory. +Type the following: :: @@ -265,8 +269,10 @@ breath and type the following: 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 -|ns3| without examples and tests if you wish. +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 typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the @@ -305,7 +311,8 @@ development snapshot that you downloaded; e.g. 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 @@ -313,14 +320,19 @@ 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, :: @@ -396,6 +408,7 @@ Now go ahead and switch back to the debug build that includes the examples and t :: + ./waf clean ./waf -d debug --enable-examples --enable-tests configure The build system is now configured and you can build the debug versions of @@ -405,6 +418,10 @@ 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 @@ -425,8 +442,17 @@ available in waf. To explore these options, type: 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, -but now you know how to change the configuration and build optimized code. +Finally, as an aside, it is possible to specify that waf builds the +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 ************