1 {project} Installation Instructions for Version {fullver}
2 =========================================================
3 Michael Wild <themiwi@users.sourceforge.net>
5 v{fullver}, {localdate}
8 :apidoc: {homepage}/doc/Doxygen/html
9 :asciidoc: http://www.methods.co.nz/asciidoc[Asciidoc]
10 :bash: http://www.gnu.org/software/bash/[BASH]
11 :cd-adapco: http://www.cd-adapco.com[CD-adapco]
12 :dblatex: http://dblatex.sourceforge.net[dblatex]
13 :debian: http://debian.org[Debian]
14 :dvipng: http://sourceforge.net/projects/dvipng[dvipng]
15 :emacs: http://www.gnu.org/software/emacs[Emacs]
16 :fop: http://xmlgraphics.apache.org/fop[Apache FOP]
17 :latex: http://www.latex-project.org[LaTeX]
18 :libccmio: https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz
19 :linuxcommand: http://linuxcommand.org
20 :mathjax: http://www.mathjax.org[MathJax]
21 :metis: http://glaros.dtc.umn.edu/gkhome/fetch/sw/metis/metis-5.0pre2.tar.gz
22 :mgridgen: http://www-users.cs.umn.edu/~moulitsa/download/ParMGridGen-1.0.tar.gz
23 :parmetis: http://glaros.dtc.umn.edu/gkhome/fetch/sw/parmetis/ParMetis-3.1.tar.gz
24 :scotch: http://master.dl.sourceforge.net/project/freefoam/ThirdParty/scotch/scotch_5.1.7.dfsg.orig.tar.gz
25 :tarball: http://master.dl.sourceforge.net/sourceforge/freefoam/freefoam-{fullver}.tar.bz2
26 :zlib: http://master.dl.sourceforge.net/project/freefoam/ThirdParty/zlib/zlib-1.2.5.tar.gz
27 :zsh: http://www.zsh.org/[ZSH]
29 Obtaining the Prerequisites
30 ---------------------------
31 Some of the libraries {project} requires (or optionally can use) are often not
32 readily available as an installable package and are quite tricky to install
33 manually. {project} can automatically download and build these libraries for
34 you, refer to below instructions. However, if you are behind a firewall or
35 CMake is unable to download a source package, you can do so manually and place
36 the files in the 'ThirdParty' directory in the {project} source tree. When you
37 run CMake, it will detect the presence of the files and not try to download
40 You can obtain the source packages from the following URLs:
57 - Install the prerequisites documented in the link:README.html[README] file. If
58 your distribution does not have 'METIS', 'ParMetis', 'MGRIDGEN' or 'libccmio'
59 be not worried, {project} can handle those for you.
60 - Download the {project} source and unpack it somewhere convenient. For the
61 further instructions we will use +$HOME/Source/+.
63 ---------------------------------------------------------------------------
64 $ mkdir -p $HOME/Source
67 $ tar xjf freefoam-{fullver}.tar.bz2
68 ---------------------------------------------------------------------------
69 - Create a build tree and _cd_ into it:
72 $ mkdir $HOME/Source/freefoam-{fullver}-build
73 $ cd $HOME/Source/freefoam-{fullver}-build
75 - Start CMake-configuration:
78 $ ccmake $HOME/Source/freefoam-{fullver}
80 - Press the +c+ key. Use the arrow keys to navigate up and down and press
81 +enter+ to edit a field. To commit the change, press +enter+ again, or +ESC+
82 to abandon the change. ON/OFF fields are toggled by pressing +enter+.
83 Advanced options can be displayed by hitting the +t+ key.
84 * Set +CMAKE_BUILD_TYPE+ to 'Release' for an optimized build.
85 * If CMake complains that it can't find MPI, and you don't want to install
86 it, disable +FOAM_USE_MPI+.
87 * Select the default Pstream implementation by setting +FOAM_DEFAULT_PSTREAM+
88 to one of 'dummy' or 'mpi'. This setting will only influence the contents
89 of the <<globalconfig,global 'controlDict' file>>.
90 * If you want to use the 'metis' and 'parmetis' decomposition methods, make
91 sure that +FOAM_ENABLE_METIS+ and +FOAM_ENABLE_PARMETIS+ are enabled,
92 respectively. If you do not have 'METIS' or 'ParMetis' installed, enable
93 +FOAM_BUILD_PRIVATE_METIS+ or +FOAM_BUILD_PRIVATE_PARMETIS+, respectively.
94 CMake will then try to download and build the selected libraries for you.
95 Conversely, if one of the libraries is provided by your system, you can
96 turn the respective setting to 'OFF'. Please note that if your system
97 provides only 'ParMetis', you do not have to install 'METIS', as the former
98 also contains 'METIS' in an older version.
99 * If you want to use the 'MGridGen' agglomeration method for the GAMG solver,
100 you need to enable +FOAM_ENABLE_MGRIDGEN+ and if the library is not
101 installed on your system ensure that +FOAM_BUILD_PRIVATE_MGRIDGEN+ is
102 enabled. See <<enable-mgridgen,above>> regarding the unknown license status
104 * In order to build 'ccm26ToFoam', a conversion utility for grids generated
105 with 'ProStar/ccm' (C) version 2.6, enable the setting
106 +FOAM_ENABLE_CCMIO+ and if 'libccmio' is not installed on your system,
107 also +FOAM_BUILD_PRIVATE_CCMIO+. Refer to the <<enable-ccmio,above>>
108 description of the 'libccmio' package for the license restrictions which
109 apply to this package. If you decide to build a private version, please
110 read the description of <<private-ccmio,+FOAM_BUILD_PRIVATE_CCMIO>>
112 * If you plan on installing {project}, set +CMAKE_INSTALL_PREFIX+ to the base
113 directory under which {project} should reside.
114 * For more fine-grained control over what gets installed where, adjust
115 +FOAM_INSTALL_CONFIG_PATH+, +FOAM_INSTALL_HEADER_PATH+,
116 +FOAM_INSTALL_LIBRARY_PATH+, +FOAM_INSTALL_FRAMEWORK_PATH+,
117 +FOAM_INSTALL_PVFOAMREADER_PATH+ and +FOAM_INSTALL_USERDFOAM_PATH+. Paths
118 not starting with a slash ('/') will be relative to 'CMAKE_INSTALL_PREFIX'.
119 If you include a leading slash, the paths are absolute.
120 * If you want {project} to use 'float' as the floating point type instead of
121 'double', change +FOAM_DOUBLE_PRECISION+ to 'OFF'.
122 - Hit +c+ again. You shouldn't get any errors anymore now. Keep pressing +c+
123 until ccmake displays "++Press [g] to generate and exit++" in the legend at
124 the bottom of the interface.
125 - Press +g+ to generate the Makefiles and exit the ccmake interface.
126 - Start the native build tool. If you used the 'Makefile' generator
127 (which is the default for Unix-platforms), type
132 - If you have a multi-core/processor machine, you can speed things up
133 significantly by telling Make to run independent jobs in parallel.
134 A good choice for the number of parallel jobs to run is the
135 number of CPU's/cores you have in your machine plus 1 (to compensate
136 for disk-latency). For a typical dual-core machine, run
144 If you want to, you can now install {project}. Depending on the
145 +CMAKE_INSTALL_PREFIX+ and the individual +FOAM_INSTALL_*_PATH+ it is possible
146 that you have to do this as root, i.e. use +su+ or +sudo+.
153 If you didn't change +CMAKE_INSTALL_PREFIX+ and +FOAM_INSTALL_BIN_PATH+ chances
154 are that you can start using {project} right after you installed it without any
155 further steps being necessary.
158 Global Configuration Files
159 ~~~~~~~~~~~~~~~~~~~~~~~~~~
160 Unfortunately the OpenFOAM library (on which {project} builds) and some
161 applications require some files to be present for start-up. It finds those
162 in the following places (in the specified order, picking the first hit):
164 1. Under the directory specified in the +$FREEFOAM_CONFIG_DIR+ environment
166 2. In '$HOME/.{project}/{shortver}'
167 3. In '$HOME/.{project}'
168 4. In the installation directory of the configuration files. There are
169 two possible places for this:
171 '<CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_CONFIG_PATH>':: if you specified
172 +<FOAM_INSTALL_CONFIG_PATH>+ as a relative path.
173 '<FOAM_INSTALL_CONFIG_PATH>':: if you specified +<FOAM_INSTALL_CONFIG_PATH>+
176 The default location is '/usr/local/etc/{project}-{ver}'.
178 Selecting the Parallel Communications Library
179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
180 Both, {project} and OpenFOAM abstract the parallel operations into the
181 'Pstream' library, making it rather simple to firstly switch between parallel
182 implementations and secondly port the software to a new communications library.
183 However, {project} uses a much more flexible mechanism of determining which
184 'Pstream' implementation library to use than OpenFOAM. The latter does this by
185 adjusting the +LD_LIBRARY_PATH+ environment variable. As {project} wants to be
186 a well behaved Linux citizen, this is not an option. Instead, {project}
187 dynamically loads the desired 'Pstream' library at startup (i.e. as a plug-in).
188 The following list details how {project} determines what library to load (if at
191 1. If the environment variable +FREEFOAM_PSTREAM_LIBRARY+ is set,
192 {project} will try to load the library specified by it.
193 2. If the sub-dictionary +PstreamImplementation+ exists in the global
194 'controlDict' file (see <<globalconfig,'Global Configuration Files'>>), it
195 reads the value of the entry +configName+ therein. It then expects that a
196 sub-dictionary of +PstreamImplementation+ with the name specified in
197 +configName+ exists. If that sub-dictionary contains the entry +library+, it
198 will try to load a library specified by the value of that entry.
200 After {project} (possibly) loaded the library, it will try to instantiate
201 concrete implementations of the abstract base classes +PstreamImpl+,
202 +IPstreamImpl+ and +OPstreamImpl+. Which classes are to be instantiated
203 is determined as follows:
205 1. {project} queries the environment variables +FREEFOAM_PSTREAM_CLASS+,
206 +FREEFOAM_IPSTREAM_CLASS+ and +FREEFOAM_OPSTREAM_CLASS+ for the class
207 names to be instantiated.
208 2. For any of the variables not set, it requires the sub-dictionary
209 +PstreamImplementation+ to be present in the global 'controlDict', reads the
210 value of +configName+ and similarly to the library loading, loads the
211 sub-dictionary specified by that value. It then expects to find the entries
212 +Pstream+, +IPstream+ and +OPstream+ which specify the names of the classes
215 This means that one can create a global 'controlDict' file containing
216 (among other things) something like the following:
219 PstreamImplementation
226 library libdummyPstream.so;
227 Pstream dummyPstreamImpl;
228 OPstream dummyOPstreamImpl;
229 IPstream dummyIPstreamImpl;
234 library libmpiPstream.so;
235 Pstream mpiPstreamImpl;
236 OPstream mpiOPstreamImpl;
237 IPstream mpiIPstreamImpl;
243 This way the administrator can provide a global 'controlDict' in the {project}
244 installation. Every user can then override that 'controlDict' by supplying her
245 own file in her home directory as detailed in <<globalconfig,'Global
246 Configuration Files'>>. In order to select a particular 'Pstream'
247 implementation for a specific communications library, the user can then either
248 adjust the +PstreamImplementation::configName+ entry in the global
249 'controlDict' file, set the +FREEFOAM_PSTREAM_CONFIG+ variable or for full
250 control, set the variables +FREEFOAM_PSTREAM_LIBRARY+,
251 +FREEFOAM_PSTREAM_CLASS+, +FREEFOAM_IPSTREAM_CLASS+ and
252 +FREEFOAM_OPSTREAM_CLASS+.
254 Running {project} From the Build Tree
255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
256 You can use {project} without installing it first, directly from the build
257 tree. However, this might take a little bit more effort to set up because most
258 likely you will have to adjust the following environment variables:
261 Must contain '$HOME/Source/freefoam-{fullver}-build/bin'
263 Must contain '$HOME/Source/freefoam-{fullver}-build/lib/{project}-{ver}'
264 `FREEFOAM_CONFIG_DIR`::
265 Should point to '$HOME/Source/freefoam-{fullver}-build/etc'
267 Where it is assumed that you followed the <<installation,installation
268 instructions>>. If you used different paths for downloading and compiling
269 {project}, you will have to adjust these names. Refer to
270 <<environment,'Extending Search Paths And Setting Environment Variables
271 Permanently'>> if you need help setting these variables.
273 Running the tutorials
274 ---------------------
275 Now you should be able to run the tutorial cases. For this copy the +tutorials+
276 directory to some convenient place:
278 $ mkdir -p $HOME/{project}/$LOGNAME-{shortver}/run
279 $ cp -r $HOME/Source/freefoam-{fullver}-build/tutorials \
280 $HOME/{project}/$LOGNAME-{shortver}/run/
281 $ cd $HOME/{project}/$LOGNAME-{shortver}/run/tutorials
283 And try to run e.g. the 'cavity' tutorial case:
286 $ freefoam blockMesh -case cavity
287 $ freefoam checkMesh -case cavity
288 $ freefoam ico -case cavity
290 Things should run smoothly and finish without an error.
292 All the tutorials contain a script for automatic execution since some of the
293 cases are quite intricate and it is not obvious how to run them. Also, these
294 scripts are used for automated testing. The scripts are called 'Allrun', where
295 the one located in the 'tutorials' directory is a driver script to run all the
298 Obtaining the Source Code from the GIT repository
299 -------------------------------------------------
300 - Clone the {project} repository (here the clone is placed in
301 +$HOME/Source/{project}+):
303 ---------------------------------------------------------------------------
304 $ mkdir -p $HOME/Source
305 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/{project}
306 ---------------------------------------------------------------------------
307 - Proceed in the same way (replacing the path names appropriately) as in the
308 above build instructions.
310 Shell completion scripts
311 ------------------------
312 {project} comes with completions scripts for the {bash} and {zsh} shells. The
313 former is quite simplistic and only offers very basic completion of the
314 available application names. The ZSH completion, however, is quite complete and
315 also completes options and arguments for all applications. These completion
316 functions are not installed by +make install+, because no two systems have the
317 same locations for these kinds of scripts. You find them for manual
318 installation in the {project} sources in the directory
319 'data/shellFunctions/bashCompletion' and 'data/shellFunctions/zshCompletion'
320 respectively. Please refer to the documentation of your system/shell on where
325 {project} includes a rudimentary major mode for the {emacs} programming editor.
326 If you want to use this mode, place the file
327 'data/editor-modes/foamdict-mode.el' in a directory where your Emacs
328 installation finds it. Please refer to the Emacs documentation for further
331 Build Configuration Reference
332 -----------------------------
333 All installation paths below, if not absolute, are relative to
334 'CMAKE_INSTALL_PREFIX'.
336 ///////////////////////////
337 KEEP ALPHABETICALLY SORTED!
338 ///////////////////////////
342 One of '<empty>', 'Debug', 'Release', 'RelWithDebInfo' and 'MinSizeRel'.
343 Refer to the CMake documentation for more detail.
344 +CMAKE_INSTALL_PREFIX+::
345 Installation prefix under which to install {project}.
346 +FOAM_DOUBLE_PRECISION+::
347 If set to 'ON' {project} will be compiled using 'double' as the
348 floating point type. If set to 'OFF' it will use 'float'.
349 +FOAM_BUILD_FRAMEWORKS+::
350 If this is enabled, the libraries are built as frameworks. Only available on
353 +FOAM_BUILD_PRIVATE_CCMIO+::
354 Automatically download and build libccmio. Unfortunately this process may
355 fail in the download step if CMake cannot find either 'wget' or 'curl' on
356 your system, since CMake itself currently does not support 'https' URLs. If
357 this happens, the build process will abort. To fix the issue, Download the
358 file {libccmio} manually and place it in +ThirdParty/ccmio/src+ (relative to
359 the build directory). It is important that you re-run CMake *before*
360 restarting the build in order to notify the build system that the file is now
362 +FOAM_BUILD_PRIVATE_METIS+::
363 Automatically download and build 'METIS'.
364 +FOAM_BUILD_PRIVATE_MGRIDGEN+::
365 Automatically download and build 'MGRIDGEN'.
366 +FOAM_BUILD_PRIVATE_PARMETIS+::
367 Automatically download and build 'ParMetis'.
368 +FOAM_DEFAULT_PSTREAM+::
369 The default Pstream selection in the global 'controlDict' file.
370 +FOAM_DOXYDOCS_FOR_SF+::
371 This setting is for the maintainers of the {project} and indicates whether
372 the Doxygen documentation should be built for deployment on {homepage}
374 +FOAM_ENABLE_CCMIO+::
375 Enable the use of 'libccmio'. This is required to build the grid conversion
376 utility 'ccm26ToFoam'.
379 The license of 'libccmio' (C) is proprietary and requires the consent of the
380 copyright holders ({cd-adapco}) to download and use the
381 library. Further it is not allowed to redistribute it in any form. The request
382 for permission of inclusion with {debian} was answered as
383 follows by mailto:geoffrey.prewett@us.cd-adapco.com[Geoffrey Prewett]:
385 -------------------------------------------------------------------------------
388 Sorry for the delay in response. I checked back with our development director,
389 and he felt that it would be best to not include libccmio with Debian.
390 Instead, we would prefer to continue our current policy and keep it on our
391 web/FTP and have people ask for it. There are three reasons for this:
393 1) We don't support STAR on Debian, and don't want to give the impression that
395 2) We would like to keep a list of people that we give the library to.
396 3) This is not a general purpose library; its sole purpose is to communicate
397 between our products. Accepting outside changes risks committing a change that
398 would break our own software in possibly subtle ways.
400 So I regret to tell you that my company has declined to permit libccmio to be
401 distributed as part of Debian.
405 -------------------------------------------------------------------------------
407 +FOAM_ENABLE_CPACK+::
408 Enable building source and binary packages/installers with CPack.
409 +FOAM_ENABLE_DOXYGEN_DOCS+::
410 Enable building of the 'Doxygen API documentation'. The documentation will
411 only be built once and is not updated automatically. This is because it
412 depends on a huge number of files and would make dependency tracking very
413 slow and difficult to maintain. To force the re-generation of the API
414 documentation execute +make apidoc+.
415 +FOAM_ENABLE_METIS+::
416 Enable the use of the 'METIS' graph partitioning library which is required to
417 implement the 'metis' decomposition method.
419 +FOAM_ENABLE_MGRIDGEN+::
420 Enable the use of 'MGRIDGEN' which is required to build
421 'MGridGenGamgAgglomeration' providing the 'MGridGen' agglomeration method for
425 The license of 'MGRIDGEN' is unknown and the upstream authors so far have not
426 answered any inquiries to resolve the issue. If you enable the use of
427 'MGRIDGEN' you alone are responsible for ensuring that you don't violate any
428 license conditions applying to these libraries. The authors of {project} will
429 and cannot take any responsibility for your actions.
431 +FOAM_ENABLE_MANPAGE_HELP+::
432 [[foam_enable_manpage_help]]
433 Build (and install) the help-pages in manpage format. This requires a
434 complete {asciidoc} toolchain to be present.
435 +FOAM_ENABLE_PARMETIS+::
436 Enable the use of the 'ParMetis' graph partitioning library which is required
437 to implement the 'parMetis' decomposition method.
438 +FOAM_ENABLE_PDF_GUIDES+::
439 Build a PDF version of the user guide. In addition to a complete {asciidoc}
440 toolchain, this requires either {dblatex} (for better results) or {fop} to be
441 installed. If FOP is used, {latex} and {dvipng} are required.
442 +FOAM_ENABLE_XHTML_GUIDES+::
443 Build a XHTML version of the user guide. This requires a complete {asciidoc}
444 toolchain. If +FOAM_ENABLE_MATHJAX+ is disabled, this also requires {latex}
445 and {dvipng} to be available.
446 +FOAM_ENABLE_XHTML_HELP+::
447 Build (and install) the help-pages in XHTML format for the display in a web
448 browser. The requirements are the same as for
449 <<foam_enable_manpage_help,+FOAM_ENABLE_MANPAGE_HELP+>>.
451 Prefix used to mangle application names. Normally this shouldn't be changed.
452 +FOAM_ENABLE_FULL_TUTORIAL_TESTS+::
453 Run the full tutorials as tests, don't limit their run-time to a single time
455 +FOAM_INSTALL_BIN_PATH+::
456 Installation path of the binaries.
457 +FOAM_INSTALL_CMAKE_PATH+::
458 Installation path of the CMake development files.
459 +FOAM_INSTALL_CONFIG_PATH+::
460 Installation path of the configuration files.
461 +FOAM_INSTALL_DATA_PATH+::
462 Installation path of the architecture-independent files.
463 +FOAM_INSTALL_DOC_PATH+::
464 Installation path of the documentation files.
465 +FOAM_INSTALL_FRAMEWORK_PATH+::
466 Installation path of the Mac OS X frameworks. This is only available and
467 takes effect if {project} is compiled on Mac OS X, and if
468 'FOAM_BUILD_FRAMEWORKS' is enabled.
469 +FOAM_INSTALL_HEADER_PATH+::
470 Installation path of the header files. On Mac OS X, and if
471 'FOAM_BUILD_FRAMEWORKS' is enabled, this setting is ignored.
472 +FOAM_INSTALL_LIBEXEC_PATH+::
473 Installation path of the binaries which should not be on the +PATH+.
474 +FOAM_INSTALL_LIBRARY_PATH+::
475 Installation path of the libraries.
476 +FOAM_INSTALL_MAN_PATH+::
477 Installation path of the manpage files.
478 +FOAM_ENABLE_MATHJAX+::
479 When 'FOAM_ENABLE_XHTML_GUIDES' is enabled, use {mathjax} for the math
481 +FOAM_INSTALL_PLUGIN_PATH+::
482 Installation base-path of plugins.
483 +FOAM_INSTALL_PYTHON_PATH+::
484 Installation path for Python modules.
485 +FOAM_INSTALL_USERDFOAM_PATH+::
486 Installation path of the Ensight plug-in.
487 +FOAM_INSTALL_TUTORIALS_PATH+::
488 Installation path of the tutorials.
490 Use {fop} instead of {dblatex} when building the PDF of the user guide.
492 If enabled, {project} will use the MPI parallel communications library.
493 This is required in order to build some of the libraries and utilities.
494 +FOAM_USE_LOCAL_DOXYGEN_DOCS+::
495 This setting influences the location in which the Doxygen source
496 code documentation is looked for if any of the {project} applications
497 is invoked with the '-doc' or '-srcDoc' options. If it is disabled,
498 the documentation will be loaded over the network from
499 {apidoc}. If you enable it, the
500 documentation will be loaded locally. This requires that you either
501 build and install the documentation by enabling +FOAM_ENABLE_DOXYGEN_DOCS+,
502 or provide the required HTML files otherwise.
504 This is the program used to display the Doxygen source code documentation
505 if any of the {project} applications is invoked with the '-doc' or '-srcDoc'
506 options. The special value of 'ECHO' changes the behaviour to just write
507 the location of the HTML file to the output. This is a good setting if
508 you're system doesn't have any kind of HTML browser installed (such
510 +FOAM_HTML_DOC_BROWSER_COMMAND+::
511 This is the command with which to invoke the HTML browser. By default
512 it calls the program named in +HTML_DOC_BROWSER+ and passes it the
513 name/URL of the documentation file to be displayed. You shouldn't
514 have to change this unless your HTML browser requires some unusual
515 options or arguments.
520 The {project} Executables Are Not Found By The Shell
521 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
522 There are three possible reasons for this:
524 1. Your shell (notably 'csh', 'tcsh' and 'zsh') requires you to refresh the
525 cache of available executables. You can do so by entering the command:
531 2. If 'rehashing' didn't solve the problem, the problem most likely is that you
532 installed {project} into a non-standard location by changing the
533 configuration variables +CMAKE_INSTALL_PREFIX+ or +FOAM_INSTALL_BIN_PATH+ in
534 which case the executables where installed into a directory not searched by
535 the shell. In this case you have to add the installation directory of the
536 executables to the +PATH+ variable. There are two possible locations:
539 '<CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_BIN_PATH>':: if you specified
540 +FOAM_INSTALL_BIN_PATH+ as a relative path
541 '<FOAM_INSTALL_BIN_PATH>':: if you specified +FOAM_INSTALL_BIN_PATH+ as an
545 After extending the +PATH+ variable with the installation directory of the
546 executables, you should be able to run all {project} applications as any other
547 binary available on the system. See <<environment,'Extending Search Paths And
548 Setting Environment Variables Permanently'>> for
549 instructions on how to extend the search path.
551 3. This option is similar to the previous solution and applies if you want to
552 run {project} from the build tree (i.e. without running +make install+). In
553 this case you again have to make sure that your shell finds the executables
554 built by CMake by extending the +PATH+ variable. Further, you have to tell
555 {project} where to find the global configuration files (see
556 <<globalconfig,'Global Configuration Files'>>). Here, you have the option to
557 place the files under your home directory or set an environment variable.
558 The former can be achieved by:
561 $ mkdir -p $HOME/.{project}/{shortver}
562 $ cp $HOME/Source/freefoam-{fullver}-build/etc/controlDict \
563 $HOME/.{project}/{shortver}
564 $ cp $HOME/Source/freefoam-{fullver}-build/etc/cellModels \
565 $HOME/.{project}/{shortver}
566 $ cp -r $HOME/Source/freefoam-{fullver}-build/etc/thermoData \
567 $HOME/.{project}/{shortver}
570 The latter (and recommended) method is to set the environment variable
571 +FREEFOAM_CONFIG_DIR+ to '$HOME/Source/freefoam-{fullver}-build/etc'. Adjust
572 the paths to match the build tree to your actual setup.
574 Starting Any {project} Application Fails Because Some Libraries Cannot Be Found
575 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
576 Although CMake should have taken care of this by using +RPATH+ on Linux and
577 +install_name+ on Mac OS X, it might be necessary on some systems to adjust the
578 library search paths:
580 +LD_LIBRARY_PATH+:: This variable is used by all Unix like systems (e.g. Linux,
582 +DYLD_LIBRARY_PATH+:: This variable is used by Mac OS X.
584 If you installed {project}, there are (as with the executables), two possible
585 installation directories:
587 '<CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_LIBRARY_PATH>':: if you specified
588 +FOAM_INSTALL_LIBRARY_PATH+ as a relative path.
589 '<FOAM_INSTALL_LIBRARY_PATH>':: if you specified +FOAM_INSTALL_LIBRARY_PATH+ as
592 If you are trying to run from the build tree, you have to include
593 '$HOME/Source/freefoam-{fullver}-build/lib/{project}-{ver}' in the above
594 mentioned search paths (where you have to adjust the location of the build tree
595 to your actual setup).
597 A Running {project} Application Aborts Because It Can't 'dlopen' A Library
598 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
599 {project} (and OpenFOAM) often dynamically load libraries at run-time (a.k.a
600 plug-ins) to add features the user requested without requiring that the whole
601 application be recompiled. This makes it very simple to add new boundary
602 conditions, turbulence and combustion models etc. However, it also requires
603 that {project} must be able to find these libraries at run-time. The operating
604 system function which does the loading of the libraries ('dlopen') usually
605 tries to find the library with the given name in several places; namely a
606 default search path and a search path configured by one or multiple environment
607 variables such as +LD_LIBRARY_PATH+ or +DYLD_LIBRARY_PATH+ (on Mac OS X). The
608 details vary from platform to platform, so you best consult the documentation
609 of 'dlopen' for the details.
611 Additionally {project} allows you to configure a custom search path for
612 plug-ins in the <<globalconfig,global 'controlDict'>> file by listing the
613 directories to be searched in the list +LibrarySearchPaths+. By default
614 {project} is configured to search for plug-ins in the location where CMake
617 If you want to add your own plug-in libraries (e.g. you want to add your own
618 boundary conditions class), you most probably will want to extend this search
621 {project} Aborts When Trying To Instantiate a Plugin Class
622 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
623 If you get a warning message similar to the following
626 From function dlLibraryTable::open(const dictionary& dict, const word& libsEntry, const TablePtr tablePtr)
627 in file XXX/src/OpenFOAM/db/dlLibraryTable/dlLibraryTableTemplates.C at line 68
628 library "libfieldFunctionObjects.so" did not introduce any new entries
630 (where +XXX+ is the path to the {project} source code and the actual library
631 name can be different), followed by a fatal error stating that {project} does
632 not know a class or type, e.g.
634 --> FOAM FATAL ERROR:
635 Unknown function type fieldAverage
637 Table of functionObjects is empty
640 From function functionObject::New(const word& name, const Time&, const dictionary&)
641 in file XXX/src/OpenFOAM/db/functionObjects/functionObject/functionObject.C at line 74.
645 and you are absolutely sure that the named type actually exists in the library
646 mentioned in the preceding warning message, the issue is very likely that
647 {project} is loading the plugin library from a different binary tree than the
648 executable belongs to.
651 Always make sure that you never load plugins from different binary trees (where
652 the build tree and the install tree count as such). If you want to run a binary
653 from the build tree but already have a corresponding installation tree, use the
654 +FREEFOAM_CONFIG_DIR+ environment variable to point {project} to the directory
655 '<path to build tree>/etc/' containing the global 'controlDict' file in the
656 **build tree**. Otherwise the binaries are likely to be incompatible with each
660 Extending Search Paths And Setting Environment Variables Permanently
661 --------------------------------------------------------------------
662 The way one sets environment variables and extends the executable and library
663 search paths permanently strongly depends on the shell used. Usually one has to
664 create or change an initialization file in the users home directory. In the
665 following this will be discussed very briefly for the popular shells 'BASH' and
666 'tcsh'. However, if you need more help or want information on using the shell,
667 there is an excellent tutorial available at {linuxcommand}.
671 The BASH shell is the default shell for most Linux/Unix distributions. Most
672 systems configure the BASH shell such that it reads the text file
673 '$HOME/.bashrc' when starting up, so this is the place where one appends
674 customizations of the environment variables. On some systems this file is not
675 processed by default (notably Mac OS X). In this case you can use
676 '$HOME/.bash_profile'.
678 Referencing A Variable
679 ^^^^^^^^^^^^^^^^^^^^^^
680 To retrieve the value stored in a shell variable or environment variable, one
681 prefixes its name with the dollar (+$+) character.
685 The syntax for setting a variable and making it available to child-processes of
686 the shell is the following:
688 $ export variable_name=variable_value
690 Note that no white-space characters are allowed surrounding the +=+ sign.
692 Extending A Search Path
693 ^^^^^^^^^^^^^^^^^^^^^^^
694 The shell and other Unix system facilities use environment variables to locate
695 executables and dynamically linked libraries. These search paths consist of
696 strings naming directories in which the executables and libraries should be
697 searched for. The individual paths are separated by a colon (+:+) character. To
698 add the e.g. the directory '$HOME/bin' to the search path for executables, one
699 would do the following:
701 $ export PATH=$PATH:$HOME/bin
703 which appends '$HOME/bin' to the end of the +PATH+ variable.
707 Some users and administrators prefer to use a 'C-Shell', such as the TCSH. Here
708 you can use e.g. the file '$HOME/.tcshrc' to customize the environment.
710 Referencing A Variable
711 ^^^^^^^^^^^^^^^^^^^^^^
712 As with the BASH, one retrieves the value stored in a shell variable or
713 environment variable by prefixing its name with the dollar (+$+) character.
714 Sometimes it is also necessary to protect the variable name by surrounding it
715 with curly braces (+{+ and +}+).
719 The syntax for setting a variable and making it available to child-processes of
720 the shell is the following:
722 $ setenv variable_name variable_value
725 Extending A Search Path
726 ^^^^^^^^^^^^^^^^^^^^^^^
727 The shell and other Unix system facilities use environment variables to locate
728 executables and dynamically linked libraries. These search paths consist of
729 strings naming directories in which the executables and libraries should be
730 searched for. The individual paths are separated by a colon (+:+) character. To
731 add the e.g. the directory '$HOME/bin' to the search path for executables, one
732 would do the following:
735 $ setenv PATH ${PATH}:${HOME}/bin
737 which appends '$HOME/bin' to the end of the +PATH+ variable. Note that
738 'C-shells' usually require the user to type 'rehash' after changing the +PATH+
739 variable to update the cache of available programs.
741 ////////////////////////////////////////////////////////////////////
742 Process with: asciidoc -a toc -f data/asciidoc/html.conf INSTALL
744 Vim users, this is for you:
745 vim: ft=asciidoc sw=2 expandtab fenc=utf-8
746 ////////////////////////////////////////////////////////////////////