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 :aymptote: http://asymptote.sourceforge.net
11 :bison: http://gnu.org/s/bison
12 :bugreport: http://sourceforge.net/apps/mantisbt/freefoam
13 :ccmio: https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz
14 :cmake: http://cmake.org
15 :dblatex: http://dblatex.sourceforge.net
16 :doxygen: http://www.doxygen.org
17 :flex: http://flex.sourceforge.net
18 :fop: http://xmlgraphics.apache.org/fop
19 :gcc: http://gcc.gnu.org
20 :git: http://git.or.cz
21 :graphviz: http://graphviz.org
22 :latex: http://latex-project.org
23 :m4: http://www.gnu.org/software/m4/
24 :make: http://www.gnu.org/software/make
25 :mathjax: http://www.mathjax.org
26 :metis: http://glaros.dtc.umn.edu/gkhome/metis/metis/overview
27 :mgridgen: http://glaros.dtc.umn.edu/gkhome/mgridgen/overview
28 :openfoamforum: http://www.cfd-online.com/Forums/openfoam
29 :openmpi: http://www.open-mpi.org[OpenMPI]
30 :paraview: http://www.paraview.org
31 :parmetis: http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview
32 :readline: http://gnu.org/s/readline
33 :scotch: http://www.labri.fr/perso/pelegrin/scotch
34 :zlib: http://www.zlib.net
38 {project} is free software; you can redistribute it and/or modify it under the
39 terms of the GNU General Public License as published by the Free Software
40 Foundation; either version 3 of the License, or (at your option) any later
41 version. See the file COPYING in this directory, for a description of the GNU
42 General Public License terms under which you can copy the files.
46 {project} is developed and tested on Linux, but should work with other Unix
47 style systems, notably Mac OS X (C). The support for Microsoft Windows is a
48 goal, which, however, is still far off.
50 Required software to build {project}
51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53 In order to build {project} you need to have CMake with version 2.8.2 or
54 newer installed. In order to follow the link:INSTALL.html[INSTALL]
55 instructions, make sure that you also install the package contain the curses
56 GUI ccmake if using a package manager (e.g. on Linux systems. For Debian
57 and Ubuntu the package is called _cmake-curses-gui_). {cmake}
58 [[build_system]]Build system::
59 CMake requires a native build system. On Unix-like platforms GNU Make is
61 [[cxx_compiler]]{cpp} compiler::
62 In order to build {project} you need a {cpp} compiler with good support for
63 template expressions. The g++ compiler from GCC-4.3 and above will do
66 The flex lexer generator. Version 2.5.33 is known to work. For more recent
67 versions there have been reports of problems. {flex}
69 zlib compression library. {zlib}
71 The SCOTCH graph partitioning library. Version 5.1.7 is know to work.
74 The Python interpreter. Version 2.6 is known to work, but care has been taken
75 to make {project} work with versions from 2.4 on, including 3.x.
78 In order to build the man pages or the user guide, AsciiDoc is required
79 which has not yet been ported to Python 3. This is why Python version 2 is also
80 required (only at build-time for the documentation) if a Python 3 interpreter
85 [[asciidoc]]AsciiDoc::
86 In order to create the man-pages or the XHTML and PDF documentation you need
87 to have a fully working AsciiDoc toolchain installed. Versions newer than 8.5
88 are known to work. AsciiDoc itself needs Python 2.4 or newer (but not 3.x),
89 xsltproc, xmllint from libxml2, the DocBook XML DTD's and the DocBook XSL
90 stylesheets. Refer to the AsciiDoc installation instructions for the details.
91 Also note, that AsciiDoc versions 8.6.5 and 8.6.6 contain a bug which makes
92 it depend on Python 2.5 and newer. {asciidoc}
93 [[asymptote]]Asymptote::
94 Asymptote, the powerful descriptive vector-graphics language, is used to
95 generate many of the graphics in the User Guide. Note that Asymptote
96 itself depends on a <<latex,LaTeX>> installation. {asymptote}
98 If you choose to build <<scotch,SCOTCH>> locally by enabling
99 link:INSTALL.html#private-scotch[+FOAM_BUILD_PRIVATE_SCOTCH+], the Bison
100 parser generator is required. {bison}
102 If you want to build the PDF version of the user guide, it is recommended
103 that you have dblatex installed, as the generated output is superior to that
104 generated with the alternative, Apache FOP. Since dblatex uses LaTeX as its
105 rendering backend, it depends on a <<latex,LaTeX>> installation. {dblatex}
107 Automatic API-documentation generator. Required to build the source
108 documentation. {doxygen}
110 If you want to build the PDF version of the user guide but can't or don't
111 want to install <<dblatex,dblatex>>, Apache FOP can be used instead. It's
112 output, however, is inferior to that of dblatex, especially that of the
115 To check out a current development version of {project}, git is required.
117 [[graphviz]]Graphviz::
118 The graphs in the User Guide and the API documentation are require the
119 Graphviz package for their generation. {graphviz}
121 Both, <<dblatex,dblatex>> and <<asymptote,Asymptote>> require a decent LaTeX
122 installation. If you install LaTeX via a package manager, make sure that you
123 also install the packages providing the 'units.sty' LaTeX package and the
124 extra fonts. On Debian and Ubuntu systems, they are called
125 'texlive-latex-extra' and 'texlive-fonts-recommended', respectively. {latex}
126 [[libccmio]]libccmio::
127 pro-STAR (C) input/output library. {project} can build this automatically for
128 you. Please refer to the link:INSTALL.html#enable-ccmio[INSTALL] file for
129 license restrictions. {ccmio}
131 Some of the provided tutorial cases require the M4 macro processor. {m4}
133 If you enable MathJax for math-rendering in the XHTML version of the user
134 guide, but don't want to use the shared installation over the network, you
135 can install MathJax locally. {mathjax}
137 The METIS graph partitioning library, version 5.0.1. If your package
138 manager doesn't contain it, you can also have {project} build it
139 automatically for you (see the <<installation,installation section>>).
141 [[mgridgen]]MGRIDGEN::
142 MGRIDGEN is a grid coarsening library for multi-grid solvers. {project} can
143 build this automatically for you. Please refer to the
144 link:INSTALL.html#enable-parmgridgen[INSTALL] file for license restrictions.
146 [[paraview]]ParaView::
147 The {project} utility 'para' requires this visualization application, version
148 3.8 or later. {paraview}
149 [[parlib]]Parallel Communications Library::
150 In order to run {project} in parallel, a communications library is required.
151 Currently the only available options is MPI (_Message Passing Interface_).
152 There are many implementations of the MPI standard. The one that has been
153 tested and is known to work with {project} is {openmpi}.
154 [[parmetis]]ParMetis::
155 If you use an MPI library, the ParMetis library is required. If your package
156 manager doesn't contain this library, {project} can build it automatically
157 for you (refer to the <<installation,installation notes>> below). {parmetis}
158 [[readline]]GNU Readline::
159 The 'setSet' utility can be used in an interactive mode which is greatly
160 improved if using the GNU Readline library for history and command line
161 editing support. {readline}
166 For exhaustive installation and basic usage instructions, refer to the
167 link:INSTALL.html[INSTALL] file.
171 All the applications and the frequently used script utilities come with a brief
172 man-page. Unfortunately, most of them are little more than stubs and need more
173 work. The man-page _freefoam(1)_ gives a short overview over all applications
174 and utilities and documents the {project} configuration options.
176 API-documentation is available from {apidoc}.
178 Further, most {project} applications and utilities support the '-doc' and
179 '-srcDoc' options, which will automatically display the API-documentation and
180 the source code of the application, respectively.
185 - {openfoamforum} *please only ask questions related to _OpenFOAM_ there*.
187 Reporting Bugs in {project}
188 ---------------------------
191 ///////////////////////////////////////////////////////////////////
192 Process with: asciidoc -a toc -f data/asciidoc/html.conf README
194 Vim users, this is for you:
195 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
196 ///////////////////////////////////////////////////////////////////