nsmiracle mini-HowTo

Index

1. Introduction
2. Requirements
3. Installation
1. ns-allinone
2. nsmiracle

1. Introduction

This is a very brief tutorial for the installation of the nsmiracle extension the NS simulator.

The ns-allinone-2.33 package is already patched for dynamic libraries. No patch is necessary.

The package dei80211mr is already included in the ns-allinone-2.33 package. Therefore its installation is not needed anymore.

This tutorial has been written by Federico Guerra — fguerra at dei.unipd.it based on the previous made by Nicola Baldo.

2. Requirements

We need the following things:

• the ns-allinone package. Version 2.33 can be downloaded here.
• the nsmiracle package, which can be dowloaded from the repository as instructed here.

Back to Index

Back to NSMiracle Home Page

3. Installation

We will now explain the installation process step-by-step. In this tutorial, we will assume that all downloaded packages have been put in the directory /locale/ns, as shown here below:

user@pcuser:/locale/ns$ ls -l
total 69820
-rw-r--r--  1 user usergroup 70466306 Apr 17 19:45 ns-allinone-2.33.tar.gz
drw-r--r--  1 user usergroup   558144 Apr 23 13:53 nsmiracle-rep

Furthermore, we assume that the user has write permission on the directory /locale/ns/ — this is needed e.g. to create the directory /locale/ns/lib in which dynamic libraries will be installed.

Of course, your mileage may vary — just adjust the paths to your needs.

Back to Index

Back to NSMiracle Home Page

3.1 ns-allinone

Unpack the ns-allinone package:

user@pcuser:/locale/ns$ tar xzf ns-allinone-2.33.tar.gz 

Build NS:

user@pcuser:/locale/ns$ cd ns-allinone-2.33
user@pcuser:/locale/ns/ns-allinone-2.33$ ./install

The build process will generate a lot of output and will last something between 5 and 30 minutes, depending on how fast is your hardware.

If the build process has been successful, you will see the following message:

Ns-allinone package has been installed successfully.
Here are the installation places:
tcl8.4.18:      /locale/ns/ns-allinone-2.33/{bin,include,lib}
tk8.4.18:               /locale/ns/ns-allinone-2.31/{bin,include,lib}
otcl:           /locale/ns/ns-allinone-2.33/otcl-1.13
tclcl:          /locale/ns/ns-allinone-2.33/tclcl-1.19
ns:             /locale/ns/ns-allinone-2.33/ns-2.31/ns
nam:    /locale/ns/ns-allinone-2.33/nam-1.13/nam
xgraph: /locale/ns/ns-allinone-2.33/xgraph-12.1
gt-itm:   /locale/ns/ns-allinone-2.33/itm, edriver, sgb2alt, sgb2ns, sgb2comns, sgb2hierns

----------------------------------------------------------------------------------

Please put /locale/ns/ns-allinone-2.33/bin:/locale/ns/ns-allinone-2.33/tcl8.4.18/unix:/locale/ns/ns-allinone-2.33/tk8.4.18/unix
into your PATH environment; so that you'll be able to run itm/tclsh/wish/xgraph.

IMPORTANT NOTICES:

(1) You MUST put /locale/ns/ns-allinone-2.33/otcl-1.13, /locale/ns/ns-allinone-2.33/lib,
    into your LD_LIBRARY_PATH environment variable.
    If it complains about X libraries, add path to your X libraries
    into LD_LIBRARY_PATH.
    If you are using csh, you can set it like:
                setenv LD_LIBRARY_PATH 
    If you are using sh, you can set it like:
                export LD_LIBRARY_PATH=

(2) You MUST put /locale/ns/ns-allinone-2.33/tcl8.4.18/library into your TCL_LIBRARY environmental
    variable. Otherwise ns/nam will complain during startup.


After these steps, you can now run the ns validation suite with
cd ns-2.33; ./validate

For trouble shooting, please first read ns problems page
http://www.isi.edu/nsnam/ns/ns-problems.html. Also search the ns mailing list archive
for related posts.

The above mentioned update of the environment variables PATH, LD_LIBRARY_PATH and TCL_LIBRARY is needed for the simulator to work. For the common case of bash users, the preferred way of accomplishing this is to edit the ~/.bashrc file. At this point we anticipate that later on we will need to add also /locale/ns/lib to LD_LIBRARY_PATH in order for the NS simulator to find the nsmiracle libraries (cygwin users will need to add /locale/ns/bin to their PATH for the same purpose). We suggest to perform all this modifications now so that we need to edit ~/.bashrc only once.

A long story short, all you need to do is to add the following at the end of your ~/.bashrc:

