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></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></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 <div id="toc">
 558   <div id="toctitle">Table of Contents</div>
 559   <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
 560 </div>
 561 </div>
 562 <div id="content">
 563 <div id="preamble">
 564 <div class="sectionbody">
 565 <div class="paragraph"><p><a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a></p></div>
 566 </div>
 567 </div>
 568 <h2 id="_building_freefoam">Building FreeFOAM</h2>
 569 <div class="sectionbody">
 570 <div class="ulist"><ul>
 571 <li>
 572 <p>
 573 Install the prerequisites documented in the <a href="README.html">README</a> file. If
 574   your distribution does not have <em>METIS</em>, <em>ParMetis</em>, <em>MGRIDGEN</em> or <em>libccmio</em>
 575   be not worried, FreeFOAM can handle those for you.
 576 </p>
 577 </li>
 578 <li>
 579 <p>
 580 Download the FreeFOAM source and unpack it somewhere convenient. For the
 581   further instructions we will use <tt>$HOME/Source/</tt>.
 582 </p>
 583 <div class="listingblock">
 584 <div class="content">
 585 <pre><tt>$ mkdir -p $HOME/Source
 586 $ cd $HOME/Source
 587 $ wget http://master.dl.sourceforge.net/sourceforge/freefoam/freefoam-{fullver}.tar.bz2
 588 $ tar xjf freefoam-{fullver}.tar.bz2</tt></pre>
 589 </div></div>
 590 </li>
 591 <li>
 592 <p>
 593 Create a build tree and <em>cd</em> into it:
 594 </p>
 595 <div class="listingblock">
 596 <div class="content">
 597 <pre><tt>$ mkdir $HOME/Source/freefoam-{fullver}-build
 598 $ cd $HOME/Source/freefoam-{fullver}-build</tt></pre>
 599 </div></div>
 600 </li>
 601 <li>
 602 <p>
 603 Start CMake-configuration:
 604 </p>
 605 <div class="listingblock">
 606 <div class="content">
 607 <pre><tt>$ ccmake $HOME/Source/freefoam-{fullver}</tt></pre>
 608 </div></div>
 609 </li>
 610 <li>
 611 <p>
 612 Press the <tt>c</tt> key. Use the arrow keys to navigate up and down and press
 613   <tt>enter</tt> to edit a field. To commit the change, press <tt>enter</tt> again, or <tt>ESC</tt>
 614   to abandon the change.  ON/OFF fields are toggled by pressing <tt>enter</tt>.
 615   Advanced options can be displayed by hitting the <tt>t</tt> key.
 616 </p>
 617 <div class="ulist"><ul>
 618 <li>
 619 <p>
 620 Set <tt>CMAKE_BUILD_TYPE</tt> to <em>Release</em> for an optimized build.
 621 </p>
 622 </li>
 623 <li>
 624 <p>
 625 If CMake complains that it can&#8217;t find MPI, and you don&#8217;t want to install it, disable
 626     <tt>FOAM_USE_MPI</tt>. If, instead, you want to use GAMMA, enable <tt>FOAM_USE_GAMMA</tt>.
 627     You can also enable more than one of the options.
 628 </p>
 629 <div class="admonitionblock">
 630 <table><tr>
 631 <td class="icon">
 632 <div class="title">Note</div>
 633 </td>
 634 <td class="content">Currently only the MPI implementation is available.</td>
 635 </tr></table>
 636 </div>
 637 </li>
 638 <li>
 639 <p>
 640 Select the default Pstream implementation by setting <tt>FOAM_DEFAULT_PSTREAM</tt>
 641     to one of <em>dummy</em>, <em>mpi</em> or <em>gamma</em>. This setting will only influence
 642     the contents of the <a href="#globalconfig">global <em>controlDict</em> file</a>.
 643 </p>
 644 </li>
 645 <li>
 646 <p>
 647 If CMake told you it couldn&#8217;t find ParaView:
 648 </p>
 649 <div class="olist arabic"><ol class="arabic">
 650 <li>
 651 <p>
 652 Set <tt>ParaView_DIR</tt> to the path of the directory containing
 653     <em>ParaViewConfig.cmake</em>, which is most likely the ParaView build directory.
 654 </p>
 655 </li>
 656 <li>
 657 <p>
 658 If you do not want to build the ParaView plug-ins, disable
 659     <tt>FOAM_BUILD_PARAVIEW_PLUGINS</tt>
 660 </p>
 661 </li>
 662 </ol></div>
 663 </li>
 664 <li>
 665 <p>
 666 If you want to use the <em>metis</em> and <em>parmetis</em> decomposition methods, make
 667     sure that <tt>FOAM_ENABLE_METIS</tt> and <tt>FOAM_ENABLE_PARMETIS</tt> are enabled,
 668     respectively. If you do not have <em>METIS</em> or <em>ParMetis</em> installed, enable
 669     <tt>FOAM_BUILD_PRIVATE_METIS</tt> or <tt>FOAM_BUILD_PRIVATE_PARMETIS</tt>, respectively.
 670     CMake will then try to download and build the selected libraries for you.
 671     Conversely, if one of the libraries is provided by your system, you can
 672     turn the respective setting to <em>OFF</em>. Please note that if your system
 673     provides only <em>ParMetis</em>, you do not have to install <em>METIS</em>, as the former
 674     also contains <em>METIS</em> in an older version.
 675 </p>
 676 </li>
 677 <li>
 678 <p>
 679 If you want to use the <em>MGridGen</em> agglomeration method for the GAMG solver,
 680     you need to enable <tt>FOAM_ENABLE_MGRIDGEN</tt> and if the library is not
 681     installed on your system ensure that <tt>FOAM_BUILD_PRIVATE_MGRIDGEN</tt> is
 682     enabled. See <a href="#enable-mgridgen">above</a> regarding the unknown license status
 683     of this package.
 684 </p>
 685 </li>
 686 <li>
 687 <p>
 688 In order to build <em>ccm26ToFoam</em>, a conversion utility for grids generated
 689     with <em>ProStar/ccm</em> &#169; version 2.6, enable the setting
 690     <tt>FOAM_ENABLE_CCMIO</tt> and if <em>libccmio</em> is not installed on your system,
 691     also <tt>FOAM_BUILD_PRIVATE_CCMIO</tt>. Refer to the <a href="#enable-ccmio">above</a>
 692     description of the <em>libccmio</em> package for the license restrictions which
 693     apply to this package. If you decide to build a private version, please
 694     read the description of <a href="#private-ccmio">+FOAM_BUILD_PRIVATE_CCMIO</a>
 695     carefully.
 696 </p>
 697 </li>
 698 <li>
 699 <p>
 700 If you plan on installing FreeFOAM, set <tt>CMAKE_INSTALL_PREFIX</tt> to the base directory
 701     under which FreeFOAM should reside.
 702 </p>
 703 </li>
 704 <li>
 705 <p>
 706 For more fine-grained control over what gets installed where, adjust
 707     <tt>FOAM_INSTALL_CONFIG_PATH</tt>, <tt>FOAM_INSTALL_HEADER_PATH</tt>, <tt>FOAM_INSTALL_LIBRARY_PATH</tt>,
 708     <tt>FOAM_INSTALL_FRAMEWORK_PATH</tt>, <tt>FOAM_INSTALL_PV3FOAMREADER_PATH</tt>,
 709     <tt>FOAM_INSTALL_PVFOAMREADER_PATH</tt> and <tt>FOAM_INSTALL_USERDFOAM_PATH</tt>. Paths not
 710     starting with a slash (<em>/</em>) will be relative to <em>CMAKE_INSTALL_PREFIX</em>. If
 711     you include a leading slash, the paths are absolute.
 712 </p>
 713 </li>
 714 <li>
 715 <p>
 716 If you want FreeFOAM to use <em>float</em> as the floating point type instead of
 717     <em>double</em>, change <tt>FOAM_DOUBLE_PRECISION</tt> to <em>OFF</em>.
 718 </p>
 719 </li>
 720 </ul></div>
 721 </li>
 722 <li>
 723 <p>
 724 Hit <tt>c</tt> again. You shouldn&#8217;t get any errors anymore now. Keep pressing <tt>c</tt>
 725   until ccmake displays "<tt>Press [g] to generate and exit</tt>" in the legend at
 726   the bottom of the interface.
 727 </p>
 728 </li>
 729 <li>
 730 <p>
 731 Press <tt>g</tt> to generate the Makefiles and exit the ccmake interface.
 732 </p>
 733 </li>
 734 <li>
 735 <p>
 736 Start the native build tool. If you used the <em>Makefile</em> generator
 737   (which is the default for Unix-platforms), type
 738 </p>
 739 <div class="listingblock">
 740 <div class="content">
 741 <pre><tt>$ make</tt></pre>
 742 </div></div>
 743 </li>
 744 <li>
 745 <p>
 746 If you have a multi-core/processor machine, you can speed things up
 747   significantly by telling Make to run independent jobs in parallel.
 748   A good choice for the number of parallel jobs to run is the
 749   number of CPU&#8217;s/cores you have in your machine plus 1 (to compensate
 750   for disk-latency). For a typical dual-core machine, run
 751 </p>
 752 <div class="listingblock">
 753 <div class="content">
 754 <pre><tt>$ make -j3</tt></pre>
 755 </div></div>
 756 </li>
 757 </ul></div>
 758 </div>
 759 <h2 id="_installing_freefoam">Installing FreeFOAM</h2>
 760 <div class="sectionbody">
 761 <div class="paragraph"><p>If you want to, you can now install FreeFOAM. Depending on the
 762 <tt>CMAKE_INSTALL_PREFIX</tt> and the individual <tt>FOAM_INSTALL_*_PATH</tt> it is possible
 763 that you have to do this as root, i.e. use <tt>su</tt> or <tt>sudo</tt>.</p></div>
 764 <div class="listingblock">
 765 <div class="content">
 766 <pre><tt>$ make install</tt></pre>
 767 </div></div>
 768 </div>
 769 <h2 id="_using_freefoam">Using FreeFOAM</h2>
 770 <div class="sectionbody">
 771 <div class="paragraph"><p>If you didn&#8217;t change <tt>CMAKE_INSTALL_PREFIX</tt> and <tt>FOAM_INSTALL_BIN_PATH</tt> chances
 772 are that you can start using FreeFOAM right after you installed it without any
 773 further steps being necessary.</p></div>
 774 <h3 id="globalconfig">Global Configuration Files</h3><div style="clear:left"></div>
 775 <div class="paragraph"><p>Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
 776 applications require some files to be present for start-up. It finds those
 777 in the following places (in the specified order, picking the first hit):</p></div>
 778 <div class="olist arabic"><ol class="arabic">
 779 <li>
 780 <p>
 781 Under the directory specified in the <tt>$FREEFOAM_CONFIG_DIR</tt> environment
 782    variable
 783 </p>
 784 </li>
 785 <li>
 786 <p>
 787 </p>
 788 </li>
 789 <li>
 790 <p>
 791 In <em>$HOME/.FreeFOAM</em>
 792 </p>
 793 </li>
 794 <li>
 795 <p>
 796 In the installation directory of the configuration files. There are
 797    two possible places for this:
 798 </p>
 799 <div class="dlist"><dl>
 800 <dt class="hdlist1">
 801 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FOAM_INSTALL_CONFIG_PATH&gt;</em>
 802 </dt>
 803 <dd>
 804 <p>
 805 if you specified
 806      <tt>&lt;FOAM_INSTALL_CONFIG_PATH&gt;</tt> as a relative path.
 807 </p>
 808 </dd>
 809 <dt class="hdlist1">
 810 <em>&lt;FOAM_INSTALL_CONFIG_PATH&gt;</em>
 811 </dt>
 812 <dd>
 813 <p>
 814 if you specified <tt>&lt;FOAM_INSTALL_CONFIG_PATH&gt;</tt> as
 815     an absolute path.
 816 </p>
 817 <div class="paragraph"><p></p></div>
 818 </dd>
 819 </dl></div>
 820 </li>
 821 </ol></div>
 822 <h3 id="_selecting_the_parallel_communications_library">Selecting the Parallel Communications Library</h3><div style="clear:left"></div>
 823 <div class="paragraph"><p>Both, FreeFOAM and OpenFOAM abstract the parallel operations into the <em>Pstream</em>
 824 library, making it rather simple to firstly switch between parallel
 825 implementations and secondly port the software to a new communications library.
 826 However, FreeFOAM uses a much more flexible mechanism of determining which
 827 <em>Pstream</em> implementation library to use than OpenFOAM. The latter does this by
 828 adjusting the <tt>LD_LIBRARY_PATH</tt> environment variable.  As FreeFOAM wants to be a
 829 well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically
 830 loads the desired <em>Pstream</em> library at startup (i.e. as a plug-in).  The
 831 following list details how FreeFOAM determines what library to load (if at all):</p></div>
 832 <div class="olist arabic"><ol class="arabic">
 833 <li>
 834 <p>
 835 If the environment variable <tt>FREEFOAM_PSTREAM_LIBRARY</tt> is set,
 836    FreeFOAM will try to load the library specified by it.
 837 </p>
 838 </li>
 839 <li>
 840 <p>
 841 If the sub-dictionary <tt>PstreamImplementation</tt> exists in the global
 842    <em>controlDict</em> file (see <a href="#globalconfig"><em>Global Configuration Files</em></a>), it
 843    reads the value of the entry <tt>configName</tt> therein. It then expects that a
 844    sub-dictionary of <tt>PstreamImplementation</tt> with the name specified in
 845    <tt>configName</tt> exists. If that sub-dictionary contains the entry <tt>library</tt>, it
 846    will try to load a library specified by the value of that entry.
 847 </p>
 848 </li>
 849 </ol></div>
 850 <div class="paragraph"><p>After FreeFOAM (possibly) loaded the library, it will try to instantiate
 851 concrete implementations of the abstract base classes <tt>PstreamImpl</tt>,
 852 <tt>IPstreamImpl</tt> and <tt>OPstreamImpl</tt>. Which classes are to be instantiated
 853 is determined as follows:</p></div>
 854 <div class="olist arabic"><ol class="arabic">
 855 <li>
 856 <p>
 857 FreeFOAM queries the environment variables <tt>FREEFOAM_PSTREAM_CLASS</tt>,
 858    <tt>FREEFOAM_IPSTREAM_CLASS</tt> and <tt>FREEFOAM_OPSTREAM_CLASS</tt> for the class
 859    names to be instantiated.
 860 </p>
 861 </li>
 862 <li>
 863 <p>
 864 For any of the variables not set,  it requires the sub-dictionary
 865    <tt>PstreamImplementation</tt> to be present in the global <em>controlDict</em>, reads the
 866    value of <tt>configName</tt> and similarly to the library loading, loads the
 867    sub-dictionary specified by that value. It then expects to find the entries
 868    <tt>Pstream</tt>, <tt>IPstream</tt> and <tt>OPstream</tt> which specify the names of the classes
 869    to load.
 870 </p>
 871 </li>
 872 </ol></div>
 873 <div class="paragraph"><p>This means that one can create a global <em>controlDict</em> file containing
 874 (among other things) something like the following:</p></div>
 875 <div class="exampleblock">
 876 <div class="exampleblock-content">
 877 <div class="listingblock">
 878 <div class="content">
 879 <pre><tt>PstreamImplementation
 880 {
 881     //configName dummy;
 882     configName mpi;
 883
 884     dummy
 885     {
 886         library libdummyPstream.so;
 887         Pstream dummyPstreamImpl;
 888         OPstream dummyOPstreamImpl;
 889         IPstream dummyIPstreamImpl;
 890     }
 891
 892     mpi
 893     {
 894         library libmpiPstream.so;
 895         Pstream mpiPstreamImpl;
 896         OPstream mpiOPstreamImpl;
 897         IPstream mpiIPstreamImpl;
 898     }
 899 }</tt></pre>
 900 </div></div>
 901 </div></div>
 902 <div class="paragraph"><p>This way the administrator can provide a global <em>controlDict</em> in the FreeFOAM
 903 installation. Every user can then override that <em>controlDict</em> by supplying her
 904 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
 905 for a specific communications library, the user can then either adjust the
 906 <tt>PstreamImplementation::configName</tt> entry in the global <em>controlDict</em> file, set
 907 the <tt>FREEFOAM_PSTREAM_CONFIG</tt> variable or for full control, set the variables
 908 <tt>FREEFOAM_PSTREAM_LIBRARY</tt>, <tt>FREEFOAM_PSTREAM_CLASS</tt>, <tt>FREEFOAM_IPSTREAM_CLASS</tt>
 909 and <tt>FREEFOAM_OPSTREAM_CLASS</tt>.</p></div>
 910 <h3 id="_running_freefoam_from_the_build_tree">Running FreeFOAM From the Build Tree</h3><div style="clear:left"></div>
 911 <div class="paragraph"><p>You can use FreeFOAM without installing it first, directly from the build tree.
 912 However, this might take a little bit more effort to set up because most likely
 913 you will have to adjust the following environment variables:</p></div>
 914 <div class="dlist"><dl>
 915 <dt class="hdlist1">
 916 PATH
 917 </dt>
 918 <dd>
 919 <p>
 920 </p>
 921 </dd>
 922 <dt class="hdlist1">
 923 LD_LIBRARY_PATH
 924 </dt>
 925 <dd>
 926 <p>
 927 </p>
 928 </dd>
 929 <dt class="hdlist1">
 930 FREEFOAM_CONFIG_DIR
 931 </dt>
 932 <dd>
 933 <p>
 934 </p>
 935 </dd>
 936 </dl></div>
 937 <div class="paragraph"><p>Where it is assumed that you followed the <a href="#installation">installation instructions</a>. If
 938 you used different paths for downloading and compiling FreeFOAM, you will have
 939 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
 940 variables.</p></div>
 941 </div>
 942 <h2 id="_running_the_tutorials">Running the tutorials</h2>
 943 <div class="sectionbody">
 944 <div class="paragraph"><p>Now you should be able to run the tutorial cases. For this copy the <tt>tutorials</tt>
 945 directory to some convenient place:</p></div>
 946 <div class="listingblock">
 947 <div class="content">
 948 <pre><tt>$ mkdir -p $HOME/FreeFOAM/$LOGNAME-{shortver}/run
 949 $ cp -r $HOME/Source/freefoam-{fullver}-build/tutorials $HOME/FreeFOAM/$LOGNAME-{shortver}/run/
 950 $ cd $HOME/FreeFOAM/$LOGNAME-{shortver}/run/tutorials</tt></pre>
 951 </div></div>
 952 <div class="paragraph"><p>And try to run e.g. the <em>cavity</em> tutorial case:</p></div>
 953 <div class="listingblock">
 954 <div class="content">
 955 <pre><tt>$ cd icoFoam
 956 $ freefoam blockMesh -case cavity
 957 $ freefoam checkMesh -case cavity
 958 $ freefoam ico -case cavity</tt></pre>
 959 </div></div>
 960 <div class="paragraph"><p>Things should run smoothly and finish without an error.</p></div>
 961 <div class="paragraph"><p>All the tutorials contain a script for automatic execution since some of the
 962 cases are quite intricate and it is not obvious how to run them. Also, these
 963 scripts are used for automated testing. The scripts are called <em>Allrun</em>, where
 964 the one located in the <em>tutorials</em> directory is a driver script to run all the
 965 other tutorials.</p></div>
 966 </div>
 967 <h2 id="_obtaining_the_source_code_from_the_git_repository">Obtaining the Source Code from the GIT repository</h2>
 968 <div class="sectionbody">
 969 <div class="ulist"><ul>
 970 <li>
 971 <p>
 972 Clone the FreeFOAM repository (here the clone is placed in
 973   <tt>$HOME/Source/FreeFOAM</tt>):
 974 </p>
 975 <div class="listingblock">
 976 <div class="content">
 977 <pre><tt>$ mkdir -p $HOME/Source
 978 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM</tt></pre>
 979 </div></div>
 980 </li>
 981 <li>
 982 <p>
 983 Proceed in the same way (replacing the path names apropriately) as in the
 984   above build instructions.
 985 </p>
 986 </li>
 987 </ul></div>
 988 </div>
 989 <h2 id="_shell_completion_scripts">Shell completion scripts</h2>
 990 <div class="sectionbody">
 991 <div class="paragraph"><p>FreeFOAM comes with completions scripts for the
 992 <a href="http://www.gnu.org/software/bash/">BASH</a> and <a href="http://www.zsh.org/">ZSH</a> shells.
 993 The former is quite simplistic and only offers very basic completion of the
 994 available application names. The ZSH completion, however, is quite complete and
 995 also completes options and arguments for all applications. These completion
 996 functions are not installed by <tt>make install</tt>, because no two systems have the
 997 same locations for these kinds of scripts. You find them for manual
 998 installation in the FreeFOAM sources in the directory
 999 <em>data/shellFunctions/bashCompletion</em> and <em>data/shellFunctions/zshCompletion</em>
