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.5.3" />
   7 <title>FreeFOAM Installation Instructions for Version 0.1.0rc4</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#revnumber, span#revdate, span#revremark {
  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.0em;
 122   margin-bottom: 1.5em;
 123 }
 124 div.admonitionblock {
 125   margin-top: 2.0em;
 126   margin-bottom: 2.0em;
 127   margin-right: 10%;
 128   color: #606060;
 129 }
 130
 131 div.content { /* Block element content. */
 132   padding: 0;
 133 }
 134
 135 /* Block element titles. */
 136 div.title, caption.title {
 137   color: #527bbd;
 138   font-family: sans-serif;
 139   font-weight: bold;
 140   text-align: left;
 141   margin-top: 1.0em;
 142   margin-bottom: 0.5em;
 143 }
 144 div.title + * {
 145   margin-top: 0;
 146 }
 147
 148 td div.title:first-child {
 149   margin-top: 0.0em;
 150 }
 151 div.content div.title:first-child {
 152   margin-top: 0.0em;
 153 }
 154 div.content + div.title {
 155   margin-top: 0.0em;
 156 }
 157
 158 div.sidebarblock > div.content {
 159   background: #ffffee;
 160   border: 1px solid silver;
 161   padding: 0.5em;
 162 }
 163
 164 div.listingblock > div.content {
 165   border: 1px solid silver;
 166   background: #f4f4f4;
 167   padding: 0.5em;
 168 }
 169
 170 div.quoteblock, div.verseblock {
 171   padding-left: 1.0em;
 172   margin-left: 1.0em;
 173   margin-right: 10%;
 174   border-left: 5px solid #dddddd;
 175   color: #777777;
 176 }
 177
 178 div.quoteblock > div.attribution {
 179   padding-top: 0.5em;
 180   text-align: right;
 181 }
 182
 183 div.verseblock > pre.content {
 184   font-family: inherit;
 185 }
 186 div.verseblock > div.attribution {
 187   padding-top: 0.75em;
 188   text-align: left;
 189 }
 190 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 191 div.verseblock + div.attribution {
 192   text-align: left;
 193 }
 194
 195 div.admonitionblock .icon {
 196   vertical-align: top;
 197   font-size: 1.1em;
 198   font-weight: bold;
 199   text-decoration: underline;
 200   color: #527bbd;
 201   padding-right: 0.5em;
 202 }
 203 div.admonitionblock td.content {
 204   padding-left: 0.5em;
 205   border-left: 3px solid #dddddd;
 206 }
 207
 208 div.exampleblock > div.content {
 209   border-left: 3px solid #dddddd;
 210   padding-left: 0.5em;
 211 }
 212
 213 div.imageblock div.content { padding-left: 0; }
 214 span.image img { border-style: none; }
 215 a.image:visited { color: white; }
 216
 217 dl {
 218   margin-top: 0.8em;
 219   margin-bottom: 0.8em;
 220 }
 221 dt {
 222   margin-top: 0.5em;
 223   margin-bottom: 0;
 224   font-style: normal;
 225   color: navy;
 226 }
 227 dd > *:first-child {
 228   margin-top: 0.1em;
 229 }
 230
 231 ul, ol {
 232     list-style-position: outside;
 233 }
 234 ol.arabic {
 235   list-style-type: decimal;
 236 }
 237 ol.loweralpha {
 238   list-style-type: lower-alpha;
 239 }
 240 ol.upperalpha {
 241   list-style-type: upper-alpha;
 242 }
 243 ol.lowerroman {
 244   list-style-type: lower-roman;
 245 }
 246 ol.upperroman {
 247   list-style-type: upper-roman;
 248 }
 249
 250 div.compact ul, div.compact ol,
 251 div.compact p, div.compact p,
 252 div.compact div, div.compact div {
 253   margin-top: 0.1em;
 254   margin-bottom: 0.1em;
 255 }
 256
 257 div.tableblock > table {
 258   border: 3px solid #527bbd;
 259 }
 260 thead, p.table.header {
 261   font-family: sans-serif;
 262   font-weight: bold;
 263 }
 264 tfoot {
 265   font-weight: bold;
 266 }
 267 td > div.verse {
 268   white-space: pre;
 269 }
 270 p.table {
 271   margin-top: 0;
 272 }
 273 /* Because the table frame attribute is overriden by CSS in most browsers. */
 274 div.tableblock > table[frame="void"] {
 275   border-style: none;
 276 }
 277 div.tableblock > table[frame="hsides"] {
 278   border-left-style: none;
 279   border-right-style: none;
 280 }
 281 div.tableblock > table[frame="vsides"] {
 282   border-top-style: none;
 283   border-bottom-style: none;
 284 }
 285
 286
 287 div.hdlist {
 288   margin-top: 0.8em;
 289   margin-bottom: 0.8em;
 290 }
 291 div.hdlist tr {
 292   padding-bottom: 15px;
 293 }
 294 dt.hdlist1.strong, td.hdlist1.strong {
 295   font-weight: bold;
 296 }
 297 td.hdlist1 {
 298   vertical-align: top;
 299   font-style: normal;
 300   padding-right: 0.8em;
 301   color: navy;
 302 }
 303 td.hdlist2 {
 304   vertical-align: top;
 305 }
 306 div.hdlist.compact tr {
 307   margin: 0;
 308   padding-bottom: 0;
 309 }
 310
 311 .comment {
 312   background: yellow;
 313 }
 314
 315 .footnote, .footnoteref {
 316   font-size: 0.8em;
 317 }
 318
 319 span.footnote, span.footnoteref {
 320   vertical-align: super;
 321 }
 322
 323 #footnotes {
 324   margin: 20px 0 20px 0;
 325   padding: 7px 0 0 0;
 326 }
 327
 328 #footnotes div.footnote {
 329   margin: 0 0 5px 0;
 330 }
 331
 332 #footnotes hr {
 333   border: none;
 334   border-top: 1px solid silver;
 335   height: 1px;
 336   text-align: left;
 337   margin-left: 0;
 338   width: 20%;
 339   min-width: 100px;
 340 }
 341
 342
 343 @media print {
 344   div#footer-badges { display: none; }
 345 }
 346
 347 div#toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 div#toctitle {
 352   color: #527bbd;
 353   font-family: sans-serif;
 354   font-size: 1.1em;
 355   font-weight: bold;
 356   margin-top: 1.0em;
 357   margin-bottom: 0.1em;
 358 }
 359
 360 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 361   margin-top: 0;
 362   margin-bottom: 0;
 363 }
 364 div.toclevel2 {
 365   margin-left: 2em;
 366   font-size: 0.9em;
 367 }
 368 div.toclevel3 {
 369   margin-left: 4em;
 370   font-size: 0.9em;
 371 }
 372 div.toclevel4 {
 373   margin-left: 6em;
 374   font-size: 0.9em;
 375 }
 376 /* Workarounds for IE6's broken and incomplete CSS2. */
 377
 378 div.sidebar-content {
 379   background: #ffffee;
 380   border: 1px solid silver;
 381   padding: 0.5em;
 382 }
 383 div.sidebar-title, div.image-title {
 384   color: #527bbd;
 385   font-family: sans-serif;
 386   font-weight: bold;
 387   margin-top: 0.0em;
 388   margin-bottom: 0.5em;
 389 }
 390
 391 div.listingblock div.content {
 392   border: 1px solid silver;
 393   background: #f4f4f4;
 394   padding: 0.5em;
 395 }
 396
 397 div.quoteblock-attribution {
 398   padding-top: 0.5em;
 399   text-align: right;
 400 }
 401
 402 pre.verseblock-content {
 403   font-family: inherit;
 404 }
 405 div.verseblock-attribution {
 406   padding-top: 0.75em;
 407   text-align: left;
 408 }
 409
 410 div.exampleblock-content {
 411   border-left: 3px solid #dddddd;
 412   padding-left: 0.5em;
 413 }
 414
 415 /* IE6 sets dynamically generated links as visited. */
 416 div#toc a:visited { color: blue; }
 417 </style>
 418 <script type="text/javascript">
 419 /*<![CDATA[*/
 420 window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
 421 var asciidoc = {  // Namespace.
 422
 423 /////////////////////////////////////////////////////////////////////
 424 // Table Of Contents generator
 425 /////////////////////////////////////////////////////////////////////
 426
 427 /* Author: Mihai Bazon, September 2002
 428  * http://students.infoiasi.ro/~mishoo
 429  *
 430  * Table Of Content generator
 431  * Version: 0.4
 432  *
 433  * Feel free to use this script under the terms of the GNU General Public
 434  * License, as long as you do not remove or alter this notice.
 435  */
 436
 437  /* modified by Troy D. Hanson, September 2006. License: GPL */
 438  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 439
 440 // toclevels = 1..4.
 441 toc: function (toclevels) {
 442
 443   function getText(el) {
 444     var text = "";
 445     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 446       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 447         text += i.data;
 448       else if (i.firstChild != null)
 449         text += getText(i);
 450     }
 451     return text;
 452   }
 453
 454   function TocEntry(el, text, toclevel) {
 455     this.element = el;
 456     this.text = text;
 457     this.toclevel = toclevel;
 458   }
 459
 460   function tocEntries(el, toclevels) {
 461     var result = new Array;
 462     var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
 463     // Function that scans the DOM tree for header elements (the DOM2
 464     // nodeIterator API would be a better technique but not supported by all
 465     // browsers).
 466     var iterate = function (el) {
 467       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 468         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 469           var mo = re.exec(i.tagName);
 470           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 471             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 472           }
 473           iterate(i);
 474         }
 475       }
 476     }
 477     iterate(el);
 478     return result;
 479   }
 480
 481   var toc = document.getElementById("toc");
 482   var entries = tocEntries(document.getElementById("content"), toclevels);
 483   for (var i = 0; i < entries.length; ++i) {
 484     var entry = entries[i];
 485     if (entry.element.id == "")
 486       entry.element.id = "_toc_" + i;
 487     var a = document.createElement("a");
 488     a.href = "#" + entry.element.id;
 489     a.appendChild(document.createTextNode(entry.text));
 490     var div = document.createElement("div");
 491     div.appendChild(a);
 492     div.className = "toclevel" + entry.toclevel;
 493     toc.appendChild(div);
 494   }
 495   if (entries.length == 0)
 496     toc.parentNode.removeChild(toc);
 497 },
 498
 499
 500 /////////////////////////////////////////////////////////////////////
 501 // Footnotes generator
 502 /////////////////////////////////////////////////////////////////////
 503
 504 /* Based on footnote generation code from:
 505  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 506  */
 507
 508 footnotes: function () {
 509   var cont = document.getElementById("content");
 510   var noteholder = document.getElementById("footnotes");
 511   var spans = cont.getElementsByTagName("span");
 512   var refs = {};
 513   var n = 0;
 514   for (i=0; i<spans.length; i++) {
 515     if (spans[i].className == "footnote") {
 516       n++;
 517       // Use [\s\S] in place of . so multi-line matches work.
 518       // Because JavaScript has no s (dotall) regex flag.
 519       note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 520       noteholder.innerHTML +=
 521         "<div class='footnote' id='_footnote_" + n + "'>" +
 522         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 523         n + "</a>. " + note + "</div>";
 524       spans[i].innerHTML =
 525         "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 526         "' title='View footnote' class='footnote'>" + n + "</a>]";
 527       var id =spans[i].getAttribute("id");
 528       if (id != null) refs["#"+id] = n;
 529     }
 530   }
 531   if (n == 0)
 532     noteholder.parentNode.removeChild(noteholder);
 533   else {
 534     // Process footnoterefs.
 535     for (i=0; i<spans.length; i++) {
 536       if (spans[i].className == "footnoteref") {
 537         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 538         href = href.match(/#.*/)[0];  // Because IE return full URL.
 539         n = refs[href];
 540         spans[i].innerHTML =
 541           "[<a href='#_footnote_" + n +
 542           "' title='View footnote' class='footnote'>" + n + "</a>]";
 543       }
 544     }
 545   }
 546 }
 547
 548 }
 549 /*]]>*/
 550 </script>
 551 </head>
 552 <body>
 553 <div id="header">
 554 <h1>FreeFOAM Installation Instructions for Version 0.1.0rc4</h1>
 555 <span id="author">Michael Wild</span><br />
 556 <span id="email"><tt>&lt;<a href="mailto:themiwi@users.sourceforge.net">themiwi@users.sourceforge.net</a>&gt;</tt></span><br />
 557 <span id="revnumber">version 0.1.0rc4,</span>
 558 <span id="revdate">2010-06-18</span>
 559 <div id="toc">
 560   <div id="toctitle">Table of Contents</div>
 561   <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
 562 </div>
 563 </div>
 564 <div id="content">
 565 <div id="preamble">
 566 <div class="sectionbody">
 567 <div class="paragraph"><p><a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a></p></div>
 568 </div>
 569 </div>
 570 <h2 id="_building_freefoam">1. Building FreeFOAM</h2>
 571 <div class="sectionbody">
 572 <div class="ulist"><ul>
 573 <li>
 574 <p>
 575 Install the prerequisites documented in the <a href="README.html">README</a> file. If
 576   your distribution does not have <em>METIS</em>, <em>ParMetis</em>, <em>MGRIDGEN</em> or <em>libccmio</em>
 577   be not worried, FreeFOAM can handle those for you.
 578 </p>
 579 </li>
 580 <li>
 581 <p>
 582 Download the FreeFOAM source and unpack it somewhere convenient. For the
 583   further instructions we will use <tt>$HOME/Source/</tt>.
 584 </p>
 585 <div class="listingblock">
 586 <div class="content">
 587 <pre><tt>$ mkdir -p $HOME/Source
 588 $ cd $HOME/Source
 589 $ wget http://master.dl.sourceforge.net/sourceforge/freefoam/freefoam-0.1.0rc4.tar.bz2
 590 $ tar xjf freefoam-0.1.0rc4.tar.bz2</tt></pre>
 591 </div></div>
 592 </li>
 593 <li>
 594 <p>
 595 Create a build tree and <em>cd</em> into it:
 596 </p>
 597 <div class="listingblock">
 598 <div class="content">
 599 <pre><tt>$ mkdir $HOME/Source/freefoam-0.1.0rc4-build
 600 $ cd $HOME/Source/freefoam-0.1.0rc4-build</tt></pre>
 601 </div></div>
 602 </li>
 603 <li>
 604 <p>
 605 Start CMake-configuration:
 606 </p>
 607 <div class="listingblock">
 608 <div class="content">
 609 <pre><tt>$ ccmake $HOME/Source/freefoam-0.1.0rc4</tt></pre>
 610 </div></div>
 611 </li>
 612 <li>
 613 <p>
 614 Press the <tt>c</tt> key. Use the arrow keys to navigate up and down and press
 615   <tt>enter</tt> to edit a field. To commit the change, press <tt>enter</tt> again, or <tt>ESC</tt>
 616   to abandon the change.  ON/OFF fields are toggled by pressing <tt>enter</tt>.
 617   Advanced options can be displayed by hitting the <tt>t</tt> key.
 618 </p>
 619 <div class="ulist"><ul>
 620 <li>
 621 <p>
 622 Set <tt>CMAKE_BUILD_TYPE</tt> to <em>Release</em> for an optimized build.
 623 </p>
 624 </li>
 625 <li>
 626 <p>
 627 If CMake complains that it can&#8217;t find MPI, and you don&#8217;t want to install it, disable
 628     <tt>FOAM_USE_MPI</tt>. If, instead, you want to use GAMMA, enable <tt>FOAM_USE_GAMMA</tt>.
 629     You can also enable more than one of the options.
 630 </p>
 631 <div class="admonitionblock">
 632 <table><tr>
 633 <td class="icon">
 634 <div class="title">Note</div>
 635 </td>
 636 <td class="content">Currently only the MPI implementation is available.</td>
 637 </tr></table>
 638 </div>
 639 </li>
 640 <li>
 641 <p>
 642 Select the default Pstream implementation by setting <tt>FOAM_DEFAULT_PSTREAM</tt>
 643     to one of <em>dummy</em>, <em>mpi</em> or <em>gamma</em>. This setting will only influence
 644     the contents of the <a href="#globalconfig">global <em>controlDict</em> file</a>.
 645 </p>
 646 </li>
 647 <li>
 648 <p>
 649 If CMake told you it couldn&#8217;t find ParaView:
 650 </p>
 651 <div class="olist arabic"><ol class="arabic">
 652 <li>
 653 <p>
 654 Set <tt>ParaView_DIR</tt> to the path of the directory containing
 655     <em>ParaViewConfig.cmake</em>, which is most likely the ParaView build directory.
 656 </p>
 657 </li>
 658 <li>
 659 <p>
 660 If you do not want to build the ParaView plug-ins, disable
 661     <tt>FOAM_BUILD_PARAVIEW_PLUGINS</tt>
 662 </p>
 663 </li>
 664 </ol></div>
 665 </li>
 666 <li>
 667 <p>
 668 If you want to use the <em>metis</em> and <em>parmetis</em> decomposition methods, make
 669     sure that <tt>FOAM_ENABLE_METIS</tt> and <tt>FOAM_ENABLE_PARMETIS</tt> are enabled,
 670     respectively. If you do not have <em>METIS</em> or <em>ParMetis</em> installed, enable
 671     <tt>FOAM_BUILD_PRIVATE_METIS</tt> or <tt>FOAM_BUILD_PRIVATE_PARMETIS</tt>, respectively.
 672     CMake will then try to download and build the selected libraries for you.
 673     Conversely, if one of the libraries is provided by your system, you can
 674     turn the respective setting to <em>OFF</em>. Please note that if your system
 675     provides only <em>ParMetis</em>, you do not have to install <em>METIS</em>, as the former
 676     also contains <em>METIS</em> in an older version.
 677 </p>
 678 </li>
 679 <li>
 680 <p>
 681 If you want to use the <em>MGridGen</em> agglomeration method for the GAMG solver,
 682     you need to enable <tt>FOAM_ENABLE_MGRIDGEN</tt> and if the library is not
 683     installed on your system ensure that <tt>FOAM_BUILD_PRIVATE_MGRIDGEN</tt> is
 684     enabled. See <a href="#enable-mgridgen">above</a> regarding the unknown license status
 685     of this package.
 686 </p>
 687 </li>
 688 <li>
 689 <p>
 690 In order to build <em>ccm26ToFoam</em>, a conversion utility for grids generated
 691     with <em>ProStar/ccm</em> &#169; version 2.6, enable the setting
 692     <tt>FOAM_ENABLE_CCMIO</tt> and if <em>libccmio</em> is not installed on your system,
 693     also <tt>FOAM_BUILD_PRIVATE_CCMIO</tt>. Refer to the <a href="#enable-ccmio">above</a>
 694     description of the <em>libccmio</em> package for the license restrictions which
 695     apply to this package. If you decide to build a private version, please
 696     read the description of <a href="#private-ccmio">+FOAM_BUILD_PRIVATE_CCMIO</a>
 697     carefully.
 698 </p>
 699 </li>
 700 <li>
 701 <p>
 702 If you plan on installing FreeFOAM, set <tt>CMAKE_INSTALL_PREFIX</tt> to the base directory
 703     under which FreeFOAM should reside.
 704 </p>
 705 </li>
 706 <li>
 707 <p>
 708 For more fine-grained control over what gets installed where, adjust
 709     <tt>FOAM_INSTALL_CONFIG_PATH</tt>, <tt>FOAM_INSTALL_HEADER_PATH</tt>, <tt>FOAM_INSTALL_LIBRARY_PATH</tt>,
 710     <tt>FOAM_INSTALL_FRAMEWORK_PATH</tt>, <tt>FOAM_INSTALL_PV3FOAMREADER_PATH</tt>,
 711     <tt>FOAM_INSTALL_PVFOAMREADER_PATH</tt> and <tt>FOAM_INSTALL_USERDFOAM_PATH</tt>. Paths not
 712     starting with a slash (<em>/</em>) will be relative to <em>CMAKE_INSTALL_PREFIX</em>. If
 713     you include a leading slash, the paths are absolute.
 714 </p>
 715 </li>
 716 <li>
 717 <p>
 718 If you want FreeFOAM to use <em>float</em> as the floating point type instead of
 719     <em>double</em>, change <tt>FOAM_DOUBLE_PRECISION</tt> to <em>OFF</em>.
 720 </p>
 721 </li>
 722 </ul></div>
 723 </li>
 724 <li>
 725 <p>
 726 Hit <tt>c</tt> again. You shouldn&#8217;t get any errors anymore now. Keep pressing <tt>c</tt>
 727   until ccmake displays "<tt>Press [g] to generate and exit</tt>" in the legend at
 728   the bottom of the interface.
 729 </p>
 730 </li>
 731 <li>
 732 <p>
 733 Press <tt>g</tt> to generate the Makefiles and exit the ccmake interface.
 734 </p>
 735 </li>
 736 <li>
 737 <p>
 738 Start the native build tool. If you used the <em>Makefile</em> generator
 739   (which is the default for Unix-platforms), type
 740 </p>
 741 <div class="listingblock">
 742 <div class="content">
 743 <pre><tt>$ make</tt></pre>
 744 </div></div>
 745 </li>
 746 <li>
 747 <p>
 748 If you have a multi-core/processor machine, you can speed things up
 749   significantly by telling Make to run independent jobs in parallel.
 750   A good choice for the number of parallel jobs to run is the
 751   number of CPU&#8217;s/cores you have in your machine plus 1 (to compensate
 752   for disk-latency). For a typical dual-core machine, run
 753 </p>
 754 <div class="listingblock">
 755 <div class="content">
 756 <pre><tt>$ make -j3</tt></pre>
 757 </div></div>
 758 </li>
 759 </ul></div>
 760 </div>
 761 <h2 id="_installing_freefoam">2. Installing FreeFOAM</h2>
 762 <div class="sectionbody">
 763 <div class="paragraph"><p>If you want to, you can now install FreeFOAM. Depending on the
 764 <tt>CMAKE_INSTALL_PREFIX</tt> and the individual <tt>FOAM_INSTALL_*_PATH</tt> it is possible
 765 that you have to do this as root, i.e. use <tt>su</tt> or <tt>sudo</tt>.</p></div>
 766 <div class="listingblock">
 767 <div class="content">
 768 <pre><tt>$ make install</tt></pre>
 769 </div></div>
 770 </div>
 771 <h2 id="_using_freefoam">3. Using FreeFOAM</h2>
 772 <div class="sectionbody">
 773 <div class="paragraph"><p>If you didn&#8217;t change <tt>CMAKE_INSTALL_PREFIX</tt> and <tt>FOAM_INSTALL_BIN_PATH</tt> chances
 774 are that you can start using FreeFOAM right after you installed it without any
 775 further steps being necessary.</p></div>
 776 <h3 id="globalconfig">3.1. Global Configuration Files</h3><div style="clear:left"></div>
 777 <div class="paragraph"><p>Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
 778 applications require some files to be present for start-up. It finds those
 779 in the following places (in the specified order, picking the first hit):</p></div>
 780 <div class="olist arabic"><ol class="arabic">
 781 <li>
 782 <p>
 783 Under the directory specified in the <tt>$FREEFOAM_CONFIG_DIR</tt> environment
 784    variable
 785 </p>
 786 </li>
 787 <li>
 788 <p>
 789 In <em>$HOME/.FreeFOAM/0.1</em>
 790 </p>
 791 </li>
 792 <li>
 793 <p>
 794 In <em>$HOME/.FreeFOAM</em>
 795 </p>
 796 </li>
 797 <li>
 798 <p>
 799 In the installation directory of the configuration files. There are
 800    two possible places for this:
 801 </p>
 802 <div class="dlist"><dl>
 803 <dt class="hdlist1">
 804 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FOAM_INSTALL_CONFIG_PATH&gt;</em>
 805 </dt>
 806 <dd>
 807 <p>
 808 if you specified
 809      <tt>&lt;FOAM_INSTALL_CONFIG_PATH&gt;</tt> as a relative path.
 810 </p>
 811 </dd>
 812 <dt class="hdlist1">
 813 <em>&lt;FOAM_INSTALL_CONFIG_PATH&gt;</em>
 814 </dt>
 815 <dd>
 816 <p>
 817 if you specified <tt>&lt;FOAM_INSTALL_CONFIG_PATH&gt;</tt> as
 818     an absolute path.
 819 </p>
 820 <div class="paragraph"><p>The default location is <em>/usr/local/etc/FreeFOAM-0.1.0</em>.</p></div>
 821 </dd>
 822 </dl></div>
 823 </li>
 824 </ol></div>
 825 <h3 id="_selecting_the_parallel_communications_library">3.2. Selecting the Parallel Communications Library</h3><div style="clear:left"></div>
 826 <div class="paragraph"><p>Both, FreeFOAM and OpenFOAM abstract the parallel operations into the <em>Pstream</em>
 827 library, making it rather simple to firstly switch between parallel
 828 implementations and secondly port the software to a new communications library.
 829 However, FreeFOAM uses a much more flexible mechanism of determining which
 830 <em>Pstream</em> implementation library to use than OpenFOAM. The latter does this by
 831 adjusting the <tt>LD_LIBRARY_PATH</tt> environment variable.  As FreeFOAM wants to be a
 832 well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically
 833 loads the desired <em>Pstream</em> library at startup (i.e. as a plug-in).  The
 834 following list details how FreeFOAM determines what library to load (if at all):</p></div>
 835 <div class="olist arabic"><ol class="arabic">
 836 <li>
 837 <p>
 838 If the environment variable <tt>FREEFOAM_PSTREAM_LIBRARY</tt> is set,
 839    FreeFOAM will try to load the library specified by it.
 840 </p>
 841 </li>
 842 <li>
 843 <p>
 844 If the sub-dictionary <tt>PstreamImplementation</tt> exists in the global
 845    <em>controlDict</em> file (see <a href="#globalconfig"><em>Global Configuration Files</em></a>), it
 846    reads the value of the entry <tt>configName</tt> therein. It then expects that a
 847    sub-dictionary of <tt>PstreamImplementation</tt> with the name specified in
 848    <tt>configName</tt> exists. If that sub-dictionary contains the entry <tt>library</tt>, it
 849    will try to load a library specified by the value of that entry.
 850 </p>
 851 </li>
 852 </ol></div>
 853 <div class="paragraph"><p>After FreeFOAM (possibly) loaded the library, it will try to instantiate
 854 concrete implementations of the abstract base classes <tt>PstreamImpl</tt>,
 855 <tt>IPstreamImpl</tt> and <tt>OPstreamImpl</tt>. Which classes are to be instantiated
 856 is determined as follows:</p></div>
 857 <div class="olist arabic"><ol class="arabic">
 858 <li>
 859 <p>
 860 FreeFOAM queries the environment variables <tt>FREEFOAM_PSTREAM_CLASS</tt>,
 861    <tt>FREEFOAM_IPSTREAM_CLASS</tt> and <tt>FREEFOAM_OPSTREAM_CLASS</tt> for the class
 862    names to be instantiated.
 863 </p>
 864 </li>
 865 <li>
 866 <p>
 867 For any of the variables not set,  it requires the sub-dictionary
 868    <tt>PstreamImplementation</tt> to be present in the global <em>controlDict</em>, reads the
 869    value of <tt>configName</tt> and similarly to the library loading, loads the
 870    sub-dictionary specified by that value. It then expects to find the entries
 871    <tt>Pstream</tt>, <tt>IPstream</tt> and <tt>OPstream</tt> which specify the names of the classes
 872    to load.
 873 </p>
 874 </li>
 875 </ol></div>
 876 <div class="paragraph"><p>This means that one can create a global <em>controlDict</em> file containing
 877 (among other things) something like the following:</p></div>
 878 <div class="exampleblock">
 879 <div class="exampleblock-content">
 880 <div class="listingblock">
 881 <div class="content">
 882 <pre><tt>PstreamImplementation
 883 {
 884     //configName dummy;
 885     configName mpi;
 886
 887     dummy
 888     {
 889         library libdummyPstream.so;
 890         Pstream dummyPstreamImpl;
 891         OPstream dummyOPstreamImpl;
 892         IPstream dummyIPstreamImpl;
 893     }
 894
 895     mpi
 896     {
 897         library libmpiPstream.so;
 898         Pstream mpiPstreamImpl;
 899         OPstream mpiOPstreamImpl;
 900         IPstream mpiIPstreamImpl;
 901     }
 902 }</tt></pre>
 903 </div></div>
 904 </div></div>
 905 <div class="paragraph"><p>This way the administrator can provide a global <em>controlDict</em> in the FreeFOAM
 906 installation. Every user can then override that <em>controlDict</em> by supplying her
 907 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
 908 for a specific communications library, the user can then either adjust the
 909 <tt>PstreamImplementation::configName</tt> entry in the global <em>controlDict</em> file, set
 910 the <tt>FREEFOAM_PSTREAM_CONFIG</tt> variable or for full control, set the variables
 911 <tt>FREEFOAM_PSTREAM_LIBRARY</tt>, <tt>FREEFOAM_PSTREAM_CLASS</tt>, <tt>FREEFOAM_IPSTREAM_CLASS</tt>
 912 and <tt>FREEFOAM_OPSTREAM_CLASS</tt>.</p></div>
 913 <h3 id="_running_freefoam_from_the_build_tree">3.3. Running FreeFOAM From the Build Tree</h3><div style="clear:left"></div>
 914 <div class="paragraph"><p>You can use FreeFOAM without installing it first, directly from the build tree.
 915 However, this might take a little bit more effort to set up because most likely
 916 you will have to adjust the following environment variables:</p></div>
 917 <div class="dlist"><dl>
 918 <dt class="hdlist1">
 919 PATH
 920 </dt>
 921 <dd>
 922 <p>
 923 Must contain <em>$HOME/Source/freefoam-0.1.0rc4-build/bin</em>
 924 </p>
 925 </dd>
 926 <dt class="hdlist1">
 927 LD_LIBRARY_PATH
 928 </dt>
 929 <dd>
 930 <p>
 931 Must contain <em>$HOME/Source/freefoam-0.1.0rc4-build/lib/FreeFOAM-0.1.0</em>
 932 </p>
 933 </dd>
 934 <dt class="hdlist1">
 935 FREEFOAM_CONFIG_DIR
 936 </dt>
 937 <dd>
 938 <p>
 939 Should point to <em>$HOME/Source/freefoam-0.1.0rc4-build/etc</em>
 940 </p>
 941 </dd>
 942 </dl></div>
 943 <div class="paragraph"><p>Where it is assumed that you followed the <a href="#installation">installation instructions</a>. If
 944 you used different paths for downloading and compiling FreeFOAM, you will have
 945 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
 946 variables.</p></div>
 947 </div>
 948 <h2 id="_running_the_tutorials">4. Running the tutorials</h2>
 949 <div class="sectionbody">
 950 <div class="paragraph"><p>Now you should be able to run the tutorial cases. For this copy the <tt>tutorials</tt>
 951 directory to some convenient place:</p></div>
 952 <div class="listingblock">
 953 <div class="content">
 954 <pre><tt>$ mkdir -p $HOME/FreeFOAM/$LOGNAME-0.1/run
 955 $ cp -r $HOME/Source/freefoam-0.1.0rc4-build/tutorials $HOME/FreeFOAM/$LOGNAME-0.1/run/
 956 $ cd $HOME/FreeFOAM/$LOGNAME-0.1/run/tutorials</tt></pre>
 957 </div></div>
 958 <div class="paragraph"><p>And try to run e.g. the <em>cavity</em> tutorial case:</p></div>
 959 <div class="listingblock">
 960 <div class="content">
 961 <pre><tt>$ cd icoFoam
 962 $ freefoam blockMesh -case cavity
 963 $ freefoam checkMesh -case cavity
 964 $ freefoam ico -case cavity</tt></pre>
 965 </div></div>
 966 <div class="paragraph"><p>Things should run smoothly and finish without an error.</p></div>
 967 </div>
 968 <h2 id="_obtaining_the_source_code_from_the_git_repository">5. Obtaining the Source Code from the GIT repository</h2>
 969 <div class="sectionbody">
 970 <div class="ulist"><ul>
 971 <li>
 972 <p>
 973 Clone the FreeFOAM repository (here the clone is placed in
 974   <tt>$HOME/Source/FreeFOAM</tt>):
 975 </p>
 976 <div class="listingblock">
 977 <div class="content">
 978 <pre><tt>$ mkdir -p $HOME/Source
 979 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM</tt></pre>
 980 </div></div>
 981 </li>
 982 <li>
 983 <p>
 984 Proceed in the same way (replacing the path names apropriately) as in the
 985   above build instructions.
 986 </p>
 987 </li>
 988 </ul></div>
 989 </div>
 990 <h2 id="_shell_completion_scripts">6. Shell completion scripts</h2>
 991 <div class="sectionbody">
 992 <div class="paragraph"><p>FreeFOAM comes with completions scripts for the
 993 <a href="http://www.gnu.org/software/bash/">BASH</a> and <a href="http://www.zsh.org/">ZSH</a> shells.
 994 The former is quite simplistic and only offers very basic completion of the
 995 available application names. The ZSH completion, however, is quite complete and
 996 also completes options and arguments for all applications. These completion
 997 functions are not installed by <tt>make install</tt>, because no two systems have the
 998 same locations for these kinds of scripts. You find them for manual
 999 installation in the FreeFOAM sources in the directory
