Nicolas Christin: ns-2 on Cygwin

Building ns-2 on Cygwin [versions 2.27, 2.26 and 2.1b9a(*)]

This is the pre-ns-2.28 ns-cgwin page from Nicolas Christin, previously abailable at http://www.sims.berkeley.edu/~christin/ns-cygwin.shtml

Here are relatively simple instructions to get the ns-2 network simulator package to fully build on Cygwin for Microsoft Windows 9x/ME/NT/2000/XP. The major differences with the native Win32 build are that (1) you can build allinone, without the need for downloading separate components, (2) the build process doesn't require VisualStudio to compile any component, (3) nam won't run as a standalone Windows application, but within the Cygwin XFree86 server, (4) unless you are using an older version of Cygwin, validation tests should work, and (5), as of ns-2.26, the native Win32 build is not actively maintained anymore, so that you have to use Cygwin. You are strongly advised to read the entire set of following instructions first, before proceeding with the actual install.

Please do not email me privately about this webpage, ns-2, Cygwin, or XFree86, except for pointing out mistakes or typos in this web page. If you have questions, post them on the ns-users mailing-list instead, out of fairness for other users. See Russ Allbery's excellent page for a complete list of reasons why I will not reply to private emails.

(*)Important remark: due to a few syntactic glitches, ns-allinone-2.1b9a does not compile anymore with recent (>= 3.3) versions of gcc. We have no plans in backporting to 2.1b9a the (trivial) patch which fixes those glitches. You should upgrade to 2.27. If that is not feasible, look at the patch ns-allinone-2.26-cygwin.patch for inspiration on how to fix the few compilation problems, or use gcc-3.2.

