ENH: Updated FreeFOAM ascii-art in template-files
[freefoam.git] / README
blob4b1690b5e00688c93f7902710a595a3c6af8ac2a
1 :ver: 0.1.0
3 FreeFOAM README for version {ver}
4 =================================
5 Michael Wild <themiwi@users.sourceforge.net>
6 v{ver}, 23 Mar 2009
7 :Author Initials: MW
8 :linkcss!:
9 :numbered:
10 :toc:
11 http://freefoam.sourceforge.net
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.
21 System requirements
22 -------------------
23 FreeFOAM is developed and tested on Linux, but should work with other Unix style
24 systems, notably Mac OS X (C). The support for Microsoft Windows is a goal,
25 which, however, is still far off.
27 Required software to build FreeFOAM
28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29 [[git]]git::
30   Currently you need git to obtain the FreeFOAM source code. http://git.or.cz
31 [[cmake]]CMake::
32   In order to build FreeFOAM you need to have CMake with version 2.6.2 or
33   newer installed. http://cmake.org
34 [[build_system]]Build system::
35   CMake requires a native build system. On Unix like platforms GNU Make is
36   recommended. http://www.gnu.org/software/make
37 [[cxx_compiler]]C++ compiler::
38   In order to build FreeFOAM you need a C\++ compiler with good support for
39   template expressions. The g++ compiler from GCC-4.3 and above will do
40   fine. http://gcc.gnu.org
41 [[flex]]flex::
42   The flex lexer generator. Version 2.5.33 is known to work. For more recent
43   versions there have been reports of problems. http://flex.sourceforge.net
44 [[zlib]]zlib::
45   zlib compression library. http://www.zlib.net
46 [[metis]]METIS::
47   The METIS graph partitioning library, version 5.0pre2. If your package manager
48   doesn't contain it, you can also have FreeFOAM build it automatically for you
49   (see the <<installation,installation section>>).
50   http://glaros.dtc.umn.edu/gkhome/metis/metis/overview
52 Optional software
53 ~~~~~~~~~~~~~~~~~
54 [[parlib]]Parallel Communications Library::
55   In order to run FreeFOAM in parallel, a communications library is required.
56   The following list gives an overview of the available options:
57   - MPI (_Message Passing Interface_): There are many implementations of the MPI
58     standard. The one that has been tested and is known to work with FreeFOAM
59     is http://www.open-mpi.org[OpenMPI].
60   - PVM (_Parallel Virtual Machine_) is available from
61     http://www.csm.ornl.gov/pvm.
62   - GAMMA (_Genoa Active Message MAchine_) is available from
63     http://www.disi.unige.it/project/gamma.
64 [[parmetis]]ParMetis::
65   If you use an MPI library, the ParMetis library is required. If your package
66   manager doesn't contain this library, FreeFOAM can build it automatically for
67   you (refer to the <<installation,installation notes>> below).
68   http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview
69 [[mgridgen]]MGRIDGEN::
70   MGRIDGEN is a grid coarsening library for multi-grid solvers. FreeFOAM can
71   build this automatically for you (refer to the installation notes below).
72   http://glaros.dtc.umn.edu/gkhome/mgridgen/overview
74 [WARNING]
75 The license of 'MGRIDGEN' and 'PARMGRIDGEN' is unknown and the upstream authors
76 so far have not answered any inquiries to resolve the issue. If you enable the
77 use of 'MGRIDGEN' and 'PARMGRIDGEN' you alone are responsible for ensuring that
78 you don't violate any license conditions applying to these libraries. The
79 authors of FreeFOAM will and cannot take any responsibility for your
80 actions.
82 [[libccmio]]libccmio::
83   pro-STAR (C) input/output library. FreeFOAM can build this automatically for
84   you (refer to the <<installation,installation notes>> below).
85   https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz
87 [WARNING]
88 The license of 'libccmio' (C) is proprietary and requires the consent of the
89 copyright holders (http://www.cd-adapco.com[CD-adapco]) to download and use the
90 library. Further it is not allowed to redistribute it in any form. The request
91 for permission of inclusion with http://debian.org[Debian] was answered as
92 follows by mailto:geoffrey.prewett@us.cd-adapco.com[Geoffrey Prewett]:
94 --------------------------------------------------------------------------------
95 Gerber,
97 Sorry for the delay in response.  I checked back with our development director,
98 and he felt that it would be best to not include libccmio with Debian.
99 Instead, we would prefer to continue our current policy and keep it on our
100 web/FTP and have people ask for it.  There are three reasons for this:
102 1) We don't support STAR on Debian, and don't want to give the impression that we do.
103 2) We would like to keep a list of people that we give the library to.
104 3) This is not a general purpose library;  its sole purpose is to communicate
105 between our products.  Accepting outside changes risks committing a change that
106 would break our own software in possibly subtle ways.
108 So I regret to tell you that my company has declined to permit libccmio to be
109 distributed as part of Debian.
111 Regards,
112 Geoff Prewett
113 --------------------------------------------------------------------------------
115 [[paraview]]ParaView::
116   If you want to build the http://paraview.org[ParaView] plug-ins, you need a
117   ParaView with the development headers *and* the corresponding CMake configuration
118   files ('ParaViewConfig.cmake', 'ParaViewUse.cmake', 'ParaViewLibraryDepends*.cmake').
119   Most likely this means that you have to build ParaView yourself.
120   http://paraview.org
121 [[m4]]M4::
122   Some of the provided tutorial cases require the M4 macro processor.
123   http://www.gnu.org/software/m4/
124 [[doxygen]]Doxygen::
125   Automatic API-documentation generator. Required to build the source
126   documentation. http://www.doxygen.org
128 [[installation]]
129 Installation
130 ------------
131 This section needs serious expanding, but the short version is:
133 - Install the prerequisites. If your distribution does not have 'METIS',
134   'ParMetis', 'MGRIDGEN' or 'libccmio' be not worried, FreeFOAM can handle
135   those for you.
136 - Clone the FreeFOAM repository (here the clone is placed in
137   +$HOME/Source/FreeFOAM+):
139 ---------------------------------------------------------------------------
140 $ mkdir -p $HOME/Source
141 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM
142 ---------------------------------------------------------------------------
143 - Create a build tree and _cd_ into it:
145 ---------------
146 $ mkdir $HOME/Source/FreeFOAM-build
147 $ cd $HOME/Source/FreeFOAM-build
148 ---------------
149 - Start CMake-configuration:
151 ---------------
152 $ ccmake ../FreeFOAM
153 ---------------
154 - Press the +c+ key. Use the arrow keys to navigate up and down and press
155   +enter+ to edit a field. To commit the change, press +enter+ again, or +ESC+
156   to abandon the change.  ON/OFF fields are toggled by pressing +enter+.
157   Advanced options can be displayed by hitting the +t+ key.
158   * Set +CMAKE_BUILD_TYPE+ to 'Release' for an optimized build.
159   * If CMake complains that it can't find MPI, and you don't want to install it, disable
160     +FF_USE_MPI+. If, instead, you want to use GAMMA or PVM, enable +FF_USE_GAMMA+ or
161     +FF_USE_PVM+, respectively. You can also enable more than one of the options.
163 [NOTE]
164 Currently only MPI implementation is available.
166   * Select the default Pstream implementation by setting +FF_DEFAULT_PSTREAM+
167     to one of 'dummy', 'mpi', 'pvm' or 'gamma'. This setting will only influence
168     the contents of the <<globalconfig,global 'controlDict' file>>.
169   * If CMake told you it couldn't find ParaView:
170     . Set +ParaView_DIR+ to the path of the directory containing
171     'ParaViewConfig.cmake', which is most likely the ParaView build directory.
172     . If you do not want to build the ParaView plug-ins, disable
173     +FF_BUILD_PARAVIEW_PLUGINS+
174   * If you do not have 'METIS' or 'ParMetis', enable
175     +FF_BUILD_PRIVATE_METIS+ or +FF_BUILD_PRIVATE_PARMETIS+, respectively.
176     CMake will then try to download and build the selected libraries for you.
177     Conversely, if one of the libraries is provided by your system, you can turn
178     the respective setting to 'OFF'. Please note that if your system provides
179     only 'ParMetis', you do not have to install 'METIS', as the former also
180     contains 'METIS' in an older version.
181   * If you want to use the 'MGridGen' agglomeration method for the GAMG solver,
182     you need to enable +FF_ENABLE_PARMGRIDGEN+ and if the library is not
183     installed on your system ensure that +FF_BUILD_PRIVATE_PARMGRIDGEN+ is
184     enabled. See <<parmgridgen,above>> regarding the unknown license status of
185     this package.
186   * In order to build 'ccm26ToFoam', a conversion utility for grids generated
187     with 'ProStar/ccm' (C) version 2.6, enable the setting +FF_ENABLE_CCMIO+
188     and if 'libccmio' is not installed on your system, also
189     +FF_BUILD_PRIVATE_CCMIO+.  Refer to the <<libccmio,above>> description of
190     the 'libccmio' package for the license restrictions which apply to this
191     package.
192   * If you plan on installing FreeFOAM, set +CMAKE_INSTALL_PREFIX+ to the base directory
193     under which FreeFOAM should reside.
194   * For more fine-grained control over what gets installed where, adjust
195     +FF_INSTALL_CONFIG_PATH+, +FF_INSTALL_HEADER_PATH+, +FF_INSTALL_LIB_PATH+,
196     +FF_INSTALL_FRAMEWORK_PATH+, +FF_INSTALL_PV3FOAMREADER_PATH+,
197     +FF_INSTALL_PVFOAMREADER_PATH+ and +FF_INSTALL_USERDFOAM_PATH+. Paths not
198     starting with a slash ('/') will be relative to 'CMAKE_INSTALL_PREFIX'. If
199     you include a leading slash, the paths are absolute.
200   * If you want FreeFOAM to use 'float' as the floating point type instead of
201     'double', change +FF_DOUBLE_PRECISION+ to 'OFF'.
202 - Hit the +c+ key again. If you enabled +FF_BUILD_PRIVATE_CCMIO+, CMake will fail
203   to download https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz.
204   Please follow the instructions in the error message on how to work around this
205   problem, or download the file manually and place it in +ThirdParty/ccmio/+
206   (relative to the build directory). Then hit +c+ again.
207 - You shouldn't get any errors anymore now. Keep pressing +c+ until ccmake
208   displays "++Press [g] to generate and exit++" in the legend at the bottom of
209   the interface.
210 - Press +g+ to generate the Makefiles and exit the ccmake interface.
211 - Start the native build tool. If you used the 'Makefile' generator
212   (which is the default for Unix-platforms), type
214 ----------------
215 $ make
216 ----------------
217 - If you have a multi-core/processor machine, you can speed things up
218   significantly by telling Make to run independent jobs in parallel.
219   A good choice for the number of parallel jobs to run is the
220   number of CPU's/cores you have in your machine plus 1 (to compensate
221   for disk-latency). For a typical dual-core machine, run
223 ----------------
224 $ make -j3
225 ----------------
226 - If you want to, you can now install FreeFOAM (depending on the
227   +CMAKE_INSTALL_PREFIX+ and the individual +FF_INSTALL_*_PATH+
228   it is possible that you have to do this as root, i.e. use
229   +su+ or +sudo+).
231 ---------------
232 $ make install
233 ---------------
235 Using FreeFOAM
236 ~~~~~~~~~~~~~~
238 If you didn't change +CMAKE_INSTALL_PREFIX+ and +FF_INSTALL_BIN_PATH+ chances
239 are that you can start using FreeFOAM right after you installed it without any
240 further steps being necessary.
242 [[globalconfig]]
243 Global Configuration Files
244 ^^^^^^^^^^^^^^^^^^^^^^^^^^
245 Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
246 applications require some files to be present for start-up. It finds those
247 in the following places (in the specified order, picking the first hit):
249 1. Under the directory specified in the +$FREEFOAM_CONFIG_DIR+ environment
250    variable
251 2. In '$HOME/.FreeFOAM/{ver}'
252 3. In '$HOME/.FreeFOAM'
253 4. In the installation directory of the configuration files. There are
254    two possible places for this:
256    '<CMAKE_INSTALL_PREFIX>/<FF_INSTALL_CONFIG_PATH>':: if you specified
257      +<FF_INSTALL_CONFIG_PATH>+ as a relative path.
258     '<FF_INSTALL_CONFIG_PATH>':: if you specified +<FF_INSTALL_CONFIG_PATH>+ as
259     an absolute path.
261 The default location is '/usr/local/etc/FreeFOAM/1.0'.
263 Selecting the Parallel Communications Library
264 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
265 Both, FreeFOAM and OpenFOAM abstract the parallel operations into the 'Pstream'
266 library, making it rather simple to firstly switch between parallel
267 implementations and secondly port the software to a new communications library.
268 However, FreeFOAM uses a much more flexible mechanism of determining which
269 'Pstream' implementation library to use than OpenFOAM. The latter does this by
270 adjusting the +LD_LIBRARY_PATH+ environment variable.  As FreeFOAM wants to be a
271 well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically
272 loads the desired 'Pstream' library at startup (i.e. as a plug-in).  The
273 following list details how FreeFOAM determines what library to load (if at all):
275 1. If the environment variable +FREEFOAM_PSTREAM_LIBRARY+ is set,
276    FreeFOAM will try to load the library specified by it.
277 2. If the sub-dictionary +PstreamImplementation+ exists in the global
278    'controlDict' file (see <<globalconfig,'Global Configuration Files'>>), it
279    reads the value of the entry +configName+ therein. It then expects that a
280    sub-dictionary of +PstreamImplementation+ with the name specified in
281    +configName+ exists. If that sub-dictionary contains the entry +library+, it
282    will try to load a library specified by the value of that entry.
284 After FreeFOAM (possibly) loaded the library, it will try to instantiate
285 concrete implementations of the abstract base classes +PstreamImpl+,
286 +IPstreamImpl+ and +OPstreamImpl+. Which classes are to be instantiated
287 is determined as follows:
289 1. FreeFOAM queries the environment variables +FREEFOAM_PSTREAM_CLASS+,
290    +FREEFOAM_IPSTREAM_CLASS+ and +FREEFOAM_OPSTREAM_CLASS+ for the class
291    names to be instantiated.
292 2. For any of the variables not set,  it requires the sub-dictionary
293    +PstreamImplementation+ to be present in the global 'controlDict', reads the
294    value of +configName+ and similarly to the library loading, loads the
295    sub-dictionary specified by that value. It then expects to find the entries
296    +Pstream+, +IPstream+ and +OPstream+ which specify the names of the classes
297    to load.
299 This means that one can create a global 'controlDict' file containing
300 (among other things) something like the following:
301 =========
302 ---------
303 PstreamImplementation
305     //configName dummy;
306     configName mpi;
308     dummy
309     {
310         library libdummyPstream.so;
311         Pstream dummyPstreamImpl;
312         OPstream dummyOPstreamImpl;
313         IPstream dummyIPstreamImpl;
314     }
316     mpi
317     {
318         library libmpiPstream.so;
319         Pstream mpiPstreamImpl;
320         OPstream mpiOPstreamImpl;
321         IPstream mpiIPstreamImpl;
322     }
324 ---------
325 =========
327 This way the administrator can provide a global 'controlDict' in the FreeFOAM
328 installation. Every user can then override that 'controlDict' by supplying her
329 own file in her home directory as detailed in <<globalconfig,'Global
330 Configuration Files'>>. In order to select a particular 'Pstream' implementation
331 for a specific communications library, the user can then either adjust the
332 +PstreamImplementation::configName+ entry in the global 'controlDict' file, set
333 the +FREEFOAM_PSTREAM_CONFIG+ variable or for full control, set the variables
334 +FREEFOAM_PSTREAM_LIBRARY+, +FREEFOAM_PSTREAM_CLASS+, +FREEFOAM_IPSTREAM_CLASS+
335 and +FREEFOAM_OPSTREAM_CLASS+.
337 Running FreeFOAM From the Build Tree
338 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
339 You can use FreeFOAM without installing it first, directly from the build tree.
340 However, this might take a little bit more effort to set up because most likely
341 you will have to adjust the following environment variables:
343 PATH:: Must contain '$HOME/Source/FreeFOAM-build/bin'
344 LD_LIBRARY_PATH:: Must contain '$HOME/Source/FreeFOAM-build/lib'
345 FREEFOAM_CONFIG_DIR:: Should point to '$HOME/Source/FreeFOAM-build/etc'
347 Where it is assumed that you followed the <<installation,installation instructions>>. If
348 you used different paths for downloading and compiling FreeFOAM, you will have
349 to adjust these names. Refer to <<environment,'Extending Search Paths And
350 Setting Environment Variables Permanently'>> if you need help setting these
351 variables.
353 Running the tutorials
354 ~~~~~~~~~~~~~~~~~~~~~
355 Now you should be able to run the tutorial cases. For this copy the +tutorials+
356 directory to some convenient place:
357 ---------------
358 $ mkdir -p $HOME/FreeFOAM/$LOGNAME-0.1.0/run
359 $ cp -r $HOME/Source/FreeFOAM-build/tutorials $HOME/FreeFOAM/$LOGNAME-0.1.0/run/
360 $ cd $HOME/FreeFOAM/$LOGNAME-0.1.0/run
361 ---------------
362 And try to run e.g. the 'cavity' tutorial case:
363 ---------------
364 $ cd icoFoam
365 $ blockMesh -case cavity
366 $ checkMesh -case cavity
367 $ icoFoam -case cavity
368 ---------------
369 Things should run smoothly and finish without an error.
371 Build Configuration Reference
372 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
373 [glossary]
374 +CMAKE_BUILD_TYPE+::
375   One of '<empty>', 'Debug', 'Release', 'RelWithDebInfo' and 'MinSizeRel'.
376   Refer to the CMake documentation for more detail.
377 +FF_DOUBLE_PRECISION+::
378   If set to 'ON' FreeFOAM will be compiled using 'double' as the
379   floating point type. If set to 'OFF' it will use 'float'.
380 +FF_BUILD_FRAMEWORK+::
381   If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
382 +CMAKE_INSTALL_PREFIX+::
383   Installation prefix under which to install FreeFOAM.
384 +FF_INSTALL_BIN_PATH+::
385   Installation path of the binaries. If not absolute, it is relative to
386   'CMAKE_INSTALL_PREFIX'.
387 +FF_INSTALL_CONFIG_PATH+::
388   Installation path of the configuration files. If not absolute, it is
389   relative to 'CMAKE_INSTALL_PREFIX'.
390 +FF_INSTALL_HEADER_PATH+::
391   Installation path of the header files. If not absolute, it is
392   relative to 'CMAKE_INSTALL_PREFIX'. On Mac OS X, and if
393   'FF_BUILD_FRAMEWORK' is enabled, this setting is ignored.
394 +FF_INSTALL_LIB_PATH+::
395   Installation path of the libraries. If not absolute, it is
396   relative to 'CMAKE_INSTALL_PREFIX'.
397 +FF_INSTALL_FRAMEWORK_PATH+::
398   Installation path of the Mac OS X frameworks. If not absolute, it is
399   relative to 'CMAKE_INSTALL_PREFIX'. This is only available and takes
400   effect if FreeFOAM is compiled on Mac OS X, and if
401   'FF_BUILD_FRAMEWORK' is enabled.
402 +FF_INSTALL_PV3FOAMREADER_PATH+::
403   Installation path of the ParaView3 plug-ins. If not absolute, it is
404   relative to 'CMAKE_INSTALL_PREFIX'.
405 +FF_INSTALL_PVFOAMREADER_PATH+::
406   Installation path of the ParaView2 plug-ins. If not absolute, it is
407   relative to 'CMAKE_INSTALL_PREFIX'.
408 +FF_INSTALL_USERDFOAM_PATH+::
409   Installation path of the Ensight plug-in. If not absolute, it is
410   relative to 'CMAKE_INSTALL_PREFIX'.
411 +EXECUTABLE_PREFIX+::
412   Prefix which get prepended to the name of the executables. This defaults to
413   'ff_' and serves the disambiguation of names.
414 +FF_USE_GAMMA+::
415   If enabled, FreeFOAM will use the GAMMA parallel communications library.
416 +FF_USE_MPI+::
417   If enabled, FreeFOAM will use the MPI parallel communications library.
418   This is required in order to build some of the libraries and utilities.
419 +FF_USE_PVM+::
420   If enabled, FreeFOAM will use the PVM parallel communications library.
421 +FF_DEFAULT_PSTREAM+::
422   The default Pstream selection in the global 'controlDict' file.
423 +FF_BUILD_PARAVIEW_PLUGINS+::
424   Whether to build the ParaView plug-ins. If enabled, FreeFOAM requires a
425   ParaView build tree and the 'ParaView_DIR' variable set to the path of it.
426 +FF_ENABLE_CCMIO+::
427   Enable the use of 'libccmio'. This is required to build the grid conversion
428   utility 'ccm26ToFoam'. Note that you need the permission of the copyright
429   holders (http://cd-adapco.com[CD-adapco]) to download, build and use the
430   library. Refer to the <<libccmio,description>> of the package for the
431   details.
432 +FF_BUILD_PRIVATE_CCMIO+::
433   Automatically download and build libccmio. Unfortunately this process will
434   fail in the download step, since CMake currently does not support 'https'
435   URLs. But you will get specific instructions from the build system on how to
436   get around this problem.
437 +FF_BUILD_PRIVATE_METIS+::
438   Automatically download and build 'METIS'.
439 +FF_BUILD_PRIVATE_PARMETIS+::
440   Automatically download and build 'ParMetis'.
441 +FF_ENABLE_PARMGRIDGEN+::
442   Enable the use of 'PARMGRIDGEN' and 'MGRIDGEN' which is required to build
443   'MGridGenGamgAgglomeration' providing the 'MGridGen' agglomeration method for
444   the GAMG solver. Be aware that if you use these libraries, that you alone are
445   responsible to comply with the license restrictions associated with them.
446   Refer to the <<parmgridgen,description>> of the package for more information.
447 +FF_BUILD_PRIVATE_PARMGRIDGEN+::
448   Automatically download and build 'PARMGRIDGEN' and 'MGRIDGEN'.
449 +FF_BUILD_DOXYGEN_DOCS+::
450   Enable building of the 'Doxygen API documentation'. The documentation will
451   only be built once and is not updated automatically. This is because it
452   depends on a huge number of files and would make dependency tracking very
453   slow and difficult to maintain. To force the re-generation of the API
454   documentation execute +make apidoc+.
456 Documentation
457 -------------
458 http://freefoam.sourceforge.net/doc/Doxygen/html
460 Help
461 ----
462 - http://freefoam.sourceforge.net
463 - https://freefoam.wiki.sourceforge.net/MailingLists
464 - http://www.cfd-online.com/Forums/openfoam/ *please only ask questions related
465   to _OpenFOAM_ there*.
467 Reporting Bugs in FreeFOAM
468 --------------------------
469 https://sourceforge.net/tracker/?group_id=215833
471 Troubleshooting
472 ---------------
474 The FreeFOAM Executables Are Not Found By The Shell
475 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
476 There are three possible reasons for this:
478 1. Your shell (notably 'csh', 'tcsh' and 'zsh') requires you to refresh the
479    cache of available executables. You can do so by entering the command:
481 --------------
482 $ rehash
483 --------------
485 2. If 'rehashing' didn't solve the problem, the problem most likely is that you
486    installed FreeFOAM into a non-standard location by changing the configuration
487    variables +CMAKE_INSTALL_PREFIX+ or +FF_INSTALL_BIN_PATH+ in which case the
488    executables where installed into a directory not searched by the shell. In
489    this case you have to add the installation directory of the executables to
490    the +PATH+ variable. There are two possible locations:
493 '<CMAKE_INSTALL_PREFIX>/<FF_INSTALL_BIN_PATH>':: if you specified
494   +FF_INSTALL_BIN_PATH+ as a relative path
495 '<FF_INSTALL_BIN_PATH>':: if you specified +FF_INSTALL_BIN_PATH+ as an absolute
496   path
499 After extending the +PATH+ variable with the installation directory of the
500 executables, you should be able to run all FreeFOAM applications as any other
501 binary available on the system. See <<environment,'Extending Search Paths And
502 Setting Environment Variables Permanently'>> for
503 instructions on how to extend the search path.
505 3. This option is similar to the previous solution and applies if you want to
506    run FreeFOAM from the build tree (i.e. without running +make install+). In
507    this case you again have to make sure that your shell finds the executables
508    built by CMake by extending the +PATH+ variable. Further, you have to tell
509    FreeFOAM where to find the global configuration files (see
510    <<globalconfig,'Global Configuration Files'>>). Here, you have the option to
511    place the files under your home directory or set an environment variable. The
512    former can be achieved by:
514 --------------
515 $ mkdir -p $HOME/.FreeFOAM/0.1.0
516 $ cp $HOME/Source/FreeFOAM-build/etc/controlDict $HOME/.FreeFOAM/0.1.0
517 $ cp $HOME/Source/FreeFOAM-build/etc/cellModels $HOME/.FreeFOAM/0.1.0
518 $ cp -r $HOME/Source/FreeFOAM-build/etc/thermoData $HOME/.FreeFOAM/0.1.0
519 --------------
521 The latter (and recommended) method is to set the environment variable
522 +FREEFOAM_CONFIG_DIR+ to '$HOME/Source/FreeFOAM-build/etc'. Adjust paths to the
523 build tree to your actual setup.
525 Starting Any FreeFOAM Application Fails Because Some Libraries Cannot Be Found
526 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
527 Although CMake should have taken care of this by using +RPATH+ on Linux and
528 +install_name+ on Mac OS X, it might be necessary on some systems to adjust the
529 library search paths:
531 +LD_LIBRARY_PATH+:: This variable is used by all Unix like systems (e.g. Linux,
532   Mac OS X, etc.)
533 +DYLD_LIBRARY_PATH+:: This variable is used by Mac OS X.
535 If you installed FreeFOAM, there are (as with the executables), two possible
536 installation directories:
538 '<CMAKE_INSTALL_PREFIX>/<FF_INSTALL_LIB_PATH>':: if you specified
539   +FF_INSTALL_LIB_PATH+ as a relative path.
540 '<FF_INSTALL_LIB_PATH>':: if you specified +FF_INSTALL_LIB_PATH+ as an absolute
541   path.
543 If you are trying to run from the build tree, you have to include
544 '$HOME/Source/FreeFOAM-build/lib/FreeFOAM/0.1' in the above mentioned search
545 paths (where you have to adjust the location of the build tree to your actual
546 setup).
548 A Running FreeFOAM Application Aborts Because It Can't 'dlopen' A Library
549 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
550 FreeFOAM (and OpenFOAM) often dynamically load libraries at run-time (a.k.a
551 plug-ins) to add features the user requested without requiring that the whole
552 application be recompiled. This makes it very simple to add new boundary
553 conditions, turbulence and combustion models etc. However, it also requires that
554 FreeFOAM must be able to find these libraries at run-time. The operating system
555 function which does the loading of the libraries ('dlopen') usually tries to
556 find the library with the given name in several places; namely a default search
557 path and a search path configured by one or multiple environment variables such
558 as +LD_LIBRARY_PATH+ or +DYLD_LIBRARY_PATH+ (on Mac OS X). The details vary from
559 platform to platform, so you best consult the documentation of 'dlopen' for the
560 details.
562 Additionally FreeFOAM allows you to configure a custom search path for plug-ins
563 in the <<globalconfig,global 'controlDict'>> file by listing the directories to
564 be searched in the list +LibrarySearchPaths+. By default FreeFOAM is configured
565 to search for plug-ins in the location where CMake installed them.
567 If you want to add your own plug-in libraries (e.g. you want to add your own
568 boundary conditions class), you most probably will want to extend this search
569 path.
571 [[environment]]
572 Extending Search Paths And Setting Environment Variables Permanently
573 --------------------------------------------------------------------
574 The way one sets environment variables and extends the executable and library
575 search paths permanently strongly depends on the shell used. Usually one has to
576 create or change an initialization file in the users home directory. In the
577 following this will be discussed very briefly for the popular shells 'BASH' and
578 'tcsh'.  However, if you need more help or want information on using the shell,
579 there is an excellent tutorial available at http://linuxcommand.org.
581 BASH
582 ~~~~
583 The BASH shell is the default shell for most Linux/Unix distributions. Most
584 systems configure the BASH shell such that it reads the text file
585 '$HOME/.bashrc' when starting up, so this is the place where one appends
586 customizations of the environment variables. On some systems this file is not
587 processed by default (notably Mac OS X). In this case you can use
588 '$HOME/.bash_profile'.
590 Referencing A Variable
591 ^^^^^^^^^^^^^^^^^^^^^^
592 To retrieve the value stored in a shell variable or environment variable, one
593 prefixes its name with the dollar (+$+) character.
595 Setting A Variable
596 ^^^^^^^^^^^^^^^^^^
597 The syntax for setting a variable and making it available to child-processes of
598 the shell is the following:
599 -------
600 $ export variable_name=variable_value
601 -------
602 Note that no white-space characters are allowed surrounding the +=+ sign.
604 Extending A Search Path
605 ^^^^^^^^^^^^^^^^^^^^^^^
606 The shell and other Unix system facilities use environment variables to locate
607 executables and dynamically linked libraries. These search paths consist of
608 strings naming directories in which the executables and libraries should be
609 searched for. The individual paths are separated by a colon (+:+) character. To
610 add the e.g. the directory '$HOME/bin' to the search path for executables, one
611 would do the following:
612 -------
613 $ export PATH=$PATH:$HOME/bin
614 -------
615 which appends '$HOME/bin' to the end of the +PATH+ variable.
617 TCSH
618 ~~~~
619 Some users and administrators prefer to use a 'C-Shell', such as the TCSH. Here
620 you can use e.g. the file '$HOME/.tcshrc' to customize the environment.
622 Referencing A Variable
623 ^^^^^^^^^^^^^^^^^^^^^^
624 As with the BASH, one retrieves the value stored in a shell variable or
625 environment variable by prefixing its name with the dollar (+$+) character.
626 Sometimes it is also necessary to protect the variable name by surrounding it
627 with curly braces (+{+ and +}+).
629 Setting A Variable
630 ^^^^^^^^^^^^^^^^^^
631 The syntax for setting a variable and making it available to child-processes of
632 the shell is the following:
633 -------
634 $ setenv variable_name variable_value
635 -------
637 Extending A Search Path
638 ^^^^^^^^^^^^^^^^^^^^^^^
639 The shell and other Unix system facilities use environment variables to locate
640 executables and dynamically linked libraries. These search paths consist of
641 strings naming directories in which the executables and libraries should be
642 searched for. The individual paths are separated by a colon (+:+) character. To
643 add the e.g. the directory '$HOME/bin' to the search path for executables, one
644 would do the following:
645 -------
646 $ setenv PATH ${PATH}:${HOME}/bin
647 -------
648 which appends '$HOME/bin' to the end of the +PATH+ variable.  Note that
649 'C-shells' usually require the user to type 'rehash' after changing the +PATH+
650 variable to update the cache of available programs.
653 ////////////////////////////////////////////////////////
654 Process with: asciidoc README
656 Vim users, this is for you:
657 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
658 ////////////////////////////////////////////////////////