README

   1 {project} README for Version {fullver}
   2 ======================================
   3 Michael Wild <themiwi@users.sourceforge.net>
   4 :Author Initials: MW
   5 v{fullver}, {localdate}
   6 {homepage}
   7
   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
  35
  36 Copyright
  37 ---------
  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.
  43
  44 System requirements
  45 -------------------
  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.
  49
  50 Required software to build {project}
  51 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  52 [[cmake]]CMake::
  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
  60   recommended. {make}
  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
  64   fine. {gcc}
  65 [[flex]]flex::
  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}
  68 [[zlib]]zlib::
  69   zlib compression library. {zlib}
  70 [[scotch]]SCOTCH::
  71   The SCOTCH graph partitioning library. Version 5.1.7 is know to work.
  72   {scotch}
  73 [[python]]Python::
  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.
  76 +
  77 [NOTE]
  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
  81 is used.
  82
  83 Optional software
  84 ~~~~~~~~~~~~~~~~~
  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}
  97 [[bison]]Bison::
  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}
 101 [[dblatex]]dblatex::
 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}
 106 [[doxygen]]Doxygen::
 107   Automatic API-documentation generator. Required to build the source
 108   documentation. {doxygen}
 109 [[fop]]Apache FOP::
 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
 113   formulas. {fop}
 114 [[git]]git::
 115   To check out a current development version of {project}, git is required.
 116   {git}
 117 [[graphviz]]Graphviz::
 118   The graphs in the User Guide and the API documentation are require the
 119   Graphviz package for their generation. {graphviz}
 120 [[latex]]LaTeX::
 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}
 130 [[m4]]M4::
 131   Some of the provided tutorial cases require the M4 macro processor. {m4}
 132 [[mathjax]]MathJax::
 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}
 136 [[metis]]METIS::
 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>>).
 140   {metis}
 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.
 145   {mgridgen}
 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}
 162
 163 [[installation]]
 164 Installation
 165 ------------
 166 For exhaustive installation and basic usage instructions, refer to the
 167 link:INSTALL.html[INSTALL] file.
 168
 169 Documentation
 170 -------------
 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.
 175
 176 API-documentation is available from {apidoc}.
 177
 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.
 181
 182 Help
 183 ----
 184 - {homepage}/support
 185 - {openfoamforum} *please only ask questions related to _OpenFOAM_ there*.
 186
 187 Reporting Bugs in {project}
 188 ---------------------------
 189 {bugreport}
 190
 191 ///////////////////////////////////////////////////////////////////
 192 Process with: asciidoc -a toc -f data/asciidoc/html.conf README
 193
 194 Vim users, this is for you:
 195 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
 196 ///////////////////////////////////////////////////////////////////