# Essential Information on Using ODEMx

# Requirements

## All Platforms

- CMake (version >= 2.8)
- POCO (revision 1094)
  - NOTE: The latest POCO release (currently 1.4.x) cannot be used because CppLog uses unreleased POCO classes. Thats why revision 1094 (which already includes these classes) from the POCO SVN repository must be used.
- GSL
  - Version 1.13 is currently used
  - TODO: It is unknown if later versions are useable as well.

## Linux, Unix, Mac OS X, Gygwin, MinGW

- make
- g++
  - tested with g++ 4.4 and 4.5
  - might also work with earlier versions if they support tr1 and RTTI
- subversion
  - needed when building poco with the external/contrib/install_contrib.sh script
  - NOTE: You need a svn client with a command line interface. On Windows, try SlikSVN
- wget or curl
  - to download gsl with external/contrib/install_contrib.sh script
- autotools
  - TODO: it is unknown if autotools is still required

# Known Developers by Build Environment

You can try to contact one of the developers below if you encounter problems when building or using ODEMx.

Build Environment | Known Developers
--- | ---
Linux | Magnus Mueller, Toralf Niebuhr
Mac OS X | Andreas Blunk, Ingmar Eveslage
MinGW/MSYS | Andreas Blunk, Ingmar Eveslage
Cygwin | -
Visual Studio | -

# Build Guide

Preliminary Notes

- in this guide `ODEMX_HOME` stands for the location of your ODEMx home directory (the absolute path)

Additional Notes

- If you develop with Eclipse, place your ODEMx build and install directories in the parent directory of `ODEMX_HOME` (e.g. `ODEMX_HOME/../build`).

## Building External Libraries

### Linux, Unix, Mac OS X, MinGW, Cygwin

1. Download (optional)
   - NOTE: you only need to download if the directory `ODEMX_HOME/external/contrib` does not already contain the following sub-directories:
     - `gsl-1.13`
     - `poco`
     - `UnitTest++`
   - automatic downloading requires (wget or curl) and a SVN command line client
   - cd to `ODEMX_HOME/external/contrib`
   - run `download_contrib.sh`
2. Build
   - create an install directory (location where all the binaries, libs, header files and docs will be placed) (e.g. `ODEMX_HOME/install`)
   - cd to `external/contrib`
   - run `install_contrib.sh` with the install directory (e.g. `./install_contrib.sh ../../install`)
     - look into `install_contrib.sh` for details - e.g. if you want to build shared libraries or with ODBC support)

## Building ODEMx

### Getting MinGW and CMake (if not already installed)

1. Install MinGW …
   - Download MinGW from http://sourceforge.net/projects/mingw/
   - Run the installer and select …
     - MinGW C++ Compiler,
     - MinGW Developer Toolkit
     - MSYS Basic System
   - Add `<MinGW_HOME>/bin` to your `PATH` environment variable
2. Install CMake …
   - Download CMake from http://www.cmake.org
   - Run the installer and let CMake add itself to the `PATH` environment variable (in installer dialog)

### Known Problems per Build Environment

- Mac OS X 10.8 with GCC 4.2
  - Compiler optimizations are not working. Do not use -O compiler flags for release builds!

### Building on Linux, Unix, Mac OS X, MinGW, Cygwin

- create a build directory in a parent of your ODEMx directory, e.g. `ODEMX_HOME/../build-eclipse-mingw`
- change directory to the created build directory
- make sure you have CMake
- generate Makefiles with cmake
  - set variable `INSTALL_PREFIX` to your install directory
  - NOTE: for debug builds, add `-D CMAKE_BUILD_TYPE=Debug` to your cmake invocation
  - sample invocations for different generators:
    - Unix
      - `cmake -G "Unix Makefiles" -D CMAKE_BUILD_TYPE=Debug -D INSTALL_PREFIX=../install ../odemx`
    - MSYS
      - `cmake -G "MSYS Makefiles" -D CMAKE_BUILD_TYPE=Debug -D INSTALL_PREFIX=../install ../odemx`
    - Eclipse CDT4 - MinGW
      - IMPORTANT: With this generator, cmake must be invoked from a new Windows shell (do not open the Windows shell from MSYS)!
      - SEE ALSO: Using Eclipse CDT4 Generator
      - `cmake -G "Eclipse CDT4 - MinGW Makefiles" -D CMAKE_BUILD_TYPE=Debug -D INSTALL_PREFIX=../install ../odemx`
- run make
- run make install

### Customizing Library Paths (optional)

If you want to use custom paths, edit the following variables (NOTE: you can also pass them as command line arguments):

- GSL – path of libgsl.a
- GSL_INSTALL_PREFIX – path of the gsl install directory (used to find includes)
  - NOTE: Your path should look similar to install_dir/ where install_dir contains directories like lib/, bin/, etc.
- POCO_DATA – path of libPocoData.a
- POCO_FOUNDATION – path of libPocoFoundation.a
- POCO_INSTALL_PREFIX – path of PoCo install directory (used to find includes)
  - NOTE: Your path should look similar to install_dir/ where install_dir contains directories like lib/, bin/, etc.
- POCO_SQLITE – path of PocoSqLite.a
- POCO_XML – path of PocoXML.a
  - NOTE: The cmake files contain hints which try to guess where you placed your libraries. If your libs are placed in POCO_INSTALL_DIR/lib and/or GSL_INSTALL_DIR/lib, then you don’t have to set the other variables.

You can pass command line arguments to CMake with `-D` like this: `-D GSL_INSTALL_PREFIX=/your_install_dir`

## Building the ODEMx Documentation (optional)

- cd to a build directory (e.g. `ODEMX_HOME/build`)
- set variables for building the documentation: `cmake -D BUILD_ONLY_DOCUMENTATION=ON -D GENERATE_DOXYGEN=ON ../`
- run `make doc` (this will place HTML files to `ODEMX_HOME/Doxygen`

## Building and Running Tests for ODEMx (optional)

- edit `ODEMX_HOME/CMakeLists.txt`
- `make` (usual make first)
- `make odemxT`
- `make test`

# Using ODEMx

## Getting Started - Your First ODEMx Project

You can create your first ODEMx project by using files from a sample project in `ODEMX_HOME/SampleProject`. The sample project includes a simple ODEMx program (`main.cpp`) and a `CMakeLists.txt`.

- create a directory for your project
- copy the contents of `ODEMX_HOME/SampleProject` to your own project
- edit `source/CMakeLists.txt`
  - set variable `ODEMX_INSTALL` to the install directory of your ODEMx build
  - for builds under MinGW/MSYS: set variable `MINGW_DIR` to the absolute path of your MinGW home directory, e.g. `C:/MinGW`
- create a build directory in a parent of the source directory, e.g. `ODEMX_HOME/SampleProject/build-eclipse-mingw`
- change directory to the created build directory
- generate Makefiles with cmake
  - NOTE: for debug builds, add `-D CMAKE_BUILD_TYPE=Debug` to your cmake invocation
  - sample invocations for different generators:
    - Unix Makefiles
      - `cmake -G "Unix Makefiles" -D CMAKE_BUILD_TYPE=Debug ../source`
    - MSYS Makefiles
      - `cmake -G "MSYS Makefiles" -D CMAKE_BUILD_TYPE=Debug ../source`
    - Eclipse CDT4 - MinGW Makefiles
      - IMPORTANT: With this generator, cmake must be invoked from a new Windows shell (do not open the Windows shell from MSYS)!
      - `cmake -G "Eclipse CDT4 - MinGW Makefiles" -D CMAKE_BUILD_TYPE=Debug ../source`
- run make

### Troubleshooting

#### Memory Exhaustion

If you experience memory exhaustion errors, you have to set the size of the process stacks explicitly.

1. Open CMakeLists.txt
2. Adapt the line at the end of the file and specify the size of the stack used by the linker. 32Kb should be sufficient in most cases.

    if(USING_MINGW)
        set_target_properties(main PROPERTIES LINK_FLAGS "-Wl,--enable-auto-import -Wl,--enable-stdcall-fixup -Wl,--stack=32768")
    endif()

### Using your Project in Eclipse

- run Eclipse
- import your project as an existing project from your projects build directory
- DO NOT select to copy the project!

# Using the ODEMx Debugger

## Compatibility Notes

- tested with Eclipse Helios and Indigo
- for MinGW, a special mingw-gdb version 7.1 is required
- not useable under Mac OS X

## Installation Notes

- install Eclipse with CDT
- install the ODEMx Debugger Plugin from this Update Site

## Preparation of ODEMx-based Projects

- make sure that you build your ODEMx library with debug symbols on (see Building ODEMx)

## Debugging a Binary with the ODEMx Debugger

- open the debug configuration of the binary execution
- at the bottom of the main tab: click Select other… and choose Standard Create Process Launcher
- in the debugger tab:
  - select an appropriate version of the ODEMx Debugger (e.g. OdemxDebugger (MinGW))
  - select your execution platform

## GUI Usage

See TODO: insert link.

## Additional Information

See TODO: insert link to diplomarbeit.