<h1>Porting <acronym>deal.II</acronym> to new systems</h1>
<p>
- <acronym>deal.II</acronym> uses very few system dependent
- features. Consequently, there is a good chance that it might also run on other
- systems besides the ones listed in the
- <a href="readme.html" targte="body">ReadMe file</a>. Nevertheless,
- there are cases where some adjustments are necessary.
- </p>
-
-
- <p>
- Basically, all the setup of the specifics or a system is done in the
- <code>./configure</code> script that is run first. This script finds out about
- operating system, processor, and the like, and then goes on testing
- whether certain features are present, or if their absence can be
- worked around.
- <code>./configure</code> is not made for human eyes. It is in fact only a
- script generated by the <code>autoconf</code> program from the files
- <code>configure.in</code> and <code>aclocal.m4</code> in the top-level directory of
- <acronym>deal.II</acronym>. The first contains the order in which
- macros are called that test for features, interspersed by shell
- script snippets that do actions depending on the results of the
- macros. The second file contains the user-defined macros used in
- <code>configure.in</code> (most macros are already predefined by autoconf).
- To understand how all this works together, you will have to have some, though
- not a whole lot of,
- knowledge of both Unix shell scripting as well as of <code>autoconf</code>
- </p>
+ <acronym>deal.II</acronym> uses very few
+ <a href="http://www.opengroup.org/austin/">POSIX</a> specific system
+ features and is otherwise fairly ISO (1998) C++ Standard compliant.
- <p>
- At the end of running <code>./configure</code>, it creates output files by
- replacing all occurrences of variables like <code>@var@</code> in input files
- by the value of the respective environment variable in
- the <code>configure</code> shell script. By convention, input files have a
- file ending <code>.in</code>; the two most important input/output file pairs
- are <code>common/Make.global_options</code>
- and <code>common/Make.global_options.in</code> as well as
- <code>include/deal.II/base/config.h.in</code>
- and <code>include/deal.II/base/config.h</code>.
+ Consequently, there is a good chance that <acronym>deal.II</acronym>
+ will run on a reasonably well behaved system besides the ones listed
+ in the <a href="readme.html" target="body">ReadMe</a>. Nevertheless,
+ there are cases where some adjustments are necessary.
</p>
-
-
- <h2>Quick porting</h2>
+ <h2>Unknown compiler</h2>
<p>
- If you find something that does not work on your system, then the
- quickest way to make <acronym>deal.II</acronym> run on your system
- is to run <code>configure</code> and change things in
- <code>common/Make.global_options</code> by hand so that it works for
- you. The downside is that
- this file is overwritten next time you run <code>./configure</code>.
- </p>
-
- <p>
- Most often, problems on new systems are caused by the compiler not
- accepting certain flags, crashing or producing invalid code on
- optimization flags, not supporting shared libraries, and the like.
- All these problems can be solved by changing
- <code>common/Make.global_options</code>, e.g. by setting the variable
- <code>enable-shared</code> to <code>no</code>, or by changing the compiler flags in
- the variables <code>CXXFLAGS.g</code> (for debug mode) or <code>CXXFLAGS.o</code> (for
- optimized mode). The most important variables in
- <code>common/Make.global_options</code> are
- <a href="development/makefiles.html">listed here</a>.
+ Currently, the <acronym>deal.II</acronym> CMake Buildsystem
+ recognizes
+ <a href="http://gcc.gnu.org/">gcc</a>,
+ <a href="http://clang.llvm.org/">clang</a>, as well as
+ <a href="http://software.intel.com/en-us/intel-compilers">icc</a>, and
+ sets up reasonable default compiler flags.
+ <ul>
+ <li>
+ To start porting for an unkown compiler, specify
+ <code>-DDEAL_II_SETUP_DEFAULT_COMPILER_FLAGS=OFF</code> and set all
+ necessary compiler flags by hand via
+ <pre>
+
+ CMAKE_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
+ </pre>
+ After that try to compile the library with minimal external
+ dependencies (<code>-DDEAL_II_ALLOW_AUTODETECTION=OFF</code>, for
+ further information see the <a href="cmake.html">deal.II CMake
+ documentation</a>).
+ <li>
+ For adding permanent support for the unknown compiler to the
+ build system, have a look at
+ <pre>
+
+ cmake/setup_compiler_flags.cmake
+ cmake/setup_compiler_flags_gnu.cmake
+ cmake/setup_compiler_flags_icc.cmake
+ </pre>
+ Patches are highly welcome! See <a href="../mail.html">here</a>
+ for information on how to get in contact with us.
+ <li>
+ You might want to have a look at
+ <pre>
+
+ cmake/checks/check_for_compiler_bugs.cmake
+ cmake/checks/check_for_compiler_features.cmake
+ cmake/checks/check_for_cxx_features.cmake
+ include/deal.II/base/config.h.in
+ </pre>
+ to see how compiler specific checks are done.
+ </ul>
</p>
-
-
- <h2>Portable porting</h2>
+ <h2>Porting to a new platform</h2>
<p>
- While the measures shown above make <acronym>deal.II</acronym> run
- on your system, it does not help other users. Neither does it mean
- that the next version will run on your system unless you do the same
- changes over again. There are basically two ways to help us make
- <acronym>deal.II</acronym> run on your system by default:
+ <acronym>deal.II</acronym> should support almost all reasonably
+ <a href="http://www.opengroup.org/austin/">POSIX</a> compliant
+ platforms out of the box. Nevertheless, the following bits of
+ information might help:
<ul>
+ <li>
+ The buildsystem of <acronym>deal.II</acronym> uses <a
+ href="http://www.cmake.org/" target="_top">CMake</a>. So,
+ in order to port <acronym>deal.II</acronym> to a new platform,
+ it is obviously necessary that <a href="http://www.cmake.org/"
+ target="_top">CMake</a> supports the platform in question
+ with at least one generator for a native build tool, see <a
+ href="http://www.cmake.org/cmake/help/documentation.html">here</a>.
+ <li>
+ <acronym>deal.II</acronym> is mainly developed with <a
+ href="http://gcc.gnu.org/">gcc</a> on GNU/Linux, so it is
+ best to begin porting to a new platform with the help of <a
+ href="http://gcc.gnu.org/">gcc</a>.
+ After that a platform specific compiler might be tried.
+ <li>
+ Almost all <a href="http://www.opengroup.org/austin/">POSIX</a>
+ specific code is well guarded with fall-back code in case the
+ specific POSIX function is not available. There is (currently)
+ one exception, though: Certain routines in
+ <code>source/base/timer.cc</code> have implementations for POSIX
+ and Windows and throw a compile time error on other platforms.
+ <li>
+ Have a look at
+ <pre>
+
+ cmake/checks/check_for_compiler_bugs.cmake
+ cmake/checks/check_for_compiler_features.cmake
+ cmake/checks/check_for_cxx_features.cmake
+ cmake/checks/check_for_system_features.cmake
+ include/deal.II/base/config.h.in
+ </pre>
+ to see how platform and compiler specific checks are done.
<li>
- <p>
- You can send us the changes you had to make so that we can include
- it into the distribution.
- </p>
-
- <li>
- <p>
- If you know the basics of <code>autoconf</code>, or of shell scripting, you
- will be able to write tests for the changes that are necessary in
- <code>configure.in</code> or <code>aclocal.m4</code> yourself. There are plenty of examples, both for
- things that we do depending on the system (for example disabling
- shared libraries on certain systems) or depending on the compiler
- (for example using some optimization flags for newer gcc
- versions), and depending on the results of feature tests. For the
- latter, you may for example take a look at the macro
- <code>DEAL_II_CHECK_ASSERT_THROW</code> in <code>aclocal.m4</code> that shows how to
- test whether the <code>AssertThrow</code> construct in
- <acronym>deal.II</acronym> works as intended (this check is
- necessary since some very old compiler versions get an internal compiler
- error on DEC Alpha machines for this construct).
- </p>
-
- <p>
- If you have made such changes to <code>configure.in</code> or
- <code>aclocal.m4</code>, run <code>autoconf</code> in the top-level directory to
- regenerate the <code>configure</code> script, which you should then run and
- see whether the output in <code>common/Make.global_options</code> matches
- your expectations.
- </p>
-
- <p>
- 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.
- </p>
+ 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!
</ul>
</p>
+ <h2>Cross compiling</h2>
+ <p>
+ It is possible to use <a href="http://www.cmake.org/"
+ target="_top">CMake</a> to cross compile
+ <acronym>deal.II</acronym> for a foreign platform. Further
+ information on that topic can be found int the <a
+ href="http://www.cmake.org/Wiki/CMake_Cross_Compiling">CMake
+ wiki</a>.
<hr>