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