1 FreeFOAM Installation Instructions for Version {fullver}
2 ========================================================
3 Michael Wild <themiwi@users.sourceforge.net>
5 v{fullver}, {localdate}
6 http://freefoam.sourceforge.net
8 Obtaining the Prerequisites
9 ---------------------------
10 Some of the libraries FreeFOAM requires (or optionally can use) are often not
11 readily available as an installable package and are quite tricky to install
12 manually. FreeFOAM can automatically download and build these libraries for
13 you, refer to below instructions. However, if you are behinde a firewall or
14 CMake is unable to download a source package, you can do so manually and
15 place the files in the 'ThirdParty' directory in the FreeFOAM source tree. When
16 you run CMake, it will detect the presence of the files and not try to
19 You can obtain the source packages from the following URLs:
22 http://master.dl.sourceforge.net/project/freefoam/ThirdParty/zlib/zlib-1.2.5.tar.gz
24 http://glaros.dtc.umn.edu/gkhome/fetch/sw/metis/metis-5.0pre2.tar.gz
26 http://glaros.dtc.umn.edu/gkhome/fetch/sw/parmetis/ParMetis-3.1.tar.gz
28 http://master.dl.sourceforge.net/project/freefoam/ThirdParty/scotch/scotch_5.1.7.dfsg.orig.tar.gz
30 http://www-users.cs.umn.edu/~moulitsa/download/ParMGridGen-1.0.tar.gz
32 https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz
36 - Install the prerequisites documented in the link:README.html[README] file. If
37 your distribution does not have 'METIS', 'ParMetis', 'MGRIDGEN' or 'libccmio'
38 be not worried, FreeFOAM can handle those for you.
39 - Download the FreeFOAM source and unpack it somewhere convenient. For the
40 further instructions we will use +$HOME/Source/+.
42 ---------------------------------------------------------------------------
43 $ mkdir -p $HOME/Source
45 $ wget http://master.dl.sourceforge.net/sourceforge/freefoam/freefoam-{fullver}.tar.bz2
46 $ tar xjf freefoam-{fullver}.tar.bz2
47 ---------------------------------------------------------------------------
48 - Create a build tree and _cd_ into it:
51 $ mkdir $HOME/Source/freefoam-{fullver}-build
52 $ cd $HOME/Source/freefoam-{fullver}-build
54 - Start CMake-configuration:
57 $ ccmake $HOME/Source/freefoam-{fullver}
59 - Press the +c+ key. Use the arrow keys to navigate up and down and press
60 +enter+ to edit a field. To commit the change, press +enter+ again, or +ESC+
61 to abandon the change. ON/OFF fields are toggled by pressing +enter+.
62 Advanced options can be displayed by hitting the +t+ key.
63 * Set +CMAKE_BUILD_TYPE+ to 'Release' for an optimized build.
64 * If CMake complains that it can't find MPI, and you don't want to install
65 it, disable +FOAM_USE_MPI+.
66 * Select the default Pstream implementation by setting +FOAM_DEFAULT_PSTREAM+
67 to one of 'dummy' or 'mpi'. This setting will only influence the contents
68 of the <<globalconfig,global 'controlDict' file>>.
69 * If you want to use the 'metis' and 'parmetis' decomposition methods, make
70 sure that +FOAM_ENABLE_METIS+ and +FOAM_ENABLE_PARMETIS+ are enabled,
71 respectively. If you do not have 'METIS' or 'ParMetis' installed, enable
72 +FOAM_BUILD_PRIVATE_METIS+ or +FOAM_BUILD_PRIVATE_PARMETIS+, respectively.
73 CMake will then try to download and build the selected libraries for you.
74 Conversely, if one of the libraries is provided by your system, you can
75 turn the respective setting to 'OFF'. Please note that if your system
76 provides only 'ParMetis', you do not have to install 'METIS', as the former
77 also contains 'METIS' in an older version.
78 * If you want to use the 'MGridGen' agglomeration method for the GAMG solver,
79 you need to enable +FOAM_ENABLE_MGRIDGEN+ and if the library is not
80 installed on your system ensure that +FOAM_BUILD_PRIVATE_MGRIDGEN+ is
81 enabled. See <<enable-mgridgen,above>> regarding the unknown license status
83 * In order to build 'ccm26ToFoam', a conversion utility for grids generated
84 with 'ProStar/ccm' (C) version 2.6, enable the setting
85 +FOAM_ENABLE_CCMIO+ and if 'libccmio' is not installed on your system,
86 also +FOAM_BUILD_PRIVATE_CCMIO+. Refer to the <<enable-ccmio,above>>
87 description of the 'libccmio' package for the license restrictions which
88 apply to this package. If you decide to build a private version, please
89 read the description of <<private-ccmio,+FOAM_BUILD_PRIVATE_CCMIO>>
91 * If you plan on installing FreeFOAM, set +CMAKE_INSTALL_PREFIX+ to the base directory
92 under which FreeFOAM should reside.
93 * For more fine-grained control over what gets installed where, adjust
94 +FOAM_INSTALL_CONFIG_PATH+, +FOAM_INSTALL_HEADER_PATH+, +FOAM_INSTALL_LIBRARY_PATH+,
95 +FOAM_INSTALL_FRAMEWORK_PATH+, +FOAM_INSTALL_PVFOAMREADER_PATH+ and
96 +FOAM_INSTALL_USERDFOAM_PATH+. Paths not starting with a slash ('/') will
97 be relative to 'CMAKE_INSTALL_PREFIX'. If you include a leading slash, the
99 * If you want FreeFOAM to use 'float' as the floating point type instead of
100 'double', change +FOAM_DOUBLE_PRECISION+ to 'OFF'.
101 - Hit +c+ again. You shouldn't get any errors anymore now. Keep pressing +c+
102 until ccmake displays "++Press [g] to generate and exit++" in the legend at
103 the bottom of the interface.
104 - Press +g+ to generate the Makefiles and exit the ccmake interface.
105 - Start the native build tool. If you used the 'Makefile' generator
106 (which is the default for Unix-platforms), type
111 - If you have a multi-core/processor machine, you can speed things up
112 significantly by telling Make to run independent jobs in parallel.
113 A good choice for the number of parallel jobs to run is the
114 number of CPU's/cores you have in your machine plus 1 (to compensate
115 for disk-latency). For a typical dual-core machine, run
123 If you want to, you can now install FreeFOAM. Depending on the
124 +CMAKE_INSTALL_PREFIX+ and the individual +FOAM_INSTALL_*_PATH+ it is possible
125 that you have to do this as root, i.e. use +su+ or +sudo+.
132 If you didn't change +CMAKE_INSTALL_PREFIX+ and +FOAM_INSTALL_BIN_PATH+ chances
133 are that you can start using FreeFOAM right after you installed it without any
134 further steps being necessary.
137 Global Configuration Files
138 ~~~~~~~~~~~~~~~~~~~~~~~~~~
139 Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
140 applications require some files to be present for start-up. It finds those
141 in the following places (in the specified order, picking the first hit):
143 1. Under the directory specified in the +$FREEFOAM_CONFIG_DIR+ environment
145 2. In '$HOME/.FreeFOAM/{shortver}'
146 3. In '$HOME/.FreeFOAM'
147 4. In the installation directory of the configuration files. There are
148 two possible places for this:
150 '<CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_CONFIG_PATH>':: if you specified
151 +<FOAM_INSTALL_CONFIG_PATH>+ as a relative path.
152 '<FOAM_INSTALL_CONFIG_PATH>':: if you specified +<FOAM_INSTALL_CONFIG_PATH>+ as
155 The default location is '/usr/local/etc/FreeFOAM-{ver}'.
157 Selecting the Parallel Communications Library
158 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
159 Both, FreeFOAM and OpenFOAM abstract the parallel operations into the 'Pstream'
160 library, making it rather simple to firstly switch between parallel
161 implementations and secondly port the software to a new communications library.
162 However, FreeFOAM uses a much more flexible mechanism of determining which
163 'Pstream' implementation library to use than OpenFOAM. The latter does this by
164 adjusting the +LD_LIBRARY_PATH+ environment variable. As FreeFOAM wants to be a
165 well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically
166 loads the desired 'Pstream' library at startup (i.e. as a plug-in). The
167 following list details how FreeFOAM determines what library to load (if at all):
169 1. If the environment variable +FREEFOAM_PSTREAM_LIBRARY+ is set,
170 FreeFOAM will try to load the library specified by it.
171 2. If the sub-dictionary +PstreamImplementation+ exists in the global
172 'controlDict' file (see <<globalconfig,'Global Configuration Files'>>), it
173 reads the value of the entry +configName+ therein. It then expects that a
174 sub-dictionary of +PstreamImplementation+ with the name specified in
175 +configName+ exists. If that sub-dictionary contains the entry +library+, it
176 will try to load a library specified by the value of that entry.
178 After FreeFOAM (possibly) loaded the library, it will try to instantiate
179 concrete implementations of the abstract base classes +PstreamImpl+,
180 +IPstreamImpl+ and +OPstreamImpl+. Which classes are to be instantiated
181 is determined as follows:
183 1. FreeFOAM queries the environment variables +FREEFOAM_PSTREAM_CLASS+,
184 +FREEFOAM_IPSTREAM_CLASS+ and +FREEFOAM_OPSTREAM_CLASS+ for the class
185 names to be instantiated.
186 2. For any of the variables not set, it requires the sub-dictionary
187 +PstreamImplementation+ to be present in the global 'controlDict', reads the
188 value of +configName+ and similarly to the library loading, loads the
189 sub-dictionary specified by that value. It then expects to find the entries
190 +Pstream+, +IPstream+ and +OPstream+ which specify the names of the classes
193 This means that one can create a global 'controlDict' file containing
194 (among other things) something like the following:
197 PstreamImplementation
204 library libdummyPstream.so;
205 Pstream dummyPstreamImpl;
206 OPstream dummyOPstreamImpl;
207 IPstream dummyIPstreamImpl;
212 library libmpiPstream.so;
213 Pstream mpiPstreamImpl;
214 OPstream mpiOPstreamImpl;
215 IPstream mpiIPstreamImpl;
221 This way the administrator can provide a global 'controlDict' in the FreeFOAM
222 installation. Every user can then override that 'controlDict' by supplying her
223 own file in her home directory as detailed in <<globalconfig,'Global
224 Configuration Files'>>. In order to select a particular 'Pstream' implementation
225 for a specific communications library, the user can then either adjust the
226 +PstreamImplementation::configName+ entry in the global 'controlDict' file, set
227 the +FREEFOAM_PSTREAM_CONFIG+ variable or for full control, set the variables
228 +FREEFOAM_PSTREAM_LIBRARY+, +FREEFOAM_PSTREAM_CLASS+, +FREEFOAM_IPSTREAM_CLASS+
229 and +FREEFOAM_OPSTREAM_CLASS+.
231 Running FreeFOAM From the Build Tree
232 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
233 You can use FreeFOAM without installing it first, directly from the build tree.
234 However, this might take a little bit more effort to set up because most likely
235 you will have to adjust the following environment variables:
237 PATH:: Must contain '$HOME/Source/freefoam-{fullver}-build/bin'
238 LD_LIBRARY_PATH:: Must contain '$HOME/Source/freefoam-{fullver}-build/lib/FreeFOAM-{ver}'
239 FREEFOAM_CONFIG_DIR:: Should point to '$HOME/Source/freefoam-{fullver}-build/etc'
241 Where it is assumed that you followed the <<installation,installation instructions>>. If
242 you used different paths for downloading and compiling FreeFOAM, you will have
243 to adjust these names. Refer to <<environment,'Extending Search Paths And
244 Setting Environment Variables Permanently'>> if you need help setting these
247 Running the tutorials
248 ---------------------
249 Now you should be able to run the tutorial cases. For this copy the +tutorials+
250 directory to some convenient place:
252 $ mkdir -p $HOME/FreeFOAM/$LOGNAME-{shortver}/run
253 $ cp -r $HOME/Source/freefoam-{fullver}-build/tutorials $HOME/FreeFOAM/$LOGNAME-{shortver}/run/
254 $ cd $HOME/FreeFOAM/$LOGNAME-{shortver}/run/tutorials
256 And try to run e.g. the 'cavity' tutorial case:
259 $ freefoam blockMesh -case cavity
260 $ freefoam checkMesh -case cavity
261 $ freefoam ico -case cavity
263 Things should run smoothly and finish without an error.
265 All the tutorials contain a script for automatic execution since some of the
266 cases are quite intricate and it is not obvious how to run them. Also, these
267 scripts are used for automated testing. The scripts are called 'Allrun', where
268 the one located in the 'tutorials' directory is a driver script to run all the
271 Obtaining the Source Code from the GIT repository
272 -------------------------------------------------
273 - Clone the FreeFOAM repository (here the clone is placed in
274 +$HOME/Source/FreeFOAM+):
276 ---------------------------------------------------------------------------
277 $ mkdir -p $HOME/Source
278 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM
279 ---------------------------------------------------------------------------
280 - Proceed in the same way (replacing the path names apropriately) as in the
281 above build instructions.
283 Shell completion scripts
284 ------------------------
285 FreeFOAM comes with completions scripts for the
286 http://www.gnu.org/software/bash/[BASH] and http://www.zsh.org/[ZSH] shells.
287 The former is quite simplistic and only offers very basic completion of the
288 available application names. The ZSH completion, however, is quite complete and
289 also completes options and arguments for all applications. These completion
290 functions are not installed by +make install+, because no two systems have the
291 same locations for these kinds of scripts. You find them for manual
292 installation in the FreeFOAM sources in the directory
293 'data/shellFunctions/bashCompletion' and 'data/shellFunctions/zshCompletion'
294 respectively. Please refer to the documentation of your system/shell on where
299 FreeFOAM includes a rudimentary major mode for the
300 http://www.gnu.org/software/emacs[Emacs] programming editor. If you want to use
301 this mode, place the file 'data/editor-modes/foamdict-mode.el' in a directory
302 where your Emacs installation finds it. Please refer to the Emacs documentation
303 for further instructions.
305 Build Configuration Reference
306 -----------------------------
309 One of '<empty>', 'Debug', 'Release', 'RelWithDebInfo' and 'MinSizeRel'.
310 Refer to the CMake documentation for more detail.
311 +FOAM_DOUBLE_PRECISION+::
312 If set to 'ON' FreeFOAM will be compiled using 'double' as the
313 floating point type. If set to 'OFF' it will use 'float'.
314 +FOAM_BUILD_FRAMEWORKS+::
315 If this is enabled, the libraries are built as frameworks. Only available on
318 Prefix used to mangle application names. Normally this shouldn't be changed.
319 +CMAKE_INSTALL_PREFIX+::
320 Installation prefix under which to install FreeFOAM.
321 +FOAM_INSTALL_BIN_PATH+::
322 Installation path of the binaries. If not absolute, it is relative to
323 'CMAKE_INSTALL_PREFIX'.
324 +FOAM_INSTALL_LIBEXEC_PATH+::
325 Installation path of the binaries which should not be on the +PATH+. If not
326 absolute, it is relative to +CMAKE_INSTALL_PREFIX+.
327 +FOAM_INSTALL_CONFIG_PATH+::
328 Installation path of the configuration files. If not absolute, it is
329 relative to 'CMAKE_INSTALL_PREFIX'.
330 +FOAM_INSTALL_HEADER_PATH+::
331 Installation path of the header files. If not absolute, it is
332 relative to 'CMAKE_INSTALL_PREFIX'. On Mac OS X, and if
333 'FOAM_BUILD_FRAMEWORKS' is enabled, this setting is ignored.
334 +FOAM_INSTALL_LIBRARY_PATH+::
335 Installation path of the libraries. If not absolute, it is
336 relative to 'CMAKE_INSTALL_PREFIX'.
337 +FOAM_INSTALL_FRAMEWORK_PATH+::
338 Installation path of the Mac OS X frameworks. If not absolute, it is
339 relative to 'CMAKE_INSTALL_PREFIX'. This is only available and takes
340 effect if FreeFOAM is compiled on Mac OS X, and if
341 'FOAM_BUILD_FRAMEWORKS' is enabled.
342 +FOAM_INSTALL_USERDFOAM_PATH+::
343 Installation path of the Ensight plug-in. If not absolute, it is
344 relative to 'CMAKE_INSTALL_PREFIX'.
346 If enabled, FreeFOAM will use the MPI parallel communications library.
347 This is required in order to build some of the libraries and utilities.
348 +FOAM_DEFAULT_PSTREAM+::
349 The default Pstream selection in the global 'controlDict' file.
351 +FOAM_ENABLE_CCMIO+::
352 Enable the use of 'libccmio'. This is required to build the grid conversion
353 utility 'ccm26ToFoam'.
356 The license of 'libccmio' (C) is proprietary and requires the consent of the
357 copyright holders (http://www.cd-adapco.com[CD-adapco]) to download and use the
358 library. Further it is not allowed to redistribute it in any form. The request
359 for permission of inclusion with http://debian.org[Debian] was answered as
360 follows by mailto:geoffrey.prewett@us.cd-adapco.com[Geoffrey Prewett]:
362 --------------------------------------------------------------------------------
365 Sorry for the delay in response. I checked back with our development director,
366 and he felt that it would be best to not include libccmio with Debian.
367 Instead, we would prefer to continue our current policy and keep it on our
368 web/FTP and have people ask for it. There are three reasons for this:
370 1) We don't support STAR on Debian, and don't want to give the impression that we do.
371 2) We would like to keep a list of people that we give the library to.
372 3) This is not a general purpose library; its sole purpose is to communicate
373 between our products. Accepting outside changes risks committing a change that
374 would break our own software in possibly subtle ways.
376 So I regret to tell you that my company has declined to permit libccmio to be
377 distributed as part of Debian.
381 --------------------------------------------------------------------------------
384 +FOAM_BUILD_PRIVATE_CCMIO+::
385 Automatically download and build libccmio. Unfortunately this process may
386 fail in the download step if CMake cannot find either 'wget' or 'curl' on
387 your system, since CMake itself currently does not support 'https' URLs. If
388 this happens, the build process will abort. To fix the issue, Download the
389 file https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz
390 manually and place it in +ThirdParty/ccmio/src+ (relative to the build
391 directory). It is important that you re-run CMake *before* restarting the
392 build in order to notify the build system that the file is now there.
393 +FOAM_ENABLE_METIS+::
394 Enable the use of the 'METIS' graph partitioning library which is required to
395 implement the 'metis' decomposition method.
396 +FOAM_BUILD_PRIVATE_METIS+::
397 Automatically download and build 'METIS'.
398 +FOAM_BUILD_PRIVATE_PARMETIS+::
399 Automatically download and build 'ParMetis'.
401 +FOAM_ENABLE_MGRIDGEN+::
402 Enable the use of 'MGRIDGEN' which is required to build
403 'MGridGenGamgAgglomeration' providing the 'MGridGen' agglomeration method for
407 The license of 'MGRIDGEN' is unknown and the upstream authors so far have not
408 answered any inquiries to resolve the issue. If you enable the use of
409 'MGRIDGEN' you alone are responsible for ensuring that you don't violate any
410 license conditions applying to these libraries. The authors of FreeFOAM will
411 and cannot take any responsibility for your actions.
413 +FOAM_BUILD_PRIVATE_MGRIDGEN+::
414 Automatically download and build 'MGRIDGEN'.
415 +FOAM_ENABLE_DOXYGEN_DOCS+::
416 Enable building of the 'Doxygen API documentation'. The documentation will
417 only be built once and is not updated automatically. This is because it
418 depends on a huge number of files and would make dependency tracking very
419 slow and difficult to maintain. To force the re-generation of the API
420 documentation execute +make apidoc+.
421 +FOAM_DOXYDOCS_FOR_SF+::
422 This setting is for the maintainers of the FreeFOAM and indicates whether the
423 Doxygen documentation should be built for deployment on
424 http://freefoam.sourceforge.net.
425 +FOAM_ENABLE_MANPAGE_HELP+::
426 [[foam_enable_manpage_help]]
427 Build (and install) the help-pages in manpage format. This requires a
428 complete http://www.methods.co.nz/asciidoc[Asciidoc] toolchain to be present.
429 +FOAM_ENABLE_XHMTL_HELP+::
430 Build (and install) the help-pages in xhtml format for the display in a web
431 browser. The requirements are the same as for
432 <<foam_enable_manpage_help,+FOAM_ENABLE_MANPAGE_HELP+>>.
433 +FOAM_USE_LOCAL_DOXYGEN_DOCS+::
434 This setting influences the location in which the Doxygen source
435 code documentation is looked for if any of the FreeFOAM applications
436 is invoked with the '-doc' or '-srcDoc' options. If it is disabled,
437 the documentation will be loaded over the network from
438 http://freefoam.sf.net/doc/Doxygen/html. If you enable it, the
439 documentation will be loaded locally. This requires that you either
440 build and install the documentation by enabling +FOAM_ENABLE_DOXYGEN_DOCS+,
441 or provide the required HTML files otherwise.
443 This is the program used to display the Doxygen source code documentation
444 if any of the FreeFOAM applications is invoked with the '-doc' or '-srcDoc'
445 options. The special value of 'ECHO' changes the behaviour to just write
446 the location of the HTML file to the output. This is a good setting if
447 you're system doesn't have any kind of HTML browser installed (such
449 +FOAM_HTML_DOC_BROWSER_COMMAND+::
450 This is the command with which to invoke the HTML browser. By default
451 it calls the program named in +HTML_DOC_BROWSER+ and passes it the
452 name/URL of the documentation file to be displayed. You shouldn't
453 have to change this unless your HTML browser requires some unusual
454 options or arguments.
459 The FreeFOAM Executables Are Not Found By The Shell
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
461 There are three possible reasons for this:
463 1. Your shell (notably 'csh', 'tcsh' and 'zsh') requires you to refresh the
464 cache of available executables. You can do so by entering the command:
470 2. If 'rehashing' didn't solve the problem, the problem most likely is that you
471 installed FreeFOAM into a non-standard location by changing the configuration
472 variables +CMAKE_INSTALL_PREFIX+ or +FOAM_INSTALL_BIN_PATH+ in which case the
473 executables where installed into a directory not searched by the shell. In
474 this case you have to add the installation directory of the executables to
475 the +PATH+ variable. There are two possible locations:
478 '<CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_BIN_PATH>':: if you specified
479 +FOAM_INSTALL_BIN_PATH+ as a relative path
480 '<FOAM_INSTALL_BIN_PATH>':: if you specified +FOAM_INSTALL_BIN_PATH+ as an absolute
484 After extending the +PATH+ variable with the installation directory of the
485 executables, you should be able to run all FreeFOAM applications as any other
486 binary available on the system. See <<environment,'Extending Search Paths And
487 Setting Environment Variables Permanently'>> for
488 instructions on how to extend the search path.
490 3. This option is similar to the previous solution and applies if you want to
491 run FreeFOAM from the build tree (i.e. without running +make install+). In
492 this case you again have to make sure that your shell finds the executables
493 built by CMake by extending the +PATH+ variable. Further, you have to tell
494 FreeFOAM where to find the global configuration files (see
495 <<globalconfig,'Global Configuration Files'>>). Here, you have the option to
496 place the files under your home directory or set an environment variable. The
497 former can be achieved by:
500 $ mkdir -p $HOME/.FreeFOAM/{shortver}
501 $ cp $HOME/Source/freefoam-{fullver}-build/etc/controlDict $HOME/.FreeFOAM/{shortver}
502 $ cp $HOME/Source/freefoam-{fullver}-build/etc/cellModels $HOME/.FreeFOAM/{shortver}
503 $ cp -r $HOME/Source/freefoam-{fullver}-build/etc/thermoData $HOME/.FreeFOAM/{shortver}
506 The latter (and recommended) method is to set the environment variable
507 +FREEFOAM_CONFIG_DIR+ to '$HOME/Source/freefoam-{fullver}-build/etc'. Adjust paths to the
508 build tree to your actual setup.
510 Starting Any FreeFOAM Application Fails Because Some Libraries Cannot Be Found
511 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
512 Although CMake should have taken care of this by using +RPATH+ on Linux and
513 +install_name+ on Mac OS X, it might be necessary on some systems to adjust the
514 library search paths:
516 +LD_LIBRARY_PATH+:: This variable is used by all Unix like systems (e.g. Linux,
518 +DYLD_LIBRARY_PATH+:: This variable is used by Mac OS X.
520 If you installed FreeFOAM, there are (as with the executables), two possible
521 installation directories:
523 '<CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_LIBRARY_PATH>':: if you specified
524 +FOAM_INSTALL_LIBRARY_PATH+ as a relative path.
525 '<FOAM_INSTALL_LIBRARY_PATH>':: if you specified +FOAM_INSTALL_LIBRARY_PATH+ as an absolute
528 If you are trying to run from the build tree, you have to include
529 '$HOME/Source/freefoam-{fullver}-build/lib/FreeFOAM-{ver}' in the above mentioned search
530 paths (where you have to adjust the location of the build tree to your actual
533 A Running FreeFOAM Application Aborts Because It Can't 'dlopen' A Library
534 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
535 FreeFOAM (and OpenFOAM) often dynamically load libraries at run-time (a.k.a
536 plug-ins) to add features the user requested without requiring that the whole
537 application be recompiled. This makes it very simple to add new boundary
538 conditions, turbulence and combustion models etc. However, it also requires that
539 FreeFOAM must be able to find these libraries at run-time. The operating system
540 function which does the loading of the libraries ('dlopen') usually tries to
541 find the library with the given name in several places; namely a default search
542 path and a search path configured by one or multiple environment variables such
543 as +LD_LIBRARY_PATH+ or +DYLD_LIBRARY_PATH+ (on Mac OS X). The details vary from
544 platform to platform, so you best consult the documentation of 'dlopen' for the
547 Additionally FreeFOAM allows you to configure a custom search path for plug-ins
548 in the <<globalconfig,global 'controlDict'>> file by listing the directories to
549 be searched in the list +LibrarySearchPaths+. By default FreeFOAM is configured
550 to search for plug-ins in the location where CMake installed them.
552 If you want to add your own plug-in libraries (e.g. you want to add your own
553 boundary conditions class), you most probably will want to extend this search
556 FreeFOAM Aborts When Trying To Instantiate a Plugin Class
557 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
558 If you get a warning message similar to the following
561 From function dlLibraryTable::open(const dictionary& dict, const word& libsEntry, const TablePtr tablePtr)
562 in file XXX/src/OpenFOAM/db/dlLibraryTable/dlLibraryTableTemplates.C at line 68
563 library "libfieldFunctionObjects.so" did not introduce any new entries
565 (where +XXX+ is the path to the FreeFOAM source code and the actual library
566 name can be different), followed by a fatal error stating that FreeFOAM does
567 not know a class or type, e.g.
569 --> FOAM FATAL ERROR:
570 Unknown function type fieldAverage
572 Table of functionObjects is empty
575 From function functionObject::New(const word& name, const Time&, const dictionary&)
576 in file XXX/src/OpenFOAM/db/functionObjects/functionObject/functionObject.C at line 74.
580 and you are absolutely sure that the named type actually exists in the library
581 mentioned in the preceding warning message, the issue is very likely that
582 FreeFOAM is loading the plugin library from a different binary tree than the
583 executable belongs to.
586 Always make sure that you never load plugins from different binary trees (where
587 the build tree and the install tree count as such). If you want to run a binary
588 from the build tree but already have a corresponding installation tree, use the
589 +FREEFOAM_CONFIG_DIR+ environment variable to point FreeFOAM to the directory
590 '<path to build tree>/etc/' containing the global 'controlDict' file in the
594 Extending Search Paths And Setting Environment Variables Permanently
595 --------------------------------------------------------------------
596 The way one sets environment variables and extends the executable and library
597 search paths permanently strongly depends on the shell used. Usually one has to
598 create or change an initialization file in the users home directory. In the
599 following this will be discussed very briefly for the popular shells 'BASH' and
600 'tcsh'. However, if you need more help or want information on using the shell,
601 there is an excellent tutorial available at http://linuxcommand.org.
605 The BASH shell is the default shell for most Linux/Unix distributions. Most
606 systems configure the BASH shell such that it reads the text file
607 '$HOME/.bashrc' when starting up, so this is the place where one appends
608 customizations of the environment variables. On some systems this file is not
609 processed by default (notably Mac OS X). In this case you can use
610 '$HOME/.bash_profile'.
612 Referencing A Variable
613 ^^^^^^^^^^^^^^^^^^^^^^
614 To retrieve the value stored in a shell variable or environment variable, one
615 prefixes its name with the dollar (+$+) character.
619 The syntax for setting a variable and making it available to child-processes of
620 the shell is the following:
622 $ export variable_name=variable_value
624 Note that no white-space characters are allowed surrounding the +=+ sign.
626 Extending A Search Path
627 ^^^^^^^^^^^^^^^^^^^^^^^
628 The shell and other Unix system facilities use environment variables to locate
629 executables and dynamically linked libraries. These search paths consist of
630 strings naming directories in which the executables and libraries should be
631 searched for. The individual paths are separated by a colon (+:+) character. To
632 add the e.g. the directory '$HOME/bin' to the search path for executables, one
633 would do the following:
635 $ export PATH=$PATH:$HOME/bin
637 which appends '$HOME/bin' to the end of the +PATH+ variable.
641 Some users and administrators prefer to use a 'C-Shell', such as the TCSH. Here
642 you can use e.g. the file '$HOME/.tcshrc' to customize the environment.
644 Referencing A Variable
645 ^^^^^^^^^^^^^^^^^^^^^^
646 As with the BASH, one retrieves the value stored in a shell variable or
647 environment variable by prefixing its name with the dollar (+$+) character.
648 Sometimes it is also necessary to protect the variable name by surrounding it
649 with curly braces (+{+ and +}+).
653 The syntax for setting a variable and making it available to child-processes of
654 the shell is the following:
656 $ setenv variable_name variable_value
659 Extending A Search Path
660 ^^^^^^^^^^^^^^^^^^^^^^^
661 The shell and other Unix system facilities use environment variables to locate
662 executables and dynamically linked libraries. These search paths consist of
663 strings naming directories in which the executables and libraries should be
664 searched for. The individual paths are separated by a colon (+:+) character. To
665 add the e.g. the directory '$HOME/bin' to the search path for executables, one
666 would do the following:
669 $ setenv PATH ${PATH}:${HOME}/bin
671 which appends '$HOME/bin' to the end of the +PATH+ variable. Note that
672 'C-shells' usually require the user to type 'rehash' after changing the +PATH+
673 variable to update the cache of available programs.
675 ///////////////////////////////////////////////////////////
676 Process with: asciidoc -a toc -f data/asciidoc.conf INSTALL
678 Vim users, this is for you:
679 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
680 ///////////////////////////////////////////////////////////