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