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