ENH: No verbose a2x output when building UserGuide

[freefoam.git] / HACKING

FreeFOAM hackers informations
=============================
Michael Wild <themiwi@users.sourceforge.net>
:Author Initials: MW
v{fullver}, {localdate}
{homepage}

:cmake: http://www.cmake.org[CMake]
:gitdocs: http://www.kernel.org/pub/software/scm/git/docs
:gitworkflows: {gitdocs}/gitworkflows.html[gitworkflows(7)]
:pythondoc: http://www.python.org/doc

Copyright
---------
FreeFOAM is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.  See the file COPYING in this directory, for a description of the GNU
General Public License terms under which you can copy the files.

Recommended Reading
-------------------

Before you participate in the FreeFOAM project and start away hacking, you
should make yourself familiar with the tools. The following sections name the
most important of them and give you a few references I used to learn them.

Git
~~~
To work on the FreeFOAM source base, you need to know your 'Git-foo'. Git is
the distributed source control system used by the FreeFOAM project, and feeling
comfortable using Git is germane to participating in the project. The official
documentation (either available through extensive man-pages or from
{gitdocs}) is of course the
authoritative source. Especially the manual page {gitworkflows} is of interest
with respect to the work flow used by the FreeFOAM project. If you prefer to
learn Git reading a book, there are the freely available online books
<<ProGit>> and <<GitCommBook>>. Learners desiring to hold a book in their hands
can either print the PDF version of <<GitCommBook>> or buy a hard-copy of
<<ProGit>> or <<VCGit>>.

CMake
~~~~~
The build system used by FreeFOAM is {cmake}. Being able to
use it on a user-level is a hard requirement for working on FreeFOAM. Pretty
quickly, though, contributors will need more understanding of the topic and
should get their hands on a copy of <<MasteringCMake>>.

Python
~~~~~~
All the 'user-land' scripts and many of the scripts used during the build of
FreeFOAM are written in Python. So, you definitely should know how to read it.
There is a good tutorial (and of course the ever-so-important reference) at
{pythondoc}. There is no book I can recommend, since I haven't read any myself.

{cpp}
~~~~~
FreeFOAM is a large {cpp} project which makes use of almost any language
feature there is. Thus it is *strongly* recommended you have a good
understanding of {cpp} in general (e.g. you should be familiar with function
overloading and polymorphism) and you absolutely *must* understand function and
class templates. So far I did not come across a single book which covers all of
these topics satisfactorily. For the more traditional {cpp} topics (i.e.
non-templated code), <<EffCXX>> and <<ExceptCXX>> are very good resources and
should also cover template programming in sufficient detail to work on the
FreeFOAM code base. If you want to know the ins and outs of {cpp} templates,
refer to <<CXXTemplates>> and to get an inkling of all the fancy stuff you can
do with them, read <<CXXMeta>>.

Coding Practices and Style
--------------------------
Follow the instructions outlined in the file 'doc/codingStyleGuide.pdf'
contained in the source distribution. Additionally, pay special attention to
the following points:

* In general, lines shouldn't be longer than 80 characters and they *must* be
  terminated by a LF. Windows-style line endings (CR+LF) are not acceptable.
* Indentation for {cpp} is 4 spaces, for Python code 3 or 2 spaces and
  CMake-code uses 2 spaces only. Never use tab characters (except where
  required by syntax).
* Avoid trailing whitespace at all costs. It is considered to be a programming
  error. However, only remove it from existing code if you change that line
  anyways. Otherwise the version control log will be very noisy and the 'blame'
  operation useless.
* Make sure that file and directory names differ not just in their
  capitalization. Also, for libraries a header name must be unique within the
  whole library, but preferably all file names are unique throughout the whole
  code base.
* New applications must provide header documentation describing *all* available
  options and arguments. Also, there must be a brief description (1-2 lines
  maximum) and an extended, informative description. Somebody reading it should
  know what to expect from this application without having to read its whole
  code.
* New applications must provide a tutorial case that can be run as a basic
  test to ensure that it runs (although, without checking the validity of the
  results).
* New CMake-Modules and functions must be documented using a header comment.

'Tour de Code'
--------------
This section describes each of the libraries briefly. This is an ongoing effort
and below items are by no means complete. The listing is alphabetical.

autoMesh::
  This library handles adaptive mesh refinement, e.g. layer insertion/deletion.
barotropicCompressibilityModel::
  Provides barotropic compressibility models (a linear model, the one by Wallis
  and another by Chung).
basicThermophysicalModels::
  Provides classes to store and compute derived thermophysical properties (such
  as sensible enthalpy, inner energy, temperature, pressure or heat capacity)
  based on the density or compressibility for pure fluids or mixtures.
chemistryModel::
  This library contains various chemistry models (e.g. based on density or
  compressibility, but also an ODE systems solver).
