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 3 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 Setting Up a Testing Dashboard
 100 ------------------------------
 101 To continually ensure that FreeFOAM builds cleanly and that all tutorial cases
 102 are runnable, FreeFOAM uses CTest which is part of CMake. The build and test
 103 results are submitted to a CDash server, which collects the data and displays
 104 it on a web-page. The following instructions will briefly line out how to set
 105 up your own dashboard client which submits the results to the FreeFOAM CDash
 106 server.
 107
 108 * Create the dashboard root directory, e.g. '$HOME/dashboards' and checkout the
 109   'dashboard' branch from the GIT repository:
 110 +
 111 ...........
 112 $ git clone -b dashboard git://repo.or.cz/freefoam.git $HOME/dashboards/scripts
 113 ...........
 114
 115 *  Create a file in the '$HOME/dashboards/scripts' directory, say
 116    'my_dashboard.cmake', with code of the following form:
 117 +
 118 ...........
 119 # Client maintainer: me@mydomain.net
 120 set(CTEST_SITE "machine.site")
 121 set(CTEST_BUILD_NAME "Branch-Platform-Compiler-Python")
 122 set(CTEST_BUILD_CONFIGURATION Debug)
 123 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
 124
 125 set(CMAKE_C_COMPILER /usr/bin/gcc)
 126 set(CMAKE_CXX_COMPILER /usr/bin/g++)
 127 set(PYTHON_EXECUTABLE /usr/bin/python)
 128 set(PYTHON2_EXECUTABLE /usr/bin/python)
 129
 130 include(${CTEST_SCRIPT_DIRECTORY}/foamDashboardCommon.cmake)
 131 ...........
 132
 133 * Then create a scheduled job to run that script. On Unix-like systems you can
 134   do so using the command `crontab -e` which should pop up a text editor where
 135   you can enter something like the following:
 136 +
 137 ...........
 138 #min hour dom mon dow command
 139 05   00   *   *   *   /usr/bin/ctest \
 140   -S ~/dashboards/scripts/my_dashboard.cmake -VV \
 141   > ~/dashboards/tests/my_dashboard.log 2>&1
 142 ...........
 143 +
 144 which will run the 'my_dashboard.cmake' script every day at 00:05. If not
 145 otherwise configured, the source and build trees will be placed in the
 146 directory '../tests', relative to the directory containing the script running
 147 the tests (i.e. '$HOME/dashboards/tests' using above example paths)
 148
 149 * For more configuration options, refer to the documentation comments in the
 150   'foamDashboardCommon.cmake' file. An online copy can be found
 151   http://repo.or.cz/w/freefoam.git/blob/refs/heads/dashboard:/foamDashboardCommon.cmake[here].
 152
 153 Merging Guide
 154 -------------
 155 These are notes mainly concerning the FreeFOAM maintainers performing the
 156 merges with the upstream repository (currently, that is me). Other may find
 157 this informative, though, and I realized that I need a checklist...
 158
 159 * Create a clone on a case-sensitive file system and check out the upstream
 160   tracking branch 'upstream/OpenFOAM-1.7.x' and +git pull+.
 161 * Check out the branch with the unified history, 'upstream/OpenFOAM' and merge
 162   in the versioned upstream branch.
 163 * Get an overview of what has been added and removed using
 164   +git show -m --name-status --no-renames --diff-filter=AD+. Of special
 165   interest are 'wmake' related files, new or removed sources, new scripts in
 166   'bin', added or removed libraries, applications and tutorials.
 167 * Check out the branch you want to merge into (usually that is 'pu') and merge
 168   with 'upstream/OpenFOAM'. There will be many merge conflicts.
 169 * Use the following checklist while merging:
 170   - Changes to 'Make/files' usually only map to the corresponding 'files.cmake'
 171     file. New source files are added to the 'SRCS' list.
 172   - New source and header files ('.C' and '.H') belonging to a library that
 173     are not mentioned in the 'Make/files' file must be added to the 'HDRS'
 174     list. This usually is not reflected by a conflict!
 175   - New link libraries added in 'Make/options' should be ported to the
 176     'CMakeLists.txt' file. New include directories should only be ported if
 177     they are 'relative includes'.
 178   - Check the 'diff' of all modified/added source files for '#include'
 179     directives. Find whether the included file belongs to a library and if so,
 180     change the '#include "header.H"' to '#include <libname/header.H>'.
 181   - Add modelines to added files.
 182   - Complete/fix the header comment of new applications.
 183   - Usually, changes inside the 'wmake' directory can be discarded.
 184   - More often than not, added scripts in 'bin' are useless to the FreeFOAM
 185     project. If not, port the script to Python if it is to be distributed in a
 186     binary package.
 187   - Newly added tutorials must be furnished with their own 'CMakeLists.txt'
 188     file and a new +add_subdirectory+ call needs to be added. Port new 'Allrun'
 189     and 'Allclean' scripts to a 'Allrun.py.in' script.
 190
 191 Release Guide
 192 -------------
 193 The following lists things to remember when creating a new release.
 194
 195 * Update 'ChangeLog', 'ReleaseNotes', 'README' and 'INSTALL'.
 196 * Update version information in 'CMakeLists.txt' and
 197   'data/asciidoc/common.conf'.
 198 * Update the copyright date in all files.
 199 * Use the 'data/utilities/foamPackSource' script to create a new, signed tag,
 200   create a tar-ball with an external signature and check-sum files.
 201
 202 Bibliography
 203 ------------
 204 [bibliography]
 205 * [[[ProGit]]] Scott Chacon. http://progit.org/['Pro Git']. Apress 2009.
 206   ISBN http://isbndb.com/search-all.html?kw=1-430-21833-9[1-430-21833-9].
 207 * [[[GitCommBook]]] Scott Chacon and many others.
 208   http://book.git-scm.com['The Git Community Book'].
 209 * [[[VCGit]]] Jon Loeliger. 'Version Control with Git'. O'Reilly 2009.
 210   ISBN http://isbndb.com/search-all.html?kw=0-596-52012-3[0-596-52012-3].
 211 * [[[MasteringCMake]]] Ken Martin, Bill Hoffman. 'Mastering CMake'.
 212   Kitware Inc. 2010.
 213   ISBN http://isbndb.com/search-all.html?kw=1-930-93422-X[1-930-93422-X]
 214 * [[[EffCXX]]] Scott Meyers. 'Effective {cpp}'. Addison-Wesley 2005.
 215   ISBN http://isbndb.com/search-all.html?kw=0-321-33487-6[0-321-33487-6].
 216 * [[[ExceptCXX]]] Herb Sutter. 'Exceptional {cpp}'. Addison-Wesley 2000.
 217   ISBN http://isbndb.com/search-all.html?kw=0-201-61562-2[0-201-61562-2].
 218 * [[[CXXTemplates]]] David Vandevoorde, Nicolai M. Josutis.
 219   '{cpp} Templates - The Complete Guide'. Addison-Wesley 2003.
 220   ISBN http://isbndb.com/search-all.html?kw=0-201-73484-2[0-201-73484-2].
 221 * [[[CXXMeta]]] David Abrahams
 222   David Abrahams, Aleksey Gurtovoy. '{cpp} Template Metaprogramming: Concepts,
 223   Tools, and Techniques from Boost and Beyond'. Addison-Wesley 2005.
 224   ISBN http://isbndb.com/search-all.html?kw=0-321-22725-5[0-321-22725-5]
 225
 226 ////////////////////////////////////////////////////////////////////
 227 Process with: asciidoc -a toc -f data/asciidoc/html.conf HACKING
 228
 229 Vim users, this is for you:
 230 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
 231 ////////////////////////////////////////////////////////////////////