/*! \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 GTNetS simulator and since version 3.6.2, ns-3.
+\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 Using GTNetS
+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.
+\section pls_simgrid_configuration_ns3 ns-3 as a SimGrid model
-<i>
-To enable GTNetS model inside SimGrid it is needed to patch the GTNetS simulator source code
-and build/install it from scratch
-</i>
+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.
- - <b>Download and enter the recent downloaded GTNetS directory</b>
+\subsection pls_simgrid_configuration_ns3_install Installing ns-3
-\verbatim
-svn checkout svn://scm.gforge.inria.fr/svn/simgrid/contrib/trunk/GTNetS/
-cd GTNetS
-\endverbatim
-
-
- - <b>Use the following commands to unzip and patch GTNetS package to work within SimGrid.</b>
-
-\verbatim
-unzip gtnets-current.zip
-tar zxvf gtnets-current-patch.tgz
-cd gtnets-current
-cat ../00*.patch | patch -p1
-\endverbatim
-
- - <b>OPTIONALLY</b> you can use a patch for itanium 64bit processor family.
-
-\verbatim
-cat ../AMD64-FATAL-Removed-DUL_SIZE_DIFF-Added-fPIC-compillin.patch | patch -p1
-\endverbatim
-
- - <b>Compile GTNetS</b>
-
- Due to portability issues it is possible that GTNetS does not compile in your architecture. The patches furnished in SimGrid SVN repository are intended for use in Linux architecture only. Unfortunately, we do not have the time, the money, neither the manpower to guarantee GTNetS portability. We advice you to use one of GTNetS communication channel to get more help in compiling GTNetS.
-
-
-\verbatim
-ln -sf Makefile.linux Makefile
-sed -i 's/-fPIC/-fPIC -fpermissive/g' Makefile
-make depend
-make debug
-\endverbatim
-
-
- - <b>NOTE</b> A lot of warnings are expected but the application should compile
- just fine. If the makefile insists in compiling some QT libraries
- please try a make clean before asking for help.
-
-
- - <b>To compile optimized version</b>
-
-\verbatim
-make opt
-\endverbatim
-
-
- - <b>Installing GTNetS</b>
-
- It is important to put the full path of your libgtsim-xxxx.so file when creating the symbolic link. Replace < userhome > by some path you have write access to.
-
-\verbatim
-ln -sf /<absolute_path>/gtnets_current/libgtsim-debug.so /<userhome>/usr/lib/libgtnets.so
-export LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}/<userhome>/usr/lib/
-mkdir /<userhome>/usr/include/gtnets
-cp -fr SRC/*.h /<userhome>/usr/include/gtnets
-\endverbatim
-
-
- - <b>Enable GTNetS support in SimGrid</b>
-
-In order to enable gtnets with simgrid you have to give where is gtnets. (path to \<gtnets_path\>/lib and \<gtnets_path\>/include)
-
-\verbatim
-cmake . -Denable_gtnets=ON -Dgtnets_path=/<userhome>/usr
-\endverbatim
-
- - <b>Once you have followed all the instructions for compiling and
- installing successfully you can activate this feature at
- runntime with the following options:</b>
-
-\verbatim
-cd simgrid
-make
-ctest -R gtnets
-\endverbatim
-
-
- - <b>Or try the GTNetS model dogbone example with</b>
-
-\verbatim
-gtnets/gtnets gtnets/onelink-p.xml gtnets/onelink-d.xml --cfg=network_model:GTNets
-\endverbatim
-
-
- A long version of this <a href="http://gforge.inria.fr/docman/view.php/12/6283/GTNetS HowTo.html">HowTo</a> it is available
-
-
- More about GTNetS simulator at <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/index.html">GTNetS Website</a>
-
-
- - <b>DISCLAIMER</b>
- The patches provided by us worked successfully with GTNetS found
- <a href="http://www.ece.gatech.edu/research/labs/MANIACS/GTNetS/software/gtnets-current.zip">here</a>,
- dated from 12th June 2008. Due to the discontinuing development of
- GTNetS it is impossible to precise a version number. We STRONGLY recommend you
- to download and install the GTNetS version found in SimGrid repository as explained above.
-
-\section pls_simgrid_configuration_ns3 Using NS3
-
-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 pls_examples Examples
+
+There is an example in the \c examples/ folder, that shows how to use the bindings. See also the \ref MSG_ex_PLS
+"documentation for this example".
+
*/
