INSTALL.html

   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">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.4.4" />
   7 <title>FreeFOAM Installation Instructions for Version 0.1.0</title>
   8 <style type="text/css">
   9 /* Debug borders */
  10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  11 /*
  12   border: 1px solid red;
  13 */
  14 }
  15
  16 body {
  17   margin: 1em 5% 1em 5%;
  18 }
  19
  20 a {
  21   color: blue;
  22   text-decoration: underline;
  23 }
  24 a:visited {
  25   color: fuchsia;
  26 }
  27
  28 em {
  29   font-style: italic;
  30   color: navy;
  31 }
  32
  33 strong {
  34   font-weight: bold;
  35   color: #083194;
  36 }
  37
  38 tt {
  39   color: navy;
  40 }
  41
  42 h1, h2, h3, h4, h5, h6 {
  43   color: #527bbd;
  44   font-family: sans-serif;
  45   margin-top: 1.2em;
  46   margin-bottom: 0.5em;
  47   line-height: 1.3;
  48 }
  49
  50 h1, h2, h3 {
  51   border-bottom: 2px solid silver;
  52 }
  53 h2 {
  54   padding-top: 0.5em;
  55 }
  56 h3 {
  57   float: left;
  58 }
  59 h3 + * {
  60   clear: left;
  61 }
  62
  63 div.sectionbody {
  64   font-family: serif;
  65   margin-left: 0;
  66 }
  67
  68 hr {
  69   border: 1px solid silver;
  70 }
  71
  72 p {
  73   margin-top: 0.5em;
  74   margin-bottom: 0.5em;
  75 }
  76
  77 ul, ol, li > p {
  78   margin-top: 0;
  79 }
  80
  81 pre {
  82   padding: 0;
  83   margin: 0;
  84 }
  85
  86 span#author {
  87   color: #527bbd;
  88   font-family: sans-serif;
  89   font-weight: bold;
  90   font-size: 1.1em;
  91 }
  92 span#email {
  93 }
  94 span#revision {
  95   font-family: sans-serif;
  96 }
  97
  98 div#footer {
  99   font-family: sans-serif;
 100   font-size: small;
 101   border-top: 2px solid silver;
 102   padding-top: 0.5em;
 103   margin-top: 4.0em;
 104 }
 105 div#footer-text {
 106   float: left;
 107   padding-bottom: 0.5em;
 108 }
 109 div#footer-badges {
 110   float: right;
 111   padding-bottom: 0.5em;
 112 }
 113
 114 div#preamble {
 115   margin-top: 1.5em;
 116   margin-bottom: 1.5em;
 117 }
 118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 120 div.admonitionblock {
 121   margin-top: 1.5em;
 122   margin-bottom: 1.5em;
 123 }
 124 div.admonitionblock {
 125   margin-top: 2.5em;
 126   margin-bottom: 2.5em;
 127 }
 128
 129 div.content { /* Block element content. */
 130   padding: 0;
 131 }
 132
 133 /* Block element titles. */
 134 div.title, caption.title {
 135   color: #527bbd;
 136   font-family: sans-serif;
 137   font-weight: bold;
 138   text-align: left;
 139   margin-top: 1.0em;
 140   margin-bottom: 0.5em;
 141 }
 142 div.title + * {
 143   margin-top: 0;
 144 }
 145
 146 td div.title:first-child {
 147   margin-top: 0.0em;
 148 }
 149 div.content div.title:first-child {
 150   margin-top: 0.0em;
 151 }
 152 div.content + div.title {
 153   margin-top: 0.0em;
 154 }
 155
 156 div.sidebarblock > div.content {
 157   background: #ffffee;
 158   border: 1px solid silver;
 159   padding: 0.5em;
 160 }
 161
 162 div.listingblock > div.content {
 163   border: 1px solid silver;
 164   background: #f4f4f4;
 165   padding: 0.5em;
 166 }
 167
 168 div.quoteblock {
 169   padding-left: 2.0em;
 170   margin-right: 10%;
 171 }
 172 div.quoteblock > div.attribution {
 173   padding-top: 0.5em;
 174   text-align: right;
 175 }
 176
 177 div.verseblock {
 178   padding-left: 2.0em;
 179   margin-right: 10%;
 180 }
 181 div.verseblock > div.content {
 182   white-space: pre;
 183 }
 184 div.verseblock > div.attribution {
 185   padding-top: 0.75em;
 186   text-align: left;
 187 }
 188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 189 div.verseblock + div.attribution {
 190   text-align: left;
 191 }
 192
 193 div.admonitionblock .icon {
 194   vertical-align: top;
 195   font-size: 1.1em;
 196   font-weight: bold;
 197   text-decoration: underline;
 198   color: #527bbd;
 199   padding-right: 0.5em;
 200 }
 201 div.admonitionblock td.content {
 202   padding-left: 0.5em;
 203   border-left: 2px solid silver;
 204 }
 205
 206 div.exampleblock > div.content {
 207   border-left: 2px solid silver;
 208   padding: 0.5em;
 209 }
 210
 211 div.imageblock div.content { padding-left: 0; }
 212 div.imageblock img { border: 1px solid silver; }
 213 span.image img { border-style: none; }
 214
 215 dl {
 216   margin-top: 0.8em;
 217   margin-bottom: 0.8em;
 218 }
 219 dt {
 220   margin-top: 0.5em;
 221   margin-bottom: 0;
 222   font-style: normal;
 223   color: navy;
 224 }
 225 dd > *:first-child {
 226   margin-top: 0.1em;
 227 }
 228
 229 ul, ol {
 230     list-style-position: outside;
 231 }
 232 ol.arabic {
 233   list-style-type: decimal;
 234 }
 235 ol.loweralpha {
 236   list-style-type: lower-alpha;
 237 }
 238 ol.upperalpha {
 239   list-style-type: upper-alpha;
 240 }
 241 ol.lowerroman {
 242   list-style-type: lower-roman;
 243 }
 244 ol.upperroman {
 245   list-style-type: upper-roman;
 246 }
 247
 248 div.compact ul, div.compact ol,
 249 div.compact p, div.compact p,
 250 div.compact div, div.compact div {
 251   margin-top: 0.1em;
 252   margin-bottom: 0.1em;
 253 }
 254
 255 div.tableblock > table {
 256   border: 3px solid #527bbd;
 257 }
 258 thead {
 259   font-family: sans-serif;
 260   font-weight: bold;
 261 }
 262 tfoot {
 263   font-weight: bold;
 264 }
 265 td > div.verse {
 266   white-space: pre;
 267 }
 268 p.table {
 269   margin-top: 0;
 270 }
 271 /* Because the table frame attribute is overriden by CSS in most browsers. */
 272 div.tableblock > table[frame="void"] {
 273   border-style: none;
 274 }
 275 div.tableblock > table[frame="hsides"] {
 276   border-left-style: none;
 277   border-right-style: none;
 278 }
 279 div.tableblock > table[frame="vsides"] {
 280   border-top-style: none;
 281   border-bottom-style: none;
 282 }
 283
 284
 285 div.hdlist {
 286   margin-top: 0.8em;
 287   margin-bottom: 0.8em;
 288 }
 289 div.hdlist tr {
 290   padding-bottom: 15px;
 291 }
 292 dt.hdlist1.strong, td.hdlist1.strong {
 293   font-weight: bold;
 294 }
 295 td.hdlist1 {
 296   vertical-align: top;
 297   font-style: normal;
 298   padding-right: 0.8em;
 299   color: navy;
 300 }
 301 td.hdlist2 {
 302   vertical-align: top;
 303 }
 304 div.hdlist.compact tr {
 305   margin: 0;
 306   padding-bottom: 0;
 307 }
 308
 309 .comment {
 310   background: yellow;
 311 }
 312
 313 @media print {
 314   div#footer-badges { display: none; }
 315 }
 316
 317 div#toctitle {
 318   color: #527bbd;
 319   font-family: sans-serif;
 320   font-size: 1.1em;
 321   font-weight: bold;
 322   margin-top: 1.0em;
 323   margin-bottom: 0.1em;
 324 }
 325
 326 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 327   margin-top: 0;
 328   margin-bottom: 0;
 329 }
 330 div.toclevel2 {
 331   margin-left: 2em;
 332   font-size: 0.9em;
 333 }
 334 div.toclevel3 {
 335   margin-left: 4em;
 336   font-size: 0.9em;
 337 }
 338 div.toclevel4 {
 339   margin-left: 6em;
 340   font-size: 0.9em;
 341 }
 342 /* Workarounds for IE6's broken and incomplete CSS2. */
 343
 344 div.sidebar-content {
 345   background: #ffffee;
 346   border: 1px solid silver;
 347   padding: 0.5em;
 348 }
 349 div.sidebar-title, div.image-title {
 350   color: #527bbd;
 351   font-family: sans-serif;
 352   font-weight: bold;
 353   margin-top: 0.0em;
 354   margin-bottom: 0.5em;
 355 }
 356
 357 div.listingblock div.content {
 358   border: 1px solid silver;
 359   background: #f4f4f4;
 360   padding: 0.5em;
 361 }
 362
 363 div.quoteblock-attribution {
 364   padding-top: 0.5em;
 365   text-align: right;
 366 }
 367
 368 div.verseblock-content {
 369   white-space: pre;
 370 }
 371 div.verseblock-attribution {
 372   padding-top: 0.75em;
 373   text-align: left;
 374 }
 375
 376 div.exampleblock-content {
 377   border-left: 2px solid silver;
 378   padding-left: 0.5em;
 379 }
 380
 381 /* IE6 sets dynamically generated links as visited. */
 382 div#toc a:visited { color: blue; }
 383 </style>
 384 <script type="text/javascript">
 385 /*<![CDATA[*/
 386 window.onload = function(){generateToc(2)}
 387 /* Author: Mihai Bazon, September 2002
 388  * http://students.infoiasi.ro/~mishoo
 389  *
 390  * Table Of Content generator
 391  * Version: 0.4
 392  *
 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.
 395  */
 396
 397  /* modified by Troy D. Hanson, September 2006. License: GPL */
 398  /* modified by Stuart Rackham, October 2006. License: GPL */
 399
 400 function getText(el) {
 401   var text = "";
 402   for (var i = el.firstChild; i != null; i = i.nextSibling) {
 403     if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 404       text += i.data;
 405     else if (i.firstChild != null)
 406       text += getText(i);
 407   }
 408   return text;
 409 }
 410
 411 function TocEntry(el, text, toclevel) {
 412   this.element = el;
 413   this.text = text;
 414   this.toclevel = toclevel;
 415 }
 416
 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
 422   // browsers).
 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)
 427         if (mo)
 428           result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 429         iterate(i);
 430       }
 431     }
 432   }
 433   iterate(el);
 434   return result;
 435 }
 436
 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");
 449     div.appendChild(a);
 450     div.className = "toclevel" + entry.toclevel;
 451     toc.appendChild(div);
 452   }
 453   if (entries.length == 0)
 454     document.getElementById("header").removeChild(toc);
 455 }
 456 /*]]>*/
 457 </script>
 458 </head>
 459 <body>
 460 <div id="header">
 461 <h1>FreeFOAM Installation Instructions for Version 0.1.0</h1>
 462 <span id="author">Michael Wild</span><br />
 463 <span id="email"><tt>&lt;<a href="mailto:themiwi@users.sourceforge.net">themiwi@users.sourceforge.net</a>&gt;</tt></span><br />
 464 <span id="revision">version 0.1.0,</span>
 465 15 May 2009
 466 <div id="toc">
 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>
 469 </div>
 470 </div>
 471 <div id="preamble">
 472 <div class="sectionbody">
 473 <div class="paragraph"><p><a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a></p></div>
 474 </div>
 475 </div>
 476 <h2 id="_building_freefoam">1. Building FreeFOAM</h2>
 477 <div class="sectionbody">
 478 <div class="ulist"><ul>
 479 <li>
 480 <p>
 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.
 484 </p>
 485 </li>
 486 <li>
 487 <p>
 488 Download the FreeFOAM source and unpack it somewhere convenient. For the
 489   further instructions we will use <tt>$HOME/Source/</tt>.
 490 </p>
 491 <div class="listingblock">
 492 <div class="content">
 493 <pre><tt>$ mkdir -p $HOME/Source
 494 $ cd $HOME/Source
 495 $ wget http://switch.dl.sourceforge.net/sourceforge/freefoam/freefoam-0.1.0rc1.tar.bz2
 496 $ tar xjf freefoam-0.1.0.tar.bz2</tt></pre>
 497 </div></div>
 498 </li>
 499 <li>
 500 <p>
 501 Create a build tree and <em>cd</em> into it:
 502 </p>
 503 <div class="listingblock">
 504 <div class="content">
 505 <pre><tt>$ mkdir $HOME/Source/freefoam-0.1.0-build
 506 $ cd $HOME/Source/freefoam-0.1.0-build</tt></pre>
 507 </div></div>
 508 </li>
 509 <li>
 510 <p>
 511 Start CMake-configuration:
 512 </p>
 513 <div class="listingblock">
 514 <div class="content">
 515 <pre><tt>$ ccmake $HOME/Source/freefoam-0.1.0</tt></pre>
 516 </div></div>
 517 </li>
 518 <li>
 519 <p>
 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.
 524 </p>
 525 <div class="ulist"><ul>
 526 <li>
 527 <p>
 528 Set <tt>CMAKE_BUILD_TYPE</tt> to <em>Release</em> for an optimized build.
 529 </p>
 530 </li>
 531 <li>
 532 <p>
 533 If CMake complains that it can&#8217;t find MPI, and you don&#8217;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.
 536 </p>
 537 <div class="admonitionblock">
 538 <table><tr>
 539 <td class="icon">
 540 <div class="title">Note</div>
 541 </td>
 542 <td class="content">Currently only MPI implementation is available.</td>
 543 </tr></table>
 544 </div>
 545 </li>
 546 <li>
 547 <p>
 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>.
 551 </p>
 552 </li>
 553 <li>
 554 <p>
 555 If CMake told you it couldn&#8217;t find ParaView:
 556 </p>
 557 <div class="olist arabic"><ol class="arabic">
 558 <li>
 559 <p>
 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.
 562 </p>
 563 </li>
 564 <li>
 565 <p>
 566 If you do not want to build the ParaView plug-ins, disable
 567     <tt>FF_BUILD_PARAVIEW_PLUGINS</tt>
 568 </p>
 569 </li>
 570 </ol></div>
 571 </li>
 572 <li>
 573 <p>
 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.
 581 </p>
 582 </li>
 583 <li>
 584 <p>
 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
 589     this package.
 590 </p>
 591 </li>
 592 <li>
 593 <p>
 594 In order to build <em>ccm26ToFoam</em>, a conversion utility for grids generated
 595     with <em>ProStar/ccm</em> &#169; 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
 599     package.
 600 </p>
 601 </li>
 602 <li>
 603 <p>
 604 If you plan on installing FreeFOAM, set <tt>CMAKE_INSTALL_PREFIX</tt> to the base directory
 605     under which FreeFOAM should reside.
 606 </p>
 607 </li>
 608 <li>
 609 <p>
 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.
 616 </p>
 617 </li>
 618 <li>
 619 <p>
 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>.
 622 </p>
 623 </li>
 624 </ul></div>
 625 </li>
 626 <li>
 627 <p>
 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.
 633 </p>
 634 </li>
 635 <li>
 636 <p>
 637 You shouldn&#8217;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
 639   the interface.
 640 </p>
 641 </li>
 642 <li>
 643 <p>
 644 Press <tt>g</tt> to generate the Makefiles and exit the ccmake interface.
 645 </p>
 646 </li>
 647 <li>
 648 <p>
 649 Start the native build tool. If you used the <em>Makefile</em> generator
 650   (which is the default for Unix-platforms), type
 651 </p>
 652 <div class="listingblock">
 653 <div class="content">
 654 <pre><tt>$ make</tt></pre>
 655 </div></div>
 656 </li>
 657 <li>
 658 <p>
 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&#8217;s/cores you have in your machine plus 1 (to compensate
 663   for disk-latency). For a typical dual-core machine, run
 664 </p>
 665 <div class="listingblock">
 666 <div class="content">
 667 <pre><tt>$ make -j3</tt></pre>
 668 </div></div>
 669 </li>
 670 </ul></div>
 671 </div>
 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>
 680 </div></div>
 681 </div>
 682 <h2 id="_using_freefoam">3. Using FreeFOAM</h2>
 683 <div class="sectionbody">
 684 <div class="paragraph"><p>If you didn&#8217;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">
 692 <li>
 693 <p>
 694 Under the directory specified in the <tt>$FREEFOAM_CONFIG_DIR</tt> environment
 695    variable
 696 </p>
 697 </li>
 698 <li>
 699 <p>
 700 In <em>$HOME/.FreeFOAM/0.1</em>
 701 </p>
 702 </li>
 703 <li>
 704 <p>
 705 In <em>$HOME/.FreeFOAM</em>
 706 </p>
 707 </li>
 708 <li>
 709 <p>
 710 In the installation directory of the configuration files. There are
 711    two possible places for this:
 712 </p>
 713 <div class="dlist"><dl>
 714 <dt class="hdlist1">
 715 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FF_INSTALL_CONFIG_PATH&gt;</em>
 716 </dt>
 717 <dd>
 718 <p>
 719 if you specified
 720      <tt>&lt;FF_INSTALL_CONFIG_PATH&gt;</tt> as a relative path.
 721 </p>
 722 </dd>
 723 <dt class="hdlist1">
 724 <em>&lt;FF_INSTALL_CONFIG_PATH&gt;</em>
 725 </dt>
 726 <dd>
 727 <p>
 728 if you specified <tt>&lt;FF_INSTALL_CONFIG_PATH&gt;</tt> as
 729     an absolute path.
 730 </p>
 731 <div class="paragraph"><p>The default location is <em>/usr/local/etc/FreeFOAM/1.0</em>.</p></div>
 732 </dd>
 733 </dl></div>
 734 </li>
 735 </ol></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">
 747 <li>
 748 <p>
 749 If the environment variable <tt>FREEFOAM_PSTREAM_LIBRARY</tt> is set,
 750    FreeFOAM will try to load the library specified by it.
 751 </p>
 752 </li>
 753 <li>
 754 <p>
 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.
 761 </p>
 762 </li>
 763 </ol></div>
 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">
 769 <li>
 770 <p>
 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.
 774 </p>
 775 </li>
 776 <li>
 777 <p>
 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
 783    to load.
 784 </p>
 785 </li>
 786 </ol></div>
 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
 794 {
 795     //configName dummy;
 796     configName mpi;
 797
 798     dummy
 799     {
 800         library libdummyPstream.so;
 801         Pstream dummyPstreamImpl;
 802         OPstream dummyOPstreamImpl;
 803         IPstream dummyIPstreamImpl;
 804     }
 805
 806     mpi
 807     {
 808         library libmpiPstream.so;
 809         Pstream mpiPstreamImpl;
 810         OPstream mpiOPstreamImpl;
 811         IPstream mpiIPstreamImpl;
 812     }
 813 }</tt></pre>
 814 </div></div>
 815 </div></div>
 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>
 829 <dt class="hdlist1">
 830 PATH
 831 </dt>
 832 <dd>
 833 <p>
 834 Must contain <em>$HOME/Source/freefoam-0.1.0-build/bin</em>
 835 </p>
 836 </dd>
 837 <dt class="hdlist1">
 838 LD_LIBRARY_PATH
 839 </dt>
 840 <dd>
 841 <p>
 842 Must contain <em>$HOME/Source/freefoam-0.1.0-build/lib/FreeFOAM/0.1</em>
 843 </p>
 844 </dd>
 845 <dt class="hdlist1">
 846 FREEFOAM_CONFIG_DIR
 847 </dt>
 848 <dd>
 849 <p>
 850 Should point to <em>$HOME/Source/freefoam-0.1.0-build/etc</em>
 851 </p>
 852 </dd>
 853 </dl></div>
 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
 857 variables.</p></div>
 858 </div>
 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.0-build/tutorials $HOME/FreeFOAM/$LOGNAME-0.1/run/
 867 $ cd $HOME/FreeFOAM/$LOGNAME-0.1/run</tt></pre>
 868 </div></div>
 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>
 876 </div></div>
 877 <div class="paragraph"><p>Things should run smoothly and finish without an error.</p></div>
 878 </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>
 882 <li>
 883 <p>
 884 Clone the FreeFOAM repository (here the clone is placed in
 885   <tt>$HOME/Source/FreeFOAM</tt>):
 886 </p>
 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>
 891 </div></div>
 892 </li>
 893 <li>
 894 <p>
 895 Proceed in the same way (replacing the path names apropriately) as in the
 896   above build instructions.
 897 </p>
 898 </li>
 899 </ul></div>
 900 </div>
 901 <h2 id="_build_configuration_reference">6. Build Configuration Reference</h2>
 902 <div class="sectionbody">
 903 <div class="dlist glossary"><dl>
 904 <dt>
 905 <tt>CMAKE_BUILD_TYPE</tt>
 906 </dt>
 907 <dd>
 908 <p>
 909   One of <em>&lt;empty&gt;</em>, <em>Debug</em>, <em>Release</em>, <em>RelWithDebInfo</em> and <em>MinSizeRel</em>.
 910   Refer to the CMake documentation for more detail.
 911 </p>
 912 </dd>
 913 <dt>
 914 <tt>FF_DOUBLE_PRECISION</tt>
 915 </dt>
 916 <dd>
 917 <p>
 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>.
 920 </p>
 921 </dd>
 922 <dt>
 923 <tt>FF_BUILD_FRAMEWORK</tt>
 924 </dt>
 925 <dd>
 926 <p>
 927   If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
 928 </p>
 929 </dd>
 930 <dt>
 931 <tt>CMAKE_INSTALL_PREFIX</tt>
 932 </dt>
 933 <dd>
 934 <p>
 935   Installation prefix under which to install FreeFOAM.
 936 </p>
 937 </dd>
 938 <dt>
 939 <tt>FF_INSTALL_BIN_PATH</tt>
 940 </dt>
 941 <dd>
 942 <p>
 943   Installation path of the binaries. If not absolute, it is relative to
 944   <em>CMAKE_INSTALL_PREFIX</em>.
 945 </p>
 946 </dd>
 947 <dt>
 948 <tt>FF_INSTALL_CONFIG_PATH</tt>
 949 </dt>
 950 <dd>
 951 <p>
 952   Installation path of the configuration files. If not absolute, it is
 953   relative to <em>CMAKE_INSTALL_PREFIX</em>.
 954 </p>
 955 </dd>
 956 <dt>
 957 <tt>FF_INSTALL_HEADER_PATH</tt>
 958 </dt>
 959 <dd>
 960 <p>
 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.
 964 </p>
 965 </dd>
 966 <dt>
 967 <tt>FF_INSTALL_LIB_PATH</tt>
 968 </dt>
 969 <dd>
 970 <p>
 971   Installation path of the libraries. If not absolute, it is
 972   relative to <em>CMAKE_INSTALL_PREFIX</em>.
 973 </p>
 974 </dd>
 975 <dt>
 976 <tt>FF_INSTALL_FRAMEWORK_PATH</tt>
 977 </dt>
 978 <dd>
 979 <p>
 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.
 984 </p>
 985 </dd>
 986 <dt>
 987 <tt>FF_INSTALL_PV3FOAMREADER_PATH</tt>
 988 </dt>
 989 <dd>
 990 <p>
 991   Installation path of the ParaView3 plug-ins. If not absolute, it is
 992   relative to <em>CMAKE_INSTALL_PREFIX</em>.
 993 </p>
 994 </dd>
 995 <dt>
 996 <tt>FF_INSTALL_PVFOAMREADER_PATH</tt>
 997 </dt>
 998 <dd>
 999 <p>
