diff --git a/doc/tutorial/source/conclusion.rst b/doc/tutorial/source/conclusion.rst index 53be0d3f3..20b256fa1 100644 --- a/doc/tutorial/source/conclusion.rst +++ b/doc/tutorial/source/conclusion.rst @@ -7,17 +7,8 @@ Conclusion Futures ******* -This document is a work in process. We hope and expect it to grow over time -to cover more and more of the nuts and bolts of |ns3|. - -We hope to add the following chapters over the next few releases: - -* The Callback System -* The Object System and Memory Management -* The Routing System -* Adding a New NetDevice and Channel -* Adding a New Protocol -* Working with Real Networks and Hosts +This document is intended as a living document. We hope and expect it to +grow over time to cover more and more of the nuts and bolts of |ns3|. Writing manual and tutorial chapters is not something we all get excited about, but it is very important to the project. If you are an expert in one of these @@ -28,10 +19,13 @@ Closing ******* |ns3| is a large and complicated system. It is impossible to cover all -of the things you will need to know in one small tutorial. +of the things you will need to know in one small tutorial. Readers +who want to learn more are encouraged to read the following additional +documentation: -We have really just scratched the surface of |ns3| in this tutorial, -but we hope to have covered enough to get you started doing useful networking -research using our favorite simulator. +* The |ns3| manual +* The |ns3| model library documentatio +* The |ns3| Doxygen (API documentation) +* The |ns3| wiki -- The |ns3| development team. diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst index 7f19084be..36f05edc7 100644 --- a/doc/tutorial/source/getting-started.rst +++ b/doc/tutorial/source/getting-started.rst @@ -53,7 +53,6 @@ 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 @@ -69,11 +68,12 @@ following displayed, adding changesets adding manifests adding file changes - added 31 changesets with 45 changes to 7 files + added 47 changesets with 67 changes to 7 files + updating to branch default 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 +``ns-3-allinone``, the contents of which should look something like the following: :: @@ -221,7 +221,7 @@ 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 +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): @@ -230,15 +230,15 @@ get a copy of a release by typing the following into your Linux shell cd mkdir tarballs cd tarballs - wget http://www.nsnam.org/releases/ns-allinone-3.10.tar.bz2 - tar xjf ns-allinone-3.10.tar.bz2 + wget http://www.nsnam.org/releases/ns-allinone-3.13.tar.bz2 + tar xjf ns-allinone-3.13.tar.bz2 -If you change into the directory ``ns-allinone-3.10`` you should see a +If you change into the directory ``ns-allinone-3.13`` you should see a number of files: :: - build.py ns-3.10/ pybindgen-0.15.0/ util.py + build.py ns-3.13/ pybindgen-0.15.0.795/ util.py constants.py nsc-0.5.2/ README You are now ready to build the |ns3| distribution. @@ -256,7 +256,7 @@ 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.10`` under your ``~/tarballs`` directory. Take a deep +``ns-allinone-3.13`` under your ``~/tarballs`` directory. Take a deep breath and type the following: :: @@ -274,7 +274,7 @@ following magic words: :: - Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build' + Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3.13/build' 'build' finished successfully (2m30.586s) Modules built: @@ -292,12 +292,12 @@ following magic words: topology-read uan virtual-net-device visualizer wifi wimax -Once the project has built you can say goodbye to your old friends, the +Once the project has built, you can stop working with the ``ns-3-allinone`` scripts. You got what you needed from them and will now -interact directly with Waf and we do it in the ``ns-3-dev`` directory, +interact directly with Waf and we do it in the |ns3| directory, not in the ``ns-3-allinone`` directory. Go ahead and change into the -``ns-3-dev`` directory (or the directory for the appropriate release you -downloaded. +|ns3| directory (or the directory for the appropriate release or +development snapshot that you downloaded; e.g. :: @@ -399,7 +399,7 @@ Now go ahead and switch back to the debug build that includes the examples and t ./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, +the |ns3| programs by simply typing :: @@ -443,7 +443,7 @@ see a report saying that, :: - 47 of 47 tests passed (47 passed, 0 failed, 0 crashed, 0 valgrind errors) + 92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors) This is the important message. @@ -486,9 +486,9 @@ You will also see output from the test runner and the output will actually look PASS: TestSuite basic-random-number PASS: TestSuite object PASS: TestSuite random-number-generators - 95 of 95 tests passed (95 passed, 0 failed, 0 crashed, 0 valgrind errors) + 92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors) -This command is typically run by ``users`` to quickly verify that an +This command is typically run by users to quickly verify that an |ns3| distribution has built correctly. Running a Script diff --git a/doc/tutorial/source/introduction.rst b/doc/tutorial/source/introduction.rst index f733c72ce..4929cf38c 100644 --- a/doc/tutorial/source/introduction.rst +++ b/doc/tutorial/source/introduction.rst @@ -25,48 +25,49 @@ A few key points are worth noting at the onset: * Ns-3 is not an extension of `ns-2 `_; it is a new simulator. The two simulators are both written in C++ but - |ns3| is a new simulator that does not support the ns-2 APIs. Some - models from ns-2 have already been ported from ns-2 to |ns3|. The - project will continue to maintain ns-2 while |ns3| is being built, + |ns3| is a new simulator that does not support the |ns2| APIs. Some + models from |ns2| have already been ported from |ns2| to |ns3|. The + project will continue to maintain |ns2| while |ns3| is being built, and will study transition and integration mechanisms. * |ns3| is open-source, and the project strives to maintain an - open environment for researchers to contribute and share their software. + open environment for researchers to contribute and share their software. -For ns-2 Users +For |ns2| Users ************** -For those familiar with ns-2, the most visible outward change when moving to -|ns3| is the choice of scripting language. Ns-2 is +For those familiar with |ns2|, the most visible outward change when moving to +|ns3| is the choice of scripting language. Programs in |ns2| are scripted in OTcl and results of simulations can be visualized using the Network Animator nam. It is not possible to run a simulation -in ns-2 purely from C++ (i.e., as a main() program without any OTcl). -Moreover, some components of ns-2 are written in C++ and others in OTcl. +in |ns2| purely from C++ (i.e., as a main() program without any OTcl). +Moreover, some components of |ns2| are written in C++ and others in OTcl. In |ns3|, the simulator is written entirely in C++, with optional Python bindings. Simulation scripts can therefore be written in C++ -or in Python. The results of some simulations can be visualized by -nam, but new animators are under development. Since |ns3| +or in Python. New animators and visualizers are available and under +current development. Since |ns3| generates pcap packet trace files, other utilities can be used to analyze traces as well. In this tutorial, we will first concentrate on scripting directly in C++ and interpreting results via trace files. But there are similarities as well (both, for example, are based on C++ -objects, and some code from ns-2 has already been ported to |ns3|). -We will try to highlight differences between ns-2 and |ns3| +objects, and some code from |ns2| has already been ported to |ns3|). +We will try to highlight differences between |ns2| and |ns3| as we proceed in this tutorial. -A question that we often hear is "Should I still use ns-2 or move to +A question that we often hear is "Should I still use |ns2| or move to |ns3|?" The answer is that it depends. |ns3| does not have -all of the models that ns-2 currently has, but on the other hand, |ns3| +all of the models that |ns2| currently has, but on the other hand, |ns3| does have new capabilities (such as handling multiple interfaces on nodes correctly, use of IP addressing and more alignment with Internet -protocols and designs, more detailed 802.11 models, etc.). ns-2 -models can usually be ported to |ns3| (a porting guide is under -development). There is active development on multiple fronts for -|ns3|. The |ns3| developers believe (and certain early users -have proven) that |ns3| is ready for active use, and should be an -attractive alternative for users looking to start new simulation projects. +protocols and designs, more detailed 802.11 models, etc.). |ns2| +models can sometimes be ported to |ns3| (a porting guide is under +development). The support available on the user mailing list, and the +developer and maintainer activity, is higher for |ns3|. A good guideline +would be to look at both simulators, and in particular the models available +for your research, but when in doubt or when starting new simulation +projects, choose the tool that is under more active development (|ns3|). Contributing ************ @@ -75,13 +76,13 @@ Contributing research community. It will rely on the ongoing contributions of the community to develop new models, debug or maintain existing ones, and share results. There are a few policies that we hope will encourage people to -contribute to |ns3| like they have for ns-2: +contribute to |ns3| like they have for |ns2|: * Open source licensing based on GNU GPLv2 compatibility * `wiki `_ * `Contributed Code - `_ page, similar to ns-2's popular Contributed Code + `_ page, similar to |ns2|'s popular Contributed Code `page `_ * Open `bug tracker diff --git a/doc/tutorial/source/resources.rst b/doc/tutorial/source/resources.rst index 34e77b776..c2b61c5c0 100644 --- a/doc/tutorial/source/resources.rst +++ b/doc/tutorial/source/resources.rst @@ -10,7 +10,7 @@ There are several important resources of which any |ns3| user must be aware. The main web site is located at http://www.nsnam.org and provides access to basic information about the |ns3| system. Detailed documentation is available through the main web site at -http://www.nsnam.org/documents.html. You can also find documents +http://www.nsnam.org/documentation/. You can also find documents relating to the system architecture from this page. There is a Wiki that complements the main |ns3| web site which you will @@ -61,9 +61,7 @@ using the Python language. The build system Waf is used on the |ns3| project. It is one of the new generation of Python-based build systems. You will not need to -understand any Python to build the existing |ns3| system, and will -only have to understand a tiny and intuitively obvious subset of Python in -order to extend the system in most cases. +understand any Python to build the existing |ns3| system. For those interested in the gory details of Waf, the main web site can be found at http://code.google.com/p/waf/. @@ -72,7 +70,7 @@ Development Environment *********************** As mentioned above, scripting in |ns3| is done in C++ or Python. -As of ns-3.2, most of the |ns3| API is available in Python, but the +Most of the |ns3| API is available in Python, but the models are written in C++ in either case. A working knowledge of C++ and object-oriented concepts is assumed in this document. We will take some time to review some of the more advanced concepts or @@ -98,26 +96,10 @@ neither make nor autotools. We use Waf for these functions. Typically an |ns3| author will work in Linux or a Linux-like environment. For those running under Windows, there do exist environments which simulate the Linux environment to various degrees. The |ns3| -project supports development in the Cygwin environment for +project has in the past (but not presently) supported development in the Cygwin environment for these users. See http://www.cygwin.com/ -for details on downloading (MinGW is presently not officially supported, -although some of the project maintainers to work with it). Cygwin provides -many of the popular Linux system commands. It can, however, sometimes be -problematic due to the way it actually does its emulation, and sometimes -interactions with other Windows software can cause problems. - -If you do use Cygwin or MinGW; and use Logitech products, we will save you -quite a bit of heartburn right off the bat and encourage you to take a look -at the `MinGW FAQ -`_. - -Search for "Logitech" and read the FAQ entry, "why does make often -crash creating a sh.exe.stackdump file when I try to compile my source code." -Believe it or not, the ``Logitech Process Monitor`` insinuates itself into -every DLL in the system when it is running. It can cause your Cygwin or -MinGW DLLs to die in mysterious ways and often prevents debuggers from -running. Beware of Logitech software when using Cygwin. - +for details on downloading, and visit the |ns3| wiki for more information +about Cygwin and |ns3|. MinGW is presently not officially supported. Another alternative to Cygwin is to install a virtual machine environment such as VMware server and install a Linux virtual machine.