]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Rewrite porting.html
authormaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Wed, 7 Nov 2012 17:32:45 +0000 (17:32 +0000)
committermaier <maier@0785d39b-7218-0410-832d-ea1e28bc413d>
Wed, 7 Nov 2012 17:32:45 +0000 (17:32 +0000)
git-svn-id: https://svn.dealii.org/branches/branch_cmake@27463 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/TODO.CMAKE
deal.II/doc/development/porting.html
deal.II/doc/development/toc.html

index f702c1452e860d5f930acba6cc47ee6e1134c7a4..0000750470ddc022a6cf647bd3bd54f45cde8583 100644 (file)
@@ -10,9 +10,6 @@ Major:
     (doc/development/toc.html already links to it)
     (A more detailed copy of what is already standing in cmake.html)
 
-  - Modify doc/porting.html
-
-
 Minor:
 
 * The following feature has to be written: TECPLOT
index 00b369be229fd2eed3da0dddec42ff4a5ffde010..23333a839fcd3411f3d3a0fd123a4b6e39eb11e5 100644 (file)
     <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>
 
index c889e1392489a99417bd57adbd4cbb63d57a32fe..242aeebfa13c7ed7b95ac030beca380b4b4176f1 100644 (file)
 
     <li> <p><a href="porting.html" target="body">Porting
          <acronym>deal.II</acronym> to a new system</a>:
-         <acronym>deal.II</acronym> uses the mechanism provided by
-         GNU&nbsp;autoconf. Therefore, porting to a reasonably
-         standardized UNIX system should not be too difficult. Other
-         systems, such as proprietary ones, might or might not work (it is
-        possible, for example, to use Microsoft Windows);
-         see the <a href="../readme.html" target="body">ReadMe</a>
-         file for more information on supported systems and porting.
+
+         <acronym>deal.II</acronym> uses CMake as build system
+         and is fairly ISO (1998) C++ Standard compliant.
+         So, porting to a reasonably <a
+         href="http://www.opengroup.org/austin/">POSIX</a> compliant
+         system with a reasonably ISO C++ compliant compiler shouldn't be
+         much work. Other (mostly proprietary) systems might require more
+         work. See the <a href="../readme.html" target="body">ReadMe</a>
+         file for more information on already supported systems. This
+         resource gives some hints for porting to unknown platforms.
         </p>
 
     <li> <p><a href="https://sourceforge.net/apps/trac/dealii" target="_top">Bugs</a>:

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.