Using OMNeT++ with Microsoft Visual C++
=======================================

Part of this documentation comes from a readme written by Balazs
KELEMEN (kelemen@sch.bme.hu) in March 2000.

*** IMPORTANT CHANGES ***
  Change in OMNeT++2.3b1: you have to compile both OMNeT++ and model files
  with exception handling and RTTI turned ON! Especially, if RTTI is not
  enabled, simulations will crash in the className() method.

  Another change is that to run big simulations that use activity(),
  you should set a LOW (!) reserved stack size in the linker options:
  64K (/stack:65536 linker flag) will do. This is because the Win32 Fiber API
  uses this number as coroutine stack size, and with the 1MB default,
  it is easy to run out of the 4GB possible address space (4GB/1MB=4096).

*** END IMPORTANT CHANGES ***


1. Prerequisites
~~~~~~~~~~~~~~~~
o  Windows XP, Windows 2000, NT4.0 or other NT-derivative.

   OMNET++ IS NOT SUPPORTED, MOREOVER IT WON'T EVEN WORK ON WIN95/98/ME,
   because it uses the Win32 Fiber API which is only available on NT systems.
   Moreover, the makefiles and some batch (.cmd) files use syntax which
   is not supported by the old command.com. Besides the above "hard"
   prohibitive factors, it is anyway advisable to use a more stable operating
   system.

o  Microsoft Visual Studio 6.0, with at least Service Pack 1 installed.
   I recommend Service Pack 5 which can be downloaded from Microsoft's site
   under the name vs6sp5.exe.

o  About 40MB free space on your hard disk. If your want to compile from
   source, you'll need about 20MB more.


2. Packages to download and install
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you use the binary release, you can skip this section, because the
package contains and the installer installs all other necessary software.

First download the following packages:
 - Tcl/Tk
 - bison/flex (only if you want to modify nedc or gned)
 - Perl (used by some tools)
 - Gnuplot (used by Plove)
 - awk, grep (used by Plove)
 - recommended: LibXML, LibXSLT (for nedtool and opp_neddoc). For nedtool
   you can also use Expat.

Appendix B (at the end of this file) and 3rdparty.txt contains some sites
where all this stuff can be found.

To unpack .tgz or .tar.gz (gzipped, tar packed) files you can use gzip and tar,
or WinZip.

After installation, check if you have the necessary environment variables set.
(See Appendix A!) These variables should be set by the install program of
the related package. Unfortunately this is not always done, so you may have to
set these manually (My Computer-->Properties-->Environment tab).


3. Compiling OMNeT++
~~~~~~~~~~~~~~~~~~~~

If you're using the binary release, you can skip this section.

Download the omnetpp source code and documentation from the omnetpp site.
If you downloaded a zip file, extract its contents to the installation
directory. If you downloaded a tgz file, copy it to the directory where
you want to install OMNeT++, and extract the archive using the command:

    tar zxvf omnetpp.tgz

*** IMPORTANT ***
   AVOID DIRECTORY NAMES WITH SPACE, '+', OR ANY OTHER SPECIAL CHARACTER.
   Odds are that the compilation will choke. In particular, do NOT write
   "OMNeT++", because the copy shell command will misunderstand it
   for file concatenation. Use "omnetpp" instead.

In this text we'll assume that the directory which contains the
simulator files is called c:\omnetpp-2.3.

Make sure the MSVC executables (nmake,cl,link,...) are in the path.
The BIN directories of the VC should appear in the PATH environment variable.
They are C:\PROGRA~1\MICROS~1\VC98\BIN and C:\PROGRA~1\MICROS~1\MSDEV98\BIN
by default.

It is also recommended that you put the c:\omnetpp-2.3\bin directory
into the path.

Check the configuser.vc file to make sure it contains the proper settings.
You'll probably have to correct the following settings in it:
    OMNETPP_ROOT=c:\omnetpp-2.3
    TK_DIR=e:/tcl
    TK_VER=8.4

Then type:
    nmake -f Makefile.vc
This should build the executables and the libraries and copy them to the bin
and lib subdirectories within the top-level omnetpp directory.

Note: As the Visual Studio IDE (and makefiles exported from the IDE)
accept only .cpp as an extension of a C++ file, the .cc files in the
samples/ directory will be renamed.

If you only want to create the executables or the libraries, type
    nmake -f Makefile.vc progs
    nmake -f Makefile.vc libs

