Using OMNeT++ on Windows with the Cygwin platform
=================================================

Based on a description from Richard Lyon (rlyon01@ozemail.com.au)

IMPORTANT: Do not use the Cygwin gcc 2.95.x compiler, as it generates flawed
exception handling code (will crash when used with coroutines/threads).
Later Cygwin gcc versions (3.2 or later) should be fine.

0. QUICKSTART

Note: If you're unsure what the following steps mean, you should probably
read the long description...

 1. install Cygwin (DOS file mode will be fine)
 2. download X11inc.zip from the OMNeT++ site then extract it to /usr/include/X11
 3. download and extract OMNeT++ (the .tgz bundle)
 4. add omnetpp/bin to the PATH
 5. do the usual GNU stuff: ./configure, make
 6. make sure nedtool, gned, opp_makemake and the sample simulations work

There you go!

1. Introduction

CYGNUS Solutions (now part of RedHat Inc.) produced a Unix-like development
environment for Microsoft Windows, based around the GNU compiler and binary
utilities. Cygwin includes the following packages:

   Development tools: binutils, bison, byacc, dejagnu, diff, expect, flex,
   gas, gcc, gdb, itcl, ld, libstdc++, make, patch, tcl, tix, tk, ...

   User tools: ash, bash, bzip2, diff, fileutils, findutils, gawk,
   grep, gzip, m4, sed, shellutils, tar, textutils, time, ...

The list is ever growing. The inclusion of bison, flex, tcl and tk make
this development environment an ideal candidate for running OMNeT++.
Cygwin is released under the GPL license, which means it is free and
the source code is available. Further details and downloading instructions
may be found on the web at

    http://sources.redhat.com/cygwin/

OMNeT++ (from the 2.0b1 release on) is fully supported under Cygwin.

Due to the differences between Windows and Unix, Cygwin has some quirks
compared to Unix systems. This document explains how to work around these
problems to complete the installation.


2. Installing CYGWIN

Cygwin must be installed before OMNeT++. First you should download
setup.exe which is then used to download and install the packages.
When you start setup.exe, it offers 3 possibilities:
 (1) install from internet
 (2) download from internet
 (3) install from local directory
I suggest you first download the packages and then install them from
the local directory.

You will need to be logged into the Administrator account before starting the
installation. Setup will ask:

 - the root directory. Enter the directory where you want Cygwin to be
   installed. The installer will create a Unix-like file system in this
   directory, with the familiar bin/, etc/, home/, lib/, usr/, var/
   directories.

 - install for all users/just me. This affects visibility of environment
   variables and Start Menu icons.

 - default text file type DOS/Unix. If you select DOS, the Cygwin DLL
   (the layer between the Windows API and the Cygwin programs) will
   transparently convert text files between CR/LF and LF line terminators
   for Cygwin programs, allowing these programs to 'see' LF line endings
   in files that have really CR/LFs on the disk. I recommend you use
   DOS file type.

When selection packages to install, be sure to include the following ones:
   gcc-g++
   make
   bison
   flex
   tcltk
   xorg-x11-base (FIXME is that enough?)

Also, download the BLT source from Sourceforge, untar, build (./configure;make)
and install (make install) it. FIXME refine description!

The installer will create a `Cygwin bash shell' entry in a folder
called `Cygnus Solutions' and also a desktop icon called `Cygwin'.

If you should ever want to uninstall the tools, you may do so via the
"Add/Remove Programs" control panel.

Starting Cygwin will pop up a bash shell with all special environment
variables set up for you.  If you are running Windows 95 or 98 and are faced
with the error message "Out of environment space", you need to increase the
amount of environment space in your config.sys and try again.  Adding the
line `shell=C:\command.com /e:4096 /p' should do the trick if `C:' is your
system drive letter.

Within the bash shell, the installation directory will appear as "/".
Your Windows drives will appear as /cygdrive/c/, /cygdrive/d/, etc.
(Don't be surprised when you don't see a /cygdrive directory in the
file system though!) The cygpath program allows you to convert between
Cygwin-style and Windows style directory names.

It is a good idea to create a .bash_profile for each user who will use Cygwin.
This should be stored in each users home directory (i.e. /home/<you>).
For example, an initial .bash_profile may contain:

    export PS1='# '
    alias ls='ls -aF'
    alias ll='ls -l'
    export TCL_LIBRARY=c:/cygwin/usr/share/tcl8.3

TCL_LIBRARY is necessary to allow tcl/tk to operate correctly.

An editor will be required during the installation. For Unix diehards,
Cygwin contains vi, or you can download emacs. A good NT port of emacs
is available from:

http://www.cs.washington.edu/homes/voelker/ntemacs.html


3. Getting Tcl/Tk to work

The Tcl/Tk libs seemingly don't recognize Cygwin paths. For TCL_LIBRARY,
be sure to use a Windows-style directory name, e.g. use
   TCL_LIBRARY=c:/cygwin11/usr/share/tcl8.3
and not
   TCL_LIBRARY=/usr/share/tcl8.3     ;# WRONG!

Another issue is that Cygwin misses X11 headers that are normally required
to build programs with Tcl/Tk. If you're getting compilation errors like
    /usr/include/tk.h:77: X11/Xlib.h: No such file or directory
while building Tkenv, download X11inc.zip from the OMNeT++ site, and extract
it to your /usr/include/X11 directory.


4. Installing OMNeT++

Download the omnetpp source code and documentation from the omnetpp site.
Make sure you select to download the unix archive omnetpp.tgz.

From the startup menu open the bash shell. This a character based console,
which works in a similar manner to the dos console window. The difference is
that you use unix commands like ls, rm, mkdir, etc ...

Copy the omnetpp archive to the directory where you want to install it
(usually your home directory). Extract the archive using the command:

    tar zxvf omnetpp.tgz

A sub-directory called omnetpp will be created which will contain the simulator
files. You should now add the following lines to your startup file .bash_profile:

    export PATH=$PATH:~/omnetpp/bin

For the variables to be included in the bash environment you will need to
restart the bash shell before proceeding. All following commands in this
section are entered on the bash command line.

First you should check configure.user to make sure it contains the settings
you need:
    notepad configure.user

Note that currently you cannot build dynamic libraries (DLLs) from OMNeT++
sources on CygWin.

Then the usual GNU-like stuff:
    ./configure
    make

You should now test all samples and check they run correctly. As an
example, the dyna example is started by entering the following commands:

    cd ~/omnetpp/samples/dyna
    ./dyna

By default the samples will run using the Tcl/Tk environment. You should see
nice gui windows and dialogs.


5. Reconfiguring the libraries

If you need to recompile the OMNeT++ components with different flags (e.g.
for debugging or optimized for speed), then cd to the top-level omnetpp
directory, edit configure.user accordingly, then say:

    ./configure
    make clean
    make

If you want to recompile just a single library, then cd to the directory
of the library and type:

    make clean
    make

The built libraries and programs are immediately copied to the lib/ and 
bin/ subdirs.


6. Comments

Any questions concerning the use of Cygwin should be directed to the Cygwin
mail list at gnu-win32@cygnus.com. OMNeT++ specific questions should be
directed to the mail list at omnetpp-l@ecselists.eng.monash.edu.au.

If you find any errors in this document please let me know.