1000 <em>data/shellFunctions/bashCompletion</em> and <em>data/shellFunctions/zshCompletion</em>
1001 respectively. Please refer to the documentation of your system/shell on where
1002 to place them.</p></div>
1003 </div>
1004 <h2 id="_emacs_mode">7. Emacs mode</h2>
1005 <div class="sectionbody">
1006 <div class="paragraph"><p>FreeFOAM includes a rudimentary major mode for the
1007 <a href="http://www.gnu.org/software/emacs">Emacs</a> programming editor. If you want to use
1008 this mode, place the file <em>data/editor-modes/foamdict-mode.el</em> in a directory
1009 where your Emacs installation finds it. Please refer to the Emacs documentation
1010 for further instructions.</p></div>
1011 </div>
1012 <h2 id="_build_configuration_reference">8. Build Configuration Reference</h2>
1013 <div class="sectionbody">
1014 <div class="dlist glossary"><dl>
1015 <dt>
1016 <tt>CMAKE_BUILD_TYPE</tt>
1017 </dt>
1018 <dd>
1019 <p>
1020   One of <em>&lt;empty&gt;</em>, <em>Debug</em>, <em>Release</em>, <em>RelWithDebInfo</em> and <em>MinSizeRel</em>.
1021   Refer to the CMake documentation for more detail.
1022 </p>
1023 </dd>
1024 <dt>
1025 <tt>FOAM_DOUBLE_PRECISION</tt>
1026 </dt>
1027 <dd>
1028 <p>
1029   If set to <em>ON</em> FreeFOAM will be compiled using <em>double</em> as the
1030   floating point type. If set to <em>OFF</em> it will use <em>float</em>.
1031 </p>
1032 </dd>
1033 <dt>
1034 <tt>FOAM_BUILD_FRAMEWORKS</tt>
1035 </dt>
1036 <dd>
1037 <p>
1038   If this is enabled, the libraries are built as frameworks. Only available on
1039   Mac OS X.
1040 </p>
1041 </dd>
1042 <dt>
1043 <tt>FOAM_EXE_PREFIX</tt>
1044 </dt>
1045 <dd>
1046 <p>
1047   Prefix used to mangle application names. Normally this shouldn&#8217;t be changed.
1048 </p>
1049 </dd>
1050 <dt>
1051 <tt>CMAKE_INSTALL_PREFIX</tt>
1052 </dt>
1053 <dd>
1054 <p>
1055   Installation prefix under which to install FreeFOAM.
1056 </p>
1057 </dd>
1058 <dt>
1059 <tt>FOAM_INSTALL_BIN_PATH</tt>
1060 </dt>
1061 <dd>
1062 <p>
1063   Installation path of the binaries. If not absolute, it is relative to
1064   <em>CMAKE_INSTALL_PREFIX</em>.
1065 </p>
1066 </dd>
1067 <dt>
1068 <tt>FOAM_INSTALL_LIBEXEC_PATH</tt>
1069 </dt>
1070 <dd>
1071 <p>
1072   Installation path of the binaries which should not be on the <tt>PATH</tt>. If not
1073   absolute, it is relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
1074 </p>
1075 </dd>
1076 <dt>
1077 <tt>FOAM_INSTALL_CONFIG_PATH</tt>
1078 </dt>
1079 <dd>
1080 <p>
1081   Installation path of the configuration files. If not absolute, it is
1082   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1083 </p>
1084 </dd>
1085 <dt>
1086 <tt>FOAM_INSTALL_HEADER_PATH</tt>
1087 </dt>
1088 <dd>
1089 <p>
1090   Installation path of the header files. If not absolute, it is
1091   relative to <em>CMAKE_INSTALL_PREFIX</em>. On Mac OS X, and if
1092   <em>FOAM_BUILD_FRAMEWORKS</em> is enabled, this setting is ignored.
1093 </p>
1094 </dd>
1095 <dt>
1096 <tt>FOAM_INSTALL_LIBRARY_PATH</tt>
1097 </dt>
1098 <dd>
1099 <p>
1100   Installation path of the libraries. If not absolute, it is
1101   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1102 </p>
1103 </dd>
1104 <dt>
1105 <tt>FOAM_INSTALL_FRAMEWORK_PATH</tt>
1106 </dt>
1107 <dd>
1108 <p>
1109   Installation path of the Mac OS X frameworks. If not absolute, it is
1110   relative to <em>CMAKE_INSTALL_PREFIX</em>. This is only available and takes
1111   effect if FreeFOAM is compiled on Mac OS X, and if
1112   <em>FOAM_BUILD_FRAMEWORKS</em> is enabled.
1113 </p>
1114 </dd>
1115 <dt>
1116 <tt>FOAM_INSTALL_PV3FOAMREADER_PATH</tt>
1117 </dt>
1118 <dd>
1119 <p>
1120   Installation path of the ParaView3 plug-ins. If not absolute, it is
1121   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1122 </p>
1123 </dd>
1124 <dt>
1125 <tt>FOAM_INSTALL_PVFOAMREADER_PATH</tt>
1126 </dt>
1127 <dd>
1128 <p>
1129   Installation path of the ParaView2 plug-ins. If not absolute, it is
1130   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1131 </p>
1132 </dd>
1133 <dt>
1134 <tt>FOAM_INSTALL_USERDFOAM_PATH</tt>
1135 </dt>
1136 <dd>
1137 <p>
1138   Installation path of the Ensight plug-in. If not absolute, it is
1139   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1140 </p>
1141 </dd>
1142 <dt>
1143 <tt>FOAM_USE_GAMMA</tt>
1144 </dt>
1145 <dd>
1146 <p>
1147   If enabled, FreeFOAM will use the GAMMA parallel communications library.
1148   This is currently not implemented.
1149 </p>
1150 </dd>
1151 <dt>
1152 <tt>FOAM_USE_MPI</tt>
1153 </dt>
1154 <dd>
1155 <p>
1156   If enabled, FreeFOAM will use the MPI parallel communications library.
1157   This is required in order to build some of the libraries and utilities.
1158 </p>
1159 </dd>
1160 <dt>
1161 <tt>FOAM_DEFAULT_PSTREAM</tt>
1162 </dt>
1163 <dd>
1164 <p>
1165   The default Pstream selection in the global <em>controlDict</em> file.
1166 </p>
1167 </dd>
1168 <dt>
1169 <tt>FOAM_BUILD_PARAVIEW_PLUGINS</tt>
1170 </dt>
1171 <dd>
1172 <p>
1173   Whether to build the ParaView plug-ins. If enabled, FreeFOAM requires a
1174   ParaView build tree and the <em>ParaView_DIR</em> variable set to the path of it.
1175 </p>
1176 </dd>
1177 <dt>
1178 <tt>FOAM_ENABLE_CCMIO</tt>
1179 </dt>
1180 <dd>
1181 <p>
1182   Enable the use of <em>libccmio</em>. This is required to build the grid conversion
1183   utility <em>ccm26ToFoam</em>.
1184 </p>
1185 <div class="admonitionblock" id="enable-ccmio">
1186 <table><tr>
1187 <td class="icon">
1188 <div class="title">Warning</div>
1189 </td>
1190 <td class="content">The license of <em>libccmio</em> &#169; is proprietary and requires the consent of the
1191 copyright holders (<a href="http://www.cd-adapco.com">CD-adapco</a>) to download and use the
1192 library. Further it is not allowed to redistribute it in any form. The request
1193 for permission of inclusion with <a href="http://debian.org">Debian</a> was answered as
1194 follows by <a href="mailto:geoffrey.prewett@us.cd-adapco.com">Geoffrey Prewett</a>:</td>
1195 </tr></table>
1196 </div>
1197 <div class="listingblock">
1198 <div class="content">
1199 <pre><tt>Gerber,
1200
1201 Sorry for the delay in response.  I checked back with our development director,
1202 and he felt that it would be best to not include libccmio with Debian.
1203 Instead, we would prefer to continue our current policy and keep it on our
1204 web/FTP and have people ask for it.  There are three reasons for this:
1205
1206 1) We don't support STAR on Debian, and don't want to give the impression that we do.
1207 2) We would like to keep a list of people that we give the library to.
1208 3) This is not a general purpose library;  its sole purpose is to communicate
1209 between our products.  Accepting outside changes risks committing a change that
1210 would break our own software in possibly subtle ways.
1211
1212 So I regret to tell you that my company has declined to permit libccmio to be
1213 distributed as part of Debian.
1214
1215 Regards,
1216 Geoff Prewett</tt></pre>
1217 </div></div>
1218 </dd>
1219 <dt>
1220 <tt>FOAM_BUILD_PRIVATE_CCMIO</tt>
1221 </dt>
1222 <dd>
1223 <p>
1224   Automatically download and build libccmio. Unfortunately this process may
1225   fail in the download step if CMake cannot find either <em>wget</em> or <em>curl</em> on
1226   your system, since CMake itself currently does not support <em>https</em> URLs. If
1227   this happens, the build process will abort. To fix the issue, Download the
1228   file <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>
1229   manually and place it in <tt>ThirdParty/ccmio/src</tt> (relative to the build
1230   directory). It is important that you re-run CMake <strong>before</strong> restarting the
1231   build in order to notify the build system that the file is now there.
1232 </p>
1233 </dd>
1234 <dt>
1235 <tt>FOAM_ENABLE_METIS</tt>
1236 </dt>
1237 <dd>
1238 <p>
1239   Enable the use of the <em>METIS</em> graph partitioning library which is required to
1240   implement the <em>metis</em> decomposition method.
1241 </p>
1242 </dd>
1243 <dt>
1244 <tt>FOAM_BUILD_PRIVATE_METIS</tt>
1245 </dt>
1246 <dd>
1247 <p>
1248   Automatically download and build <em>METIS</em>.
1249 </p>
1250 </dd>
1251 <dt>
1252 <tt>FOAM_BUILD_PRIVATE_PARMETIS</tt>
1253 </dt>
1254 <dd>
1255 <p>
1256   Automatically download and build <em>ParMetis</em>.
1257 </p>
1258 </dd>
1259 <dt>
1260 <tt>FOAM_ENABLE_MGRIDGEN</tt>
1261 </dt>
1262 <dd>
1263 <p>
1264   Enable the use of <em>MGRIDGEN</em> which is required to build
1265   <em>MGridGenGamgAgglomeration</em> providing the <em>MGridGen</em> agglomeration method for
1266   the GAMG solver.
1267 </p>
1268 <div class="admonitionblock" id="enable-mgridgen">
1269 <table><tr>
1270 <td class="icon">
1271 <div class="title">Warning</div>
1272 </td>
1273 <td class="content">The license of <em>MGRIDGEN</em> is unknown and the upstream authors so far have not
1274 answered any inquiries to resolve the issue. If you enable the use of
1275 <em>MGRIDGEN</em> you alone are responsible for ensuring that you don&#8217;t violate any
1276 license conditions applying to these libraries. The authors of FreeFOAM will
1277 and cannot take any responsibility for your actions.</td>
1278 </tr></table>
1279 </div>
1280 </dd>
1281 <dt>
1282 <tt>FOAM_BUILD_PRIVATE_MGRIDGEN</tt>
1283 </dt>
1284 <dd>
1285 <p>
1286   Automatically download and build <em>MGRIDGEN</em>.
1287 </p>
1288 </dd>
1289 <dt>
1290 <tt>FOAM_ENABLE_DOXYGEN_DOCS</tt>
1291 </dt>
1292 <dd>
1293 <p>
1294   Enable building of the <em>Doxygen API documentation</em>. The documentation will
1295   only be built once and is not updated automatically. This is because it
1296   depends on a huge number of files and would make dependency tracking very
1297   slow and difficult to maintain. To force the re-generation of the API
1298   documentation execute <tt>make apidoc</tt>.
1299 </p>
1300 </dd>
1301 <dt>
1302 <tt>FOAM_DOXYDOCS_FOR_SF</tt>
1303 </dt>
1304 <dd>
1305 <p>
1306   This setting is for the maintainers of the FreeFOAM and indicates whether the
1307   Doxygen documentation should be built for deployment on
1308   <a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a>.
1309 </p>
1310 </dd>
1311 <dt>
1312 <tt>FOAM_ENABLE_MANPAGE_HELP</tt>
1313 </dt>
1314 <dd>
1315 <p>
1316   <a id="foam_enable_manpage_help"></a>
1317   Build (and install) the help-pages in manpage format. This requires a
1318   complete <a href="http://www.methods.co.nz/asciidoc">Asciidoc</a> toolchain to be present.
1319 </p>
1320 </dd>
1321 <dt>
1322 <tt>FOAM_ENABLE_XHMTL_HELP</tt>
1323 </dt>
1324 <dd>
1325 <p>
1326   Build (and install) the help-pages in xhtml format for the display in a web
1327   browser. The requirements are the same as for
1328   <a href="#foam_enable_manpage_help"><tt>FOAM_ENABLE_MANPAGE_HELP</tt></a>.
1329 </p>
1330 </dd>
1331 <dt>
1332 <tt>FOAM_USE_LOCAL_DOXYGEN_DOCS</tt>
1333 </dt>
1334 <dd>
1335 <p>
1336   This setting influences the location in which the Doxygen source
1337   code documentation is looked for if any of the FreeFOAM applications
1338   is invoked with the <em>-doc</em> or <em>-srcDoc</em> options. If it is disabled,
1339   the documentation will be loaded over the network from
1340   <a href="http://freefoam.sf.net/doc/Doxygen/html">http://freefoam.sf.net/doc/Doxygen/html</a>. If you enable it, the
1341   documentation will be loaded locally. This requires that you either
1342   build and install the documentation by enabling <tt>FOAM_ENABLE_DOXYGEN_DOCS</tt>,
1343   or provide the required HTML files otherwise.
1344 </p>
1345 </dd>
1346 <dt>
1347 <tt>HTML_DOC_BROWSER</tt>
1348 </dt>
1349 <dd>
1350 <p>
1351   This is the program used to display the Doxygen source code documentation
1352   if any of the FreeFOAM applications is invoked with the <em>-doc</em> or <em>-srcDoc</em>
1353   options. The special value of <em>ECHO</em> changes the behaviour to just write
1354   the location of the HTML file to the output. This is a good setting if
1355   you&#8217;re system doesn&#8217;t have any kind of HTML browser installed (such
1356   as on a cluster).
1357 </p>
1358 </dd>
1359 <dt>
1360 <tt>FOAM_HTML_DOC_BROWSER_COMMAND</tt>
1361 </dt>
1362 <dd>
1363 <p>
1364   This is the command with which to invoke the HTML browser. By default
1365   it calls the program named in <tt>HTML_DOC_BROWSER</tt> and passes it the
1366   name/URL of the documentation file to be displayed. You shouldn&#8217;t
1367   have to change this unless your HTML browser requires some unusual
1368   options or arguments.
1369 </p>
1370 </dd>
1371 </dl></div>
1372 </div>
1373 <h2 id="_troubleshooting">9. Troubleshooting</h2>
1374 <div class="sectionbody">
1375 <h3 id="_the_freefoam_executables_are_not_found_by_the_shell">9.1. The FreeFOAM Executables Are Not Found By The Shell</h3><div style="clear:left"></div>
1376 <div class="paragraph"><p>There are three possible reasons for this:</p></div>
1377 <div class="olist arabic"><ol class="arabic">
1378 <li>
1379 <p>
1380 Your shell (notably <em>csh</em>, <em>tcsh</em> and <em>zsh</em>) requires you to refresh the
1381    cache of available executables. You can do so by entering the command:
1382 </p>
1383 <div class="listingblock">
1384 <div class="content">
1385 <pre><tt>$ rehash</tt></pre>
1386 </div></div>
1387 </li>
1388 <li>
1389 <p>
1390 If <em>rehashing</em> didn&#8217;t solve the problem, the problem most likely is that you
1391    installed FreeFOAM into a non-standard location by changing the configuration
1392    variables <tt>CMAKE_INSTALL_PREFIX</tt> or <tt>FOAM_INSTALL_BIN_PATH</tt> in which case the
1393    executables where installed into a directory not searched by the shell. In
1394    this case you have to add the installation directory of the executables to
1395    the <tt>PATH</tt> variable. There are two possible locations:
1396 </p>
1397 <div class="dlist"><dl>
1398 <dt class="hdlist1">
1399 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FOAM_INSTALL_BIN_PATH&gt;</em>
1400 </dt>
1401 <dd>
1402 <p>
1403 if you specified
1404   <tt>FOAM_INSTALL_BIN_PATH</tt> as a relative path
1405 </p>
1406 </dd>
1407 <dt class="hdlist1">
1408 <em>&lt;FOAM_INSTALL_BIN_PATH&gt;</em>
1409 </dt>
1410 <dd>
1411 <p>
1412 if you specified <tt>FOAM_INSTALL_BIN_PATH</tt> as an absolute
1413   path
1414 </p>
1415 </dd>
1416 </dl></div>
1417 <div class="paragraph"><p>After extending the <tt>PATH</tt> variable with the installation directory of the
1418 executables, you should be able to run all FreeFOAM applications as any other
1419 binary available on the system. See <a href="#environment"><em>Extending Search Paths And Setting Environment Variables Permanently</em></a> for
1420 instructions on how to extend the search path.</p></div>
1421 </li>
1422 <li>
1423 <p>
1424 This option is similar to the previous solution and applies if you want to
1425    run FreeFOAM from the build tree (i.e. without running <tt>make install</tt>). In
1426    this case you again have to make sure that your shell finds the executables
1427    built by CMake by extending the <tt>PATH</tt> variable. Further, you have to tell
1428    FreeFOAM where to find the global configuration files (see
1429    <a href="#globalconfig"><em>Global Configuration Files</em></a>). Here, you have the option to
1430    place the files under your home directory or set an environment variable. The
1431    former can be achieved by:
1432 </p>
1433 <div class="listingblock">
1434 <div class="content">
1435 <pre><tt>$ mkdir -p $HOME/.FreeFOAM/0.1
1436 $ cp $HOME/Source/freefoam-0.1.0rc4-build/etc/controlDict $HOME/.FreeFOAM/0.1
1437 $ cp $HOME/Source/freefoam-0.1.0rc4-build/etc/cellModels $HOME/.FreeFOAM/0.1
1438 $ cp -r $HOME/Source/freefoam-0.1.0rc4-build/etc/thermoData $HOME/.FreeFOAM/0.1</tt></pre>
1439 </div></div>
1440 <div class="paragraph"><p>The latter (and recommended) method is to set the environment variable
1441 <tt>FREEFOAM_CONFIG_DIR</tt> to <em>$HOME/Source/freefoam-0.1.0rc4-build/etc</em>. Adjust paths to the
1442 build tree to your actual setup.</p></div>
1443 </li>
1444 </ol></div>
1445 <h3 id="_starting_any_freefoam_application_fails_because_some_libraries_cannot_be_found">9.2. Starting Any FreeFOAM Application Fails Because Some Libraries Cannot Be Found</h3><div style="clear:left"></div>
1446 <div class="paragraph"><p>Although CMake should have taken care of this by using <tt>RPATH</tt> on Linux and
1447 <tt>install_name</tt> on Mac OS X, it might be necessary on some systems to adjust the
1448 library search paths:</p></div>
1449 <div class="dlist"><dl>
1450 <dt class="hdlist1">
1451 <tt>LD_LIBRARY_PATH</tt>
1452 </dt>
1453 <dd>
1454 <p>
1455 This variable is used by all Unix like systems (e.g. Linux,
1456   Mac OS X, etc.)
1457 </p>
1458 </dd>
1459 <dt class="hdlist1">
1460 <tt>DYLD_LIBRARY_PATH</tt>
1461 </dt>
1462 <dd>
1463 <p>
1464 This variable is used by Mac OS X.
1465 </p>
1466 </dd>
1467 </dl></div>
1468 <div class="paragraph"><p>If you installed FreeFOAM, there are (as with the executables), two possible
1469 installation directories:</p></div>
1470 <div class="dlist"><dl>
1471 <dt class="hdlist1">
1472 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FOAM_INSTALL_LIBRARY_PATH&gt;</em>
1473 </dt>
1474 <dd>
1475 <p>
1476 if you specified
1477   <tt>FOAM_INSTALL_LIBRARY_PATH</tt> as a relative path.
1478 </p>
1479 </dd>
1480 <dt class="hdlist1">
1481 <em>&lt;FOAM_INSTALL_LIBRARY_PATH&gt;</em>
1482 </dt>
1483 <dd>
1484 <p>
1485 if you specified <tt>FOAM_INSTALL_LIBRARY_PATH</tt> as an absolute
1486   path.
1487 </p>
1488 </dd>
1489 </dl></div>
1490 <div class="paragraph"><p>If you are trying to run from the build tree, you have to include
1491 <em>$HOME/Source/freefoam-0.1.0rc4-build/lib/FreeFOAM-0.1.0</em> in the above mentioned search
1492 paths (where you have to adjust the location of the build tree to your actual
1493 setup).</p></div>
1494 <h3 id="_a_running_freefoam_application_aborts_because_it_can_8217_t_em_dlopen_em_a_library">9.3. A Running FreeFOAM Application Aborts Because It Can&#8217;t <em>dlopen</em> A Library</h3><div style="clear:left"></div>
1495 <div class="paragraph"><p>FreeFOAM (and OpenFOAM) often dynamically load libraries at run-time (a.k.a
1496 plug-ins) to add features the user requested without requiring that the whole
1497 application be recompiled. This makes it very simple to add new boundary
1498 conditions, turbulence and combustion models etc. However, it also requires that
1499 FreeFOAM must be able to find these libraries at run-time. The operating system
1500 function which does the loading of the libraries (<em>dlopen</em>) usually tries to
1501 find the library with the given name in several places; namely a default search
1502 path and a search path configured by one or multiple environment variables such
1503 as <tt>LD_LIBRARY_PATH</tt> or <tt>DYLD_LIBRARY_PATH</tt> (on Mac OS X). The details vary from
1504 platform to platform, so you best consult the documentation of <em>dlopen</em> for the
1505 details.</p></div>
1506 <div class="paragraph"><p>Additionally FreeFOAM allows you to configure a custom search path for plug-ins
1507 in the <a href="#globalconfig">global <em>controlDict</em></a> file by listing the directories to
1508 be searched in the list <tt>LibrarySearchPaths</tt>. By default FreeFOAM is configured
1509 to search for plug-ins in the location where CMake installed them.</p></div>
1510 <div class="paragraph"><p>If you want to add your own plug-in libraries (e.g. you want to add your own
1511 boundary conditions class), you most probably will want to extend this search
1512 path.</p></div>
1513 <h3 id="_freefoam_aborts_when_trying_to_instantiate_a_plugin_class">9.4. FreeFOAM Aborts When Trying To Instantiate a Plugin Class</h3><div style="clear:left"></div>
1514 <div class="paragraph"><p>If you get a warning message similar to the following</p></div>
1515 <div class="literalblock">
1516 <div class="content">
1517 <pre><tt>--&gt; FOAM Warning :
1518     From function dlLibraryTable::open(const dictionary&amp; dict, const word&amp; libsEntry, const TablePtr tablePtr)
1519     in file XXX/src/OpenFOAM/db/dlLibraryTable/dlLibraryTableTemplates.C at line 68
1520     library "libfieldFunctionObjects.so" did not introduce any new entries</tt></pre>
1521 </div></div>
1522 <div class="paragraph"><p>(where <tt>XXX</tt> is the path to the FreeFOAM source code and the actual library
1523 name can be different), followed by a fatal error stating that FreeFOAM does
1524 not know a class or type, e.g.</p></div>
1525 <div class="literalblock">
1526 <div class="content">
1527 <pre><tt>--&gt; FOAM FATAL ERROR:
1528 Unknown function type fieldAverage</tt></pre>
1529 </div></div>
1530 <div class="literalblock">
1531 <div class="content">
1532 <pre><tt>Table of functionObjects is empty</tt></pre>
1533 </div></div>
1534 <div class="literalblock">
1535 <div class="content">
1536 <pre><tt>From function functionObject::New(const word&amp; name, const Time&amp;, const dictionary&amp;)
1537 in file XXX/src/OpenFOAM/db/functionObjects/functionObject/functionObject.C at line 74.</tt></pre>
1538 </div></div>
1539 <div class="literalblock">
1540 <div class="content">
1541 <pre><tt>FOAM exiting</tt></pre>
1542 </div></div>
1543 <div class="paragraph"><p>and you are absolutely sure that the named type actually exists in the library
1544 mentioned in the preceding warning message, the issue is very likely that
1545 FreeFOAM is loading the plugin library from a different binary tree than the
1546 executable belongs to.</p></div>
1547 <div class="admonitionblock">
1548 <table><tr>
1549 <td class="icon">
1550 <div class="title">Important</div>
1551 </td>
1552 <td class="content">Always make sure that you never load plugins from different binary trees (where
1553 the build tree and the install tree count as such). If you want to run a binary
1554 from the build tree but already have a corresponding installation tree, use the
1555 <tt>FREEFOAM_CONFIG_DIR</tt> environment variable to point FreeFOAM to the directory
1556 <em>&lt;path to build tree&gt;/etc/</em> containing the global <em>controlDict</em> file in the
1557 <strong>build tree</strong>.</td>
1558 </tr></table>
1559 </div>
1560 </div>
1561 <h2 id="environment">10. Extending Search Paths And Setting Environment Variables Permanently</h2>
1562 <div class="sectionbody">
1563 <div class="paragraph"><p>The way one sets environment variables and extends the executable and library
1564 search paths permanently strongly depends on the shell used. Usually one has to
1565 create or change an initialization file in the users home directory. In the
1566 following this will be discussed very briefly for the popular shells <em>BASH</em> and
1567 <em>tcsh</em>.  However, if you need more help or want information on using the shell,
1568 there is an excellent tutorial available at <a href="http://linuxcommand.org">http://linuxcommand.org</a>.</p></div>
1569 <h3 id="_bash">10.1. BASH</h3><div style="clear:left"></div>
1570 <div class="paragraph"><p>The BASH shell is the default shell for most Linux/Unix distributions. Most
1571 systems configure the BASH shell such that it reads the text file
1572 <em>$HOME/.bashrc</em> when starting up, so this is the place where one appends
1573 customizations of the environment variables. On some systems this file is not
1574 processed by default (notably Mac OS X). In this case you can use
1575 <em>$HOME/.bash_profile</em>.</p></div>
1576 <h4 id="_referencing_a_variable">10.1.1. Referencing A Variable</h4>
1577 <div class="paragraph"><p>To retrieve the value stored in a shell variable or environment variable, one
1578 prefixes its name with the dollar (<tt>$</tt>) character.</p></div>
1579 <h4 id="_setting_a_variable">10.1.2. Setting A Variable</h4>
1580 <div class="paragraph"><p>The syntax for setting a variable and making it available to child-processes of
1581 the shell is the following:</p></div>
1582 <div class="listingblock">
1583 <div class="content">
1584 <pre><tt>$ export variable_name=variable_value</tt></pre>
1585 </div></div>
1586 <div class="paragraph"><p>Note that no white-space characters are allowed surrounding the <tt>=</tt> sign.</p></div>
1587 <h4 id="_extending_a_search_path">10.1.3. Extending A Search Path</h4>
1588 <div class="paragraph"><p>The shell and other Unix system facilities use environment variables to locate
1589 executables and dynamically linked libraries. These search paths consist of
1590 strings naming directories in which the executables and libraries should be
1591 searched for. The individual paths are separated by a colon (<tt>:</tt>) character. To
1592 add the e.g. the directory <em>$HOME/bin</em> to the search path for executables, one
1593 would do the following:</p></div>
1594 <div class="listingblock">
1595 <div class="content">
1596 <pre><tt>$ export PATH=$PATH:$HOME/bin</tt></pre>
1597 </div></div>
1598 <div class="paragraph"><p>which appends <em>$HOME/bin</em> to the end of the <tt>PATH</tt> variable.</p></div>
1599 <h3 id="_tcsh">10.2. TCSH</h3><div style="clear:left"></div>
1600 <div class="paragraph"><p>Some users and administrators prefer to use a <em>C-Shell</em>, such as the TCSH. Here
1601 you can use e.g. the file <em>$HOME/.tcshrc</em> to customize the environment.</p></div>
1602 <h4 id="_referencing_a_variable_2">10.2.1. Referencing A Variable</h4>
1603 <div class="paragraph"><p>As with the BASH, one retrieves the value stored in a shell variable or
1604 environment variable by prefixing its name with the dollar (<tt>$</tt>) character.
1605 Sometimes it is also necessary to protect the variable name by surrounding it
1606 with curly braces (<tt>{</tt> and <tt>}</tt>).</p></div>
1607 <h4 id="_setting_a_variable_2">10.2.2. Setting A Variable</h4>
1608 <div class="paragraph"><p>The syntax for setting a variable and making it available to child-processes of
1609 the shell is the following:</p></div>
1610 <div class="listingblock">
1611 <div class="content">
1612 <pre><tt>$ setenv variable_name variable_value</tt></pre>
1613 </div></div>
1614 <h4 id="_extending_a_search_path_2">10.2.3. Extending A Search Path</h4>
1615 <div class="paragraph"><p>The shell and other Unix system facilities use environment variables to locate
1616 executables and dynamically linked libraries. These search paths consist of
1617 strings naming directories in which the executables and libraries should be
1618 searched for. The individual paths are separated by a colon (<tt>:</tt>) character. To
1619 add the e.g. the directory <em>$HOME/bin</em> to the search path for executables, one
1620 would do the following:</p></div>
1621 <div class="listingblock">
1622 <div class="content">
1623 <pre><tt>$ setenv PATH ${PATH}:${HOME}/bin</tt></pre>
1624 </div></div>
1625 <div class="paragraph"><p>which appends <em>$HOME/bin</em> to the end of the <tt>PATH</tt> variable.  Note that
1626 <em>C-shells</em> usually require the user to type <em>rehash</em> after changing the <tt>PATH</tt>
1627 variable to update the cache of available programs.</p></div>
1628 </div>
1629 </div>
1630 <div id="footnotes"><hr /></div>
1631 <div id="footer">
1632 <div id="footer-text">
1633 Version 0.1.0rc4<br />
1634 Last updated 2010-06-18 08:59:01 CEST
1635 </div>
1636 </div>
1637 </body>
1638 </html>