HACKING

   1 FreeFOAM hackers informations
   2 =============================
   3 Michael Wild <themiwi@users.sourceforge.net>
   4 :Author Initials: MW
   5 v{fullver}, {localdate}
   6 {homepage}
   7
   8 :cmake: http://www.cmake.org[CMake]
   9 :gitdocs: http://www.kernel.org/pub/software/scm/git/docs
  10 :gitworkflows: {gitdocs}/gitworkflows.html[gitworkflows(7)]
  11 :pythondoc: http://www.python.org/doc
  12
  13 Copyright
  14 ---------
  15 FreeFOAM is free software; you can redistribute it and/or modify it under the
  16 terms of the GNU General Public License as published by the Free Software
  17 Foundation; either version 2 of the License, or (at your option) any later
  18 version.  See the file COPYING in this directory, for a description of the GNU
  19 General Public License terms under which you can copy the files.
  20
  21 Recommended Reading
  22 -------------------
  23
  24 Before you participate in the FreeFOAM project and start away hacking, you
  25 should make yourself familiar with the tools. The following sections name the
  26 most important of them and give you a few references I used to learn them.
  27
  28 Git
  29 ~~~
  30 To work on the FreeFOAM source base, you need to know your 'Git-foo'. Git is
  31 the distributed source control system used by the FreeFOAM project, and feeling
  32 comfortable using Git is germane to participating in the project. The official
  33 documentation (either available through extensive man-pages or from
  34 {gitdocs}) is of course the
  35 authoritative source. Especially the manual page {gitworkflows} is of interest
  36 with respect to the work flow used by the FreeFOAM project. If you prefer to
  37 learn Git reading a book, there are the freely available online books
  38 <<ProGit>> and <<GitCommBook>>. Learners desiring to hold a book in their hands
  39 can either print the PDF version of <<GitCommBook>> or buy a hard-copy of
  40 <<ProGit>> or <<VCGit>>.
  41
  42 CMake
  43 ~~~~~
  44 The build system used by FreeFOAM is {cmake}. Being able to
  45 use it on a user-level is a hard requirement for working on FreeFOAM. Pretty
  46 quickly, though, contributors will need more understanding of the topic and
  47 should get their hands on a copy of <<MasteringCMake>>.
  48
  49 Python
  50 ~~~~~~
  51 All the 'user-land' scripts and many of the scripts used during the build of
  52 FreeFOAM are written in Python. So, you definitely should know how to read it.
  53 There is a good tutorial (and of course the ever-so-important reference) at
  54 {pythondoc}. There is no book I can recommend, since I haven't read any myself.
  55
  56 {cpp}
  57 ~~~~~
  58 FreeFOAM is a large {cpp} project which makes use of almost any language
  59 feature there is. Thus it is *strongly* recommended you have a good
  60 understanding of {cpp} in general (e.g. you should be familiar with function
  61 overloading and polymorphism) and you absolutely *must* understand function and
  62 class templates. So far I did not come across a single book which covers all of
  63 these topics satisfactorily. For the more traditional {cpp} topics (i.e.
  64 non-templated code), <<EffCXX>> and <<ExceptCXX>> are very good resources and
  65 should also cover template programming in sufficient detail to work on the
  66 FreeFOAM code base. If you want to know the ins and outs of {cpp} templates,
  67 refer to <<CXXTemplates>> and to get an inkling of all the fancy stuff you can
  68 do with them, read <<CXXMeta>>.
  69
  70 Coding Practices and Style
  71 --------------------------
  72 Follow the instructions outlined in the file 'doc/codingStyleGuide.pdf'
  73 contained in the source distribution. Additionally, pay special attention to
  74 the following points:
  75
  76 * In general, lines shouldn't be longer than 80 characters and they *must* be
  77   terminated by a LF. Windows-style line endings (CR+LF) are not acceptable.
  78 * Indentation for {cpp} is 4 spaces, for Python code 3 or 2 spaces and
  79   CMake-code uses 2 spaces only. Never use tab characters (except where
  80   required by syntax).
  81 * Avoid trailing whitespace at all costs. It is considered to be a programming
  82   error. However, only remove it from existing code if you change that line
  83   anyways. Otherwise the version control log will be very noisy and the 'blame'
  84   operation useless.
  85 * Make sure that file and directory names differ not just in their
  86   capitalization. Also, for libraries a header name must be unique within the
  87   whole library, but preferably all file names are unique throughout the whole
  88   code base.
  89 * New applications must provide header documentation describing *all* available
  90   options and arguments. Also, there must be a brief description (1-2 lines
  91   maximum) and an extended, informative description. Somebody reading it should
  92   know what to expect from this application without having to read its whole
  93   code.
  94 * New applications must provide a tutorial case that can be run as a basic
  95   test to ensure that it runs (although, without checking the validity of the
  96   results).
  97 * New CMake-Modules and functions must be documented using a header comment.
  98
  99 Merging Guide
 100 -------------
 101 These are notes mainly concerning the FreeFOAM maintainers performing the
 102 merges with the upstream repository (currently, that is me). Other may find
 103 this informative, though, and I realized that I need a checklist...
 104
 105 * Create a clone on a case-sensitive file system and check out the upstream
 106   tracking branch 'upstream/OpenFOAM-1.7.x' and +git pull+.
 107 * Check out the branch with the unified history, 'upstream/OpenFOAM' and merge
 108   in the versioned upstream branch.
 109 * Get an overview of what has been added and removed using
 110   +git show -m --name-status --no-renames --diff-filter=AD+. Of special
 111   interest are 'wmake' related files, new or removed sources, new scripts in
 112   'bin', added or removed libraries, applications and tutorials.
 113 * Check out the branch you want to merge into (usually that is 'pu') and merge
 114   with 'upstream/OpenFOAM'. There will be many merge conflicts.
 115 * Use the following checklist while merging:
 116   - Changes to 'Make/files' usually only map to the corresponding 'files.cmake'
 117     file. New source files are added to the 'SRCS' list.
 118   - New source and header files ('.C' and '.H') belonging to a library that
 119     are not mentioned in the 'Make/files' file must be added to the 'HDRS'
 120     list. This usually is not reflected by a conflict!
 121   - New link libraries added in 'Make/options' should be ported to the
 122     'CMakeLists.txt' file. New include directories should only be ported if
 123     they are 'relative includes'.
 124   - Check the 'diff' of all modified/added source files for '#include'
 125     directives. Find whether the included file belongs to a library and if so,
 126     change the '#include "header.H"' to '#include <libname/header.H>'.
 127   - Add modelines to added files.
 128   - Complete/fix the header comment of new applications.
 129   - Usually, changes inside the 'wmake' directory can be discarded.
 130   - More often than not, added scripts in 'bin' are useless to the FreeFOAM
 131     project. If not, port the script to Python if it is to be distributed in a
 132     binary package.
 133   - Newly added tutorials must be furnished with their own 'CMakeLists.txt'
 134     file and a new +add_subdirectory+ call needs to be added. Port new 'Allrun'
 135     and 'Allclean' scripts to a 'Allrun.py.in' script.
 136
 137 Release Guide
 138 -------------
 139 The following lists things to remember when creating a new release.
 140
 141 * Update 'ChangeLog', 'ReleaseNotes', 'README' and 'INSTALL'.
 142 * Update version information in 'CMakeLists.txt' and
 143   'data/asciidoc/common.conf'.
 144 * Update the copyright date in all files.
 145 * Use the 'data/utilities/foamPackSource' script to create a new, signed tag,
 146   create a tar-ball with an external signature and check-sum files.
 147
 148 Bibliography
 149 ------------
 150 [bibliography]
 151 * [[[ProGit]]] Scott Chacon. http://progit.org/['Pro Git']. Apress 2009.
 152   ISBN http://isbndb.com/search-all.html?kw=1-430-21833-9[1-430-21833-9].
 153 * [[[GitCommBook]]] Scott Chacon and many others.
 154   http://book.git-scm.com['The Git Community Book'].
 155 * [[[VCGit]]] Jon Loeliger. 'Version Control with Git'. O'Reilly 2009.
 156   ISBN http://isbndb.com/search-all.html?kw=0-596-52012-3[0-596-52012-3].
 157 * [[[MasteringCMake]]] Ken Martin, Bill Hoffman. 'Mastering CMake'.
 158   Kitware Inc. 2010.
 159   ISBN http://isbndb.com/search-all.html?kw=1-930-93422-X[1-930-93422-X]
 160 * [[[EffCXX]]] Scott Meyers. 'Effective {cpp}'. Addison-Wesley 2005.
 161   ISBN http://isbndb.com/search-all.html?kw=0-321-33487-6[0-321-33487-6].
 162 * [[[ExceptCXX]]] Herb Sutter. 'Exceptional {cpp}'. Addison-Wesley 2000.
 163   ISBN http://isbndb.com/search-all.html?kw=0-201-61562-2[0-201-61562-2].
 164 * [[[CXXTemplates]]] David Vandevoorde, Nicolai M. Josutis.
 165   '{cpp} Templates - The Complete Guide'. Addison-Wesley 2003.
 166   ISBN http://isbndb.com/search-all.html?kw=0-201-73484-2[0-201-73484-2].
 167 * [[[CXXMeta]]] David Abrahams
 168   David Abrahams, Aleksey Gurtovoy. '{cpp} Template Metaprogramming: Concepts,
 169   Tools, and Techniques from Boost and Beyond'. Addison-Wesley 2005.
 170   ISBN http://isbndb.com/search-all.html?kw=0-321-22725-5[0-321-22725-5]
 171
 172 ////////////////////////////////////////////////////////////////////
 173 Process with: asciidoc -a toc -f data/asciidoc/html.conf HACKING
 174
 175 Vim users, this is for you:
 176 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
 177 ////////////////////////////////////////////////////////////////////