coalCombustion::
  Contains classes relevant to the simulation of coal combustion (specialised
  particle cloud coal parcel, surface reaction models).
compressibleLESModels::
  Provides a large variety of compressible LES subgrid-scale models.
compressibleRASModels::
  Supplies various compressible RANS turbulence models.
compressibleTurbulenceModel::
  Contains a common interface and infrastructure for compressible turbulence
  models.
conversion::
  This library comprises several file-format conversion classes (e.g. for
  Ensight and Star-CD).
decompositionMethods::
  The library contains common infrastructure and interfaces for decomposition
  domain methods, as well as several actual decomposition methods
  (geometrical, hierarchical, manual and one using the 'scotch' graph library).
dieselSpray::
  Provides classes relevant to Diesel-spray modelling (breakup, atomization,
  evaporation, drag, collision, wall interaction etc.).
dsmc::
  This library contains classes for 'Direct Simulation Monte Carlo'.
dummyPstream::
  This is the serial implementation of the 'Pstream' communications library.
dynamicFvMesh::
  Provides classes for dynamic and topology-changing finite volume meshes.
dynamicMesh::
  This library provides mesh manipulation methods (e.g. addition/removal of
  cell layers, mesh-motion solvers, sliding interfaces etc.)
edgeMesh::
  A simple mesh type consisting of points connected by edges.
engine::
  This is a support-library for internal combustion engine solvers.
errorEstimation::
  Residual error estimation and error-driven mesh refinement classes.
fieldFunctionObjects::
  Runtime-loadable function objects for the extraction statistics/diagnostics
  from a field.
finiteVolume::
  This library contains everything related to the finite volume (FV) method,
  such as mesh classes, discretisation and interpolation schemes, matrices and
  other basic CFD related tools.
foamCalcFunctions::
  Functions for the 'foamCalc' utility application.
forces::
  Runtime-loadable function objects used to extract forces and
  force-coefficients on selected patches.
fvMotionSolvers::
  Library containing various finite volume mesh motion solvers where the motion
  velocity is set as a boundary condition.
genericPatchFields::
  Generic finite volume and point patch field types.
incompressibleLESModels::
  Large Eddy Simulation (LES) models for incompressible flow.
incompressibleRASModels::
  Reynolds Averaged Simulation (RAS) models for incompressible flow.
incompressibleTransportModels::
  Transport model classes for incompressible flow.
incompressibleTurbulenceModel::
  Base classes for the incompressible turbulence models.
interfaceProperties::
  Classes describing interface properties and compression for two-phase flows.
IOFunctionObjects::
  A function object to write registered objects which would otherwise not be
  written.
lagrangian::
  Basic classes for Lagrangian particle tracking.
lagrangianIntermediate::
  Advance classes for Lagrangian particle tracking.
laminarFlameSpeedModels::
  Laminar flame speed models.
LESdeltas::
  Various LES delta models.
LESfilters::
  Various LES filters.
liquidMixture::
  A class representing a mixture of liquids.
liquids::
  Thermophysical properties of various liquids.
meshTools::
  A collection of classes and functions of mesh-related tasks, such as
  searching, splitting into regions, creating sets etc.
metisDecomp::
  Domain decomposition method using the 'METIS' graph library.
MGridGenGAMGAgglomeration::
  Cell-agglomeration for the 'GAMG' solver using the 'MGridGen' library.
molecularMeasurements::
  Statistic extraction library for molecular dynamics simulations.
molecule::
  Library containing classes for molecular dynamics (MD) simulations.
mpiPstream::
  This is the MPI-parallel implementation of the 'Pstream' communications
  library.
ODE::
  Library to solve ODE's for each cell.
OpenFOAM::
  Basic infrastructure, such as containers, primitive types, streams, fields
  and meshes.
OSspecific::
  Functions wrapping operating-system specific functionality.
parMetisDecomp::
  Domain decomposition method using the 'ParMetis' library.
pdf::
  Provides various probability density functions (PDF).
postCalc::
  Generic wrapper to calculate quantities in a post-processing step.
potential::
  Models for various potentials in molecular dynamics simulations.
radiation::
  Various radiation models.
randomProcesses::
  A library to create a turbulent velocity and pressure field according to a
  wave-number spectrum and which is divergence-free.
reactionThermophysicalModels::
  Reaction- and combustion-thermophysical models.
sampling::
  A data-sampling library (extraction along a line, on a plane, patch etc.).
scotchDecomp::
  Domain decomposition method using the 'SCOTCH' graph library.
solidMixture::
  A class for the thermophysical properties of a solid mixture.
solidParticle::
  A simple solid, spherical particle class with one-way coupling with the
  continuous phase.
solids::
  Thermophysical properties models for various solid materials.
specie::
  Basic classes for thermphysical properties models.
surfMesh::
  A library with classes for many surface-mesh formats.
systemCall::
  A function object allowing the user to call an external program at run-time.
