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 (=): 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 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...