<li><a href="#operatingshortcuts">Shortcuts</a></li>
</ol>
</li>
+ <li><a href="#build">Configuring and Building deal.II</a>
+ <ol>
+ <li><a href="#buildtargets">Primary build targets</a></li>
+ <li><a href="#buildinformation">Information about current configuration</a></li>
+ <li><a href="#buildinsource">Out-of-source versus in-source builds</a></li>
+ <li><a href="#buildgenerator">CMake Generators</a></li>
+ <li><a href="#buildinstall">Installation</a></li>
+ </ol>
+ </li>
<li><a href="#configure">Configuration options</a>
<ol>
<li><a href="#configurefeature">Feature configuration</a></li>
<li><a href="#compiling">Compiling only certain parts</a></li>
</ol>
</div>
-
+
<a name="operating"></a>
<h2>Operating cmake</h2>
will be expanded to the full <code>DEAL_II_COMPONENT_*</code> variable name).
</p>
+
+
+ <a name="build"></a>
+ <h2>Configuring and Building deal.II</h2>
+
+ <p>
+ This section provides some further details and advanced topics with
+ respect to configuration and building that is not covered in the <a
+ href="../readme.html" target="body">README</a>.
+ </p>
+
+ <a name="buildtargets"></a>
+ <h3>Primary build targets</h3>
+
+ <p> The current list of primary build targets can be queried via
+ <code>make info</code>:
+ <pre>
+
+ ###
+ #
+ # The following targets are available (invoke via $ make <target>):
+ #
+ # all - compiles the library and all enabled components
+ # clean - removes all generated files
+ # install - installs into CMAKE_INSTALL_PREFIX
+ # help - prints a list of valid top level targets
+ # info - prints this help message
+ #
+ # edit_cache - runs ccmake for changing (cached) configuration variables
+ # and reruns the configure and generate phases of CMake
+ # rebuild_cache - reruns the configure and generate phases of CMake
+ #
+ # compat_files - builds and installs the 'compat_files' component
+ # documentation - builds and installs the 'documentation' component
+ # examples - builds and installs the 'examples' component
+ # library - builds and installs the 'library' component
+ # mesh_converter - builds and installs the 'mesh_converter' component
+ # parameter_gui - builds and installs the 'parameter_gui' component
+ #
+ # test - runs a minimal set of tests
+ #
+ # setup_test - sets up the testsuite subprojects
+ # clean_test - runs the 'clean' target in every testsuite subproject
+ # prune_test - removes all testsuite subprojects
+ #
+ ###
+ </pre>
+
+
+ <a name="buildinformation"></a>
+ <h3>Information about current configuration</h3>
+
+ <p>
+ A configuration run of <code>cmake</code> (or <code>ccmake</code>)
+ writes a short summary of the current configuration into
+ <code>CMAKE_BUILD_DIR/summary.log</code>:
+ <pre>
+
+ ###
+ #
+ # deal.II configuration:
+ # CMAKE_BUILD_TYPE: DebugRelease
+ # BUILD_SHARED_LIBS: ON
+ # CMAKE_INSTALL_PREFIX: /tmp/deal.II/install
+ # CMAKE_SOURCE_DIR: /tmp/deal.II/deal.II (Version 8.1.pre)
+ # CMAKE_BINARY_DIR: /tmp/deal.II/build
+ # CMAKE_CXX_COMPILER: GNU 4.7.3 on platform Linux x86_64
+ # /usr/bin/c++
+ #
+ # Configured Features (DEAL_II_ALLOW_BUNDLED = ON, DEAL_II_ALLOW_AUTODETECTION = ON):
+ # ( DEAL_II_WITH_64BIT_INDICES = OFF )
+ # DEAL_II_WITH_ARPACK set up with external dependencies
+ # DEAL_II_WITH_BOOST set up with external dependencies
+ # [...]
+ #
+ # Component configuration:
+ # DEAL_II_COMPONENT_COMPAT_FILES
+ # ( DEAL_II_COMPONENT_DOCUMENTATION = OFF )
+ # DEAL_II_COMPONENT_EXAMPLES
+ # DEAL_II_COMPONENT_MESH_CONVERTER
+ # ( DEAL_II_COMPONENT_PARAMETER_GUI = OFF )
+ #
+ # Detailed information (compiler flags, feature configuration) can be found in detailed.log
+ #
+ # Run $ make info to print a help message with a list of top level targets
+ #
+ ###
+ </pre>
+ This summary is also printed at the end of the configuration phase.
+ It tells you about build and install directory locations, feature
+ configuration (whether a feature is enabled with external/internal
+ dependencies, disabled or forced) and component configuration.
+ A more detailed version can be found in
+ <code>CMAKE_BUILD_DIR/detailed.log</code> that also includes detailed
+ information about feature configuration, e.g.
+ <pre>
+
+ # DEAL_II_WITH_BOOST set up with external dependencies
+ # BOOST_VERSION = 1.52.0
+ # BOOST_DIR =
+ # Boost_INCLUDE_DIRS = /usr/include
+ # Boost_LIBRARIES = /usr/lib64/libboost_serialization-mt.so;/usr/lib64/libboost_system-mt.so;
+ # [...]
+ </pre>
+ If this information is not sufficient, you might want to have a look
+ at the following files in <code>CMAKE_BUILD_DIR</code>
+ <ul>
+ <li><code>CMakeCache.txt</code>: The file CMake stores its cached
+ variables in. Do not change directly.
+ <li><code>include/deal.II/base/config.h</code>: The generated
+ config.h file
+ <li><code>lib/cmake/deal.II/deal.IIConfig.cmake</code>: The project
+ configuration file for external projects.
+ </ul>
+ </p>
+
+
+
+ <a name="buildinsource"></a>
+ <h3>Out-of-source versus in-source builds</h3>
+
+ <p>
+ A so called out-of-source build is a setup where the build directory
+ (the directory containing intermediate and generated files) is
+ different from the source directory (the directory containing the
+ source code). With CMake an out-of-source build is set up by invoking
+ <code>cmake</code> (or <code>ccmake</code>) from the designated build
+ directory, so for example (a build directory under the source
+ directory):
+ <pre>
+
+ $ mkdir build
+ $ cd build
+ $ cmake ..
+ </pre>
+ The big advantage is that source files and intermediate files are
+ strictly separated (highly desired for version control) and that you
+ can have multiple build directories (with different configuration) at
+ the same time.
+ </p>
+
+ <p>
+ <b>Note:</b> However, under rare occasions an in-source build might be
+ useful or needed , so it is supported
+ <pre>
+
+ $ cmake .
+ </pre>
+ But we highly discourage it!
+ </p>
+
+ <a name="buildgenerator"></a>
+ <h3>CMake Generators</h3>
+
+ <p>
+ Cmake is a <i>Makefile Generator</i>. This allows to switch the
+ generator that is used to something different. If you for example want
+ to automatically generate an Eclipse project of deal.II, you can run
+ <pre>
+
+ $ cmake -G"Eclipse CDT4 - Unix Makefiles" [...]
+ </pre>
+ and load up the build directory as a project directly into Eclipse.
+ Have a look at the <a href="https://code.google.com/p/dealii/w/list"
+ target="_top">Wiki</a> for more information.
+ </p>
+
+ <p>
+ An interesting alternative to (GNU) Make might also be <a
+ href="http://martine.github.io/ninja/">Ninja</a>. Configure via
+ <pre>
+
+ $ cmake -GNinja [...]
+ </pre>
+ and run <code>ninja</code> instead of <code>make</code>.
+ </p>
+
+
+ <a name="buildinstall"></a>
+ <h3>Installation</h3>
+
+ <p>
+ It is not necessary to install the library in order to use deal.II.
+ Invoking the <code>all</code> or <code>library</code> target will
+ compile the library and set up all necessary configuration in the
+ build directory so that external projects can directly use it.
+ However, we strongly recommend to proceed in the way explained in the
+ <a href="../readme.html" target="body">README</a> and install the
+ library to a designated install directory (different from source and
+ build directory).
+ </p>
+
+ <p>
+ For installing the library it is necessary to set the CMake variable
+ <code>CMAKE_INSTALL_PREFIX</code> to the designated install
+ directory. You can do this by invoking <code>cmake</code> together
+ with <code>-DCMAKE_INSTALL_PREFIX=<...></code> or by invoking
+ <code>ccmake</code>.
+ </p>
+
+ <p>
+ <b>Note:</b> When you don't install deal.II to an install directory
+ and use it directly from a build directory,
+ both, the build <i>and</i> source directories have to be kept.
+ </p>
+
+ <p>
+ <b>Note:</b> It is not necessary for the source, build and or install
+ directory to be different. All combinations are supported.
+ </p>
+
+
+ <h4>Install a single component</h4>
+
+ <p>
+ If you want to only generate, compile and install a specific
+ component (most notably the documentation) you can use one of the
+ following top level targets:
+ <pre>
+
+ compat_files - builds and installs the 'compat_files' component
+ documentation - builds and installs the 'documentation' component
+ examples - builds and installs the 'examples' component
+ library - builds and installs the 'library' component
+ mesh_converter - builds and installs the 'mesh_converter' component
+ parameter_gui - builds and installs the 'parameter_gui' component
+ </pre>
+
+
<a name="configure"></a>
<h2>Configuration options</h2>
</p>
+
<a name="configurefeature"></a>
<h3>Feature configuration</h3>
<h3> Installation </h3>
<p>
- the location,
- where the <acronym>deal.II</acronym> library will be
- installed to is set with the help of
+ the location, where the <acronym>deal.II</acronym> library will be
+ installed when invoking <code>make install</code> to is set with the
+ help of
<pre>
CMAKE_INSTALL_PREFIX
Please note that depending on whether
<code>DEAL_II_COMPONENT_COMPAT_FILES</code> is set, there will be
- different directory structures:
+ a different default directory structure:
<ul>
<li>
With <code>DEAL_II_COMPONENT_COMPAT_FILES=ON</code>:
</p>
<p>
- The individual target directories can be overwritten by setting the
+ The default directory structure can be changed by by setting the
following variables:
<pre>
library. Rather, <code>make install</code> will still want to have both
libraries up to date and will therefore invoke <code>make all</code>
automatically. To restrict builds in such a way that only one library
- will be installed, see <a href="#configurebuild">this section</a>.
+ will be installed, see <a href="#configurebuild">configuration</a>
+ and <a href="#buildinstall">installation</a> sections.
</p>
<hr />
projects / dealii-svn.git / commitdiff