thermophysicalFunctions::
  A collection of thermophysical functions.
topoChangerFvMesh::
  Classes to support topology-changing finite volume meshes.
triSurface::
  Triangulated surface description and patch information classes.
utilityFunctionObjects::
  Miscellaneous function objects (static pressure computation, calculation of
  intensive fields in DSMC simulations)

Merging Guide
-------------
These are notes mainly concerning the FreeFOAM maintainers performing the
merges with the upstream repository (currently, that is me). Other may find
this informative, though, and I realized that I need a checklist...

* Create a clone on a case-sensitive file system and check out the upstream
  tracking branch 'upstream/OpenFOAM-1.7.x' and +git pull+.
* Check out the branch with the unified history, 'upstream/OpenFOAM' and merge
  in the versioned upstream branch.
* Get an overview of what has been added and removed using
  +git show -m --name-status --no-renames --diff-filter=AD+. Of special
  interest are 'wmake' related files, new or removed sources, new scripts in
  'bin', added or removed libraries, applications and tutorials.
* Check out the branch you want to merge into (usually that is 'pu') and merge
  with 'upstream/OpenFOAM'. There will be many merge conflicts.
* Use the following checklist while merging:
  - Changes to 'Make/files' usually only map to the corresponding 'files.cmake'
    file. New source files are added to the 'SRCS' list.
  - New source and header files ('.C' and '.H') belonging to a library that
    are not mentioned in the 'Make/files' file must be added to the 'HDRS'
    list. This usually is not reflected by a conflict!
  - New link libraries added in 'Make/options' should be ported to the
    'CMakeLists.txt' file. New include directories should only be ported if
    they are 'relative includes'.
  - Check the 'diff' of all modified/added source files for '#include'
    directives. Find whether the included file belongs to a library and if so,
    change the '#include "header.H"' to '#include <libname/header.H>'.
  - Add modelines to added files.
  - Complete/fix the header comment of new applications.
  - Usually, changes inside the 'wmake' directory can be discarded.
  - More often than not, added scripts in 'bin' are useless to the FreeFOAM
    project. If not, port the script to Python if it is to be distributed in a
    binary package.
  - Newly added tutorials must be furnished with their own 'CMakeLists.txt'
    file and a new +add_subdirectory+ call needs to be added. Port new 'Allrun'
    and 'Allclean' scripts to a 'Allrun.py.in' script.

Release Guide
-------------
The following lists things to remember when creating a new release.

* Update 'ChangeLog' and 'ReleaseNotes'
* Update version information in 'CMakeLists.txt' and
  'data/asciidoc/common.conf'
* Use the 'data/utilities/foamPackSource' script to create a new, signed tag,
  create a tar-ball with an external signature and check-sum files.

Bibliography
------------
[bibliography]
* [[[ProGit]]] Scott Chacon. http://progit.org/['Pro Git']. Apress 2009.
  ISBN http://isbndb.com/search-all.html?kw=1-430-21833-9[1-430-21833-9].
* [[[GitCommBook]]] Scott Chacon and many others.
  http://book.git-scm.com['The Git Community Book'].
* [[[VCGit]]] Jon Loeliger. 'Version Control with Git'. O'Reilly 2009.
  ISBN http://isbndb.com/search-all.html?kw=0-596-52012-3[0-596-52012-3].
* [[[MasteringCMake]]] Ken Martin, Bill Hoffman. 'Mastering CMake'.
  Kitware Inc. 2010.
  ISBN http://isbndb.com/search-all.html?kw=1-930-93422-X[1-930-93422-X]
* [[[EffCXX]]] Scott Meyers. 'Effective {cpp}'. Addison-Wesley 2005.
  ISBN http://isbndb.com/search-all.html?kw=0-321-33487-6[0-321-33487-6].
* [[[ExceptCXX]]] Herb Sutter. 'Exceptional {cpp}'. Addison-Wesley 2000.
  ISBN http://isbndb.com/search-all.html?kw=0-201-61562-2[0-201-61562-2].
* [[[CXXTemplates]]] David Vandevoorde, Nicolai M. Josutis.
  '{cpp} Templates - The Complete Guide'. Addison-Wesley 2003.
  ISBN http://isbndb.com/search-all.html?kw=0-201-73484-2[0-201-73484-2].
* [[[CXXMeta]]] David Abrahams
  David Abrahams, Aleksey Gurtovoy. '{cpp} Template Metaprogramming: Concepts,
  Tools, and Techniques from Boost and Beyond'. Addison-Wesley 2005.
  ISBN http://isbndb.com/search-all.html?kw=0-321-22725-5[0-321-22725-5]

////////////////////////////////////////////////////////////////////
Process with: asciidoc -a toc -f data/asciidoc/html.conf HACKING

Vim users, this is for you:
vim: ft=asciidoc sw=2 expandtab fenc=utf-8
////////////////////////////////////////////////////////////////////