Building the core and models in OMNeT++/OMNEST

===========================================

Building the core

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

1. Dealing with platform differences

On Unix-like systems (Linux,OSX,Windows/MinGW,Windows/Cygwin): autoconf.

User can give hints to the ./configure script by editing configure.user.
Makefiles do NOT get configured (ie. there are no Makefile.in files);
instead, they all include a common Makefile.inc file (which IS created
by ./configure, from Makefile.inc.in). This Makefile.inc gets included
by simulation model makefiles as well (more later). Makefiles are
hand-written, and require GNU Make.

Windows and Visual C++: settings are in configuser.vc, to be edited

by the user. No configuration step (like autoconf on Linux) is used.
Makefiles are called Makefile.vc, and they all include configuser.vc.
Compiler path and variables (INCLUDE,LIB) are not in configuser.vc,
they must be set externally (e.g. via the vcvars32.bat file) as
environment variables before invoking the nmake. nmake.exe is used.
Simulation model makefiles also include the configuser.vc file.

Both Makefile.inc and configuser.vc contain a variable named TOOLCHAIN_NAME,

whose value identifies the compiler on that platform. Currently used
values are: "gcc", "icpc" (Intel), "vc71", "vc80", "vc90", "mingw".
This will be used to generate names for directories that hold libs
compiled with various compilers.

2. Debug/Release builds

Both Makefile.inc and configuser.vc define CFLAGS_DEBUG and CFLAGS_RELEASE,

and a MODE variable controls which one becomes CFLAGS. LDFLAGS gets set up
similarly. The value of MODE can be "debug" or "release". MODE can be
set as environment variable, or specified on the MAKE command line
as "make MODE=debug" or "nmake -f Makefile.vc MODE=debug". The default
setting is "release".

3. Out-of-directory builds

It is possible to build so that object files get placed under a separate

directory tree. This directory is "obj/<configname>", and it has src/sim,
src/envir etc subdirectories. Libraries built are similarly placed
under "lib/<configname>" (but no further subdirs here). <configname>
currently comes from the CONFIGNAME make variable. We should probably
produce CONFIGNAME as "$(TOOLCHAIN_NAME)-$(MODE)", which will yield subdir
names like "vc80-debug", "vc80-release", "mingw-debug", etc.

Building simulation models

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

1. Generated makefiles

Simulation models are built using makefiles generated by opp_makemake.

The same opp_makemake program can generate both Makefile (GNU Make syntax)
and Makefile.vc (nmake syntax). The --nmake option selects between the two.

2. Finding OMNeT++ and required settings

The opp_makemake program or the generated makefiles don't contain a reference

to the concrete OMNeT++ installation or its configuration. Generated
makefiles include the config file (Makefile.inc or configuser.vc).

How do makefiles know the location of the config file? GNU Make makes it
possible to run a program during makefile preprocesssing, and assign its
output to a makefile variable (VAR=$(shell prog ...)). The generated
makefile uses the $(shell) syntax to invoke "opp_configfilepath" (part of
OMNeT++) which prints the location of the config file. Thus it is enough
if OMNeT++ is in the PATH, and no other setting, makefile editing or
makefile re-generation is needed.

nmake has no such facility, so config file is found using an environment

variable (or makefile variable). OMNETPP_CONFIGNAME or OMNETPP_PATH
can be used for this purpose. In addition, the makefile generator writes
the config file location into the generated makefile, so the environment
variable is not needed while the model is build on the same computer.

3. Debug/release build

The correct set of CFLAGS/LDFLAGS are selected by MODE=debug/release (needs

to be passed to make from outside, or set in an environment variable). Linker
path is $(OMNETPP_ROOT)/lib/$(TOOLCHAIN_NAME)-$(MODE). The default MODE is
"release".

Other MODEs can be defined by the user (if s/he takes the effort). Makefiles
or opp_makemake do not enforce these names.

4. Out-of-directory build

For out-of-directory builds, currently the output directory $O is to be

specified at makefile creation (opp_makemake command-line option).
If the user has a multi-directory model (like INET), each subdirectory
needs a (different) opp_makemake option (--outdir ../../../out/Transport/TCP,
and so on).

The project root directory can be determined by opp_makemake

as the nearest ancestor directory that contains a ".project" file, or
alternatively, passed to opp_makemake with a command-line option.

Paths within the project are converted to relative.

Create softlinks (or batch file) into the current dir to the out/<executable>.

5. Automatic updating of makefiles

E.g. list of object files gets updated automatically?

6. Shared libs
Models get compiled into a shared lib. E.g. "aloha.so"; and we'd generate
an "aloha" script with "opp_run aloha.so" as content; it would also set the
LD_LIBRARY_PATH to the appropriate lib/<configname>.

7. Single makefile for multi-directory models

It could be possible to build INET with a single makefile; OBJS would contain
object files from all directories.