To delete all built files, type
    nmake -f Makefile.vc clean

As the result of the compilation the following files should have been created:
In the bin directory:
    seedtool.exe nedc.exe gned.exe nedtool.exe, ...

In the lib directory:
    sim_std.lib envir.lib cmdenv.lib tkenv.lib nedxml.lib


4. Building the samples from the MSVC IDE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To build a sample simulation, start MSVC and open the workspace (.dsw) file.
The simulation should build without any project file adjustment.

The top-level makefile automatically renames the .cc files to .cpp;
but if you want to do it manually, you can run samples/cc2cpp.bat.
The top-level makefile also automatically configures the project (.dsp)
files by substituting the correct Tcl/Tk version and library location.

*** NOTE ***
   BY DEFAULT, THE SAMPLE SIMULATIONS BUILT FROM THE MSVC IDE WILL USE THE
   COMMAND-LINE USER INTERFACE. To change to the graphical interface,
   choose Build|Set active configuration from the MSVC menu and select
   "Debug-Tkenv" or "Release-Tkenv", then re-link the executable.
   Choosing "Debug-Cmdenv" or "Release-Cmdenv" will revert to the command-line
   user interface.

If you need to modify the names of the Tcl/Tk libs (because you installed
a Tcl/Tk version other than 8.4), see Project|Settings --> 'Link' tab -->
choose 'Input' from combo --> Libraries.

*** NOTE ***
   While trying to build some of the samples in the MSVC IDE, you might
   get the following error, even if perl *is* in the PATH:

   Processing .\token.msg with opp_msgc
   'Perl is not recognized as an internal or external command, operable
   program or batch file. Error executing c:\windows\system32\cmd.exe

   This is probably a Visual Studio bug. I'm not sure under which
   circumstances it occurs. It was reported on Windows XP + MSVC 6.0 without
   a service pack (?), but I've been unable to reproduce it on Windows 2000 +
   MSVC 6.0 SP5. Anyhow, if this occurs on your PC, try one/both of the
   following:
     a) install Visual Studio Service Pack 5 (vs6sp5.exe) or later
     b) edit opp_msgc.cmd (in the ..\OMNeT++\bin directory) and
        supply the full path to perl.exe in line 4 (i.e. change "perl" to
        "c:\OMNeT++\bin\perl.exe", "c:\Perl\bin\perl.exe" or the location
        of your perl program)
   If this doesn't work out, please let me know. You can also try the
   workaround described in Mudassar Farooq's email to the mailing list
   on 2/18/2003, with subject "Perl Problem".

   Thanks to Farooq for finding out about this bug.


5. Creating your own simulations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can choose between using the MSVC IDE and makefiles+your favourite
programmer's editor (mine is MED). The latter one may seem more cumbersome,
but actually using the opp_nmakemake tool (described later) you can set up
the build environment within seconds.

If you opt for the MSVC IDE, you can set up the project file in the following
way:

 1. Start by copying and renaming one of the .dsp files from the samples
    directory. It already contains the necessary compiler/linker flags,
    Tkenv/Cmdenv configurations, and so on.

    You can also use the OMNeT++ App Wizard, available under
    File|New -> Projects in the MSVC IDE. This is automatically
    installed by the binary release.

 2. Adjust the project settings so that MSVC will find OMNeT++'s components
    that are needed to build simulation programs. Make sure you enter these
    settings for *all* configurations (In the Project|Settings dialog,
    select 'All configurations' from the combo in the top-left corner.)
    - include path: You must tell MSVC the location of omnetpp.h and other
      header files.  Add c:\omnetpp-2.3\include to the include path in
      Project|Settings --> 'C/C++' tab --> 'Preprocessor' category -->
      Additional include directories.
    - library path: MSVC needs to know where to find sim_std.lib, envir.lib
      and other libraries. Add omnetpp/lib to the linker path in
      Project|Settings --> 'Link' tab --> 'Input' category -->
      Additional library path.
    - nedc: It's advisable to put OMNeT++'s bin directory into the PATH
      so that MSVC will find the NED compiler. (An alternative is to enter
      explicit nedc path for each NED file's Custom build step, but that's
      much more cumbersome.)

 3. Add C++ files to the project. Note that they need to have .cpp extension.
    You might need to rename your .cc files to .cpp (ren *.cc *.cpp) and add
    them to the project.

 4. Add the .ned files to the project and set custom build option for them:
       Description:  NED Compiling $(InputPath)
       Command:      nedc -s _n.cpp $(InputPath)
       Outputs:      $(InputPath)_n.cpp
    Hint: you can select all .ned files together, and 'All configurations'
    from the combo at the left of the Settings dialog, and then you have to
    type this settings only once.
    Note: If you copied one of the sample projects, you'll have to adjust
    Command, because they contain explicit nedc path (..\..\bin\nedc).

 5. For each .ned file, add a corresponding _n.cpp file.
    Hint: if you 'Compile' the .ned files, the _n.cpp files will be created,
    and you can select them all at once in the 'Add files' dialog.

 6. Required compiler settings: exception handling ON, run-time type info
    (RTTI) ON. Also, set the necessary reserved stack size to 64K (needed
    for the Fiber API).

 7. Choose the appropriate configuration from Build|Set active configuration...
    Note: for Tkenv, the simulation will be linked with sim_std.lib, envir.lib,
    tkenv.lib and the Tcl/Tk libraries (link as Win32 Console app...).
    For Cmdenv, this will be sim_std.lib, envir.lib, and cmdenv.lib.