1000 respectively. Please refer to the documentation of your system/shell on where
1001 to place them.</p></div>
1002 </div>
1003 <h2 id="_emacs_mode">Emacs mode</h2>
1004 <div class="sectionbody">
1005 <div class="paragraph"><p>FreeFOAM includes a rudimentary major mode for the
1006 <a href="http://www.gnu.org/software/emacs">Emacs</a> programming editor. If you want to use
1007 this mode, place the file <em>data/editor-modes/foamdict-mode.el</em> in a directory
1008 where your Emacs installation finds it. Please refer to the Emacs documentation
1009 for further instructions.</p></div>
1010 </div>
1011 <h2 id="_build_configuration_reference">Build Configuration Reference</h2>
1012 <div class="sectionbody">
1013 <div class="dlist glossary"><dl>
1014 <dt>
1015 <tt>CMAKE_BUILD_TYPE</tt>
1016 </dt>
1017 <dd>
1018 <p>
1019   One of <em>&lt;empty&gt;</em>, <em>Debug</em>, <em>Release</em>, <em>RelWithDebInfo</em> and <em>MinSizeRel</em>.
1020   Refer to the CMake documentation for more detail.
1021 </p>
1022 </dd>
1023 <dt>
1024 <tt>FOAM_DOUBLE_PRECISION</tt>
1025 </dt>
1026 <dd>
1027 <p>
1028   If set to <em>ON</em> FreeFOAM will be compiled using <em>double</em> as the
1029   floating point type. If set to <em>OFF</em> it will use <em>float</em>.
1030 </p>
1031 </dd>
1032 <dt>
1033 <tt>FOAM_BUILD_FRAMEWORKS</tt>
1034 </dt>
1035 <dd>
1036 <p>
1037   If this is enabled, the libraries are built as frameworks. Only available on
1038   Mac OS X.
1039 </p>
1040 </dd>
1041 <dt>
1042 <tt>FOAM_EXE_PREFIX</tt>
1043 </dt>
1044 <dd>
1045 <p>
1046   Prefix used to mangle application names. Normally this shouldn&#8217;t be changed.
1047 </p>
1048 </dd>
1049 <dt>
1050 <tt>CMAKE_INSTALL_PREFIX</tt>
1051 </dt>
1052 <dd>
1053 <p>
1054   Installation prefix under which to install FreeFOAM.
1055 </p>
1056 </dd>
1057 <dt>
1058 <tt>FOAM_INSTALL_BIN_PATH</tt>
1059 </dt>
1060 <dd>
1061 <p>
1062   Installation path of the binaries. If not absolute, it is relative to
1063   <em>CMAKE_INSTALL_PREFIX</em>.
1064 </p>
1065 </dd>
1066 <dt>
1067 <tt>FOAM_INSTALL_LIBEXEC_PATH</tt>
1068 </dt>
1069 <dd>
1070 <p>
1071   Installation path of the binaries which should not be on the <tt>PATH</tt>. If not
1072   absolute, it is relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
1073 </p>
1074 </dd>
1075 <dt>
1076 <tt>FOAM_INSTALL_CONFIG_PATH</tt>
1077 </dt>
1078 <dd>
1079 <p>
1080   Installation path of the configuration files. If not absolute, it is
1081   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1082 </p>
1083 </dd>
1084 <dt>
1085 <tt>FOAM_INSTALL_HEADER_PATH</tt>
1086 </dt>
1087 <dd>
1088 <p>
1089   Installation path of the header files. If not absolute, it is
1090   relative to <em>CMAKE_INSTALL_PREFIX</em>. On Mac OS X, and if
1091   <em>FOAM_BUILD_FRAMEWORKS</em> is enabled, this setting is ignored.
1092 </p>
1093 </dd>
1094 <dt>
1095 <tt>FOAM_INSTALL_LIBRARY_PATH</tt>
1096 </dt>
1097 <dd>
1098 <p>
1099   Installation path of the libraries. If not absolute, it is
1100   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1101 </p>
1102 </dd>
1103 <dt>
1104 <tt>FOAM_INSTALL_FRAMEWORK_PATH</tt>
1105 </dt>
1106 <dd>
1107 <p>
1108   Installation path of the Mac OS X frameworks. If not absolute, it is
1109   relative to <em>CMAKE_INSTALL_PREFIX</em>. This is only available and takes
1110   effect if FreeFOAM is compiled on Mac OS X, and if
1111   <em>FOAM_BUILD_FRAMEWORKS</em> is enabled.
1112 </p>
1113 </dd>
1114 <dt>
1115 <tt>FOAM_INSTALL_PV3FOAMREADER_PATH</tt>
1116 </dt>
1117 <dd>
1118 <p>
1119   Installation path of the ParaView3 plug-ins. If not absolute, it is
1120   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1121 </p>
1122 </dd>
1123 <dt>
1124 <tt>FOAM_INSTALL_PVFOAMREADER_PATH</tt>
1125 </dt>
1126 <dd>
1127 <p>
1128   Installation path of the ParaView2 plug-ins. If not absolute, it is
1129   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1130 </p>
1131 </dd>
1132 <dt>
1133 <tt>FOAM_INSTALL_USERDFOAM_PATH</tt>
1134 </dt>
1135 <dd>
1136 <p>
1137   Installation path of the Ensight plug-in. If not absolute, it is
1138   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1139 </p>
1140 </dd>
1141 <dt>
1142 <tt>FOAM_USE_GAMMA</tt>
1143 </dt>
1144 <dd>
1145 <p>
1146   If enabled, FreeFOAM will use the GAMMA parallel communications library.
1147   This is currently not implemented.
1148 </p>
1149 </dd>
1150 <dt>
1151 <tt>FOAM_USE_MPI</tt>
1152 </dt>
1153 <dd>
1154 <p>
1155   If enabled, FreeFOAM will use the MPI parallel communications library.
1156   This is required in order to build some of the libraries and utilities.
1157 </p>
1158 </dd>
1159 <dt>
1160 <tt>FOAM_DEFAULT_PSTREAM</tt>
1161 </dt>
1162 <dd>
1163 <p>
1164   The default Pstream selection in the global <em>controlDict</em> file.
1165 </p>
1166 </dd>
1167 <dt>
1168 <tt>FOAM_BUILD_PARAVIEW_PLUGINS</tt>
1169 </dt>
1170 <dd>
1171 <p>
1172   Whether to build the ParaView plug-ins. If enabled, FreeFOAM requires a
1173   ParaView build tree and the <em>ParaView_DIR</em> variable set to the path of it.
1174 </p>
1175 </dd>
1176 <dt>
1177 <tt>FOAM_ENABLE_CCMIO</tt>
1178 </dt>
1179 <dd>
1180 <p>
1181   Enable the use of <em>libccmio</em>. This is required to build the grid conversion
1182   utility <em>ccm26ToFoam</em>.
1183 </p>
1184 <div class="admonitionblock" id="enable-ccmio">
1185 <table><tr>
1186 <td class="icon">
1187 <div class="title">Warning</div>
1188 </td>
1189 <td class="content">The license of <em>libccmio</em> &#169; is proprietary and requires the consent of the
1190 copyright holders (<a href="http://www.cd-adapco.com">CD-adapco</a>) to download and use the
1191 library. Further it is not allowed to redistribute it in any form. The request
1192 for permission of inclusion with <a href="http://debian.org">Debian</a> was answered as
1193 follows by <a href="mailto:geoffrey.prewett@us.cd-adapco.com">Geoffrey Prewett</a>:</td>
1194 </tr></table>
1195 </div>
1196 <div class="listingblock">
1197 <div class="content">
1198 <pre><tt>Gerber,
1199
1200 Sorry for the delay in response.  I checked back with our development director,
1201 and he felt that it would be best to not include libccmio with Debian.
1202 Instead, we would prefer to continue our current policy and keep it on our
1203 web/FTP and have people ask for it.  There are three reasons for this:
1204
1205 1) We don't support STAR on Debian, and don't want to give the impression that we do.
1206 2) We would like to keep a list of people that we give the library to.
1207 3) This is not a general purpose library;  its sole purpose is to communicate
1208 between our products.  Accepting outside changes risks committing a change that
1209 would break our own software in possibly subtle ways.
1210
1211 So I regret to tell you that my company has declined to permit libccmio to be
1212 distributed as part of Debian.
1213
1214 Regards,
1215 Geoff Prewett</tt></pre>
1216 </div></div>
1217 </dd>
1218 <dt>
1219 <tt>FOAM_BUILD_PRIVATE_CCMIO</tt>
1220 </dt>
1221 <dd>
1222 <p>
1223   Automatically download and build libccmio. Unfortunately this process may
1224   fail in the download step if CMake cannot find either <em>wget</em> or <em>curl</em> on
1225   your system, since CMake itself currently does not support <em>https</em> URLs. If
1226   this happens, the build process will abort. To fix the issue, Download the
1227   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>
1228   manually and place it in <tt>ThirdParty/ccmio/src</tt> (relative to the build
1229   directory). It is important that you re-run CMake <strong>before</strong> restarting the
1230   build in order to notify the build system that the file is now there.
1231 </p>
1232 </dd>
1233 <dt>
1234 <tt>FOAM_ENABLE_METIS</tt>
1235 </dt>
1236 <dd>
1237 <p>
1238   Enable the use of the <em>METIS</em> graph partitioning library which is required to
1239   implement the <em>metis</em> decomposition method.
1240 </p>
1241 </dd>
1242 <dt>
1243 <tt>FOAM_BUILD_PRIVATE_METIS</tt>
1244 </dt>
1245 <dd>
1246 <p>
1247   Automatically download and build <em>METIS</em>.
1248 </p>
1249 </dd>
1250 <dt>
1251 <tt>FOAM_BUILD_PRIVATE_PARMETIS</tt>
1252 </dt>
1253 <dd>
1254 <p>
1255   Automatically download and build <em>ParMetis</em>.
1256 </p>
1257 </dd>
1258 <dt>
1259 <tt>FOAM_ENABLE_MGRIDGEN</tt>
1260 </dt>
1261 <dd>
1262 <p>
1263   Enable the use of <em>MGRIDGEN</em> which is required to build
1264   <em>MGridGenGamgAgglomeration</em> providing the <em>MGridGen</em> agglomeration method for
1265   the GAMG solver.
1266 </p>
1267 <div class="admonitionblock" id="enable-mgridgen">
1268 <table><tr>
1269 <td class="icon">
1270 <div class="title">Warning</div>
1271 </td>
1272 <td class="content">The license of <em>MGRIDGEN</em> is unknown and the upstream authors so far have not
1273 answered any inquiries to resolve the issue. If you enable the use of
1274 <em>MGRIDGEN</em> you alone are responsible for ensuring that you don&#8217;t violate any
1275 license conditions applying to these libraries. The authors of FreeFOAM will
1276 and cannot take any responsibility for your actions.</td>
1277 </tr></table>
1278 </div>
1279 </dd>
1280 <dt>
1281 <tt>FOAM_BUILD_PRIVATE_MGRIDGEN</tt>
1282 </dt>
1283 <dd>
1284 <p>
1285   Automatically download and build <em>MGRIDGEN</em>.
1286 </p>
1287 </dd>
1288 <dt>
1289 <tt>FOAM_ENABLE_DOXYGEN_DOCS</tt>
1290 </dt>
1291 <dd>
1292 <p>
1293   Enable building of the <em>Doxygen API documentation</em>. The documentation will
1294   only be built once and is not updated automatically. This is because it
1295   depends on a huge number of files and would make dependency tracking very
1296   slow and difficult to maintain. To force the re-generation of the API
1297   documentation execute <tt>make apidoc</tt>.
1298 </p>
1299 </dd>
1300 <dt>
1301 <tt>FOAM_DOXYDOCS_FOR_SF</tt>
1302 </dt>
1303 <dd>
1304 <p>
1305   This setting is for the maintainers of the FreeFOAM and indicates whether the
1306   Doxygen documentation should be built for deployment on
1307   <a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a>.
1308 </p>
1309 </dd>
1310 <dt>
1311 <tt>FOAM_ENABLE_MANPAGE_HELP</tt>
1312 </dt>
1313 <dd>
1314 <p>
1315   <a id="foam_enable_manpage_help"></a>
1316   Build (and install) the help-pages in manpage format. This requires a
1317   complete <a href="http://www.methods.co.nz/asciidoc">Asciidoc</a> toolchain to be present.
1318 </p>
1319 </dd>
1320 <dt>
1321 <tt>FOAM_ENABLE_XHMTL_HELP</tt>
1322 </dt>
1323 <dd>
1324 <p>
1325   Build (and install) the help-pages in xhtml format for the display in a web
1326   browser. The requirements are the same as for
1327   <a href="#foam_enable_manpage_help"><tt>FOAM_ENABLE_MANPAGE_HELP</tt></a>.
1328 </p>
1329 </dd>
1330 <dt>
1331 <tt>FOAM_USE_LOCAL_DOXYGEN_DOCS</tt>
1332 </dt>
1333 <dd>
1334 <p>
1335   This setting influences the location in which the Doxygen source
1336   code documentation is looked for if any of the FreeFOAM applications
1337   is invoked with the <em>-doc</em> or <em>-srcDoc</em> options. If it is disabled,
1338   the documentation will be loaded over the network from
1339   <a href="http://freefoam.sf.net/doc/Doxygen/html">http://freefoam.sf.net/doc/Doxygen/html</a>. If you enable it, the
1340   documentation will be loaded locally. This requires that you either
1341   build and install the documentation by enabling <tt>FOAM_ENABLE_DOXYGEN_DOCS</tt>,
1342   or provide the required HTML files otherwise.
1343 </p>
1344 </dd>
1345 <dt>
1346 <tt>HTML_DOC_BROWSER</tt>
1347 </dt>
1348 <dd>
1349 <p>
1350   This is the program used to display the Doxygen source code documentation
1351   if any of the FreeFOAM applications is invoked with the <em>-doc</em> or <em>-srcDoc</em>
1352   options. The special value of <em>ECHO</em> changes the behaviour to just write
1353   the location of the HTML file to the output. This is a good setting if
1354   you&#8217;re system doesn&#8217;t have any kind of HTML browser installed (such
1355   as on a cluster).
1356 </p>
1357 </dd>
1358 <dt>
1359 <tt>FOAM_HTML_DOC_BROWSER_COMMAND</tt>
1360 </dt>
1361 <dd>
1362 <p>
1363   This is the command with which to invoke the HTML browser. By default
1364   it calls the program named in <tt>HTML_DOC_BROWSER</tt> and passes it the
1365   name/URL of the documentation file to be displayed. You shouldn&#8217;t
1366   have to change this unless your HTML browser requires some unusual
1367   options or arguments.
1368 </p>
1369 </dd>
1370 </dl></div>
1371 </div>
1372 <h2 id="_troubleshooting">Troubleshooting</h2>
1373 <div class="sectionbody">
1374 <h3 id="_the_freefoam_executables_are_not_found_by_the_shell">The FreeFOAM Executables Are Not Found By The Shell</h3><div style="clear:left"></div>
1375 <div class="paragraph"><p>There are three possible reasons for this:</p></div>
1376 <div class="olist arabic"><ol class="arabic">
1377 <li>
1378 <p>
1379 Your shell (notably <em>csh</em>, <em>tcsh</em> and <em>zsh</em>) requires you to refresh the
1380    cache of available executables. You can do so by entering the command:
1381 </p>
1382 <div class="listingblock">
1383 <div class="content">
1384 <pre><tt>$ rehash</tt></pre>
1385 </div></div>
1386 </li>
1387 <li>
1388 <p>
1389 If <em>rehashing</em> didn&#8217;t solve the problem, the problem most likely is that you
1390    installed FreeFOAM into a non-standard location by changing the configuration
1391    variables <tt>CMAKE_INSTALL_PREFIX</tt> or <tt>FOAM_INSTALL_BIN_PATH</tt> in which case the
1392    executables where installed into a directory not searched by the shell. In
1393    this case you have to add the installation directory of the executables to
1394    the <tt>PATH</tt> variable. There are two possible locations:
1395 </p>
1396 <div class="dlist"><dl>
1397 <dt class="hdlist1">
1398 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FOAM_INSTALL_BIN_PATH&gt;</em>
1399 </dt>
1400 <dd>
1401 <p>
1402 if you specified
1403   <tt>FOAM_INSTALL_BIN_PATH</tt> as a relative path
1404 </p>
1405 </dd>
1406 <dt class="hdlist1">
1407 <em>&lt;FOAM_INSTALL_BIN_PATH&gt;</em>
1408 </dt>
1409 <dd>
1410 <p>
1411 if you specified <tt>FOAM_INSTALL_BIN_PATH</tt> as an absolute
1412   path
1413 </p>
1414 </dd>
1415 </dl></div>
1416 <div class="paragraph"><p>After extending the <tt>PATH</tt> variable with the installation directory of the
1417 executables, you should be able to run all FreeFOAM applications as any other
1418 binary available on the system. See <a href="#environment"><em>Extending Search Paths And Setting Environment Variables Permanently</em></a> for
1419 instructions on how to extend the search path.</p></div>
1420 </li>
1421 <li>
1422 <p>
1423 This option is similar to the previous solution and applies if you want to
1424    run FreeFOAM from the build tree (i.e. without running <tt>make install</tt>). In
1425    this case you again have to make sure that your shell finds the executables
1426    built by CMake by extending the <tt>PATH</tt> variable. Further, you have to tell
1427    FreeFOAM where to find the global configuration files (see
1428    <a href="#globalconfig"><em>Global Configuration Files</em></a>). Here, you have the option to
1429    place the files under your home directory or set an environment variable. The
1430    former can be achieved by:
1431 </p>
1432 <div class="listingblock">
1433 <div class="content">
1434 <pre><tt>$ mkdir -p $HOME/.FreeFOAM/{shortver}
1435 $ cp $HOME/Source/freefoam-{fullver}-build/etc/controlDict $HOME/.FreeFOAM/{shortver}
1436 $ cp $HOME/Source/freefoam-{fullver}-build/etc/cellModels $HOME/.FreeFOAM/{shortver}
1437 $ cp -r $HOME/Source/freefoam-{fullver}-build/etc/thermoData $HOME/.FreeFOAM/{shortver}</tt></pre>
1438 </div></div>
1439 <div class="paragraph"><p>The latter (and recommended) method is to set the environment variable
1440 build tree to your actual setup.</p></div>
1441 </li>
1442 </ol></div>
1443 <h3 id="_starting_any_freefoam_application_fails_because_some_libraries_cannot_be_found">Starting Any FreeFOAM Application Fails Because Some Libraries Cannot Be Found</h3><div style="clear:left"></div>
1444 <div class="paragraph"><p>Although CMake should have taken care of this by using <tt>RPATH</tt> on Linux and
1445 <tt>install_name</tt> on Mac OS X, it might be necessary on some systems to adjust the
1446 library search paths:</p></div>
1447 <div class="dlist"><dl>
1448 <dt class="hdlist1">
1449 <tt>LD_LIBRARY_PATH</tt>
1450 </dt>
1451 <dd>
1452 <p>
1453 This variable is used by all Unix like systems (e.g. Linux,
1454   Mac OS X, etc.)
1455 </p>
1456 </dd>
1457 <dt class="hdlist1">
1458 <tt>DYLD_LIBRARY_PATH</tt>
1459 </dt>
1460 <dd>
1461 <p>
1462 This variable is used by Mac OS X.
1463 </p>
1464 </dd>
1465 </dl></div>
1466 <div class="paragraph"><p>If you installed FreeFOAM, there are (as with the executables), two possible
1467 installation directories:</p></div>
1468 <div class="dlist"><dl>
1469 <dt class="hdlist1">
1470 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FOAM_INSTALL_LIBRARY_PATH&gt;</em>
1471 </dt>
1472 <dd>
1473 <p>
1474 if you specified
1475   <tt>FOAM_INSTALL_LIBRARY_PATH</tt> as a relative path.
1476 </p>
1477 </dd>
1478 <dt class="hdlist1">
1479 <em>&lt;FOAM_INSTALL_LIBRARY_PATH&gt;</em>
1480 </dt>
1481 <dd>
1482 <p>
1483 if you specified <tt>FOAM_INSTALL_LIBRARY_PATH</tt> as an absolute
1484   path.
1485 </p>
1486 </dd>
1487 </dl></div>
1488 <div class="paragraph"><p>If you are trying to run from the build tree, you have to include
1489 paths (where you have to adjust the location of the build tree to your actual
1490 setup).</p></div>
1491 <h3 id="_a_running_freefoam_application_aborts_because_it_can_8217_t_em_dlopen_em_a_library">A Running FreeFOAM Application Aborts Because It Can&#8217;t <em>dlopen</em> A Library</h3><div style="clear:left"></div>
1492 <div class="paragraph"><p>FreeFOAM (and OpenFOAM) often dynamically load libraries at run-time (a.k.a
1493 plug-ins) to add features the user requested without requiring that the whole
1494 application be recompiled. This makes it very simple to add new boundary
1495 conditions, turbulence and combustion models etc. However, it also requires that
1496 FreeFOAM must be able to find these libraries at run-time. The operating system
1497 function which does the loading of the libraries (<em>dlopen</em>) usually tries to
1498 find the library with the given name in several places; namely a default search
1499 path and a search path configured by one or multiple environment variables such
1500 as <tt>LD_LIBRARY_PATH</tt> or <tt>DYLD_LIBRARY_PATH</tt> (on Mac OS X). The details vary from
1501 platform to platform, so you best consult the documentation of <em>dlopen</em> for the
1502 details.</p></div>
1503 <div class="paragraph"><p>Additionally FreeFOAM allows you to configure a custom search path for plug-ins
1504 in the <a href="#globalconfig">global <em>controlDict</em></a> file by listing the directories to
1505 be searched in the list <tt>LibrarySearchPaths</tt>. By default FreeFOAM is configured
1506 to search for plug-ins in the location where CMake installed them.</p></div>
1507 <div class="paragraph"><p>If you want to add your own plug-in libraries (e.g. you want to add your own
1508 boundary conditions class), you most probably will want to extend this search
1509 path.</p></div>
1510 <h3 id="_freefoam_aborts_when_trying_to_instantiate_a_plugin_class">FreeFOAM Aborts When Trying To Instantiate a Plugin Class</h3><div style="clear:left"></div>
1511 <div class="paragraph"><p>If you get a warning message similar to the following</p></div>
1512 <div class="literalblock">
1513 <div class="content">
1514 <pre><tt>--&gt; FOAM Warning :
1515     From function dlLibraryTable::open(const dictionary&amp; dict, const word&amp; libsEntry, const TablePtr tablePtr)
1516     in file XXX/src/OpenFOAM/db/dlLibraryTable/dlLibraryTableTemplates.C at line 68
1517     library "libfieldFunctionObjects.so" did not introduce any new entries</tt></pre>
1518 </div></div>
1519 <div class="paragraph"><p>(where <tt>XXX</tt> is the path to the FreeFOAM source code and the actual library
1520 name can be different), followed by a fatal error stating that FreeFOAM does
1521 not know a class or type, e.g.</p></div>
1522 <div class="literalblock">
1523 <div class="content">
1524 <pre><tt>--&gt; FOAM FATAL ERROR:
1525 Unknown function type fieldAverage</tt></pre>
1526 </div></div>
1527 <div class="literalblock">
1528 <div class="content">
1529 <pre><tt>Table of functionObjects is empty</tt></pre>
1530 </div></div>
1531 <div class="literalblock">
1532 <div class="content">
1533 <pre><tt>From function functionObject::New(const word&amp; name, const Time&amp;, const dictionary&amp;)
1534 in file XXX/src/OpenFOAM/db/functionObjects/functionObject/functionObject.C at line 74.</tt></pre>
1535 </div></div>
1536 <div class="literalblock">
1537 <div class="content">
1538 <pre><tt>FOAM exiting</tt></pre>
1539 </div></div>
1540 <div class="paragraph"><p>and you are absolutely sure that the named type actually exists in the library
1541 mentioned in the preceding warning message, the issue is very likely that
1542 FreeFOAM is loading the plugin library from a different binary tree than the
1543 executable belongs to.</p></div>
1544 <div class="admonitionblock">
1545 <table><tr>
1546 <td class="icon">
1547 <div class="title">Important</div>
1548 </td>
1549 <td class="content">Always make sure that you never load plugins from different binary trees (where
1550 the build tree and the install tree count as such). If you want to run a binary
1551 from the build tree but already have a corresponding installation tree, use the
1552 <tt>FREEFOAM_CONFIG_DIR</tt> environment variable to point FreeFOAM to the directory
1553 <em>&lt;path to build tree&gt;/etc/</em> containing the global <em>controlDict</em> file in the
1554 <strong>build tree</strong>.</td>
1555 </tr></table>
1556 </div>
1557 </div>
1558 <h2 id="environment">Extending Search Paths And Setting Environment Variables Permanently</h2>
1559 <div class="sectionbody">
1560 <div class="paragraph"><p>The way one sets environment variables and extends the executable and library
1561 search paths permanently strongly depends on the shell used. Usually one has to
1562 create or change an initialization file in the users home directory. In the
1563 following this will be discussed very briefly for the popular shells <em>BASH</em> and
1564 <em>tcsh</em>.  However, if you need more help or want information on using the shell,
1565 there is an excellent tutorial available at <a href="http://linuxcommand.org">http://linuxcommand.org</a>.</p></div>
1566 <h3 id="_bash">BASH</h3><div style="clear:left"></div>
1567 <div class="paragraph"><p>The BASH shell is the default shell for most Linux/Unix distributions. Most
1568 systems configure the BASH shell such that it reads the text file
1569 <em>$HOME/.bashrc</em> when starting up, so this is the place where one appends
1570 customizations of the environment variables. On some systems this file is not
1571 processed by default (notably Mac OS X). In this case you can use
1572 <em>$HOME/.bash_profile</em>.</p></div>
1573 <h4 id="_referencing_a_variable">Referencing A Variable</h4>
1574 <div class="paragraph"><p>To retrieve the value stored in a shell variable or environment variable, one
1575 prefixes its name with the dollar (<tt>$</tt>) character.</p></div>
1576 <h4 id="_setting_a_variable">Setting A Variable</h4>
1577 <div class="paragraph"><p>The syntax for setting a variable and making it available to child-processes of
1578 the shell is the following:</p></div>
1579 <div class="listingblock">
1580 <div class="content">
1581 <pre><tt>$ export variable_name=variable_value</tt></pre>
1582 </div></div>
1583 <div class="paragraph"><p>Note that no white-space characters are allowed surrounding the <tt>=</tt> sign.</p></div>
1584 <h4 id="_extending_a_search_path">Extending A Search Path</h4>
1585 <div class="paragraph"><p>The shell and other Unix system facilities use environment variables to locate
1586 executables and dynamically linked libraries. These search paths consist of
1587 strings naming directories in which the executables and libraries should be
1588 searched for. The individual paths are separated by a colon (<tt>:</tt>) character. To
1589 add the e.g. the directory <em>$HOME/bin</em> to the search path for executables, one
1590 would do the following:</p></div>
1591 <div class="listingblock">
1592 <div class="content">
1593 <pre><tt>$ export PATH=$PATH:$HOME/bin</tt></pre>
1594 </div></div>
1595 <div class="paragraph"><p>which appends <em>$HOME/bin</em> to the end of the <tt>PATH</tt> variable.</p></div>
1596 <h3 id="_tcsh">TCSH</h3><div style="clear:left"></div>
1597 <div class="paragraph"><p>Some users and administrators prefer to use a <em>C-Shell</em>, such as the TCSH. Here
1598 you can use e.g. the file <em>$HOME/.tcshrc</em> to customize the environment.</p></div>
1599 <h4 id="_referencing_a_variable_2">Referencing A Variable</h4>
1600 <div class="paragraph"><p>As with the BASH, one retrieves the value stored in a shell variable or
1601 environment variable by prefixing its name with the dollar (<tt>$</tt>) character.
1602 Sometimes it is also necessary to protect the variable name by surrounding it
1603 with curly braces (<tt>{</tt> and <tt>}</tt>).</p></div>
1604 <h4 id="_setting_a_variable_2">Setting A Variable</h4>
1605 <div class="paragraph"><p>The syntax for setting a variable and making it available to child-processes of
1606 the shell is the following:</p></div>
1607 <div class="listingblock">
1608 <div class="content">
1609 <pre><tt>$ setenv variable_name variable_value</tt></pre>
1610 </div></div>
1611 <h4 id="_extending_a_search_path_2">Extending A Search Path</h4>
1612 <div class="paragraph"><p>The shell and other Unix system facilities use environment variables to locate
1613 executables and dynamically linked libraries. These search paths consist of
1614 strings naming directories in which the executables and libraries should be
1615 searched for. The individual paths are separated by a colon (<tt>:</tt>) character. To
1616 add the e.g. the directory <em>$HOME/bin</em> to the search path for executables, one
1617 would do the following:</p></div>
1618 <div class="listingblock">
1619 <div class="content">
1620 <pre><tt>$ setenv PATH ${PATH}:${HOME}/bin</tt></pre>
1621 </div></div>
1622 <div class="paragraph"><p>which appends <em>$HOME/bin</em> to the end of the <tt>PATH</tt> variable.  Note that
1623 <em>C-shells</em> usually require the user to type <em>rehash</em> after changing the <tt>PATH</tt>
1624 variable to update the cache of available programs.</p></div>
1625 </div>
1626 </div>
1627 <div id="footnotes"><hr /></div>
1628 <div id="footer">
1629 <div id="footer-text">
1630 Last updated 2010-08-01 18:48:36 CEST
1631 </div>
1632 </div>
1633 </body>
1634 </html>