1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en">
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8" />
6 <meta name=
"generator" content=
"AsciiDoc 8.4.4-dev" />
7 <title>FreeFOAM Installation Instructions for Version
0.1.0</title>
8 <style type=
"text/css">
10 p
, li
, dt
, dd
, div
, pre
, h1
, h2
, h3
, h4
, h5
, h6
{
12 border: 1px solid red;
17 margin: 1em 5% 1em 5%;
22 text-decoration: underline
;
42 h1
, h2
, h3
, h4
, h5
, h6
{
44 font-family: sans-serif
;
51 border-bottom: 2px solid silver
;
69 border: 1px solid silver
;
88 font-family: sans-serif
;
94 span#revnumber
, span#revdate
, span#revremark
{
95 font-family: sans-serif
;
99 font-family: sans-serif
;
101 border-top: 2px solid silver
;
107 padding-bottom: 0.5em;
111 padding-bottom: 0.5em;
116 margin-bottom: 1.5em;
118 div
.tableblock
, div
.imageblock
, div
.exampleblock
, div
.verseblock
,
119 div
.quoteblock
, div
.literalblock
, div
.listingblock
, div
.sidebarblock
,
120 div
.admonitionblock
{
122 margin-bottom: 1.5em;
124 div
.admonitionblock
{
126 margin-bottom: 2.5em;
129 div
.content
{ /* Block element content. */
133 /* Block element titles. */
134 div
.title
, caption
.title
{
136 font-family: sans-serif
;
140 margin-bottom: 0.5em;
146 td div
.title:first-child
{
149 div
.content div
.title:first-child
{
152 div
.content
+ div
.title
{
156 div
.sidebarblock
> div
.content
{
158 border: 1px solid silver
;
162 div
.listingblock
> div
.content
{
163 border: 1px solid silver
;
172 div
.quoteblock
> div
.attribution
{
181 div
.verseblock
> div
.content
{
184 div
.verseblock
> div
.attribution
{
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div
.verseblock
+ div
.attribution
{
193 div
.admonitionblock
.icon
{
197 text-decoration: underline
;
199 padding-right: 0.5em;
201 div
.admonitionblock td
.content
{
203 border-left: 2px solid silver
;
206 div
.exampleblock
> div
.content
{
207 border-left: 2px solid silver
;
211 div
.imageblock div
.content
{ padding-left: 0; }
212 span
.image img
{ border-style: none
; }
213 a
.image:visited
{ color: white
; }
217 margin-bottom: 0.8em;
230 list-style-position: outside
;
233 list-style-type: decimal
;
236 list-style-type: lower-alpha
;
239 list-style-type: upper-alpha
;
242 list-style-type: lower-roman
;
245 list-style-type: upper-roman
;
248 div
.compact ul
, div
.compact ol
,
249 div
.compact p
, div
.compact p
,
250 div
.compact div
, div
.compact div
{
252 margin-bottom: 0.1em;
255 div
.tableblock
> table
{
256 border: 3px solid
#527bbd;
259 font-family: sans-serif
;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div
.tableblock
> table
[frame
="void"] {
275 div
.tableblock
> table
[frame
="hsides"] {
276 border-left-style: none
;
277 border-right-style: none
;
279 div
.tableblock
> table
[frame
="vsides"] {
280 border-top-style: none
;
281 border-bottom-style: none
;
287 margin-bottom: 0.8em;
290 padding-bottom: 15px;
292 dt
.hdlist1
.strong
, td
.hdlist1
.strong
{
298 padding-right: 0.8em;
304 div
.hdlist
.compact tr
{
314 div#footer-badges
{ display: none
; }
319 font-family: sans-serif
;
323 margin-bottom: 0.1em;
326 div
.toclevel1
, div
.toclevel2
, div
.toclevel3
, div
.toclevel4
{
342 /* Workarounds for IE6's broken and incomplete CSS2. */
344 div
.sidebar-content
{
346 border: 1px solid silver
;
349 div
.sidebar-title
, div
.image-title
{
351 font-family: sans-serif
;
354 margin-bottom: 0.5em;
357 div
.listingblock div
.content
{
358 border: 1px solid silver
;
363 div
.quoteblock-attribution
{
368 div
.verseblock-content
{
371 div
.verseblock-attribution
{
376 div
.exampleblock-content
{
377 border-left: 2px solid silver
;
381 /* IE6 sets dynamically generated links as visited. */
382 div#toc
a:visited
{ color: blue
; }
384 <script type=
"text/javascript">
386 window
.onload = function(){generateToc(2)}
387 /* Author: Mihai Bazon, September 2002
388 * http://students.infoiasi.ro/~mishoo
390 * Table Of Content generator
393 * Feel free to use this script under the terms of the GNU General Public
394 * License, as long as you do not remove or alter this notice.
397 /* modified by Troy D. Hanson, September 2006. License: GPL */
398 /* modified by Stuart Rackham, October 2006. License: GPL */
400 function getText(el
) {
402 for (var i
= el
.firstChild
; i
!= null; i
= i
.nextSibling
) {
403 if (i
.nodeType
== 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
405 else if (i
.firstChild
!= null)
411 function TocEntry(el
, text
, toclevel
) {
414 this.toclevel
= toclevel
;
417 function tocEntries(el
, toclevels
) {
418 var result
= new Array
;
419 var re
= new RegExp('[hH]([2-'+(toclevels
+1)+'])');
420 // Function that scans the DOM tree for header elements (the DOM2
421 // nodeIterator API would be a better technique but not supported by all
423 var iterate = function (el
) {
424 for (var i
= el
.firstChild
; i
!= null; i
= i
.nextSibling
) {
425 if (i
.nodeType
== 1 /* Node.ELEMENT_NODE */) {
426 var mo
= re
.exec(i
.tagName
)
428 result
[result
.length
] = new TocEntry(i
, getText(i
), mo
[1]-1);
437 // This function does the work. toclevels = 1..4.
438 function generateToc(toclevels
) {
439 var toc
= document
.getElementById("toc");
440 var entries
= tocEntries(document
.getElementsByTagName("body")[0], toclevels
);
441 for (var i
= 0; i
< entries
.length
; ++i
) {
442 var entry
= entries
[i
];
443 if (entry
.element
.id
== "")
444 entry
.element
.id
= "toc" + i
;
445 var a
= document
.createElement("a");
446 a
.href
= "#" + entry
.element
.id
;
447 a
.appendChild(document
.createTextNode(entry
.text
));
448 var div
= document
.createElement("div");
450 div
.className
= "toclevel" + entry
.toclevel
;
451 toc
.appendChild(div
);
453 if (entries
.length
== 0)
454 document
.getElementById("header").removeChild(toc
);
461 <h1>FreeFOAM Installation Instructions for Version
0.1.0</h1>
462 <span id=
"author">Michael Wild
</span><br />
463 <span id=
"email"><tt><<a href=
"mailto:themiwi@users.sourceforge.net">themiwi@users.sourceforge.net
</a>></tt></span><br />
464 <span id=
"revnumber">version
0.1.0,
</span>
465 <span id=
"revdate">25 May
2009</span>
467 <div id=
"toctitle">Table of Contents
</div>
468 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.
</b></p></noscript>
472 <div class=
"sectionbody">
473 <div class=
"paragraph"><p><a href=
"http://freefoam.sourceforge.net">http://freefoam.sourceforge.net
</a></p></div>
476 <h2 id=
"_building_freefoam">1. Building FreeFOAM
</h2>
477 <div class=
"sectionbody">
478 <div class=
"ulist"><ul>
481 Install the prerequisites documented in the
<a href=
"README.html">README
</a> file. If
482 your distribution does not have
<em>METIS
</em>,
<em>ParMetis
</em>,
<em>MGRIDGEN
</em> or
<em>libccmio
</em>
483 be not worried, FreeFOAM can handle those for you.
488 Download the FreeFOAM source and unpack it somewhere convenient. For the
489 further instructions we will use
<tt>$HOME/Source/
</tt>.
491 <div class=
"listingblock">
492 <div class=
"content">
493 <pre><tt>$ mkdir -p $HOME/Source
495 $ wget http://switch.dl.sourceforge.net/sourceforge/freefoam/freefoam-
0.1.0rc3.tar.bz2
496 $ tar xjf freefoam-
0.1.0rc3.tar.bz2
</tt></pre>
501 Create a build tree and
<em>cd
</em> into it:
503 <div class=
"listingblock">
504 <div class=
"content">
505 <pre><tt>$ mkdir $HOME/Source/freefoam-
0.1.0rc3-build
506 $ cd $HOME/Source/freefoam-
0.1.0rc3-build
</tt></pre>
511 Start CMake-configuration:
513 <div class=
"listingblock">
514 <div class=
"content">
515 <pre><tt>$ ccmake $HOME/Source/freefoam-
0.1.0rc3
</tt></pre>
520 Press the
<tt>c
</tt> key. Use the arrow keys to navigate up and down and press
521 <tt>enter
</tt> to edit a field. To commit the change, press
<tt>enter
</tt> again, or
<tt>ESC
</tt>
522 to abandon the change. ON/OFF fields are toggled by pressing
<tt>enter
</tt>.
523 Advanced options can be displayed by hitting the
<tt>t
</tt> key.
525 <div class=
"ulist"><ul>
528 Set
<tt>CMAKE_BUILD_TYPE
</tt> to
<em>Release
</em> for an optimized build.
533 If CMake complains that it can
’t find MPI, and you don
’t want to install it, disable
534 <tt>FF_USE_MPI
</tt>. If, instead, you want to use GAMMA or PVM, enable
<tt>FF_USE_GAMMA
</tt> or
535 <tt>FF_USE_PVM
</tt>, respectively. You can also enable more than one of the options.
537 <div class=
"admonitionblock">
540 <div class=
"title">Note
</div>
542 <td class=
"content">Currently only MPI implementation is available.
</td>
548 Select the default Pstream implementation by setting
<tt>FF_DEFAULT_PSTREAM
</tt>
549 to one of
<em>dummy
</em>,
<em>mpi
</em>,
<em>pvm
</em> or
<em>gamma
</em>. This setting will only influence
550 the contents of the
<a href=
"#globalconfig">global
<em>controlDict
</em> file
</a>.
555 If CMake told you it couldn
’t find ParaView:
557 <div class=
"olist arabic"><ol class=
"arabic">
560 Set
<tt>ParaView_DIR
</tt> to the path of the directory containing
561 <em>ParaViewConfig.cmake
</em>, which is most likely the ParaView build directory.
566 If you do not want to build the ParaView plug-ins, disable
567 <tt>FF_BUILD_PARAVIEW_PLUGINS
</tt>
574 If you do not have
<em>METIS
</em> or
<em>ParMetis
</em>, enable
575 <tt>FF_BUILD_PRIVATE_METIS
</tt> or
<tt>FF_BUILD_PRIVATE_PARMETIS
</tt>, respectively.
576 CMake will then try to download and build the selected libraries for you.
577 Conversely, if one of the libraries is provided by your system, you can turn
578 the respective setting to
<em>OFF
</em>. Please note that if your system provides
579 only
<em>ParMetis
</em>, you do not have to install
<em>METIS
</em>, as the former also
580 contains
<em>METIS
</em> in an older version.
585 If you want to use the
<em>MGridGen
</em> agglomeration method for the GAMG solver,
586 you need to enable
<tt>FF_ENABLE_PARMGRIDGEN
</tt> and if the library is not
587 installed on your system ensure that
<tt>FF_BUILD_PRIVATE_PARMGRIDGEN
</tt> is
588 enabled. See
<a href=
"#parmgridgen">above
</a> regarding the unknown license status of
594 In order to build
<em>ccm26ToFoam
</em>, a conversion utility for grids generated
595 with
<em>ProStar/ccm
</em> © version
2.6, enable the setting
<tt>FF_ENABLE_CCMIO
</tt>
596 and if
<em>libccmio
</em> is not installed on your system, also
597 <tt>FF_BUILD_PRIVATE_CCMIO
</tt>. Refer to the
<a href=
"#libccmio">above
</a> description of
598 the
<em>libccmio
</em> package for the license restrictions which apply to this
604 If you plan on installing FreeFOAM, set
<tt>CMAKE_INSTALL_PREFIX
</tt> to the base directory
605 under which FreeFOAM should reside.
610 For more fine-grained control over what gets installed where, adjust
611 <tt>FF_INSTALL_CONFIG_PATH
</tt>,
<tt>FF_INSTALL_HEADER_PATH
</tt>,
<tt>FF_INSTALL_LIB_PATH
</tt>,
612 <tt>FF_INSTALL_FRAMEWORK_PATH
</tt>,
<tt>FF_INSTALL_PV3FOAMREADER_PATH
</tt>,
613 <tt>FF_INSTALL_PVFOAMREADER_PATH
</tt> and
<tt>FF_INSTALL_USERDFOAM_PATH
</tt>. Paths not
614 starting with a slash (
<em>/
</em>) will be relative to
<em>CMAKE_INSTALL_PREFIX
</em>. If
615 you include a leading slash, the paths are absolute.
620 If you want FreeFOAM to use
<em>float
</em> as the floating point type instead of
621 <em>double
</em>, change
<tt>FF_DOUBLE_PRECISION
</tt> to
<em>OFF
</em>.
628 Hit the
<tt>c
</tt> key again. If you enabled
<tt>FF_BUILD_PRIVATE_CCMIO
</tt>, CMake will fail
629 to download
<a href=
"https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz">https://wci.llnl.gov/codes/visit/
3rd_party/libccmio-
2.6.1.tar.gz
</a>.
630 Please follow the instructions in the error message on how to work around this
631 problem, or download the file manually and place it in
<tt>ThirdParty/ccmio/
</tt>
632 (relative to the build directory). Then hit
<tt>c
</tt> again.
637 You shouldn
’t get any errors anymore now. Keep pressing
<tt>c
</tt> until ccmake
638 displays
"<tt>Press [g] to generate and exit</tt>" in the legend at the bottom of
644 Press
<tt>g
</tt> to generate the Makefiles and exit the ccmake interface.
649 Start the native build tool. If you used the
<em>Makefile
</em> generator
650 (which is the default for Unix-platforms), type
652 <div class=
"listingblock">
653 <div class=
"content">
654 <pre><tt>$ make
</tt></pre>
659 If you have a multi-core/processor machine, you can speed things up
660 significantly by telling Make to run independent jobs in parallel.
661 A good choice for the number of parallel jobs to run is the
662 number of CPU
’s/cores you have in your machine plus
1 (to compensate
663 for disk-latency). For a typical dual-core machine, run
665 <div class=
"listingblock">
666 <div class=
"content">
667 <pre><tt>$ make -j3
</tt></pre>
672 <h2 id=
"_installing_freefoam">2. Installing FreeFOAM
</h2>
673 <div class=
"sectionbody">
674 <div class=
"paragraph"><p>If you want to, you can now install FreeFOAM. Depending on the
675 <tt>CMAKE_INSTALL_PREFIX
</tt> and the individual
<tt>FF_INSTALL_*_PATH
</tt> it is possible
676 that you have to do this as root, i.e. use
<tt>su
</tt> or
<tt>sudo
</tt>.
</p></div>
677 <div class=
"listingblock">
678 <div class=
"content">
679 <pre><tt>$ make install
</tt></pre>
682 <h2 id=
"_using_freefoam">3. Using FreeFOAM
</h2>
683 <div class=
"sectionbody">
684 <div class=
"paragraph"><p>If you didn
’t change
<tt>CMAKE_INSTALL_PREFIX
</tt> and
<tt>FF_INSTALL_BIN_PATH
</tt> chances
685 are that you can start using FreeFOAM right after you installed it without any
686 further steps being necessary.
</p></div>
687 <h3 id=
"globalconfig">3.1. Global Configuration Files
</h3><div style=
"clear:left"></div>
688 <div class=
"paragraph"><p>Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
689 applications require some files to be present for start-up. It finds those
690 in the following places (in the specified order, picking the first hit):
</p></div>
691 <div class=
"olist arabic"><ol class=
"arabic">
694 Under the directory specified in the
<tt>$FREEFOAM_CONFIG_DIR
</tt> environment
700 In
<em>$HOME/.FreeFOAM/
0.1</em>
705 In
<em>$HOME/.FreeFOAM
</em>
710 In the installation directory of the configuration files. There are
711 two possible places for this:
713 <div class=
"dlist"><dl>
715 <em><CMAKE_INSTALL_PREFIX
>/
<FF_INSTALL_CONFIG_PATH
></em>
720 <tt><FF_INSTALL_CONFIG_PATH
></tt> as a relative path.
724 <em><FF_INSTALL_CONFIG_PATH
></em>
728 if you specified
<tt><FF_INSTALL_CONFIG_PATH
></tt> as
731 <div class=
"paragraph"><p>The default location is
<em>/usr/local/etc/FreeFOAM/
0.1.0</em>.
</p></div>
736 <h3 id=
"_selecting_the_parallel_communications_library">3.2. Selecting the Parallel Communications Library
</h3><div style=
"clear:left"></div>
737 <div class=
"paragraph"><p>Both, FreeFOAM and OpenFOAM abstract the parallel operations into the
<em>Pstream
</em>
738 library, making it rather simple to firstly switch between parallel
739 implementations and secondly port the software to a new communications library.
740 However, FreeFOAM uses a much more flexible mechanism of determining which
741 <em>Pstream
</em> implementation library to use than OpenFOAM. The latter does this by
742 adjusting the
<tt>LD_LIBRARY_PATH
</tt> environment variable. As FreeFOAM wants to be a
743 well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically
744 loads the desired
<em>Pstream
</em> library at startup (i.e. as a plug-in). The
745 following list details how FreeFOAM determines what library to load (if at all):
</p></div>
746 <div class=
"olist arabic"><ol class=
"arabic">
749 If the environment variable
<tt>FREEFOAM_PSTREAM_LIBRARY
</tt> is set,
750 FreeFOAM will try to load the library specified by it.
755 If the sub-dictionary
<tt>PstreamImplementation
</tt> exists in the global
756 <em>controlDict
</em> file (see
<a href=
"#globalconfig"><em>Global Configuration Files
</em></a>), it
757 reads the value of the entry
<tt>configName
</tt> therein. It then expects that a
758 sub-dictionary of
<tt>PstreamImplementation
</tt> with the name specified in
759 <tt>configName
</tt> exists. If that sub-dictionary contains the entry
<tt>library
</tt>, it
760 will try to load a library specified by the value of that entry.
764 <div class=
"paragraph"><p>After FreeFOAM (possibly) loaded the library, it will try to instantiate
765 concrete implementations of the abstract base classes
<tt>PstreamImpl
</tt>,
766 <tt>IPstreamImpl
</tt> and
<tt>OPstreamImpl
</tt>. Which classes are to be instantiated
767 is determined as follows:
</p></div>
768 <div class=
"olist arabic"><ol class=
"arabic">
771 FreeFOAM queries the environment variables
<tt>FREEFOAM_PSTREAM_CLASS
</tt>,
772 <tt>FREEFOAM_IPSTREAM_CLASS
</tt> and
<tt>FREEFOAM_OPSTREAM_CLASS
</tt> for the class
773 names to be instantiated.
778 For any of the variables not set, it requires the sub-dictionary
779 <tt>PstreamImplementation
</tt> to be present in the global
<em>controlDict
</em>, reads the
780 value of
<tt>configName
</tt> and similarly to the library loading, loads the
781 sub-dictionary specified by that value. It then expects to find the entries
782 <tt>Pstream
</tt>,
<tt>IPstream
</tt> and
<tt>OPstream
</tt> which specify the names of the classes
787 <div class=
"paragraph"><p>This means that one can create a global
<em>controlDict
</em> file containing
788 (among other things) something like the following:
</p></div>
789 <div class=
"exampleblock">
790 <div class=
"exampleblock-content">
791 <div class=
"listingblock">
792 <div class=
"content">
793 <pre><tt>PstreamImplementation
800 library libdummyPstream.so;
801 Pstream dummyPstreamImpl;
802 OPstream dummyOPstreamImpl;
803 IPstream dummyIPstreamImpl;
808 library libmpiPstream.so;
809 Pstream mpiPstreamImpl;
810 OPstream mpiOPstreamImpl;
811 IPstream mpiIPstreamImpl;
816 <div class=
"paragraph"><p>This way the administrator can provide a global
<em>controlDict
</em> in the FreeFOAM
817 installation. Every user can then override that
<em>controlDict
</em> by supplying her
818 own file in her home directory as detailed in
<a href=
"#globalconfig"><em>Global Configuration Files
</em></a>. In order to select a particular
<em>Pstream
</em> implementation
819 for a specific communications library, the user can then either adjust the
820 <tt>PstreamImplementation::configName
</tt> entry in the global
<em>controlDict
</em> file, set
821 the
<tt>FREEFOAM_PSTREAM_CONFIG
</tt> variable or for full control, set the variables
822 <tt>FREEFOAM_PSTREAM_LIBRARY
</tt>,
<tt>FREEFOAM_PSTREAM_CLASS
</tt>,
<tt>FREEFOAM_IPSTREAM_CLASS
</tt>
823 and
<tt>FREEFOAM_OPSTREAM_CLASS
</tt>.
</p></div>
824 <h3 id=
"_running_freefoam_from_the_build_tree">3.3. Running FreeFOAM From the Build Tree
</h3><div style=
"clear:left"></div>
825 <div class=
"paragraph"><p>You can use FreeFOAM without installing it first, directly from the build tree.
826 However, this might take a little bit more effort to set up because most likely
827 you will have to adjust the following environment variables:
</p></div>
828 <div class=
"dlist"><dl>
834 Must contain
<em>$HOME/Source/freefoam-
0.1.0rc3-build/bin
</em>
842 Must contain
<em>$HOME/Source/freefoam-
0.1.0rc3-build/lib/FreeFOAM-
0.1.0</em>
850 Should point to
<em>$HOME/Source/freefoam-
0.1.0rc3-build/etc
</em>
854 <div class=
"paragraph"><p>Where it is assumed that you followed the
<a href=
"#installation">installation instructions
</a>. If
855 you used different paths for downloading and compiling FreeFOAM, you will have
856 to adjust these names. Refer to
<a href=
"#environment"><em>Extending Search Paths And Setting Environment Variables Permanently
</em></a> if you need help setting these
859 <h2 id=
"_running_the_tutorials">4. Running the tutorials
</h2>
860 <div class=
"sectionbody">
861 <div class=
"paragraph"><p>Now you should be able to run the tutorial cases. For this copy the
<tt>tutorials
</tt>
862 directory to some convenient place:
</p></div>
863 <div class=
"listingblock">
864 <div class=
"content">
865 <pre><tt>$ mkdir -p $HOME/FreeFOAM/$LOGNAME-
0.1/run
866 $ cp -r $HOME/Source/freefoam-
0.1.0rc3-build/tutorials $HOME/FreeFOAM/$LOGNAME-
0.1/run/
867 $ cd $HOME/FreeFOAM/$LOGNAME-
0.1/run
</tt></pre>
869 <div class=
"paragraph"><p>And try to run e.g. the
<em>cavity
</em> tutorial case:
</p></div>
870 <div class=
"listingblock">
871 <div class=
"content">
872 <pre><tt>$ cd icoFoam
873 $ blockMesh -case cavity
874 $ checkMesh -case cavity
875 $ icoFoam -case cavity
</tt></pre>
877 <div class=
"paragraph"><p>Things should run smoothly and finish without an error.
</p></div>
879 <h2 id=
"_obtaining_the_source_code_from_the_git_repository">5. Obtaining the Source Code from the GIT repository
</h2>
880 <div class=
"sectionbody">
881 <div class=
"ulist"><ul>
884 Clone the FreeFOAM repository (here the clone is placed in
885 <tt>$HOME/Source/FreeFOAM
</tt>):
887 <div class=
"listingblock">
888 <div class=
"content">
889 <pre><tt>$ mkdir -p $HOME/Source
890 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM
</tt></pre>
895 Proceed in the same way (replacing the path names apropriately) as in the
896 above build instructions.
901 <h2 id=
"_build_configuration_reference">6. Build Configuration Reference
</h2>
902 <div class=
"sectionbody">
903 <div class=
"dlist glossary"><dl>
905 <tt>CMAKE_BUILD_TYPE
</tt>
909 One of
<em><empty
></em>,
<em>Debug
</em>,
<em>Release
</em>,
<em>RelWithDebInfo
</em> and
<em>MinSizeRel
</em>.
910 Refer to the CMake documentation for more detail.
914 <tt>FF_DOUBLE_PRECISION
</tt>
918 If set to
<em>ON
</em> FreeFOAM will be compiled using
<em>double
</em> as the
919 floating point type. If set to
<em>OFF
</em> it will use
<em>float
</em>.
923 <tt>FF_BUILD_FRAMEWORK
</tt>
927 If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
931 <tt>CMAKE_INSTALL_PREFIX
</tt>
935 Installation prefix under which to install FreeFOAM.
939 <tt>FF_INSTALL_BIN_PATH
</tt>
943 Installation path of the binaries. If not absolute, it is relative to
944 <em>CMAKE_INSTALL_PREFIX
</em>.
948 <tt>FF_INSTALL_CONFIG_PATH
</tt>
952 Installation path of the configuration files. If not absolute, it is
953 relative to
<em>CMAKE_INSTALL_PREFIX
</em>.
957 <tt>FF_INSTALL_HEADER_PATH
</tt>
961 Installation path of the header files. If not absolute, it is
962 relative to
<em>CMAKE_INSTALL_PREFIX
</em>. On Mac OS X, and if
963 <em>FF_BUILD_FRAMEWORK
</em> is enabled, this setting is ignored.
967 <tt>FF_INSTALL_LIB_PATH
</tt>
971 Installation path of the libraries. If not absolute, it is
972 relative to
<em>CMAKE_INSTALL_PREFIX
</em>.
976 <tt>FF_INSTALL_FRAMEWORK_PATH
</tt>
980 Installation path of the Mac OS X frameworks. If not absolute, it is
981 relative to
<em>CMAKE_INSTALL_PREFIX
</em>. This is only available and takes
982 effect if FreeFOAM is compiled on Mac OS X, and if
983 <em>FF_BUILD_FRAMEWORK
</em> is enabled.
987 <tt>FF_INSTALL_PV3FOAMREADER_PATH
</tt>
991 Installation path of the ParaView3 plug-ins. If not absolute, it is
992 relative to
<em>CMAKE_INSTALL_PREFIX
</em>.
996 <tt>FF_INSTALL_PVFOAMREADER_PATH
</tt>
1000 Installation path of the ParaView2 plug-ins. If not absolute, it is
1001 relative to
<em>CMAKE_INSTALL_PREFIX
</em>.
1005 <tt>FF_INSTALL_USERDFOAM_PATH
</tt>
1009 Installation path of the Ensight plug-in. If not absolute, it is
1010 relative to
<em>CMAKE_INSTALL_PREFIX
</em>.
1014 <tt>EXECUTABLE_PREFIX
</tt>
1018 Prefix which get prepended to the name of the executables. This defaults to
1019 <em>ff_
</em> and serves the disambiguation of names.
1023 <tt>FF_USE_GAMMA
</tt>
1027 If enabled, FreeFOAM will use the GAMMA parallel communications library.
1035 If enabled, FreeFOAM will use the MPI parallel communications library.
1036 This is required in order to build some of the libraries and utilities.
1044 If enabled, FreeFOAM will use the PVM parallel communications library.
1048 <tt>FF_DEFAULT_PSTREAM
</tt>
1052 The default Pstream selection in the global
<em>controlDict
</em> file.
1056 <tt>FF_BUILD_PARAVIEW_PLUGINS
</tt>
1060 Whether to build the ParaView plug-ins. If enabled, FreeFOAM requires a
1061 ParaView build tree and the
<em>ParaView_DIR
</em> variable set to the path of it.
1065 <tt>FF_ENABLE_CCMIO
</tt>
1069 Enable the use of
<em>libccmio
</em>. This is required to build the grid conversion
1070 utility
<em>ccm26ToFoam
</em>.
1072 <div class=
"admonitionblock" id=
"enable-ccmio">
1075 <div class=
"title">Warning
</div>
1077 <td class=
"content">The license of
<em>libccmio
</em> © is proprietary and requires the consent of the
1078 copyright holders (
<a href=
"http://www.cd-adapco.com">CD-adapco
</a>) to download and use the
1079 library. Further it is not allowed to redistribute it in any form. The request
1080 for permission of inclusion with
<a href=
"http://debian.org">Debian
</a> was answered as
1081 follows by
<a href=
"mailto:geoffrey.prewett@us.cd-adapco.com">Geoffrey Prewett
</a>:
</td>
1084 <div class=
"listingblock">
1085 <div class=
"content">
1088 Sorry for the delay in response. I checked back with our development director,
1089 and he felt that it would be best to not include libccmio with Debian.
1090 Instead, we would prefer to continue our current policy and keep it on our
1091 web/FTP and have people ask for it. There are three reasons for this:
1093 1) We don't support STAR on Debian, and don't want to give the impression that we do.
1094 2) We would like to keep a list of people that we give the library to.
1095 3) This is not a general purpose library; its sole purpose is to communicate
1096 between our products. Accepting outside changes risks committing a change that
1097 would break our own software in possibly subtle ways.
1099 So I regret to tell you that my company has declined to permit libccmio to be
1100 distributed as part of Debian.
1103 Geoff Prewett
</tt></pre>
1107 <tt>FF_BUILD_PRIVATE_CCMIO
</tt>
1111 Automatically download and build libccmio. Unfortunately this process will
1112 fail in the download step, since CMake currently does not support
<em>https
</em>
1113 URLs. But you will get specific instructions from the build system on how to
1114 get around this problem.
1118 <tt>FF_BUILD_PRIVATE_METIS
</tt>
1122 Automatically download and build
<em>METIS
</em>.
1126 <tt>FF_BUILD_PRIVATE_PARMETIS
</tt>
1130 Automatically download and build
<em>ParMetis
</em>.
1134 <tt>FF_ENABLE_PARMGRIDGEN
</tt>
1138 Enable the use of
<em>PARMGRIDGEN
</em> and
<em>MGRIDGEN
</em> which is required to build
1139 <em>MGridGenGamgAgglomeration
</em> providing the
<em>MGridGen
</em> agglomeration method for
1142 <div class=
"admonitionblock" id=
"enable-parmgridgen">
1145 <div class=
"title">Warning
</div>
1147 <td class=
"content">The license of
<em>MGRIDGEN
</em> and
<em>PARMGRIDGEN
</em> is unknown and the upstream authors
1148 so far have not answered any inquiries to resolve the issue. If you enable the
1149 use of
<em>MGRIDGEN
</em> and
<em>PARMGRIDGEN
</em> you alone are responsible for ensuring that
1150 you don
’t violate any license conditions applying to these libraries. The
1151 authors of FreeFOAM will and cannot take any responsibility for your
1157 <tt>FF_BUILD_PRIVATE_PARMGRIDGEN
</tt>
1161 Automatically download and build
<em>PARMGRIDGEN
</em> and
<em>MGRIDGEN
</em>.
1165 <tt>FF_BUILD_DOXYGEN_DOCS
</tt>
1169 Enable building of the
<em>Doxygen API documentation
</em>. The documentation will
1170 only be built once and is not updated automatically. This is because it
1171 depends on a huge number of files and would make dependency tracking very
1172 slow and difficult to maintain. To force the re-generation of the API
1173 documentation execute
<tt>make apidoc
</tt>.
1178 <h2 id=
"_troubleshooting">7. Troubleshooting
</h2>
1179 <div class=
"sectionbody">
1180 <h3 id=
"_the_freefoam_executables_are_not_found_by_the_shell">7.1. The FreeFOAM Executables Are Not Found By The Shell
</h3><div style=
"clear:left"></div>
1181 <div class=
"paragraph"><p>There are three possible reasons for this:
</p></div>
1182 <div class=
"olist arabic"><ol class=
"arabic">
1185 Your shell (notably
<em>csh
</em>,
<em>tcsh
</em> and
<em>zsh
</em>) requires you to refresh the
1186 cache of available executables. You can do so by entering the command:
1188 <div class=
"listingblock">
1189 <div class=
"content">
1190 <pre><tt>$ rehash
</tt></pre>
1195 If
<em>rehashing
</em> didn
’t solve the problem, the problem most likely is that you
1196 installed FreeFOAM into a non-standard location by changing the configuration
1197 variables
<tt>CMAKE_INSTALL_PREFIX
</tt> or
<tt>FF_INSTALL_BIN_PATH
</tt> in which case the
1198 executables where installed into a directory not searched by the shell. In
1199 this case you have to add the installation directory of the executables to
1200 the
<tt>PATH
</tt> variable. There are two possible locations:
1202 <div class=
"dlist"><dl>
1203 <dt class=
"hdlist1">
1204 <em><CMAKE_INSTALL_PREFIX
>/
<FF_INSTALL_BIN_PATH
></em>
1209 <tt>FF_INSTALL_BIN_PATH
</tt> as a relative path
1212 <dt class=
"hdlist1">
1213 <em><FF_INSTALL_BIN_PATH
></em>
1217 if you specified
<tt>FF_INSTALL_BIN_PATH
</tt> as an absolute
1222 <div class=
"paragraph"><p>After extending the
<tt>PATH
</tt> variable with the installation directory of the
1223 executables, you should be able to run all FreeFOAM applications as any other
1224 binary available on the system. See
<a href=
"#environment"><em>Extending Search Paths And Setting Environment Variables Permanently
</em></a> for
1225 instructions on how to extend the search path.
</p></div>
1229 This option is similar to the previous solution and applies if you want to
1230 run FreeFOAM from the build tree (i.e. without running
<tt>make install
</tt>). In
1231 this case you again have to make sure that your shell finds the executables
1232 built by CMake by extending the
<tt>PATH
</tt> variable. Further, you have to tell
1233 FreeFOAM where to find the global configuration files (see
1234 <a href=
"#globalconfig"><em>Global Configuration Files
</em></a>). Here, you have the option to
1235 place the files under your home directory or set an environment variable. The
1236 former can be achieved by:
1238 <div class=
"listingblock">
1239 <div class=
"content">
1240 <pre><tt>$ mkdir -p $HOME/.FreeFOAM/
0.1
1241 $ cp $HOME/Source/freefoam-
0.1.0rc3-build/etc/controlDict $HOME/.FreeFOAM/
0.1
1242 $ cp $HOME/Source/freefoam-
0.1.0rc3-build/etc/cellModels $HOME/.FreeFOAM/
0.1
1243 $ cp -r $HOME/Source/freefoam-
0.1.0rc3-build/etc/thermoData $HOME/.FreeFOAM/
0.1</tt></pre>
1245 <div class=
"paragraph"><p>The latter (and recommended) method is to set the environment variable
1246 <tt>FREEFOAM_CONFIG_DIR
</tt> to
<em>$HOME/Source/freefoam-
0.1.0rc3-build/etc
</em>. Adjust paths to the
1247 build tree to your actual setup.
</p></div>
1250 <h3 id=
"_starting_any_freefoam_application_fails_because_some_libraries_cannot_be_found">7.2. Starting Any FreeFOAM Application Fails Because Some Libraries Cannot Be Found
</h3><div style=
"clear:left"></div>
1251 <div class=
"paragraph"><p>Although CMake should have taken care of this by using
<tt>RPATH
</tt> on Linux and
1252 <tt>install_name
</tt> on Mac OS X, it might be necessary on some systems to adjust the
1253 library search paths:
</p></div>
1254 <div class=
"dlist"><dl>
1255 <dt class=
"hdlist1">
1256 <tt>LD_LIBRARY_PATH
</tt>
1260 This variable is used by all Unix like systems (e.g. Linux,
1264 <dt class=
"hdlist1">
1265 <tt>DYLD_LIBRARY_PATH
</tt>
1269 This variable is used by Mac OS X.
1273 <div class=
"paragraph"><p>If you installed FreeFOAM, there are (as with the executables), two possible
1274 installation directories:
</p></div>
1275 <div class=
"dlist"><dl>
1276 <dt class=
"hdlist1">
1277 <em><CMAKE_INSTALL_PREFIX
>/
<FF_INSTALL_LIB_PATH
></em>
1282 <tt>FF_INSTALL_LIB_PATH
</tt> as a relative path.
1285 <dt class=
"hdlist1">
1286 <em><FF_INSTALL_LIB_PATH
></em>
1290 if you specified
<tt>FF_INSTALL_LIB_PATH
</tt> as an absolute
1295 <div class=
"paragraph"><p>If you are trying to run from the build tree, you have to include
1296 <em>$HOME/Source/freefoam-
0.1.0rc3-build/lib/FreeFOAM-
0.1.0</em> in the above mentioned search
1297 paths (where you have to adjust the location of the build tree to your actual
1299 <h3 id=
"_a_running_freefoam_application_aborts_because_it_can_8217_t_em_dlopen_em_a_library">7.3. A Running FreeFOAM Application Aborts Because It Can
’t
<em>dlopen
</em> A Library
</h3><div style=
"clear:left"></div>
1300 <div class=
"paragraph"><p>FreeFOAM (and OpenFOAM) often dynamically load libraries at run-time (a.k.a
1301 plug-ins) to add features the user requested without requiring that the whole
1302 application be recompiled. This makes it very simple to add new boundary
1303 conditions, turbulence and combustion models etc. However, it also requires that
1304 FreeFOAM must be able to find these libraries at run-time. The operating system
1305 function which does the loading of the libraries (
<em>dlopen
</em>) usually tries to
1306 find the library with the given name in several places; namely a default search
1307 path and a search path configured by one or multiple environment variables such
1308 as
<tt>LD_LIBRARY_PATH
</tt> or
<tt>DYLD_LIBRARY_PATH
</tt> (on Mac OS X). The details vary from
1309 platform to platform, so you best consult the documentation of
<em>dlopen
</em> for the
1311 <div class=
"paragraph"><p>Additionally FreeFOAM allows you to configure a custom search path for plug-ins
1312 in the
<a href=
"#globalconfig">global
<em>controlDict
</em></a> file by listing the directories to
1313 be searched in the list
<tt>LibrarySearchPaths
</tt>. By default FreeFOAM is configured
1314 to search for plug-ins in the location where CMake installed them.
</p></div>
1315 <div class=
"paragraph"><p>If you want to add your own plug-in libraries (e.g. you want to add your own
1316 boundary conditions class), you most probably will want to extend this search
1319 <h2 id=
"environment">8. Extending Search Paths And Setting Environment Variables Permanently
</h2>
1320 <div class=
"sectionbody">
1321 <div class=
"paragraph"><p>The way one sets environment variables and extends the executable and library
1322 search paths permanently strongly depends on the shell used. Usually one has to
1323 create or change an initialization file in the users home directory. In the
1324 following this will be discussed very briefly for the popular shells
<em>BASH
</em> and
1325 <em>tcsh
</em>. However, if you need more help or want information on using the shell,
1326 there is an excellent tutorial available at
<a href=
"http://linuxcommand.org">http://linuxcommand.org
</a>.
</p></div>
1327 <h3 id=
"_bash">8.1. BASH
</h3><div style=
"clear:left"></div>
1328 <div class=
"paragraph"><p>The BASH shell is the default shell for most Linux/Unix distributions. Most
1329 systems configure the BASH shell such that it reads the text file
1330 <em>$HOME/.bashrc
</em> when starting up, so this is the place where one appends
1331 customizations of the environment variables. On some systems this file is not
1332 processed by default (notably Mac OS X). In this case you can use
1333 <em>$HOME/.bash_profile
</em>.
</p></div>
1334 <h4 id=
"_referencing_a_variable">8.1.1. Referencing A Variable
</h4>
1335 <div class=
"paragraph"><p>To retrieve the value stored in a shell variable or environment variable, one
1336 prefixes its name with the dollar (
<tt>$
</tt>) character.
</p></div>
1337 <h4 id=
"_setting_a_variable">8.1.2. Setting A Variable
</h4>
1338 <div class=
"paragraph"><p>The syntax for setting a variable and making it available to child-processes of
1339 the shell is the following:
</p></div>
1340 <div class=
"listingblock">
1341 <div class=
"content">
1342 <pre><tt>$ export variable_name=variable_value
</tt></pre>
1344 <div class=
"paragraph"><p>Note that no white-space characters are allowed surrounding the
<tt>=
</tt> sign.
</p></div>
1345 <h4 id=
"_extending_a_search_path">8.1.3. Extending A Search Path
</h4>
1346 <div class=
"paragraph"><p>The shell and other Unix system facilities use environment variables to locate
1347 executables and dynamically linked libraries. These search paths consist of
1348 strings naming directories in which the executables and libraries should be
1349 searched for. The individual paths are separated by a colon (
<tt>:
</tt>) character. To
1350 add the e.g. the directory
<em>$HOME/bin
</em> to the search path for executables, one
1351 would do the following:
</p></div>
1352 <div class=
"listingblock">
1353 <div class=
"content">
1354 <pre><tt>$ export PATH=$PATH:$HOME/bin
</tt></pre>
1356 <div class=
"paragraph"><p>which appends
<em>$HOME/bin
</em> to the end of the
<tt>PATH
</tt> variable.
</p></div>
1357 <h3 id=
"_tcsh">8.2. TCSH
</h3><div style=
"clear:left"></div>
1358 <div class=
"paragraph"><p>Some users and administrators prefer to use a
<em>C-Shell
</em>, such as the TCSH. Here
1359 you can use e.g. the file
<em>$HOME/.tcshrc
</em> to customize the environment.
</p></div>
1360 <h4 id=
"_referencing_a_variable_2">8.2.1. Referencing A Variable
</h4>
1361 <div class=
"paragraph"><p>As with the BASH, one retrieves the value stored in a shell variable or
1362 environment variable by prefixing its name with the dollar (
<tt>$
</tt>) character.
1363 Sometimes it is also necessary to protect the variable name by surrounding it
1364 with curly braces (
<tt>{
</tt> and
<tt>}
</tt>).
</p></div>
1365 <h4 id=
"_setting_a_variable_2">8.2.2. Setting A Variable
</h4>
1366 <div class=
"paragraph"><p>The syntax for setting a variable and making it available to child-processes of
1367 the shell is the following:
</p></div>
1368 <div class=
"listingblock">
1369 <div class=
"content">
1370 <pre><tt>$ setenv variable_name variable_value
</tt></pre>
1372 <h4 id=
"_extending_a_search_path_2">8.2.3. Extending A Search Path
</h4>
1373 <div class=
"paragraph"><p>The shell and other Unix system facilities use environment variables to locate
1374 executables and dynamically linked libraries. These search paths consist of
1375 strings naming directories in which the executables and libraries should be
1376 searched for. The individual paths are separated by a colon (
<tt>:
</tt>) character. To
1377 add the e.g. the directory
<em>$HOME/bin
</em> to the search path for executables, one
1378 would do the following:
</p></div>
1379 <div class=
"listingblock">
1380 <div class=
"content">
1381 <pre><tt>$ setenv PATH ${PATH}:${HOME}/bin
</tt></pre>
1383 <div class=
"paragraph"><p>which appends
<em>$HOME/bin
</em> to the end of the
<tt>PATH
</tt> variable. Note that
1384 <em>C-shells
</em> usually require the user to type
<em>rehash
</em> after changing the
<tt>PATH
</tt>
1385 variable to update the cache of available programs.
</p></div>
1388 <div id=
"footer-text">
1390 Last updated
2009-
05-
25 21:
43:
05 CEST