/*! \page pls Packet level simulation
-It is possible to use a packet-level network simulator
-instead of the default flow-based simulation. You may want to use such
-an approach if you have doubts about the validity of the default model
-or if you want to perform some validation experiments. At the moment,
-we support the NS3 and GTNetS simulators.
+\tableofcontents
+It is possible to use a packet-level network simulator instead of the default flow-based models. You may want to use
+this feature if you have doubts about the validity of the default model or want to perform some validation experiments.
-\section pls_simgrid_configuration_gtnets GTNetS as a SimGrid model
+At the moment, we support the well-known <a href="http://www.nsnam.org/"><b>ns-3</b></a> packet-level simulator. Earlier
+releases of SimGrid did support the <b>GTNetS</b> simulator. Its support could possibly be revived by someone who would
+need it.
-\subsection pls_simgrid_configuration_gtnets_compile Compiling a patched version of GTNetS
+\section pls_simgrid_configuration_ns3 ns-3 as a SimGrid model
-GTNetS needs to be patched to work with SimGrid, so the easiest
-solution is to run the following commands:
+This section explains how to replace the SimGrid network models by those of the well-known
+<a href="http://www.nsnam.org/">ns-3</a> packet-level network simulator.
-\verbatim
-# Get the files that we prepared for you
-svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
-cd GTNetS
-
-# Unpack and patch the sources
-unzip gtnets-current.zip
-tar zxvf gtnets-current-patch.tgz
-cd gtnets-current
-cat ../*.patch | patch -p1
-
-# Compile GTNetS
-ln -sf Makefile.linux Makefile
-sed -i 's/-fPIC/-fPIC -fpermissive/g' Makefile
-make depend
-make opt # compile an optimized version (required)
-make debug # compile a debug version (optional)
-
-# Install under /opt
-mkdir -p /opt/gtnets/include /opt/gtnets/lib
-cp -fr SRC/*.h /opt/gtnets/include
-cp libgtsim-opt.so /opt/gtnets/lib/libgtsim.so
-\endverbatim
-
-Some remarks:
-
-<ul>
-
- <li>The patch
- AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch is
- only useful if you want to compile on Itanium 64bits (but should be
- harmless on other architectures). Note that we only provide support
- for Linux so far. Your patches are welcome to improve this ;)</li>
-
- <li>The compilation spits a lot of warnings, but the application
- should compile by the end. If the makefile insists in compiling
- some QT libraries please try a make clean before asking for help.</li>
-
- <li>If you need to use another version of GTNetS, then you will
- probably need to modify the patch. Please drop us a line: we will
- gratefully integrate your work. For the record, the version that we
- provide were downloaded from <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>
- on June 12th, 2008.</li>
-
- <li>Of course you can install GTNets wherever you want on your hard
- disk. We provide the commands for /opt just to help you.</li>
-</ul>
+\subsection pls_simgrid_configuration_ns3_install Installing ns-3
-Add the following to your .bashrc so that it gets defined each time:
-
-\verbatim
-export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}/opt/gtnets/lib/
-\endverbatim
-
-\subsection pls_simgrid_configuration_gtnets_config Enabling SimGrid's support for GTNetS
-
-You just have to enable GTNetS in ccmake or cmake as follows, and
-recompile SimGrid.
-
-\verbatim
-cmake . -Denable_gtnets=ON -Dgtnets_path=/opt/gtnets
-\endverbatim
-
-By the end of the configuration, cmake reports whether GTNetS was found.
-You can also double-check by executing the tests after the compilation.
-
-\verbatim
-$ ctest -R gtnets
-(several tests should be run)
-\endverbatim
-
-\subsection pls_simgrid_configuration_gtnets_use Using GTNetS from SimGrid
-
-A working example can be found in the folder examples/msg/gtnets.
-
-\verbatim
-gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network/model:GTNets
-\endverbatim
-
-For more information, please refer to the <a
-href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS
-Website</a> or to this
-<a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS
-HowTo.html">possibly outdated longer HowTo</a>
-
-\section pls_simgrid_configuration_ns3 NS3 as a SimGrid model
-
-You may want to replace the SimGrid network models by the ones of the
-well known packet-level network simulator <a href="http://www.nsnam.org/">NS-3</a> instead.
-This section explains how to do so.
-
-\subsection pls_simgrid_configuration_ns3_install Installing NS3
-
-The easiest is to install it with the package manager. Under
-Debian/Ubuntu, simply type as root:
+The easiest is to install it with the package manager. Under Debian/Ubuntu, simply type as root:
\verbatim
apt-get install libns3-dev ns3
\verbatim
# Download the source
-wget http://www.nsnam.org/release/ns-allinone-3.22.tar.bz2
-tar -xf ns-allinone-3.22.tar.bz2
-cd ns-allinone-3.22/ns-3.22/
+wget http://www.nsnam.org/release/ns-allinone-3.25.tar.bz2
+tar -xf ns-allinone-3.25.tar.bz2
+cd ns-allinone-3.25/ns-3.25/
# Configure, build and install
-./waf configure --prefix="ns-3_install_directory"
+./waf configure --prefix="/opt/ns3" # or give another path if you prefer
./waf
./waf install
\endverbatim
-For more information, please refer to the NS-3 documentation.
+For more information, please refer to the ns-3 documentation.
-\subsection pls_simgrid_configuration_ns3_config Enabling SimGrid's support for NS3
+\subsection pls_simgrid_configuration_ns3_config Enabling SimGrid's support for ns-3
-Normally, you just have to enable NS3 in ccmake or cmake as follows.
-If you installed NS3 in a regular path, just drop the ns3_path
-configuration item.
+Normally, you just have to enable ns-3 in ccmake or cmake as follows. If you installed ns-3 in a regular path, just
+drop the ns3_path configuration item.
\verbatim
-cmake . -Denable_ns3=ON -Dns3_path=<ns3_path>
+cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
\endverbatim
-By the end of the configuration, cmake reports whether NS-3 was found.
-You can also double-check by executing the tests after the compilation.
+By the end of the configuration, cmake reports whether ns-3 was found. You can also double-check by executing the tests
+after the compilation.
\verbatim
$ ctest -R ns3
-(several tests should be run)
+(test(s) should be run)
\endverbatim
-If you have a NS3 version that is not known (yet) to SimGrid, the
-detection may fail. In that case, edit the file
-buildtools/Cmake/Modules/FindNS3.cmake in your SimGrid tree. The
-required changes are very easy, and documented at the beginning of
-this file.
+If you have a ns-3 version that is not known to SimGrid (yet), the detection may fail. In that case, edit the
+tools/cmake/Modules/FindNS3.cmake file in your SimGrid tree. The
+required changes are very easy, and documented in the file header.
-If the compilation fails when linking the library because of some .a
-file that cannot be used dynamically, that's probably because you only
-installed the libns3-dev library on your Debian, where you also need
-libns3-3. That's probably a bug of the libns3-dev package that should
-depend on the dynamic libraries corresponding to its .so files.
+If the compilation fails when linking the library because of some .a file that cannot be used dynamically, this is
+probably because you only installed the libns3-dev library on your Debian, where you also need libns3-3. This is
+probably a bug of the libns3-dev package that should depend on the dynamic libraries corresponding to its .so files.
-\subsection pls_simgrid_configuration_ns3_use Using NS3 from SimGrid
+\subsection pls_simgrid_configuration_ns3_use Using ns-3 from SimGrid
-A working example of NS3/SimGrid interactions can be found in
-examples/msg/ns3. Basically, you just have to run your SimGrid
-simulation with the configuration option "network/model" set to the
-value "NS3". The rest remains unchanged.
+A working example of ns-3/SimGrid interactions can be found in examples/msg/network-ns3/. Basically, you just have to
+run your SimGrid simulation with the configuration option "network/model" set to "NS3". The rest remains unchanged.
-The following should work from the examples/msg/ns3 folder (ns3 here
-is the name of our example binary).
+The following should work from the examples/msg/network-ns3 folder (network-ns3 is the name of our example binary).
\verbatim
-./ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
+./network-ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
\endverbatim
-A ns-3 platform is automatically created from the SimGrid platform
-file that you will provide. There is some caveats to know:
+A ns-3 platform is automatically created from the provided SimGrid platform file. However, there are some known caveats:
<ul>
- <li>The default values (e.g., TCP parameters) are the ns3
- values. Don't blame us for them.</li>
+ <li>The default values (e.g., TCP parameters) are the ns3 values. Don't blame us for them.</li>
- <li>NS3 networks are routed using the shortest path algorithm, using
- ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
+ <li>ns-3 networks are routed using the shortest path algorithm, using
+ ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
- <li>End hosts cannot have more than one interface card (so, only one
- <link> in your SimGrid platform should link an end host to
- the platform ; if not, your end host will be considered as a
- router. </li>
+ <li>End hosts cannot have more than one interface card (so, only one <link> in your SimGrid platform should
+ link an end host to the platform ; if not, your end host will be considered as a router. </li>
</ul>
-
More about ns-3 simulator <a href="http://www.nsnam.org/">(Official website)</a>
+\subsection ns3_examples Examples
+
+For an example using NS3 as a SimGrid module, please refer to the
+@ref msg_ex_ns3 "relevant section" of the documentation.
+
*/