1000   Installation path of the ParaView2 plug-ins. If not absolute, it is
1001   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1002 </p>
1003 </dd>
1004 <dt>
1005 <tt>FF_INSTALL_USERDFOAM_PATH</tt>
1006 </dt>
1007 <dd>
1008 <p>
1009   Installation path of the Ensight plug-in. If not absolute, it is
1010   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1011 </p>
1012 </dd>
1013 <dt>
1014 <tt>EXECUTABLE_PREFIX</tt>
1015 </dt>
1016 <dd>
1017 <p>
1018   Prefix which get prepended to the name of the executables. This defaults to
1019   <em>ff_</em> and serves the disambiguation of names.
1020 </p>
1021 </dd>
1022 <dt>
1023 <tt>FF_USE_GAMMA</tt>
1024 </dt>
1025 <dd>
1026 <p>
1027   If enabled, FreeFOAM will use the GAMMA parallel communications library.
1028 </p>
1029 </dd>
1030 <dt>
1031 <tt>FF_USE_MPI</tt>
1032 </dt>
1033 <dd>
1034 <p>
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.
1037 </p>
1038 </dd>
1039 <dt>
1040 <tt>FF_USE_PVM</tt>
1041 </dt>
1042 <dd>
1043 <p>
1044   If enabled, FreeFOAM will use the PVM parallel communications library.
1045 </p>
1046 </dd>
1047 <dt>
1048 <tt>FF_DEFAULT_PSTREAM</tt>
1049 </dt>
1050 <dd>
1051 <p>
1052   The default Pstream selection in the global <em>controlDict</em> file.
1053 </p>
1054 </dd>
1055 <dt>
1056 <tt>FF_BUILD_PARAVIEW_PLUGINS</tt>
1057 </dt>
1058 <dd>
1059 <p>
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.
1062 </p>
1063 </dd>
1064 <dt>
1065 <tt>FF_ENABLE_CCMIO</tt>
1066 </dt>
1067 <dd>
1068 <p>
1069   Enable the use of <em>libccmio</em>. This is required to build the grid conversion
1070   utility <em>ccm26ToFoam</em>.
1071 </p>
1072 <div class="admonitionblock" id="enable-ccmio">
1073 <table><tr>
1074 <td class="icon">
1075 <div class="title">Warning</div>
1076 </td>
1077 <td class="content">The license of <em>libccmio</em> &#169; 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>
1082 </tr></table>
1083 </div>
1084 <div class="listingblock">
1085 <div class="content">
1086 <pre><tt>Gerber,
1087
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:
1092
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.
1098
1099 So I regret to tell you that my company has declined to permit libccmio to be
1100 distributed as part of Debian.
1101
1102 Regards,
1103 Geoff Prewett</tt></pre>
1104 </div></div>
1105 </dd>
1106 <dt>
1107 <tt>FF_BUILD_PRIVATE_CCMIO</tt>
1108 </dt>
1109 <dd>
1110 <p>
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.
1115 </p>
1116 </dd>
1117 <dt>
1118 <tt>FF_BUILD_PRIVATE_METIS</tt>
1119 </dt>
1120 <dd>
1121 <p>
1122   Automatically download and build <em>METIS</em>.
1123 </p>
1124 </dd>
1125 <dt>
1126 <tt>FF_BUILD_PRIVATE_PARMETIS</tt>
1127 </dt>
1128 <dd>
1129 <p>
1130   Automatically download and build <em>ParMetis</em>.
1131 </p>
1132 </dd>
1133 <dt>
1134 <tt>FF_ENABLE_PARMGRIDGEN</tt>
1135 </dt>
1136 <dd>
1137 <p>
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
1140   the GAMG solver.
1141 </p>
1142 <div class="admonitionblock" id="enable-parmgridgen">
1143 <table><tr>
1144 <td class="icon">
1145 <div class="title">Warning</div>
1146 </td>
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&#8217;t violate any license conditions applying to these libraries. The
1151 authors of FreeFOAM will and cannot take any responsibility for your
1152 actions.</td>
1153 </tr></table>
1154 </div>
1155 </dd>
1156 <dt>
1157 <tt>FF_BUILD_PRIVATE_PARMGRIDGEN</tt>
1158 </dt>
1159 <dd>
1160 <p>
1161   Automatically download and build <em>PARMGRIDGEN</em> and <em>MGRIDGEN</em>.
1162 </p>
1163 </dd>
1164 <dt>
1165 <tt>FF_BUILD_DOXYGEN_DOCS</tt>
1166 </dt>
1167 <dd>
1168 <p>
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>.
1174 </p>
1175 </dd>
1176 </dl></div>
1177 </div>
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">
1183 <li>
1184 <p>
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:
1187 </p>
1188 <div class="listingblock">
1189 <div class="content">
1190 <pre><tt>$ rehash</tt></pre>
1191 </div></div>
1192 </li>
1193 <li>
1194 <p>
1195 If <em>rehashing</em> didn&#8217;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:
1201 </p>
1202 <div class="dlist"><dl>
1203 <dt class="hdlist1">
1204 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FF_INSTALL_BIN_PATH&gt;</em>
1205 </dt>
1206 <dd>
1207 <p>
1208 if you specified
1209   <tt>FF_INSTALL_BIN_PATH</tt> as a relative path
1210 </p>
1211 </dd>
1212 <dt class="hdlist1">
1213 <em>&lt;FF_INSTALL_BIN_PATH&gt;</em>
1214 </dt>
1215 <dd>
1216 <p>
1217 if you specified <tt>FF_INSTALL_BIN_PATH</tt> as an absolute
1218   path
1219 </p>
1220 </dd>
1221 </dl></div>
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>
1226 </li>
1227 <li>
1228 <p>
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:
1237 </p>
1238 <div class="listingblock">
1239 <div class="content">
1240 <pre><tt>$ mkdir -p $HOME/.FreeFOAM/0.1
1241 $ cp $HOME/Source/freefoam-0.1.0-build/etc/controlDict $HOME/.FreeFOAM/0.1
1242 $ cp $HOME/Source/freefoam-0.1.0-build/etc/cellModels $HOME/.FreeFOAM/0.1
1243 $ cp -r $HOME/Source/freefoam-0.1.0-build/etc/thermoData $HOME/.FreeFOAM/0.1</tt></pre>
1244 </div></div>
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.0-build/etc</em>. Adjust paths to the
1247 build tree to your actual setup.</p></div>
1248 </li>
1249 </ol></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>
1257 </dt>
1258 <dd>
1259 <p>
1260 This variable is used by all Unix like systems (e.g. Linux,
1261   Mac OS X, etc.)
1262 </p>
1263 </dd>
1264 <dt class="hdlist1">
1265 <tt>DYLD_LIBRARY_PATH</tt>
1266 </dt>
1267 <dd>
1268 <p>
1269 This variable is used by Mac OS X.
1270 </p>
1271 </dd>
1272 </dl></div>
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>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FF_INSTALL_LIB_PATH&gt;</em>
1278 </dt>
1279 <dd>
1280 <p>
1281 if you specified
1282   <tt>FF_INSTALL_LIB_PATH</tt> as a relative path.
1283 </p>
1284 </dd>
1285 <dt class="hdlist1">
1286 <em>&lt;FF_INSTALL_LIB_PATH&gt;</em>
1287 </dt>
1288 <dd>
1289 <p>
1290 if you specified <tt>FF_INSTALL_LIB_PATH</tt> as an absolute
1291   path.
1292 </p>
1293 </dd>
1294 </dl></div>
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.0-build/lib/FreeFOAM/0.1</em> in the above mentioned search
1297 paths (where you have to adjust the location of the build tree to your actual
1298 setup).</p></div>
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&#8217;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
1310 details.</p></div>
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
1317 path.</p></div>
1318 </div>
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>
1343 </div></div>
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>
1355 </div></div>
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>
1371 </div></div>
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>
1382 </div></div>
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>
1386 </div>
1387 <div id="footer">
1388 <div id="footer-text">
1389 Version 0.1.0<br />
1390 Last updated 2009-05-15 11:34:17 CEST
1391 </div>
1392 </div>
1393 </body>
1394 </html>