You may also use the OMNeT++ App Wizard and AddNEDFileToProject macro
(part of the OMNeT++ package) to ease some of these steps.


6. Using auto-generated makefiles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

From 2.3b1, OMNeT++ can automatically generate makefiles for your simulations.
Open a command prompt, cd to the directory of your sources, then type

    opp_nmakemake

A file called Makefile.vc will be created, based on the source files you
currently have in the directory. Then you can build your simulation
simply by typing

    nmake -f Makefile.vc

opp_nmakemake accepts a number of command-line switches, run it with the
-h option to display a list. It allows models to span over multiple
directories, the makefile be extended by makefile fragments written by
you, etc.

The generated makefile includes configuser.vc from the c:\omnetpp-2.3
directory -- it can be edited if you need different settings.


7. Reconfiguring the libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

    nmake -f Makefile.vc clean
    nmake -f Makefile.vc

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

    nmake -f Makefile.vc clean
    nmake -f Makefile.vc

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


8. Using DLLs
~~~~~~~~~~~~~

Currently it's possible to build DLLs from the OMNeT++ libraries and
link a simulation program which uses them. However, because of some
obscure technical problems associated with loading the DLLs, the resulting
simulation program will not run :-(

(Well in case you're interested why: A DLL, while initializing, cannot write
outside its address space. OMNeT++, however, would rely on this mechanism
to build global registration lists ("modules", "networks", etc). Each item
in a registration list is an object whose constructor would add the object
to the global list (an object outside the DLL), and it seems like constructors
of global objects run as part of the DLL initialisation code (DLLMain())).

To build the DLLs anyway, set the desired library suffix to ".dll" in
configuser.vc:
  LIB_SUFFIX=.dll
After re-building OMNeT++, the DLLs should appear in the lib/ directory,
together with the respective import libraries which have the .ilib suffix.
(You may want to rename them manually to .lib.)

There's one trick when using the DLLs: when you compile your model sources,
you must have the WIN32_DLL symbol #defined! It is best to pass them
to the compiler from your makefile (or if you use the IDE, add it to
Settings --> C/C++ --> Preprocessor --> Preprocessor definitions). If you
fail to do so, you'll get undefined linker symbols!


9. Using Plove
~~~~~~~~~~~~~~

If you want to use Plove, you should download and install Gnuplot.
You'll also need a couple of Unix tools like grep and awk, the easiest way
to get them is to download and install the Cygwin package from www.cygnus.com.

When you have everything installed, start Plove and set the appropriate
configuration in Options|External programs. If you entered everything correctly,
Plove should work.

A usual caveat is that Gnuplot expects forward slashes in filenames and Plove
supplies backslashes or vica versa (there are multiple incompatible builds of
Gnuplot on NT); if you suspect this might be the problem, reverse the
slash/backslash setting in Options|External programs.


10. Misc notes
~~~~~~~~~~~~~~
When using MSVC from the command line, you may get the error popup
"MSPDB60.DLL not found in the following path: ...". Funny is that the
displayed path includes MSDev98\Bin, where the MSPDB60.DLL resides indeed!!!
Solution is to copy this dll to the VC98\Bin directory. As a quick web search
showed, I'm not the only one who got this weird error...


Have fun!


Appendix A
~~~~~~~~~~
Check the existence of these environment variables (<variable>=<example value>):

MSVC variables:
 INCLUDE=%INCLUDE%;C:\PROGRA~1\MICROS~1\VC98\INCLUDE
 LIB=%LIB%;C:\PROGRA~1\MICROS~1\VC98\LIB
 Path=%PATH%;C:\PROGRA~1\Tcl\bin;C:\PROGRA~1\MICROS~1\Common\msdev98\BIN;C:\PROGRA~1\MICROS~1\VC98\BIN

Tcl/Tk variables:
 TCL_LIBRARY=C:\PROGRA~1\TCL\LIB\TCL8.3

Note:
- Visual C++: As we use command line compilation, the BIN
  directory of the Visual C++ and the DLL directory of the Visual Studio
  should appear in the PATH environment variable.
  The lib and include directories should appear in the LIB and INCLUDE
  environment variables.

- Tcl/Tk requires the following:
  - the DLL directory of Tcl should appear in the PATH.
  - the TCL_LIBRARY environment variable should be set to the directory
    which contains init.tcl. It is usually the C:/PROGRA~1/TCL/LIB/TCLx.x
    directory.


Appendix B
~~~~~~~~~~

* OMNeT++: The official site of OMNeT++ is
      http://www.hit.bme.hu/phd/vargaa/omnetpp.htm you can download the latest
      version of OMNeT++ from http://www.hit.bme.hu/anonftp/omnetpp/latest/ .
  File format: .tgz (gzipped tar)

* Tcl/Tk: (Ver 8.3) You can find installable executables in
      ftp://ftp.scriptics.com/pub/tcl/ .
      The 8.3 setup is ftp://ftp.scriptics.com/pub/tcl/tcl8_3/tcl83b2.exe .

* Gnuplot: Good Win32 ports are available from ...

* gzip and tar: These are GNU tools. There are several ports of these software
      one is ftp://sourceware.cygnus.com/pub/cygwin/ . Recommended to use UNTGZ
      Decompression Utility 0.95 freeware version ftp://garbo.uwasa.fi/pc/unix/
      (untgz095.zip)
  File Format: Zip
  Usage: untgz32.exe xxx.tgz

* WinZip: (Ver 7.0) Official site http://www.winzip.com/ download evaluation
      version from there or recommended to use http://www.tucows.com/ .

* flex / bison: They are included in the Cygwin package (http://www.cygnus.com)
      another option is http://www.monmouth.com/~wstreett/lex-yacc/lex-yacc.html


Appendix C
~~~~~~~~~~
Patching the makefiles for Win95/98, a posting from the mailing list:

Subject: Re: Questions of installation with OMNet++ on MSVC
From: Andras Varga <avarga@freemail.hu>
Date: Mon, 19 Jun 2000 20:20:57 +0200

> I've encountered some problems while installing OMNet++ on my system
> (VC6.0 + Windows 98).
> After executing nmake, the prompted message are as following:
>
> C:\omnetpp>nmake -f makefile.vc
>
[output from failed build]

Win98 doesn't seem to support '&&' and '||' as command separators,
and its cd command doesn't have the /D option (=change drive too).
I didn't test the MSVC makefiles on Win98 as I have only NT4...
When will all win32 platforms finally be equal???

I just received a nice trick (dirty hack?) from a guy at my
university to get omnetpp compiled on Win98. First, create a cdm.bat
with the following contents in the toplevel omnetpp dir:

-------
@echo off
if "%1" == "/d" shift
set DIR="%1%"
shift
shift
cd %DIR%
echo Executing %1 in %DIR% with arguments %2 %3 %4 %5 %6 %7 %8 %9
%1 %2 %3 %4 %5 %6 %7 %8 %9
-------

Then replace each 'cd' in the toplevel Makefile.vc with 'cdm'.
You may also need (I'm not sure) to remove the 'check-env' dependency
from the 'all' target in Makefile.vc line 30 if it causes problems.

With this modification you should be able to build everything but the
samples. I haven't verified though if it really works, and I won't
be able to support it... Hope it helps though.

Oops, and it doesn't hurt to enlarge the environment space for
the command prompt where you compile.

If you try this and you can refine it, you're most welcome to post an
update here...

