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 :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
  30
  31 Copyright
  32 ---------
  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 2 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.
  38
  39 System requirements
  40 -------------------
  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.
  44
  45 Required software to build {project}
  46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  47 [[cmake]]CMake::
  48   In order to build {project} you need to have CMake with version 2.8.0 or
  49   newer installed. {cmake}
  50 [[build_system]]Build system::
  51   CMake requires a native build system. On Unix-like platforms GNU Make is
  52   recommended. {make}
  53 [[cxx_compiler]]{cpp} compiler::
  54   In order to build {project} you need a {cpp} compiler with good support for
  55   template expressions. The g++ compiler from GCC-4.3 and above will do
  56   fine. {gcc}
  57 [[flex]]flex::
  58   The flex lexer generator. Version 2.5.33 is known to work. For more recent
  59   versions there have been reports of problems. {flex}
  60 [[zlib]]zlib::
  61   zlib compression library. {zlib}
  62 [[scotch]]SCOTCH::
  63   The SCOTCH graph partitioning library. Version 5.1.7 is know to work.
  64   {scotch}
  65 [[python]]Python::
  66   The Python interpreter. Version 2.6.1 is known to work, but care has been
  67   taken to make {project} work with versions from 2.4 on, including 3.x.
  68
  69 Optional software
  70 ~~~~~~~~~~~~~~~~~
  71 [[git]]git::
  72   To check out a current development version of {project}, git is required.
  73   {git}
  74 [[parlib]]Parallel Communications Library::
  75   In order to run {project} in parallel, a communications library is required.
  76   The following list gives an overview of the available options:
  77   - MPI (_Message Passing Interface_): There are many implementations of the
  78     MPI standard. The one that has been tested and is known to work with
  79     {project} is {openmpi}.
  80 [[metis]]METIS::
  81   The METIS graph partitioning library, version 5.0pre2. If your package
  82   manager doesn't contain it, you can also have {project} build it
  83   automatically for you (see the <<installation,installation section>>).
  84   {metis}
  85 [[parmetis]]ParMetis::
  86   If you use an MPI library, the ParMetis library is required. If your package
  87   manager doesn't contain this library, {project} can build it automatically
  88   for you (refer to the <<installation,installation notes>> below). {parmetis}
  89 [[mgridgen]]MGRIDGEN:: MGRIDGEN is a grid coarsening library for multi-grid
  90   solvers. {project} can build this automatically for you. Please refer to the
  91   link:INSTALL.html#enable-parmgridgen[INSTALL] file for license restrictions.
  92   {mgridgen}
  93 [[libccmio]]libccmio::
  94   pro-STAR (C) input/output library. {project} can build this automatically for
  95   you. Please refer to the link:INSTALL.html#enable-ccmio[INSTALL] file for
  96   license restrictions. {ccmio}
  97 [[paraview]]ParaView::
  98   The {project} utility 'para' requires this visualization application, version
  99   3.8 or later. {paraview}
 100 [[m4]]M4::
 101   Some of the provided tutorial cases require the M4 macro processor. {m4}
 102 [[doxygen]]Doxygen::
 103   Automatic API-documentation generator. Required to build the source
 104   documentation. {doxygen}
 105 [[asciidoc]]Asciidoc::
 106   In order to create the man-pages or the XHTML and PDF documentation you need
 107   to have a fully working Asciidoc toolchain installed. Versions newer than 8.5
 108   are known to work. Asciidoc itself needs Python 2.4 or newer (but not 3.x),
 109   xsltproc, the DocBook XML DTD's and the DocBook XSL stylesheets. Refer to the
 110   Asciidoc installation instructions for the details. {asciidoc}
 111 [[dblatex]]dblatex::
 112   If you want to build the PDF version of the user guide, it is recommended
 113   that you have dblatex installed, as the generated output is superior to that
 114   generated with the alternative, Apache FOP. {dblatex}
 115 [[fop]]Apache FOP::
 116   If you want to build the PDF version of the user guide bug can't or don't
 117   want to install <<dblatex>>, Apache FOP can be used instead. It's output,
 118   however, is inferior to that of dblatex, especially that of the formulas.
 119   {fop}
 120 [[mathjax]]MathJax::
 121   If you enable MathJax for math-rendering in the XHTML version of the user
 122   guide, but don't want to use the shared installation over the network, you
 123   can install MathJax locally. {mathjax}
 124
 125 [[installation]]
 126 Installation
 127 ------------
 128 For exhaustive installation and basic usage instructions, refer to the
 129 link:INSTALL.html[INSTALL] file.
 130
 131 Documentation
 132 -------------
 133 All the applications and the frequently used script utilities come with a brief
 134 man-page. Unfortunately, most of them are little more than stubs and need more
 135 work. The man-page _freefoam(1)_ gives a short overview over all applications
 136 and utilities and documents the {project} configuration options.
 137
 138 API-documentation is available from {apidoc}.
 139
 140 Further, most {project} applications and utilities support the '-doc' and
 141 '-srcDoc' options, which will automatically display the API-documentation and
 142 the source code of the application, respectively.
 143
 144 Help
 145 ----
 146 - {homepage}/support
 147 - {openfoamforum} *please only ask questions related to _OpenFOAM_ there*.
 148
 149 Reporting Bugs in {project}
 150 ---------------------------
 151 {bugreport}
 152
 153 ///////////////////////////////////////////////////////////////////
 154 Process with: asciidoc -a toc -f data/asciidoc/html.conf README
 155
 156 Vim users, this is for you:
 157 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
 158 ///////////////////////////////////////////////////////////////////