What you need
- cygwin-1.3.12 or later. May work with older versions but I have not tried, and I would advise against it. cygwin-1.3.19-1 or later is recommended to ensure that all validation tests pass. (See here why.)
  Important: Make sure you have installed Cygwin with the UNIX text type. (It's the default during the Cygwin install procedure.) Using the DOS text type hasn't been tested, but is likely to lead to a number of errors in the validation tests. It's pretty easy to check which text type you are using, just at the prompt, do a
```
mount | grep textmode
```
  and if you don't get anything (i.e., it returns an empty string), you should be fine. If the above command does return something, you are quite likely using the DOS text type, and you may be in trouble.
  Note: I am told that you can change the text type by simply rerunning the Cygwin setup program and changing this option, without reinstalling the whole package, but have not tried it.
  Also, make sure your Cygwin installation directory does not contain any spaces. Spaces in the root directory seem to be causing a lot of problems. In particular, C:\Cygwin (the default) is a good installation directory, C:\Program Files\Cygwin is not.
- XFree86 binaries, sources and configuration files, that is, the XFree86-base, XFree86-bin, XFree86-prog, XFree86-lib, and XFree86-etc packages. They can easily be installed via the Cygwin setup.exe program if you haven't already installed them. If you are unfamiliar with XFree86 and/or Cygwin, we recommend you take a look at the Cygwin XFree86 User Guide, and the references therein.
- The make, patch and diff utilities as well as perl (5.6.1 or above). Again, those can easily be installed via the Cygwin setup.exe program if you haven't already installed them.
- Those should already present in your Cygwin install, but make sure that you have the following set of utilities available: gcc (both gcc and gcc-g++ packages - and version 3.x, not gcc2!), awk, diff, tar, gzip. If some of them are missing (which you can check from the command line by simply issuing the command and see if the shell tells you "command not found"), you must install them with the Cygwin setup.exe program before proceeding.
- This should already be present on your system, but make sure you have the w32api package installed on your system. You can verify this by issuing the command
```
cygcheck -c w32api | grep w32api
```
  If this command returns an empty string, install the w32api package with the Cygwin setup.exe program before proceeding.
- To avoid potential problems, make sure you don't have spaces in your login name and/or the Cygwin installation directory. If you do, change your login name and/or reinstall Cygwin to a different installation directory.
- For ns-allinone-2.27
  - You need ns-allinone-2.27, available at http://www.isi.edu/nsnam/dist/ns-allinone-2.27.tar.gz.
  - You need install.patch to fix a bug in the installer. (To save it, use Right click/Save as..., and save as type "all files")
  For ns-allinone-2.26
  - You need ns-allinone-2.26, available at http://www.isi.edu/nsnam/dist/ns-allinone-2.26.tar.gz
  - All the Cygwin patches have been included in the base distribution, but for some reason, an old file crept its way into the release. You will need to download nam-1.9.configure, available here. (To save it, use Right click/Save as..., and save as type "all files")
  - You need ns-allinone-2.26-cygwin.patch to fix a few problems with recent versions of Cygwin, gcc, and XFree86. (To save it, use Right click/Save as..., and save as type "all files")
- For ns-allinone-2.1b9a
  - You need ns-allinone-2.1b9a patched for gcc-3.2, available at http://www.isi.edu/nsnam/dist/ns-allinone-2.1b9a-gcc32.tar.gz
  - The patch located at http://www.isi.edu/nsnam/dist/ns-allinone-2.1b9a-gcc32-cygwin.patch. (To save it, use Right click/Save as..., and save as type "all files")
  - Remember, ns-allinone-2.1b9a does not compile with gcc-3.3.x or above(*). Stick to gcc-3.2.
How long does it take? It basically depends on your hardware, on what you already have installed on your system, and on your willingness to run the validation tests. To give a rough idea of what you can expect, a full install from scratch (i.e., without Cygwin and XFree86 already present on the system) on a 1.6GHz Pentium 4 with Windows ME was reported to take approximately three hours and a half (including validation tests), while an install of ns-2 allinone on a 2.0GHz Pentium 4M with Windows XP and both Cygwin and XFree86 already installed takes about 15 minutes, plus about an extra hour for validation.
How to install ns-2
In the following, it is important you type all shell commands the way they are given here. In particular, failure to respect the linebreaks (i.e., one command per line) will result in errors.
- ns-allinone-2.27
  - Put the ns-allinone-2.27.tar.gz file in your Cygwin home directory (typically something like C:\cygwin\home\nicolas)
  - Put the install.patch file in your Cygwin home directory as well.
  - Launch Cygwin, start an XFree86 server if you see fit (using startx)
  - From your Cygwin (bash) prompt, run the following commands (each line corresponds to a separate command):
```
gzip -d -c ns-allinone-2.27.tar.gz | tar xvf -
cd ns-allinone-2.27
patch -p0 < ~/install.patch
```
  - You can then just install everything by doing a:
```
./install
```
  - Update your environment variables:
```
export NS_HOME=`pwd`
export PATH=$NS_HOME/tcl8.4.5/unix:$NS_HOME/tk8.4.5/unix:$NS_HOME/bin:$PATH
export LD_LIBRARY_PATH=$NS_HOME/tcl8.4.5/unix:$NS_HOME/tk8.4.5/unix:\
$NS_HOME/otcl-1.8:$NS_HOME/lib:$LD_LIBRARY_PATH
export TCL_LIBRARY=$NS_HOME/tcl8.4.5/library                                    
```
    To avoid retyping these commands everytime you login you can do the following, after having updated your environment variables as described above:
    - Type pwd at the command prompt
    - Note what the shell returns: a directory of the form /home/XXX/ns-allinone-2.27/ (where XXX is your login name)
    - Update your ~/.bashrc file by adding the following commands to it:
```
export NS_HOME=/home/XXX/ns-allinone-2.27/
export PATH=$NS_HOME/tcl8.4.5/unix:$NS_HOME/tk8.4.5/unix:$NS_HOME/bin:$PATH
export LD_LIBRARY_PATH=$NS_HOME/tcl8.4.5/unix:$NS_HOME/tk8.4.5/unix:\
$NS_HOME/otcl-1.8:$NS_HOME/lib:$LD_LIBRARY_PATH
export TCL_LIBRARY=$NS_HOME/tcl8.4.5/library
```
      where you replace /home/XXX/ns-allinone-2.27/ by whatever pwd returned. Make sure you respect the line breaks as shown above.
  - (Optional, run the validation tests with
```
cd ns-2.27; ./validate
```
    after having updated your PATH, LD_LIBRARY_PATH, and TCL_LIBRARY environment variables as described above. Note that the regression suite should work on Cygwin, contrary to classical Win32 builds. Some tests may fail on old versions of Cygwin, this is described later.)
  - That's it, you should have a fully functional ns-allinone-2.27 in your Cygwin environment.
    
    Note: In some cases, re-running ./configure after installation results in an error regarding the X11 library being missing. A quick workaround is discussed in this post in the ns-users mailing-list archives.
    If something doesn't work, send email to the ns-users mailing-list (so that everybody else can see your problem as well) with a detailed output.
- ns-allinone-2.26
  - Put the ns-allinone-2.26.tar.gz file in your Cygwin home directory (typically something like C:\cygwin\home\nicolas)
  - Put the nam-1.9.configure and ns-allinone-2.26-cygwin.patch files in your Cygwin home directory as well.
  - Launch Cygwin, start an XFree86 server if you see fit (using startx)
  - From your Cygwin (bash) prompt, run the following commands (each line corresponds to a separate command):
```
gzip -d -c ns-allinone-2.26.tar.gz | tar xvf -
mv nam-1.9.configure ns-allinone-2.26/nam-1.9/configure
cd ns-allinone-2.26
patch -p0 < ~/ns-allinone-2.26-cygwin.patch 
```
  - You can then just install everything by doing a:
```
./install
```
  - Update your environment variables:
```
export NS_HOME=`pwd`
export PATH=$NS_HOME/tcl8.3.2/unix:$NS_HOME/tk8.3.2/unix:$NS_HOME/bin:$PATH
export LD_LIBRARY_PATH=$NS_HOME/tcl8.3.2/unix:$NS_HOME/tk8.3.2/unix:\
$NS_HOME/otcl-1.0a8:$NS_HOME/lib:$LD_LIBRARY_PATH
export TCL_LIBRARY=$NS_HOME/tcl8.3.2/library                                    
```
    To avoid retyping these commands everytime you login you can do the following, after having updated your environment variables as described above:
    - Type pwd at the command prompt
    - Note what the shell returns: a directory of the form /home/XXX/ns-allinone-2.26/ (where XXX is your login name)
    - Update your ~/.bashrc file by adding the following commands to it:
```
export NS_HOME=/home/XXX/ns-allinone-2.26/
export PATH=$NS_HOME/tcl8.3.2/unix:$NS_HOME/tk8.3.2/unix:$NS_HOME/bin:$PATH
export LD_LIBRARY_PATH=$NS_HOME/tcl8.3.2/unix:$NS_HOME/tk8.3.2/unix:\
$NS_HOME/otcl-1.0a8:$NS_HOME/lib:$LD_LIBRARY_PATH
export TCL_LIBRARY=$NS_HOME/tcl8.3.2/library
```
      where you replace /home/XXX/ns-allinone-2.26/ by whatever pwd returned. Make sure you respect the line breaks as shown above.
  - (Optional, run the validation tests with
```
cd ns-2.26; ./validate
```
    after having updated your PATH, LD_LIBRARY_PATH, and TCL_LIBRARY environment variables as described above. Note that the regression suite should work on Cygwin, contrary to classical Win32 builds. Some tests may fail on old versions of Cygwin, this is described later.)
  - That's it, you should have a fully functional ns-allinone-2.26 in your Cygwin environment.
    
    If something doesn't work, send email to the ns-users mailing-list (so that everybody else can see your problem as well) with a detailed output.
- ns-allinone-2.1b9a
- - Put the ns-allinone-2.1b9a-gcc32.tar.gz file in your Cygwin home directory (typically something like C:\cygwin\home\nicolas)
  - Put the ns-allinone-2.1b9a-gcc32-cygwin.patch file in your Cygwin home directory as well.
  - Launch Cygwin, start an XFree86 server if you see fit (using startx)
  - From your Cygwin (bash) prompt, run the following commands (each line corresponds to a separate command):
```
gzip -d -c ns-allinone-2.1b9a-gcc32.tar.gz | tar xvf -
cd ns-allinone-2.1b9a
patch -p0 < ../ns-allinone-2.1b9a-gcc32-cygwin.patch
```
    You should get an output resembling:
```
patching file ./gt-itm/src/Makefile
patching file ./install
patching file ./nam-1.0a11a/config.sub
patching file ./nam-1.0a11a/configure
patching file ./ns-2.1b9a/bin/raw2xg
patching file ./ns-2.1b9a/diffusion3/lib/nr/nr.hh
patching file ./ns-2.1b9a/tcl/test/test-suite-simple-full.tcl
patching file ./sgb/Makefile
patching file ./tcl8.3.2/generic/tcl.h
patching file ./tcl8.3.2/unix/Makefile.in
```
    If you are running a version of Cygwin between 1.3.12 and 1.3.16-1, you need to modify the install file in the top directory of the distribution. Replace
```
cd ./xgraph-$XGRAPHVER
./configure
```
    by
```
cd ./xgraph-$XGRAPHVER
./configure
touch stamp-h
```
    If the patch succeded, you are all set, and can run
```
./install
```
    If the patch failed, resulting in an error, it probably means that you modified the ns tree prior to trying to apply the patch, or are not using ns-allinone-2.1b9a-gcc32. Jump to the section on what the patch actually does, and do the changes by hand.
  - Update your environment variables:
```
export NS_HOME=`pwd`
export PATH=$NS_HOME/tcl8.3.2/unix:$NS_HOME/tk8.3.2/unix:$NS_HOME/bin:$PATH
export LD_LIBRARY_PATH=$NS_HOME/tcl8.3.2/unix:$NS_HOME/tk8.3.2/unix:\
$NS_HOME/otcl-1.0a8:$NS_HOME/lib:$LD_LIBRARY_PATH
export TCL_LIBRARY=$NS_HOME/tcl8.3.2/library                                    
```
    To avoid retyping these commands everytime you login you can do the following, after having updated your environment variables as described above:
    - Type pwd at the command prompt
    - Note what the shell returns: a directory of the form /home/XXX/ns-allinone-2.1b9a/ (where XXX is your login name)
    - Update your ~/.bashrc file by adding the following commands to it:
```
export NS_HOME=/home/XXX/ns-allinone-2.1b9a/
export PATH=$NS_HOME/tcl8.3.2/unix:$NS_HOME/tk8.3.2/unix:$NS_HOME/bin:$PATH
export LD_LIBRARY_PATH=$NS_HOME/tcl8.3.2/unix:$NS_HOME/tk8.3.2/unix:\
$NS_HOME/otcl-1.0a8:$NS_HOME/lib:$LD_LIBRARY_PATH
export TCL_LIBRARY=$NS_HOME/tcl8.3.2/library
```
      where you replace /home/XXX/ns-allinone-2.1b9a/ by whatever pwd returned. Make sure you respect the line breaks as shown above.
  - (Optional, run the validation tests with
```
cd ns-2.1b9a; ./validate
```
    after having updated your PATH, LD_LIBRARY_PATH, and TCL_LIBRARY environment variables as described above. Note that the regression suite should work on Cygwin, contrary to classical Win32 builds. Some tests may fail for old versions of Cygwin, though, this is described later.)
  - That's it, you should have a fully functional ns-allinone-2.1b9a in your Cygwin environment.
    
    If something doesn't work, send email to the ns-users mailing-list (so that everybody else can see your problem as well) with a detailed output.
    
    If you don't want to/can't run the patch command, what the patch actually does is detailed at the end of the email.
How to run it
- start your XFree86 server from Cygwin with startx.
- configure your PATH, LD_LIBRARY_PATH and TCL_LIBRARY environment variables as you were told when the install script completed, and you should be all set. (Note: I am talking about the PATH environment variable in Cygwin, not the Windows PATH variable.)
- nam will run under XFree86 for Cygwin, it will be a window in your XFree86 server, not a "Windows window".
What breaks: well, pretty much nothing.
- Unless you are running cygwin-1.3.19-1 or a later version, some validation tests fail. These failures are caused by event reordering and are not a cause for concern. Tests that may fail are:
  - For all versions between cygwin-1.3.12 and cygwin-1.3.18-1: test-all-intserv, test-all-plm, test-all-WLtutorial, test-all-diffusion3
  - Only for some versions older than cygwin-1.3.16-1: test-all-friendly, test-all-mcache, test-all-webcache, test-all-wireless-shadowing, test-all-wireless-lan-aodv, test-all-wireless-gridkeeper, test-all-wireless-diffusion, test-all-wireless-lan-newnode, test-all-cbq-v1, test-all-tagged-trace.
  As you can see, it is really a good idea to upgrade to cygwin-1.3.19-1 or later.
- If you did not use ns-allinone-2.26-cygwin.patch, which includes a fix contributed by Jörg Diederich, Queue/PI does not work out of the box. This is not Cygwin-specific (the same problem was also reported on Mandrake Linux 9.0), and is explained in in that post to the ns-users mailing-list.
- The emulator (nse) isn't even compiled. nse currently only runs on BSD, Linux and MacOS X (as of ns-2.26), so this is not surprising. I am working on getting it to run on Cygwin - not completely straightforward, but it appears to be doable. Stay tuned for a patch.
Important disclaimer
- Questions about how to set up Cygwin, XFree86 on Cygwin, or your favorite windows manager will be silently ignored (at least by me), as everything is clearly explained on the various documents one can find at http://www.cygwin.com
What the ns-2.1b9a patch does (useful for if one wants to take a shot at using this type of install on an older version(*) - changes already included in the daily snapshot are marked as such.)
- Nothing is changed for xgraph, cweb, zlib, otcl, tclcl, or tk. These guys compile out of the box.
- The sgb Makefile is modified so that the line
```
rm test.gb sample.out test_io test_graph test_flip test_sample
```
  is replaced by
```
rm -f test.gb sample.out test_io.exe test_graph.exe\ 
test_flip.exe test_sample.exe
```
  [Fix integrated in ns-allinone-2.26, 02/28/2003]
- gt-itm/src/Makefile is modified so that the line starting with eval.o is moved before the line starting with edriver.o, and the line starting with edriver.o is moved before the line starting with edriver. (Note: this is not Cygwin specific, I believe it's just a plain old bug.)
  [Fix integrated in ns-allinone-2.26, 02/28/2003]
- The major "problem" is with tcl8.3.2. In generic/tcl.h, before the lines
```
/*
 * For C++ compilers, use extern "C"
 */
```
  the patch adds
```
/* CYGWIN */
#ifdef __CYGWIN__
#define HAVE_TM_ZONE 1
#endif
```
  The timezone in the tm structure defined in sys/time.h is one of these types that are weirdly defined in Cygwin, so ./configure doesn't get it right, but it does exist.
  
  Also, in unix/Makefile.in, the stub (re)generation has to be removed. In other words, the lines
```
$(GENERIC_DIR)/tclStubInit.c: $(GENERIC_DIR)/tcl.decls \
                $(GENERIC_DIR)/tclInt.decls
        $(TCL_EXE) $(TOOL_DIR)/genStubs.tcl $(GENERIC_DIR) \
                $(GENERIC_DIR)/tcl.decls $(GENERIC_DIR)/tclInt.decls
```
  are deleted. The stubs have no reason to be regenerated, and if they are, make bails out because of a circular dependency. For some reason, this line is called at the first compile on Cygwin, and it shouldn't. Removing it is a pretty dirty hack, but it works. A cleaner solution (via an autoconf test) would be appreciated.
  [More elegant solution now included in the install file of ns-allinone-2.26, 02/28/2003]
- ns itself has to be patched.
  - First, the patch modifies the file diffusion3/lib/nr.hh as follows. The lines
```
#ifdef sparc
typedef char int8_t;
#else
```
    are replaced by
```
#if defined (sparc) || defined (__CYGWIN__)
typedef char int8_t;
#else
```
    [Committed to daily snapshot, 02/03/2003]
  - Second, indep-utils/cmu-scen-gen/setdest/setdest.cc and indep-utils/cmu-scen-gen/setdest/setdest2.cc include a file that does not exist in Cygwin. In both files, one has to replace
```
#if !defined(sun)
```
    by
```
#if !defined(sun) && !defined(__CYGWIN__)
```
    to make sure setdest compiles.
    [Committed to daily snapshot, 02/03/2003]
  - Third, bin/raw2xg (a simple Perl script) has to be modified, because diff is not smart enough to infer that 1e-05 and 1.e-05 are the same thing, causing some validation tests to fail while they are in fact successful. We take care of this issue, by replacing
```
return ($time, $flow * $flow_factor + ($seq % $modulus) * $scale);
```
    by
```
$plotted = $flow * $flow_factor + ($seq % $modulus) * $scale;
$plotted =~ s/\.e/e/g; # to ensure Cygwin compatibility
return ($time, $plotted);
```
    [Committed to daily snapshot, 02/03/2003]
  - Still because some validation tests fail when they shouldn't, we ought to modify tcl/test/test-suite-simple-full.tcl as follows. First, we replace
```
sub BEGIN { $c = 0; @p = @a = @d = @lu = @ld = (); }
/^[\+-] / && do {
```
    by
```
sub BEGIN { $c = 0; @p = @a = @d = @lu = @ld = (); }
$plotted = $F[7] + ($F[10] % 90040) * 0.00001;
$plotted =~ s/\.e/e/g; # needed for Cygwin compatibility

/^[\+-] / && do {
```
    and then,
```
push(@p, $F[1], ' ',            \
        $F[7] + ($F[10] % 90040) * 0.00001, "\n");
```
    by
```
push(@p, $F[1], ' ',            \
       $plotted, "\n");
```
    everywhere. Observant people will have noted this is in fact exactly the same fix as in the previous item, except that this particular test doesn't use raw2xg but in fact inlines the same code, probably for historical reasons.
    [Committed to daily snapshot, 02/03/2003]
  - And the last modification to ensure that all tests that are supposed to work actually do work concerns the file tcl/test/test-suite-wireless-lan-newnode.tcl. A file isn't properly closed in the version of ns that is currently shipped. While this doesn't matter much on UNIX, Windows won't let you remove that file until it's closed, causing the test to miserably fail. This can be easily remedied by replacing
```
TestSuite instproc finish-basenode {} {
        $self instvar ns_
        global quiet opt
 
        $ns_ flush-trace
```
    by
```
TestSuite instproc finish-basenode {} {
        $self instvar ns_
        global quiet opt tracefd
 
        $ns_ flush-trace
        flush $tracefd
        close $tracefd
```
    [Committed to daily snapshot, 02/03/2003]
- nam has to be patched. In config.sub, cygwin32* has to be replaced by cygwin*.
  [Fixed in daily snapshot, 10/19/2002]
  
  As you can see, none of this is rocket science, yet, it appears to be working just fine. Note that despite running atop an emulation layer, as opposed to the native Win32 build, the Cygwin build appears to run reasonably fast.

(*) For installs of older versions (including 2.1b9a without the gcc-3.2 patches), you will first have to get ns-2 to compile with gcc-3.2. A roadmap of the changes is available in the ns-users mailing-list archives (search them!) at http://mailman.isi.edu/pipermail/ns-users/2002-September/025559.html, http://mailman.isi.edu/pipermail/ns-users/2002-October/026168.html, http://mailman.isi.edu/pipermail/ns-users/2002-October/026186.html, and http://mailman.isi.edu/pipermail/ns-users/2002-October/026138.html, and http://mailman.isi.edu/pipermail/ns-users/2002-October/026389.html for nam. (Entire discussion and ideas courtesy of George Riley, Igor Sobrado, Jun He, Piyush Kenghar, and myself.)
Thomas Knoll has actually prepared a summary of these posts, and instructions on how to patch ns-allinone-2.1b6a, as well as a patched tree for gcc-3.2 of ns-allinone-2.1b6a. He has made all of this available in this page. Presumably, you only need to go through the Cygwin specific modifications detailed above to get 2.1b6a to compile in Cygwin, but I haven't tried it. Last modified: