Porting deal.II
Keywords: deal.II porting

# Porting deal.II to new systems

deal.II uses very few POSIX specific system features and is otherwise fairly ISO (2011) C++ Standard compliant. Consequently, there is a good chance that deal.II will run on a reasonably well behaved system besides the ones listed in the ReadMe. Nevertheless, there are cases where some adjustments are necessary.

## Unknown compiler

Currently, the deal.II CMake build system recognizes gcc, clang, as well as icc, and sets up reasonable default compiler flags.

- To start porting to an unknown compiler, specify `-DDEAL_II_SETUP_DEFAULT_COMPILER_FLAGS=OFF` and set all necessary compiler flags by hand via

      DEAL_II_CXX_FLAGS         - used during all builds
      DEAL_II_CXX_FLAGS_DEBUG   - additional flags for the debug library
      DEAL_II_CXX_FLAGS_RELEASE - additional flags for the release library

  After that try to compile the library with minimal external dependencies (`-DDEAL_II_ALLOW_AUTODETECTION=OFF`, for further information see the deal.II CMake documentation).
- For adding permanent support for the unknown compiler to the build system, have a look at

      cmake/setup_compiler_flags.cmake
      cmake/setup_compiler_flags_gnu.cmake
      cmake/setup_compiler_flags_icc.cmake

  Patches are highly welcome! See here for information on how to get in contact with us.
- You might want to have a look at

      cmake/checks/check_01_for_compiler_features.cmake
      cmake/checks/check_01_for_cxx_features.cmake
      cmake/checks/check_03_for_compiler_bugs.cmake
      include/deal.II/base/config.h.in

  to see how compiler specific checks are done.

## Porting to a new platform

deal.II should support almost all reasonably POSIX compliant platforms out of the box. Nevertheless, the following bits of information might help:

- The build system of deal.II uses CMake. So, in order to port deal.II to a new platform, it is obviously necessary that CMake supports the platform in question with at least one generator for a native build tool, see here.
- deal.II is mainly developed with gcc on GNU/Linux, so it is best to begin porting to a new platform with the help of gcc. After that a platform specific compiler might be tried.
- Almost all POSIX specific code is well guarded with fall-back code in case the specific POSIX function is not available. There is (currently) one exception, though: Routines that measure elapsed CPU time in `source/base/timer.cc` have implementations for POSIX and Windows and will not work correctly on other platforms.
- Have a look at

      cmake/checks/check_01_cxx_features.cmake
      cmake/checks/check_02_compiler_features.cmake
      cmake/checks/check_02_system_features.cmake
      cmake/checks/check_03_compiler_bugs.cmake
      include/deal.II/base/config.h.in

  to see how platform and compiler specific checks are done.
- Of course, we would be happy to hear about the changes you made for your system, so that we can include them into the next version of the library!

## Cross compiling

It is possible to use CMake to cross compile deal.II for a foreign platform. Further information on that topic can be found at the CMake wiki.

You have to set up a native deal.II build directory first and run `make expand_instantiations_exe` in it. The executable is needed for the build system (and obviously the cross compiled version cannot be used). Locate the `expand_instantiations` executable (it usually resides under `${CMAKE_BINARY_DIR}/bin` and export its location with the `PATH` environment variable.

Assuming you have a working cross compilation toolchain, the next step is to set up a toolchain file (or for for Windows64 using MinGW). After that invoke `cmake` with something like:

    $ cmake -DCMAKE_TOOLCHAIN_FILE=<...>/Toolchain.sample \
            -DDEAL_II_FORCE_BUNDLED_BOOST=ON \
            -DDEAL_II_ALLOW_AUTODETECTION=OFF \
            ../deal.II

where `CMAKE_TOOLCHAIN_FILE` points to the toolchain file. The remaining configuration can be adjusted at will, see the documentation.