1 {project} README for Version {fullver}
2 ======================================
3 Michael Wild <themiwi@users.sourceforge.net>
5 v{fullver}, {localdate}
8 :apidoc: {homepage}/doc/v{fullver}/API
9 :asciidoc: http://www.methods.co.nz/asciidoc
10 :bugreport: http://sourceforge.net/apps/mantisbt/freefoam
11 :ccmio: https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz
12 :cmake: http://cmake.org
13 :dblatex: http://dblatex.sourceforge.net
14 :doxygen: http://www.doxygen.org
15 :flex: http://flex.sourceforge.net
16 :fop: http://xmlgraphics.apache.org/fop
17 :gcc: http://gcc.gnu.org
18 :git: http://git.or.cz
19 :m4: http://www.gnu.org/software/m4/
20 :make: http://www.gnu.org/software/make
21 :mathjax: http://www.mathjax.org
22 :metis: http://glaros.dtc.umn.edu/gkhome/metis/metis/overview
23 :mgridgen: http://glaros.dtc.umn.edu/gkhome/mgridgen/overview
24 :openfoamforum: http://www.cfd-online.com/Forums/openfoam
25 :openmpi: http://www.open-mpi.org[OpenMPI]
26 :paraview: http://www.paraview.org
27 :parmetis: http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview
28 :scotch: http://www.labri.fr/perso/pelegrin/scotch
29 :zlib: http://www.zlib.net
33 {project} is free software; you can redistribute it and/or modify it under the
34 terms of the GNU General Public License as published by the Free Software
35 Foundation; either version 3 of the License, or (at your option) any later
36 version. See the file COPYING in this directory, for a description of the GNU
37 General Public License terms under which you can copy the files.
41 {project} is developed and tested on Linux, but should work with other Unix
42 style systems, notably Mac OS X (C). The support for Microsoft Windows is a
43 goal, which, however, is still far off.
45 Required software to build {project}
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
48 In order to build {project} you need to have CMake with version 2.8.2 or
49 newer installed. In order to follow the link:INSTALL.html[INSTALL]
50 instructions, make sure that you also install the package contain the curses
51 GUI ccmake if using a package manager (e.g. on Linux systems. For Debian
52 and Ubuntu the package is called _cmake-curses-gui_). {cmake}
53 [[build_system]]Build system::
54 CMake requires a native build system. On Unix-like platforms GNU Make is
56 [[cxx_compiler]]{cpp} compiler::
57 In order to build {project} you need a {cpp} compiler with good support for
58 template expressions. The g++ compiler from GCC-4.3 and above will do
61 The flex lexer generator. Version 2.5.33 is known to work. For more recent
62 versions there have been reports of problems. {flex}
64 zlib compression library. {zlib}
66 The SCOTCH graph partitioning library. Version 5.1.7 is know to work.
69 The Python interpreter. Version 2.6 is known to work, but care has been taken
70 to make {project} work with versions from 2.4 on, including 3.x.
73 In order to build the man pages or the user guide, AsciiDoc is required
74 which has not yet been ported to Python 3. This is why Python version 2 is also
75 required (only at build-time for the documentation) if a Python 3 interpreter
81 To check out a current development version of {project}, git is required.
83 [[parlib]]Parallel Communications Library::
84 In order to run {project} in parallel, a communications library is required.
85 Currently the only available options is MPI (_Message Passing Interface_).
86 There are many implementations of the MPI standard. The one that has been
87 tested and is known to work with {project} is {openmpi}.
89 The METIS graph partitioning library, version 5.0.1. If your package
90 manager doesn't contain it, you can also have {project} build it
91 automatically for you (see the <<installation,installation section>>).
93 [[parmetis]]ParMetis::
94 If you use an MPI library, the ParMetis library is required. If your package
95 manager doesn't contain this library, {project} can build it automatically
96 for you (refer to the <<installation,installation notes>> below). {parmetis}
97 [[mgridgen]]MGRIDGEN:: MGRIDGEN is a grid coarsening library for multi-grid
98 solvers. {project} can build this automatically for you. Please refer to the
99 link:INSTALL.html#enable-parmgridgen[INSTALL] file for license restrictions.
101 [[libccmio]]libccmio::
102 pro-STAR (C) input/output library. {project} can build this automatically for
103 you. Please refer to the link:INSTALL.html#enable-ccmio[INSTALL] file for
104 license restrictions. {ccmio}
105 [[paraview]]ParaView::
106 The {project} utility 'para' requires this visualization application, version
107 3.8 or later. {paraview}
109 Some of the provided tutorial cases require the M4 macro processor. {m4}
111 Automatic API-documentation generator. Required to build the source
112 documentation. {doxygen}
113 [[asciidoc]]AsciiDoc::
114 In order to create the man-pages or the XHTML and PDF documentation you need
115 to have a fully working AsciiDoc toolchain installed. Versions newer than 8.5
116 are known to work. AsciiDoc itself needs Python 2.4 or newer (but not 3.x),
117 xsltproc, the DocBook XML DTD's and the DocBook XSL stylesheets. Refer to the
118 AsciiDoc installation instructions for the details. Also note, that AsciiDoc
119 versions 8.6.5 and 8.6.6 contain a bug which makes it depend on Python 2.5
120 and newer. {asciidoc}
122 If you want to build the PDF version of the user guide, it is recommended
123 that you have dblatex installed, as the generated output is superior to that
124 generated with the alternative, Apache FOP. {dblatex}
126 If you want to build the PDF version of the user guide but can't or don't
127 want to install <<dblatex>>, Apache FOP can be used instead. It's output,
128 however, is inferior to that of dblatex, especially that of the formulas.
131 If you enable MathJax for math-rendering in the XHTML version of the user
132 guide, but don't want to use the shared installation over the network, you
133 can install MathJax locally. {mathjax}
138 For exhaustive installation and basic usage instructions, refer to the
139 link:INSTALL.html[INSTALL] file.
143 All the applications and the frequently used script utilities come with a brief
144 man-page. Unfortunately, most of them are little more than stubs and need more
145 work. The man-page _freefoam(1)_ gives a short overview over all applications
146 and utilities and documents the {project} configuration options.
148 API-documentation is available from {apidoc}.
150 Further, most {project} applications and utilities support the '-doc' and
151 '-srcDoc' options, which will automatically display the API-documentation and
152 the source code of the application, respectively.
157 - {openfoamforum} *please only ask questions related to _OpenFOAM_ there*.
159 Reporting Bugs in {project}
160 ---------------------------
163 ///////////////////////////////////////////////////////////////////
164 Process with: asciidoc -a toc -f data/asciidoc/html.conf README
166 Vim users, this is for you:
167 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
168 ///////////////////////////////////////////////////////////////////