export LD_LIBRARY_PATH=/locale/ns/ns-allinone-2.33/otcl-1.13:/locale/ns/ns-allinone-2.33/lib:/locale/ns/lib:$LD_LIBRARY_PATH
export PATH=/locale/ns/ns-allinone-2.33/bin:/locale/ns/ns-allinone-2.33/tcl8.4.18/unix:/locale/ns/ns-allinone-2.33/tk8.4.18/unix:/locale/ns/bin:$PATH
export TCL_LIBRARY=/locale/ns/ns-allinone-2.33/tcl8.4.18/library

Please note that the paths to be added vary according to the NS version you're installing; in all cases, stick to the path suggested by the message appearing at the end of the ns-allinone build. Furthermore, rember to reload ~/.bashrc on all open console sessions, so that the environment variables are updated:

user@pcuser:/locale/ns$ source ~/.bashrc

Now, check if the ns executable can be found:

user@pcuser:/locale/ns$ which ns

/locale/ns/ns-allinone-2.33/bin/ns

Finally, we need to test if NS can successfully run simulations. I personally suggest not to run the validate script suggested at the end of the NS build — it is a quite long process, and we can be satisfied with a much simpler test. Just download the ns-simple.tcl script, save it somewhere (e.g., in /locale/ns/) and run it:

user@pcuser:/locale/ns$ ns ns-simple.tcl
CBR packet size = 1000
CBR interval = 0.0080000000000000002
user@pcuser:/locale/ns$

If your ns installation was successful, the simulation will run correctly in a few seconds, and at the end the Network Animator (NAM) will pop up in a new window showing you a nice animation of what you simulated. If you're not familiar with ns, this is the good time to have a look at the NS by Example web page to understand NS basics.

If you had any problems with your ns-2 installation, check out the ns-2 installation problems, bug fixes, and help page.

Back to Index

Back to NSMiracle Home Page

3.2 nsmiracle

The dei80211mr package is already installed in your ns-allinone-2.33 directory.

Cd into the directory /trunk/main of the downloaded repository.

Lanch ./autogen.sh to generate the configure file.

We need to pass some additional parameters to ./configure:

• --with-ns-allinone=<directory>, which is needed to make NS C++ header files (.h) available to the compilation of nsmiracle;
• --prefix=<directory>, which is convenient so that the nsmiracle library will be installed in directory/lib;
• --disable-static, which is convenient so that only dynamic libraries are built — we don't need static libraries since they cannot be used within NS, and we can just save the time by not building them.
• --with-dei80211mr=<directory>, which enables the build of some nsmiracle extensions designed specifically for the dei80211mr library.
In this last case, <directory> is the path in which the dei80211mr package resides, e.g., /locale/ns/ns-allinone-2.33/dei80211mr-1.1.4.

The commands to be executed are reported below:

user@pcuser:/locale/ns/nsmiracle-rep/trunk/main$ ./configure --with-ns-allinone=/locale/ns/ns-allinone-2.33 --prefix=/locale/ns --disable-static --with-dei80211mr=/locale/ns/ns-allinone-2.33/dei80211mr-1.1.4
user@pcuser:/locale/ns/nsmiracle-rep/trunk/main$ make

user@pcuser:/locale/ns/nsmiracle-rep/trunk/main$ make install

• remember to adapt all paths to your needs, unless you're using /locale/ns.
• make sure that the tests run by ./configure have been successful, in particular the tests for ns-allinone
• after running make install, make sure that the path in which library have been installed is in your LD_LIBRARY_PATH environment variable. If you have followed the instructions you should have installed it in /locale/ns/

If everything was OK, you will be able to run the provided sample simulation scripts, e.g.:

user@pcuser:/locale/ns/nsmiracle-rep/trunk/main$ cd samples
user@pcuser:/locale/ns/nsmiracle-rep/trunk/main/samples$ ns link_with_errors_cbr.tcl
Simulating........................................done!
Packet Error Ratio  :   0.050000
Throughput          :   68360.897567
Tracefile     : /tmp/link_with_errors_cbr.tcl.tr
user@pcuser:/locale/ns/nsmiracle-rep/trunk/main/samples$ 
user@pcuser:/locale/ns/nsmiracle-rep/trunk/main/samples$ 
user@pcuser:/locale/ns/nsmiracle-rep/trunk/main/samples$ ns dei80211mr_infrastruct_plus_wired_voip.tcl
num_nodes is set 5
Simulating...done!

Tracefile     : /tmp/voip_wlan_infrastruct_wired.tr
Results file  : /tmp/stats_dei80211mr_infrastruct_plus_wired_voip.tcl_4_6Mbps.log

Again, if you encounter any problems while building the nsmiracle library, you can refer to the nsmiracle-users mailing list.

Back to Index

Back to NSMiracle Home Page