README.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.4.4" />
   7 <title>FreeFOAM README for version 0.1.0</title>
   8 <style type="text/css">
   9 /* Debug borders */
  10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  11 /*
  12   border: 1px solid red;
  13 */
  14 }
  15
  16 body {
  17   margin: 1em 5% 1em 5%;
  18 }
  19
  20 a {
  21   color: blue;
  22   text-decoration: underline;
  23 }
  24 a:visited {
  25   color: fuchsia;
  26 }
  27
  28 em {
  29   font-style: italic;
  30   color: navy;
  31 }
  32
  33 strong {
  34   font-weight: bold;
  35   color: #083194;
  36 }
  37
  38 tt {
  39   color: navy;
  40 }
  41
  42 h1, h2, h3, h4, h5, h6 {
  43   color: #527bbd;
  44   font-family: sans-serif;
  45   margin-top: 1.2em;
  46   margin-bottom: 0.5em;
  47   line-height: 1.3;
  48 }
  49
  50 h1, h2, h3 {
  51   border-bottom: 2px solid silver;
  52 }
  53 h2 {
  54   padding-top: 0.5em;
  55 }
  56 h3 {
  57   float: left;
  58 }
  59 h3 + * {
  60   clear: left;
  61 }
  62
  63 div.sectionbody {
  64   font-family: serif;
  65   margin-left: 0;
  66 }
  67
  68 hr {
  69   border: 1px solid silver;
  70 }
  71
  72 p {
  73   margin-top: 0.5em;
  74   margin-bottom: 0.5em;
  75 }
  76
  77 ul, ol, li > p {
  78   margin-top: 0;
  79 }
  80
  81 pre {
  82   padding: 0;
  83   margin: 0;
  84 }
  85
  86 span#author {
  87   color: #527bbd;
  88   font-family: sans-serif;
  89   font-weight: bold;
  90   font-size: 1.1em;
  91 }
  92 span#email {
  93 }
  94 span#revision {
  95   font-family: sans-serif;
  96 }
  97
  98 div#footer {
  99   font-family: sans-serif;
 100   font-size: small;
 101   border-top: 2px solid silver;
 102   padding-top: 0.5em;
 103   margin-top: 4.0em;
 104 }
 105 div#footer-text {
 106   float: left;
 107   padding-bottom: 0.5em;
 108 }
 109 div#footer-badges {
 110   float: right;
 111   padding-bottom: 0.5em;
 112 }
 113
 114 div#preamble {
 115   margin-top: 1.5em;
 116   margin-bottom: 1.5em;
 117 }
 118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 120 div.admonitionblock {
 121   margin-top: 1.5em;
 122   margin-bottom: 1.5em;
 123 }
 124 div.admonitionblock {
 125   margin-top: 2.5em;
 126   margin-bottom: 2.5em;
 127 }
 128
 129 div.content { /* Block element content. */
 130   padding: 0;
 131 }
 132
 133 /* Block element titles. */
 134 div.title, caption.title {
 135   color: #527bbd;
 136   font-family: sans-serif;
 137   font-weight: bold;
 138   text-align: left;
 139   margin-top: 1.0em;
 140   margin-bottom: 0.5em;
 141 }
 142 div.title + * {
 143   margin-top: 0;
 144 }
 145
 146 td div.title:first-child {
 147   margin-top: 0.0em;
 148 }
 149 div.content div.title:first-child {
 150   margin-top: 0.0em;
 151 }
 152 div.content + div.title {
 153   margin-top: 0.0em;
 154 }
 155
 156 div.sidebarblock > div.content {
 157   background: #ffffee;
 158   border: 1px solid silver;
 159   padding: 0.5em;
 160 }
 161
 162 div.listingblock > div.content {
 163   border: 1px solid silver;
 164   background: #f4f4f4;
 165   padding: 0.5em;
 166 }
 167
 168 div.quoteblock {
 169   padding-left: 2.0em;
 170   margin-right: 10%;
 171 }
 172 div.quoteblock > div.attribution {
 173   padding-top: 0.5em;
 174   text-align: right;
 175 }
 176
 177 div.verseblock {
 178   padding-left: 2.0em;
 179   margin-right: 10%;
 180 }
 181 div.verseblock > div.content {
 182   white-space: pre;
 183 }
 184 div.verseblock > div.attribution {
 185   padding-top: 0.75em;
 186   text-align: left;
 187 }
 188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 189 div.verseblock + div.attribution {
 190   text-align: left;
 191 }
 192
 193 div.admonitionblock .icon {
 194   vertical-align: top;
 195   font-size: 1.1em;
 196   font-weight: bold;
 197   text-decoration: underline;
 198   color: #527bbd;
 199   padding-right: 0.5em;
 200 }
 201 div.admonitionblock td.content {
 202   padding-left: 0.5em;
 203   border-left: 2px solid silver;
 204 }
 205
 206 div.exampleblock > div.content {
 207   border-left: 2px solid silver;
 208   padding: 0.5em;
 209 }
 210
 211 div.imageblock div.content { padding-left: 0; }
 212 div.imageblock img { border: 1px solid silver; }
 213 span.image img { border-style: none; }
 214
 215 dl {
 216   margin-top: 0.8em;
 217   margin-bottom: 0.8em;
 218 }
 219 dt {
 220   margin-top: 0.5em;
 221   margin-bottom: 0;
 222   font-style: normal;
 223   color: navy;
 224 }
 225 dd > *:first-child {
 226   margin-top: 0.1em;
 227 }
 228
 229 ul, ol {
 230     list-style-position: outside;
 231 }
 232 ol.arabic {
 233   list-style-type: decimal;
 234 }
 235 ol.loweralpha {
 236   list-style-type: lower-alpha;
 237 }
 238 ol.upperalpha {
 239   list-style-type: upper-alpha;
 240 }
 241 ol.lowerroman {
 242   list-style-type: lower-roman;
 243 }
 244 ol.upperroman {
 245   list-style-type: upper-roman;
 246 }
 247
 248 div.compact ul, div.compact ol,
 249 div.compact p, div.compact p,
 250 div.compact div, div.compact div {
 251   margin-top: 0.1em;
 252   margin-bottom: 0.1em;
 253 }
 254
 255 div.tableblock > table {
 256   border: 3px solid #527bbd;
 257 }
 258 thead {
 259   font-family: sans-serif;
 260   font-weight: bold;
 261 }
 262 tfoot {
 263   font-weight: bold;
 264 }
 265 td > div.verse {
 266   white-space: pre;
 267 }
 268 p.table {
 269   margin-top: 0;
 270 }
 271 /* Because the table frame attribute is overriden by CSS in most browsers. */
 272 div.tableblock > table[frame="void"] {
 273   border-style: none;
 274 }
 275 div.tableblock > table[frame="hsides"] {
 276   border-left-style: none;
 277   border-right-style: none;
 278 }
 279 div.tableblock > table[frame="vsides"] {
 280   border-top-style: none;
 281   border-bottom-style: none;
 282 }
 283
 284
 285 div.hdlist {
 286   margin-top: 0.8em;
 287   margin-bottom: 0.8em;
 288 }
 289 div.hdlist tr {
 290   padding-bottom: 15px;
 291 }
 292 dt.hdlist1.strong, td.hdlist1.strong {
 293   font-weight: bold;
 294 }
 295 td.hdlist1 {
 296   vertical-align: top;
 297   font-style: normal;
 298   padding-right: 0.8em;
 299   color: navy;
 300 }
 301 td.hdlist2 {
 302   vertical-align: top;
 303 }
 304 div.hdlist.compact tr {
 305   margin: 0;
 306   padding-bottom: 0;
 307 }
 308
 309 .comment {
 310   background: yellow;
 311 }
 312
 313 @media print {
 314   div#footer-badges { display: none; }
 315 }
 316
 317 div#toctitle {
 318   color: #527bbd;
 319   font-family: sans-serif;
 320   font-size: 1.1em;
 321   font-weight: bold;
 322   margin-top: 1.0em;
 323   margin-bottom: 0.1em;
 324 }
 325
 326 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 327   margin-top: 0;
 328   margin-bottom: 0;
 329 }
 330 div.toclevel2 {
 331   margin-left: 2em;
 332   font-size: 0.9em;
 333 }
 334 div.toclevel3 {
 335   margin-left: 4em;
 336   font-size: 0.9em;
 337 }
 338 div.toclevel4 {
 339   margin-left: 6em;
 340   font-size: 0.9em;
 341 }
 342 /* Workarounds for IE6's broken and incomplete CSS2. */
 343
 344 div.sidebar-content {
 345   background: #ffffee;
 346   border: 1px solid silver;
 347   padding: 0.5em;
 348 }
 349 div.sidebar-title, div.image-title {
 350   color: #527bbd;
 351   font-family: sans-serif;
 352   font-weight: bold;
 353   margin-top: 0.0em;
 354   margin-bottom: 0.5em;
 355 }
 356
 357 div.listingblock div.content {
 358   border: 1px solid silver;
 359   background: #f4f4f4;
 360   padding: 0.5em;
 361 }
 362
 363 div.quoteblock-attribution {
 364   padding-top: 0.5em;
 365   text-align: right;
 366 }
 367
 368 div.verseblock-content {
 369   white-space: pre;
 370 }
 371 div.verseblock-attribution {
 372   padding-top: 0.75em;
 373   text-align: left;
 374 }
 375
 376 div.exampleblock-content {
 377   border-left: 2px solid silver;
 378   padding-left: 0.5em;
 379 }
 380
 381 /* IE6 sets dynamically generated links as visited. */
 382 div#toc a:visited { color: blue; }
 383 </style>
 384 </head>
 385 <body>
 386 <div id="header">
 387 <h1>FreeFOAM README for version 0.1.0</h1>
 388 <span id="author">Michael Wild</span><br />
 389 <span id="email"><tt>&lt;<a href="mailto:themiwi@users.sourceforge.net">themiwi@users.sourceforge.net</a>&gt;</tt></span><br />
 390 <span id="revision">version 0.1.0,</span>
 391 23 Mar 2009
 392 </div>
 393 <div id="preamble">
 394 <div class="sectionbody">
 395 <div class="paragraph"><p><a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a></p></div>
 396 </div>
 397 </div>
 398 <h2 id="_copyright">1. Copyright</h2>
 399 <div class="sectionbody">
 400 <div class="paragraph"><p>FreeFOAM is free software; you can redistribute it and/or modify it under the
 401 terms of the GNU General Public License as published by the Free Software
 402 Foundation; either version 2 of the License, or (at your option) any later
 403 version.  See the file COPYING in this directory, for a description of the GNU
 404 General Public License terms under which you can copy the files.</p></div>
 405 </div>
 406 <h2 id="_system_requirements">2. System requirements</h2>
 407 <div class="sectionbody">
 408 <div class="paragraph"><p>FreeFOAM is developed and tested on Linux, but should work with other Unix style
 409 systems, notably Mac OS X (c). The support for Microsoft Windows is a goal,
 410 which, however, is still far off.</p></div>
 411 <h3 id="_required_software_to_build_freefoam">2.1. Required software to build FreeFOAM</h3><div style="clear:left"></div>
 412 <div class="dlist"><dl>
 413 <dt class="hdlist1">
 414 <a id="git"></a>git
 415 </dt>
 416 <dd>
 417 <p>
 418   Currently you need git to obtain the FreeFOAM source code. <a href="http://git.or.cz">http://git.or.cz</a>
 419 </p>
 420 </dd>
 421 <dt class="hdlist1">
 422 <a id="cmake"></a>CMake
 423 </dt>
 424 <dd>
 425 <p>
 426   In order to build FreeFOAM you need to have CMake with version 2.6.2 or
 427   newer installed. <a href="http://cmake.org">http://cmake.org</a>
 428 </p>
 429 </dd>
 430 <dt class="hdlist1">
 431 <a id="build_system"></a>Build system
 432 </dt>
 433 <dd>
 434 <p>
 435   CMake requires a native build system. On Unix like platforms GNU Make is
 436   recommended. <a href="http://www.gnu.org/software/make">http://www.gnu.org/software/make</a>
 437 </p>
 438 </dd>
 439 <dt class="hdlist1">
 440 <a id="cxx_compiler"></a>C++ compiler
 441 </dt>
 442 <dd>
 443 <p>
 444   In order to build FreeFOAM you need a C++ compiler with good support for
 445   template expressions. The g++ compiler from GCC-4.3 and above will do
 446   fine. <a href="http://gcc.gnu.org">http://gcc.gnu.org</a>
 447 </p>
 448 </dd>
 449 <dt class="hdlist1">
 450 <a id="flex"></a>flex
 451 </dt>
 452 <dd>
 453 <p>
 454   The flex lexer generator. Version 2.5.33 is known to work. For more recent
 455   versions there have been reports of problems. <a href="http://flex.sourceforge.net">http://flex.sourceforge.net</a>
 456 </p>
 457 </dd>
 458 <dt class="hdlist1">
 459 <a id="zlib"></a>zlib
 460 </dt>
 461 <dd>
 462 <p>
 463   zlib compression library. <a href="http://www.zlib.net">http://www.zlib.net</a>
 464 </p>
 465 </dd>
 466 <dt class="hdlist1">
 467 <a id="metis"></a>METIS
 468 </dt>
 469 <dd>
 470 <p>
 471   The METIS graph partitioning library, version 5.0pre2. If your package manager
 472   doesn&#8217;t contain it, you can also have FreeFOAM build it automatically for you
 473   (see the <a href="#installation">installation section</a>).
 474   <a href="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview">http://glaros.dtc.umn.edu/gkhome/metis/metis/overview</a>
 475 </p>
 476 </dd>
 477 </dl></div>
 478 <h3 id="_optional_software">2.2. Optional software</h3><div style="clear:left"></div>
 479 <div class="dlist"><dl>
 480 <dt class="hdlist1">
 481 <a id="parlib"></a>Parallel Communications Library
 482 </dt>
 483 <dd>
 484 <p>
 485   In order to run FreeFOAM in parallel, a communications library is required.
 486   The following list gives an overview of the available options:
 487 </p>
 488 <div class="ulist"><ul>
 489 <li>
 490 <p>
 491 MPI (<em>Message Passing Interface</em>): There are many implementations of the MPI
 492     standard. The one that has been tested and is known to work with FreeFOAM
 493     is <a href="http://www.open-mpi.org">OpenMPI</a>.
 494 </p>
 495 </li>
 496 <li>
 497 <p>
 498 PVM (<em>Parallel Virtual Machine</em>) is available from
 499     <a href="http://www.csm.ornl.gov/pvm">http://www.csm.ornl.gov/pvm</a>.
 500 </p>
 501 </li>
 502 <li>
 503 <p>
 504 GAMMA (<em>Genoa Active Message MAchine</em>) is available from
 505     <a href="http://www.disi.unige.it/project/gamma">http://www.disi.unige.it/project/gamma</a>.
 506 </p>
 507 </li>
 508 </ul></div>
 509 </dd>
 510 <dt class="hdlist1">
 511 <a id="parmetis"></a>ParMetis
 512 </dt>
 513 <dd>
 514 <p>
 515   If you use an MPI library, the ParMetis library is required. If your package
 516   manager doesn&#8217;t contain this library, FreeFOAM can build it automatically for
 517   you (refer to the <a href="#installation">installation notes</a> below).
 518   <a href="http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview">http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview</a>
 519 </p>
 520 </dd>
 521 <dt class="hdlist1">
 522 <a id="mgridgen"></a>MGRIDGEN
 523 </dt>
 524 <dd>
 525 <p>
 526   MGRIDGEN is a grid coarsening library for multi-grid solvers. FreeFOAM can
 527   build this automatically for you (refer to the installation notes below).
 528   <a href="http://glaros.dtc.umn.edu/gkhome/mgridgen/overview">http://glaros.dtc.umn.edu/gkhome/mgridgen/overview</a>
 529 </p>
 530 <div class="admonitionblock">
 531 <table><tr>
 532 <td class="icon">
 533 <div class="title">Warning</div>
 534 </td>
 535 <td class="content">The license of <em>MGRIDGEN</em> and <em>PARMGRIDGEN</em> is unknown and the upstream authors
 536 so far have not answered any inquiries to resolve the issue. If you enable the
 537 use of <em>MGRIDGEN</em> and <em>PARMGRIDGEN</em> you alone are responsible for ensuring that
 538 you don&#8217;t violate any license conditions applying to these libraries. The
 539 authors of FreeFOAM will and cannot take any responsibility for your
 540 actions.</td>
 541 </tr></table>
 542 </div>
 543 </dd>
 544 <dt class="hdlist1">
 545 <a id="libccmio"></a>libccmio
 546 </dt>
 547 <dd>
 548 <p>
 549   pro-STAR (c) input/output library. FreeFOAM can build this automatically for
 550   you (refer to the <a href="#installation">installation notes</a> below).
 551   <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>
 552 </p>
 553 <div class="admonitionblock">
 554 <table><tr>
 555 <td class="icon">
 556 <div class="title">Warning</div>
 557 </td>
 558 <td class="content">The license of <em>libccmio</em> &#169; is proprietary and requires the consent of the
 559 copyright holders (<a href="http://www.cd-adapco.com">CD-adapco</a>) to download and use the
 560 library. Further it is not allowed to redistribute it in any form. The request
 561 for permission of inclusion with <a href="http://debian.org">Debian</a> was answered as
 562 follows by <a href="mailto:geoffrey.prewett@us.cd-adapco.com">Geoffrey Prewett</a>:</td>
 563 </tr></table>
 564 </div>
 565 <div class="listingblock">
 566 <div class="content">
 567 <pre><tt>Gerber,
 568
 569 Sorry for the delay in response.  I checked back with our development director,
 570 and he felt that it would be best to not include libccmio with Debian.
 571 Instead, we would prefer to continue our current policy and keep it on our
 572 web/FTP and have people ask for it.  There are three reasons for this:
 573
 574 1) We don't support STAR on Debian, and don't want to give the impression that we do.
 575 2) We would like to keep a list of people that we give the library to.
 576 3) This is not a general purpose library;  its sole purpose is to communicate
 577 between our products.  Accepting outside changes risks committing a change that
 578 would break our own software in possibly subtle ways.
 579
 580 So I regret to tell you that my company has declined to permit libccmio to be
 581 distributed as part of Debian.
 582
 583 Regards,
 584 Geoff Prewett</tt></pre>
 585 </div></div>
 586 </dd>
 587 <dt class="hdlist1">
 588 <a id="paraview"></a>ParaView
 589 </dt>
 590 <dd>
 591 <p>
 592   If you want to build the <a href="http://paraview.org">ParaView</a> plug-ins, you need a
 593   ParaView with the development headers <strong>and</strong> the corresponding CMake configuration
 594   files (<em>ParaViewConfig.cmake</em>, <em>ParaViewUse.cmake</em>, <em>ParaViewLibraryDepends*.cmake</em>).
 595   Most likely this means that you have to build ParaView yourself.
 596   <a href="http://paraview.org">http://paraview.org</a>
 597 </p>
 598 </dd>
 599 <dt class="hdlist1">
 600 <a id="m4"></a>M4
 601 </dt>
 602 <dd>
 603 <p>
 604   Some of the provided tutorial cases require the M4 macro processor.
 605   <a href="http://www.gnu.org/software/m4/">http://www.gnu.org/software/m4/</a>
 606 </p>
 607 </dd>
 608 <dt class="hdlist1">
 609 <a id="doxygen"></a>Doxygen
 610 </dt>
 611 <dd>
 612 <p>
 613   Automatic API-documentation generator. Required to build the source
 614   documentation. <a href="http://www.doxygen.org">http://www.doxygen.org</a>
 615 </p>
 616 </dd>
 617 </dl></div>
 618 </div>
 619 <h2 id="installation">3. Installation</h2>
 620 <div class="sectionbody">
 621 <div class="paragraph"><p>This section needs serious expanding, but the short version is:</p></div>
 622 <div class="ulist"><ul>
 623 <li>
 624 <p>
 625 Install the prerequisites. If your distribution does not have <em>METIS</em>,
 626   <em>ParMetis</em>, <em>MGRIDGEN</em> or <em>libccmio</em> be not worried, FreeFOAM can handle
 627   those for you.
 628 </p>
 629 </li>
 630 <li>
 631 <p>
 632 Clone the FreeFOAM repository (here the clone is placed in
 633   <tt>$HOME/Source/FreeFOAM</tt>):
 634 </p>
 635 <div class="listingblock">
 636 <div class="content">
 637 <pre><tt>$ mkdir -p $HOME/Source
 638 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM</tt></pre>
 639 </div></div>
 640 </li>
 641 <li>
 642 <p>
 643 Create a build tree and <em>cd</em> into it:
 644 </p>
 645 <div class="listingblock">
 646 <div class="content">
 647 <pre><tt>$ mkdir $HOME/Source/FreeFOAM-build
 648 $ cd $HOME/Source/FreeFOAM-build</tt></pre>
 649 </div></div>
 650 </li>
 651 <li>
 652 <p>
 653 Start CMake-configuration:
 654 </p>
 655 <div class="listingblock">
 656 <div class="content">
 657 <pre><tt>$ ccmake ../FreeFOAM</tt></pre>
 658 </div></div>
 659 </li>
 660 <li>
 661 <p>
 662 Press the <tt>c</tt> key. Use the arrow keys to navigate up and down and press
 663   <tt>enter</tt> to edit a field. To commit the change, press <tt>enter</tt> again, or <tt>ESC</tt>
 664   to abandon the change.  ON/OFF fields are toggled by pressing <tt>enter</tt>.
 665   Advanced options can be displayed by hitting the <tt>t</tt> key.
 666 </p>
 667 <div class="ulist"><ul>
 668 <li>
 669 <p>
 670 Set <tt>CMAKE_BUILD_TYPE</tt> to <em>Release</em> for an optimized build.
 671 </p>
 672 </li>
 673 <li>
 674 <p>
 675 If CMake complains that it can&#8217;t find MPI, and you don&#8217;t want to install it, disable
 676     <tt>FF_USE_MPI</tt>. If, instead, you want to use GAMMA or PVM, enable <tt>FF_USE_GAMMA</tt> or
 677     <tt>FF_USE_PVM</tt>, respectively. You can also enable more than one of the options.
 678 </p>
 679 <div class="admonitionblock">
 680 <table><tr>
 681 <td class="icon">
 682 <div class="title">Note</div>
 683 </td>
 684 <td class="content">Currently only MPI implementation is available.</td>
 685 </tr></table>
 686 </div>
 687 </li>
 688 <li>
 689 <p>
 690 Select the default Pstream implementation by setting <tt>FF_DEFAULT_PSTREAM</tt>
 691     to one of <em>dummy</em>, <em>mpi</em>, <em>pvm</em> or <em>gamma</em>. This setting will only influence
 692     the contents of the <a href="#globalconfig">global <em>controlDict</em> file</a>.
 693 </p>
 694 </li>
 695 <li>
 696 <p>
 697 If CMake told you it couldn&#8217;t find ParaView:
 698 </p>
 699 <div class="olist arabic"><ol class="arabic">
 700 <li>
 701 <p>
 702 Set <tt>ParaView_DIR</tt> to the path of the directory containing
 703     <em>ParaViewConfig.cmake</em>, which is most likely the ParaView build directory.
 704 </p>
 705 </li>
 706 <li>
 707 <p>
 708 If you do not want to build the ParaView plug-ins, disable
 709     <tt>FF_BUILD_PARAVIEW_PLUGINS</tt>
 710 </p>
 711 </li>
 712 </ol></div>
 713 </li>
 714 <li>
 715 <p>
 716 If you do not have <em>METIS</em> or <em>ParMetis</em>, enable
 717     <tt>FF_BUILD_PRIVATE_METIS</tt> or <tt>FF_BUILD_PRIVATE_PARMETIS</tt>, respectively.
 718     CMake will then try to download and build the selected libraries for you.
 719     Conversely, if one of the libraries is provided by your system, you can turn
 720     the respective setting to <em>OFF</em>. Please note that if your system provides
 721     only <em>ParMetis</em>, you do not have to install <em>METIS</em>, as the former also
 722     contains <em>METIS</em> in an older version.
 723 </p>
 724 </li>
 725 <li>
 726 <p>
 727 If you want to use the <em>MGridGen</em> agglomeration method for the GAMG solver,
 728     you need to enable <tt>FF_ENABLE_PARMGRIDGEN</tt> and if the library is not
 729     installed on your system ensure that <tt>FF_BUILD_PRIVATE_PARMGRIDGEN</tt> is
 730     enabled. See <a href="#parmgridgen">above</a> regarding the unknown license status of
 731     this package.
 732 </p>
 733 </li>
 734 <li>
 735 <p>
 736 In order to build <em>ccm26ToFoam</em>, a conversion utility for grids generated
 737     with <em>ProStar/ccm</em> &#169; version 2.6, enable the setting <tt>FF_ENABLE_CCMIO</tt>
 738     and if <em>libccmio</em> is not installed on your system, also
 739     <tt>FF_BUILD_PRIVATE_CCMIO</tt>.  Refer to the <a href="#libccmio">above</a> description of
 740     the <em>libccmio</em> package for the license restrictions which apply to this
 741     package.
 742 </p>
 743 </li>
 744 <li>
 745 <p>
 746 If you plan on installing FreeFOAM, set <tt>CMAKE_INSTALL_PREFIX</tt> to the base directory
 747     under which FreeFOAM should reside.
 748 </p>
 749 </li>
 750 <li>
 751 <p>
 752 For more fine-grained control over what gets installed where, adjust
 753     <tt>FF_INSTALL_CONFIG_PATH</tt>, <tt>FF_INSTALL_HEADER_PATH</tt>, <tt>FF_INSTALL_LIB_PATH</tt>,
 754     <tt>FF_INSTALL_FRAMEWORK_PATH</tt>, <tt>FF_INSTALL_PV3FOAMREADER_PATH</tt>,
 755     <tt>FF_INSTALL_PVFOAMREADER_PATH</tt> and <tt>FF_INSTALL_USERDFOAM_PATH</tt>. Paths not
 756     starting with a slash (<em>/</em>) will be relative to <em>CMAKE_INSTALL_PREFIX</em>. If
 757     you include a leading slash, the paths are absolute.
 758 </p>
 759 </li>
 760 <li>
 761 <p>
 762 If you want FreeFOAM to use <em>float</em> as the floating point type instead of
 763     <em>double</em>, change <tt>FF_DOUBLE_PRECISION</tt> to <em>OFF</em>.
 764 </p>
 765 </li>
 766 </ul></div>
 767 </li>
 768 <li>
 769 <p>
 770 Hit the <tt>c</tt> key again. If you enabled <tt>FF_BUILD_PRIVATE_CCMIO</tt>, CMake will fail
 771   to download <a href="https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz">https://wci.llnl.gov/codes/visit/3rd_party/libccmio-2.6.1.tar.gz</a>.
 772   Please follow the instructions in the error message on how to work around this
 773   problem, or download the file manually and place it in <tt>ThirdParty/ccmio/</tt>
 774   (relative to the build directory). Then hit <tt>c</tt> again.
 775 </p>
 776 </li>
 777 <li>
 778 <p>
 779 You shouldn&#8217;t get any errors anymore now. Keep pressing <tt>c</tt> until ccmake
 780   displays "<tt>Press [g] to generate and exit</tt>" in the legend at the bottom of
 781   the interface.
 782 </p>
 783 </li>
 784 <li>
 785 <p>
 786 Press <tt>g</tt> to generate the Makefiles and exit the ccmake interface.
 787 </p>
 788 </li>
 789 <li>
 790 <p>
 791 Start the native build tool. If you used the <em>Makefile</em> generator
 792   (which is the default for Unix-platforms), type
 793 </p>
 794 <div class="listingblock">
 795 <div class="content">
 796 <pre><tt>$ make</tt></pre>
 797 </div></div>
 798 </li>
 799 <li>
 800 <p>
 801 If you have a multi-core/processor machine, you can speed things up
 802   significantly by telling Make to run independent jobs in parallel.
 803   A good choice for the number of parallel jobs to run is the
 804   number of CPU&#8217;s/cores you have in your machine plus 1 (to compensate
 805   for disk-latency). For a typical dual-core machine, run
 806 </p>
 807 <div class="listingblock">
 808 <div class="content">
 809 <pre><tt>$ make -j3</tt></pre>
 810 </div></div>
 811 </li>
 812 <li>
 813 <p>
 814 If you want to, you can now install FreeFOAM (depending on the
 815   <tt>CMAKE_INSTALL_PREFIX</tt> and the individual <tt>FF_INSTALL_*_PATH</tt>
 816   it is possible that you have to do this as root, i.e. use
 817   <tt>su</tt> or <tt>sudo</tt>).
 818 </p>
 819 <div class="listingblock">
 820 <div class="content">
 821 <pre><tt>$ make install</tt></pre>
 822 </div></div>
 823 </li>
 824 </ul></div>
 825 <h3 id="_using_freefoam">3.1. Using FreeFOAM</h3><div style="clear:left"></div>
 826 <div class="paragraph"><p>If you didn&#8217;t change <tt>CMAKE_INSTALL_PREFIX</tt> and <tt>FF_INSTALL_BIN_PATH</tt> chances
 827 are that you can start using FreeFOAM right after you installed it without any
 828 further steps being necessary.</p></div>
 829 <h4 id="globalconfig">3.1.1. Global Configuration Files</h4>
 830 <div class="paragraph"><p>Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
 831 applications require some files to be present for start-up. It finds those
 832 in the following places (in the specified order, picking the first hit):</p></div>
 833 <div class="olist arabic"><ol class="arabic">
 834 <li>
 835 <p>
 836 Under the directory specified in the <tt>$FREEFOAM_CONFIG_DIR</tt> environment
 837    variable
 838 </p>
 839 </li>
 840 <li>
 841 <p>
 842 In <em>$HOME/.FreeFOAM/0.1.0</em>
 843 </p>
 844 </li>
 845 <li>
 846 <p>
 847 In <em>$HOME/.FreeFOAM</em>
 848 </p>
 849 </li>
 850 <li>
 851 <p>
 852 In the installation directory of the configuration files. There are
 853    two possible places for this:
 854 </p>
 855 <div class="dlist"><dl>
 856 <dt class="hdlist1">
 857 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FF_INSTALL_CONFIG_PATH&gt;</em>
 858 </dt>
 859 <dd>
 860 <p>
 861 if you specified
 862      <tt>&lt;FF_INSTALL_CONFIG_PATH&gt;</tt> as a relative path.
 863 </p>
 864 </dd>
 865 <dt class="hdlist1">
 866 <em>&lt;FF_INSTALL_CONFIG_PATH&gt;</em>
 867 </dt>
 868 <dd>
 869 <p>
 870 if you specified <tt>&lt;FF_INSTALL_CONFIG_PATH&gt;</tt> as
 871     an absolute path.
 872 </p>
 873 <div class="paragraph"><p>The default location is <em>/usr/local/etc/FreeFOAM/1.0</em>.</p></div>
 874 </dd>
 875 </dl></div>
 876 </li>
 877 </ol></div>
 878 <h4 id="_selecting_the_parallel_communications_library">3.1.2. Selecting the Parallel Communications Library</h4>
 879 <div class="paragraph"><p>Both, FreeFOAM and OpenFOAM abstract the parallel operations into the <em>Pstream</em>
 880 library, making it rather simple to firstly switch between parallel
 881 implementations and secondly port the software to a new communications library.
 882 However, FreeFOAM uses a much more flexible mechanism of determining which
 883 <em>Pstream</em> implementation library to use than OpenFOAM. The latter does this by
 884 adjusting the <tt>LD_LIBRARY_PATH</tt> environment variable.  As FreeFOAM wants to be a
 885 well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically
 886 loads the desired <em>Pstream</em> library at startup (i.e. as a plug-in).  The
 887 following list details how FreeFOAM determines what library to load (if at all):</p></div>
 888 <div class="olist arabic"><ol class="arabic">
 889 <li>
 890 <p>
 891 If the environment variable <tt>FREEFOAM_PSTREAM_LIBRARY</tt> is set,
 892    FreeFOAM will try to load the library specified by it.
 893 </p>
 894 </li>
 895 <li>
 896 <p>
 897 If the sub-dictionary <tt>PstreamImplementation</tt> exists in the global
 898    <em>controlDict</em> file (see <a href="#globalconfig"><em>Global Configuration Files</em></a>), it
 899    reads the value of the entry <tt>configName</tt> therein. It then expects that a
 900    sub-dictionary of <tt>PstreamImplementation</tt> with the name specified in
 901    <tt>configName</tt> exists. If that sub-dictionary contains the entry <tt>library</tt>, it
 902    will try to load a library specified by the value of that entry.
 903 </p>
 904 </li>
 905 </ol></div>
 906 <div class="paragraph"><p>After FreeFOAM (possibly) loaded the library, it will try to instantiate
 907 concrete implementations of the abstract base classes <tt>PstreamImpl</tt>,
 908 <tt>IPstreamImpl</tt> and <tt>OPstreamImpl</tt>. Which classes are to be instantiated
 909 is determined as follows:</p></div>
 910 <div class="olist arabic"><ol class="arabic">
 911 <li>
 912 <p>
 913 FreeFOAM queries the environment variables <tt>FREEFOAM_PSTREAM_CLASS</tt>,
 914    <tt>FREEFOAM_IPSTREAM_CLASS</tt> and <tt>FREEFOAM_OPSTREAM_CLASS</tt> for the class
 915    names to be instantiated.
 916 </p>
 917 </li>
 918 <li>
 919 <p>
 920 For any of the variables not set,  it requires the sub-dictionary
 921    <tt>PstreamImplementation</tt> to be present in the global <em>controlDict</em>, reads the
 922    value of <tt>configName</tt> and similarly to the library loading, loads the
 923    sub-dictionary specified by that value. It then expects to find the entries
 924    <tt>Pstream</tt>, <tt>IPstream</tt> and <tt>OPstream</tt> which specify the names of the classes
 925    to load.
 926 </p>
 927 </li>
 928 </ol></div>
 929 <div class="paragraph"><p>This means that one can create a global <em>controlDict</em> file containing
 930 (among other things) something like the following:</p></div>
 931 <div class="exampleblock">
 932 <div class="exampleblock-content">
 933 <div class="listingblock">
 934 <div class="content">
 935 <pre><tt>PstreamImplementation
 936 {
 937     //configName dummy;
 938     configName mpi;
 939
 940     dummy
 941     {
 942         library libdummyPstream.so;
 943         Pstream dummyPstreamImpl;
 944         OPstream dummyOPstreamImpl;
 945         IPstream dummyIPstreamImpl;
 946     }
 947
 948     mpi
 949     {
 950         library libmpiPstream.so;
 951         Pstream mpiPstreamImpl;
 952         OPstream mpiOPstreamImpl;
 953         IPstream mpiIPstreamImpl;
 954     }
 955 }</tt></pre>
 956 </div></div>
 957 </div></div>
 958 <div class="paragraph"><p>This way the administrator can provide a global <em>controlDict</em> in the FreeFOAM
 959 installation. Every user can then override that <em>controlDict</em> by supplying her
 960 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
 961 for a specific communications library, the user can then either adjust the
 962 <tt>PstreamImplementation::configName</tt> entry in the global <em>controlDict</em> file, set
 963 the <tt>FREEFOAM_PSTREAM_CONFIG</tt> variable or for full control, set the variables
 964 <tt>FREEFOAM_PSTREAM_LIBRARY</tt>, <tt>FREEFOAM_PSTREAM_CLASS</tt>, <tt>FREEFOAM_IPSTREAM_CLASS</tt>
 965 and <tt>FREEFOAM_OPSTREAM_CLASS</tt>.</p></div>
 966 <h4 id="_running_freefoam_from_the_build_tree">3.1.3. Running FreeFOAM From the Build Tree</h4>
 967 <div class="paragraph"><p>You can use FreeFOAM without installing it first, directly from the build tree.
 968 However, this might take a little bit more effort to set up because most likely
 969 you will have to adjust the following environment variables:</p></div>
 970 <div class="dlist"><dl>
 971 <dt class="hdlist1">
 972 PATH
 973 </dt>
 974 <dd>
 975 <p>
 976 Must contain <em>$HOME/Source/FreeFOAM-build/bin</em>
 977 </p>
 978 </dd>
 979 <dt class="hdlist1">
 980 LD_LIBRARY_PATH
 981 </dt>
 982 <dd>
 983 <p>
 984 Must contain <em>$HOME/Source/FreeFOAM-build/lib</em>
 985 </p>
 986 </dd>
 987 <dt class="hdlist1">
 988 FREEFOAM_CONFIG_DIR
 989 </dt>
 990 <dd>
 991 <p>
 992 Should point to <em>$HOME/Source/FreeFOAM-build/etc</em>
 993 </p>
 994 </dd>
 995 </dl></div>
 996 <div class="paragraph"><p>Where it is assumed that you followed the <a href="#installation">installation instructions</a>. If
 997 you used different paths for downloading and compiling FreeFOAM, you will have
 998 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
 999 variables.</p></div>
1000 <h3 id="_running_the_tutorials">3.2. Running the tutorials</h3><div style="clear:left"></div>
1001 <div class="paragraph"><p>Now you should be able to run the tutorial cases. For this copy the <tt>tutorials</tt>
1002 directory to some convenient place:</p></div>
1003 <div class="listingblock">
1004 <div class="content">
1005 <pre><tt>$ mkdir -p $HOME/FreeFOAM/$LOGNAME-0.1.0/run
1006 $ cp -r $HOME/Source/FreeFOAM-build/tutorials $HOME/FreeFOAM/$LOGNAME-0.1.0/run/
1007 $ cd $HOME/FreeFOAM/$LOGNAME-0.1.0/run</tt></pre>
1008 </div></div>
1009 <div class="paragraph"><p>And try to run e.g. the <em>cavity</em> tutorial case:</p></div>
1010 <div class="listingblock">
1011 <div class="content">
1012 <pre><tt>$ cd icoFoam
1013 $ blockMesh -case cavity
1014 $ checkMesh -case cavity
1015 $ icoFoam -case cavity</tt></pre>
1016 </div></div>
1017 <div class="paragraph"><p>Things should run smoothly and finish without an error.</p></div>
1018 <h3 id="_build_configuration_reference">3.3. Build Configuration Reference</h3><div style="clear:left"></div>
1019 <div class="dlist glossary"><dl>
1020 <dt>
1021 <tt>CMAKE_BUILD_TYPE</tt>
1022 </dt>
1023 <dd>
1024 <p>
1025   One of <em>&lt;empty&gt;</em>, <em>Debug</em>, <em>Release</em>, <em>RelWithDebInfo</em> and <em>MinSizeRel</em>.
1026   Refer to the CMake documentation for more detail.
1027 </p>
1028 </dd>
1029 <dt>
1030 <tt>FF_DOUBLE_PRECISION</tt>
1031 </dt>
1032 <dd>
1033 <p>
1034   If set to <em>ON</em> FreeFOAM will be compiled using <em>double</em> as the
1035   floating point type. If set to <em>OFF</em> it will use <em>float</em>.
1036 </p>
1037 </dd>
1038 <dt>
1039 <tt>FF_BUILD_FRAMEWORK</tt>
1040 </dt>
1041 <dd>
1042 <p>
1043   If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
1044 </p>
1045 </dd>
1046 <dt>
1047 <tt>CMAKE_INSTALL_PREFIX</tt>
1048 </dt>
1049 <dd>
1050 <p>
1051   Installation prefix under which to install FreeFOAM.
1052 </p>
1053 </dd>
1054 <dt>
1055 <tt>FF_INSTALL_BIN_PATH</tt>
1056 </dt>
1057 <dd>
1058 <p>
1059   Installation path of the binaries. If not absolute, it is relative to
1060   <em>CMAKE_INSTALL_PREFIX</em>.
1061 </p>
1062 </dd>
1063 <dt>
1064 <tt>FF_INSTALL_CONFIG_PATH</tt>
1065 </dt>
1066 <dd>
1067 <p>
1068   Installation path of the configuration files. If not absolute, it is
1069   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1070 </p>
1071 </dd>
1072 <dt>
1073 <tt>FF_INSTALL_HEADER_PATH</tt>
1074 </dt>
1075 <dd>
1076 <p>
1077   Installation path of the header files. If not absolute, it is
1078   relative to <em>CMAKE_INSTALL_PREFIX</em>. On Mac OS X, and if
1079   <em>FF_BUILD_FRAMEWORK</em> is enabled, this setting is ignored.
1080 </p>
1081 </dd>
1082 <dt>
1083 <tt>FF_INSTALL_LIB_PATH</tt>
1084 </dt>
1085 <dd>
1086 <p>
1087   Installation path of the libraries. If not absolute, it is
1088   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1089 </p>
1090 </dd>
1091 <dt>
1092 <tt>FF_INSTALL_FRAMEWORK_PATH</tt>
1093 </dt>
1094 <dd>
1095 <p>
1096   Installation path of the Mac OS X frameworks. If not absolute, it is
1097   relative to <em>CMAKE_INSTALL_PREFIX</em>. This is only available and takes
1098   effect if FreeFOAM is compiled on Mac OS X, and if
1099   <em>FF_BUILD_FRAMEWORK</em> is enabled.
1100 </p>
1101 </dd>
1102 <dt>
1103 <tt>FF_INSTALL_PV3FOAMREADER_PATH</tt>
1104 </dt>
1105 <dd>
1106 <p>
1107   Installation path of the ParaView3 plug-ins. If not absolute, it is
1108   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1109 </p>
1110 </dd>
1111 <dt>
1112 <tt>FF_INSTALL_PVFOAMREADER_PATH</tt>
1113 </dt>
1114 <dd>
1115 <p>
1116   Installation path of the ParaView2 plug-ins. If not absolute, it is
1117   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1118 </p>
1119 </dd>
1120 <dt>
1121 <tt>FF_INSTALL_USERDFOAM_PATH</tt>
1122 </dt>
1123 <dd>
1124 <p>
1125   Installation path of the Ensight plug-in. If not absolute, it is
1126   relative to <em>CMAKE_INSTALL_PREFIX</em>.
1127 </p>
1128 </dd>
1129 <dt>
1130 <tt>EXECUTABLE_PREFIX</tt>
1131 </dt>
1132 <dd>
1133 <p>
1134   Prefix which get prepended to the name of the executables. This defaults to
1135   <em>ff_</em> and serves the disambiguation of names.
1136 </p>
1137 </dd>
1138 <dt>
1139 <tt>FF_USE_GAMMA</tt>
1140 </dt>
1141 <dd>
1142 <p>
1143   If enabled, FreeFOAM will use the GAMMA parallel communications library.
1144 </p>
1145 </dd>
1146 <dt>
1147 <tt>FF_USE_MPI</tt>
1148 </dt>
1149 <dd>
1150 <p>
1151   If enabled, FreeFOAM will use the MPI parallel communications library.
1152   This is required in order to build some of the libraries and utilities.
1153 </p>
1154 </dd>
1155 <dt>
1156 <tt>FF_USE_PVM</tt>
1157 </dt>
1158 <dd>
1159 <p>
1160   If enabled, FreeFOAM will use the PVM parallel communications library.
1161 </p>
1162 </dd>
1163 <dt>
1164 <tt>FF_DEFAULT_PSTREAM</tt>
1165 </dt>
1166 <dd>
1167 <p>
1168   The default Pstream selection in the global <em>controlDict</em> file.
1169 </p>
1170 </dd>
1171 <dt>
1172 <tt>FF_BUILD_PARAVIEW_PLUGINS</tt>
1173 </dt>
1174 <dd>
1175 <p>
1176   Whether to build the ParaView plug-ins. If enabled, FreeFOAM requires a
1177   ParaView build tree and the <em>ParaView_DIR</em> variable set to the path of it.
1178 </p>
1179 </dd>
1180 <dt>
1181 <tt>FF_ENABLE_CCMIO</tt>
1182 </dt>
1183 <dd>
1184 <p>
1185   Enable the use of <em>libccmio</em>. This is required to build the grid conversion
1186   utility <em>ccm26ToFoam</em>. Note that you need the permission of the copyright
1187   holders (<a href="http://cd-adapco.com">CD-adapco</a>) to download, build and use the
1188   library. Refer to the <a href="#libccmio">description</a> of the package for the
1189   details.
1190 </p>
1191 </dd>
1192 <dt>
1193 <tt>FF_BUILD_PRIVATE_CCMIO</tt>
1194 </dt>
1195 <dd>
1196 <p>
1197   Automatically download and build libccmio. Unfortunately this process will
1198   fail in the download step, since CMake currently does not support <em>https</em>
1199   URLs. But you will get specific instructions from the build system on how to
1200   get around this problem.
1201 </p>
1202 </dd>
1203 <dt>
1204 <tt>FF_BUILD_PRIVATE_METIS</tt>
1205 </dt>
1206 <dd>
1207 <p>
1208   Automatically download and build <em>METIS</em>.
1209 </p>
1210 </dd>
1211 <dt>
1212 <tt>FF_BUILD_PRIVATE_PARMETIS</tt>
1213 </dt>
1214 <dd>
1215 <p>
1216   Automatically download and build <em>ParMetis</em>.
1217 </p>
1218 </dd>
1219 <dt>
1220 <tt>FF_ENABLE_PARMGRIDGEN</tt>
1221 </dt>
1222 <dd>
1223 <p>
1224   Enable the use of <em>PARMGRIDGEN</em> and <em>MGRIDGEN</em> which is required to build
1225   <em>MGridGenGamgAgglomeration</em> providing the <em>MGridGen</em> agglomeration method for
1226   the GAMG solver. Be aware that if you use these libraries, that you alone are
1227   responsible to comply with the license restrictions associated with them.
1228   Refer to the <a href="#parmgridgen">description</a> of the package for more information.
1229 </p>
1230 </dd>
1231 <dt>
1232 <tt>FF_BUILD_PRIVATE_PARMGRIDGEN</tt>
1233 </dt>
1234 <dd>
1235 <p>
1236   Automatically download and build <em>PARMGRIDGEN</em> and <em>MGRIDGEN</em>.
1237 </p>
1238 </dd>
1239 <dt>
1240 <tt>FF_BUILD_DOXYGEN_DOCS</tt>
1241 </dt>
1242 <dd>
1243 <p>
1244   Enable building of the <em>Doxygen API documentation</em>. To actually build it,
1245   execute <tt>make doc</tt>.
1246 </p>
1247 </dd>
1248 </dl></div>
1249 </div>
1250 <h2 id="_documentation">4. Documentation</h2>
1251 <div class="sectionbody">
1252 <div class="paragraph"><p><a href="http://www.OpenFOAM.org/doc">http://www.OpenFOAM.org/doc</a></p></div>
1253 </div>
1254 <h2 id="_help">5. Help</h2>
1255 <div class="sectionbody">
1256 <div class="ulist"><ul>
1257 <li>
1258 <p>
1259 <a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a>
1260 </p>
1261 </li>
1262 <li>
1263 <p>
1264 <a href="https://lists.sourceforge.net/lists/listinfo/freefoam-user">https://lists.sourceforge.net/lists/listinfo/freefoam-user</a>
1265 </p>
1266 </li>
1267 <li>
1268 <p>
1269 <a href="http://www.cfd-online.com/Forums/openfoam/">http://www.cfd-online.com/Forums/openfoam/</a> <strong>please only ask questions related
1270   to <em>OpenFOAM</em> there</strong>.
1271 </p>
1272 </li>
1273 </ul></div>
1274 </div>
1275 <h2 id="_reporting_bugs_in_freefoam">6. Reporting Bugs in FreeFOAM</h2>
1276 <div class="sectionbody">
1277 <div class="paragraph"><p><a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a></p></div>
1278 </div>
1279 <h2 id="_troubleshooting">7. Troubleshooting</h2>
1280 <div class="sectionbody">
1281 <h3 id="_the_freefoam_executables_are_not_found_by_the_shell">7.1. The FreeFOAM Executables Are Not Found By The Shell</h3><div style="clear:left"></div>
1282 <div class="paragraph"><p>There are three possible reasons for this:</p></div>
1283 <div class="olist arabic"><ol class="arabic">
1284 <li>
1285 <p>
1286 Your shell (notably <em>csh</em>, <em>tcsh</em> and <em>zsh</em>) requires you to refresh the
1287    cache of available executables. You can do so by entering the command:
1288 </p>
1289 <div class="listingblock">
1290 <div class="content">
1291 <pre><tt>$ rehash</tt></pre>
1292 </div></div>
1293 </li>
1294 <li>
1295 <p>
1296 If <em>rehashing</em> didn&#8217;t solve the problem, the problem most likely is that you
1297    installed FreeFOAM into a non-standard location by changing the configuration
1298    variables <tt>CMAKE_INSTALL_PREFIX</tt> or <tt>FF_INSTALL_BIN_PATH</tt> in which case the
1299    executables where installed into a directory not searched by the shell. In
1300    this case you have to add the installation directory of the executables to
1301    the <tt>PATH</tt> variable. There are two possible locations:
1302 </p>
1303 <div class="dlist"><dl>
1304 <dt class="hdlist1">
1305 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FF_INSTALL_BIN_PATH&gt;</em>
1306 </dt>
1307 <dd>
1308 <p>
1309 if you specified
1310   <tt>FF_INSTALL_BIN_PATH</tt> as a relative path
1311 </p>
1312 </dd>
1313 <dt class="hdlist1">
1314 <em>&lt;FF_INSTALL_BIN_PATH&gt;</em>
1315 </dt>
1316 <dd>
1317 <p>
1318 if you specified <tt>FF_INSTALL_BIN_PATH</tt> as an absolute
1319   path
1320 </p>
1321 </dd>
1322 </dl></div>
1323 <div class="paragraph"><p>After extending the <tt>PATH</tt> variable with the installation directory of the
1324 executables, you should be able to run all FreeFOAM applications as any other
1325 binary available on the system. See <a href="#environment"><em>Extending Search Paths And Setting Environment Variables Permanently</em></a> for
1326 instructions on how to extend the search path.</p></div>
1327 </li>
1328 <li>
1329 <p>
1330 This option is similar to the previous solution and applies if you want to
1331    run FreeFOAM from the build tree (i.e. without running <tt>make install</tt>). In
1332    this case you again have to make sure that your shell finds the executables
1333    built by CMake by extending the <tt>PATH</tt> variable. Further, you have to tell
1334    FreeFOAM where to find the global configuration files (see
1335    <a href="#globalconfig"><em>Global Configuration Files</em></a>). Here, you have the option to
1336    place the files under your home directory or set an environment variable. The
1337    former can be achieved by:
1338 </p>
1339 <div class="listingblock">
1340 <div class="content">
1341 <pre><tt>$ mkdir -p $HOME/.FreeFOAM/0.1.0
1342 $ cp $HOME/Source/FreeFOAM-build/etc/controlDict $HOME/.FreeFOAM/0.1.0
1343 $ cp $HOME/Source/FreeFOAM-build/etc/cellModels $HOME/.FreeFOAM/0.1.0
1344 $ cp -r $HOME/Source/FreeFOAM-build/etc/thermoData $HOME/.FreeFOAM/0.1.0</tt></pre>
1345 </div></div>
1346 <div class="paragraph"><p>The latter (and recommended) method is to set the environment variable
1347 <tt>FREEFOAM_CONFIG_DIR</tt> to <em>$HOME/Source/FreeFOAM-build/etc</em>. Adjust paths to the
1348 build tree to your actual setup.</p></div>
1349 </li>
1350 </ol></div>
1351 <h3 id="_starting_any_freefoam_application_fails_because_some_libraries_cannot_be_found">7.2. Starting Any FreeFOAM Application Fails Because Some Libraries Cannot Be Found</h3><div style="clear:left"></div>
1352 <div class="paragraph"><p>Although CMake should have taken care of this by using <tt>RPATH</tt> on Linux and
1353 <tt>install_name</tt> on Mac OS X, it might be necessary on some systems to adjust the
1354 library search paths:</p></div>
1355 <div class="dlist"><dl>
1356 <dt class="hdlist1">
1357 <tt>LD_LIBRARY_PATH</tt>
1358 </dt>
1359 <dd>
1360 <p>
1361 This variable is used by all Unix like systems (e.g. Linux,
1362   Mac OS X, etc.)
1363 </p>
1364 </dd>
1365 <dt class="hdlist1">
1366 <tt>DYLD_LIBRARY_PATH</tt>
1367 </dt>
1368 <dd>
1369 <p>
1370 This variable is used by Mac OS X.
1371 </p>
1372 </dd>
1373 </dl></div>
1374 <div class="paragraph"><p>If you installed FreeFOAM, there are (as with the executables), two possible
1375 installation directories:</p></div>
1376 <div class="dlist"><dl>
1377 <dt class="hdlist1">
1378 <em>&lt;CMAKE_INSTALL_PREFIX&gt;/&lt;FF_INSTALL_LIB_PATH&gt;</em>
1379 </dt>
1380 <dd>
1381 <p>
1382 if you specified
1383   <tt>FF_INSTALL_LIB_PATH</tt> as a relative path.
1384 </p>
1385 </dd>
1386 <dt class="hdlist1">
1387 <em>&lt;FF_INSTALL_LIB_PATH&gt;</em>
1388 </dt>
1389 <dd>
1390 <p>
1391 if you specified <tt>FF_INSTALL_LIB_PATH</tt> as an absolute
1392   path.
1393 </p>
1394 </dd>
1395 </dl></div>
1396 <div class="paragraph"><p>If you are trying to run from the build tree, you have to include
1397 <em>$HOME/Source/FreeFOAM-build/lib/FreeFOAM/0.1</em> in the above mentioned search
1398 paths (where you have to adjust the location of the build tree to your actual
1399 setup).</p></div>
1400 <h3 id="_a_running_freefoam_application_aborts_because_it_can_8217_t_em_dlopen_em_a_library">7.3. A Running FreeFOAM Application Aborts Because It Can&#8217;t <em>dlopen</em> A Library</h3><div style="clear:left"></div>
1401 <div class="paragraph"><p>FreeFOAM (and OpenFOAM) often dynamically load libraries at run-time (a.k.a
1402 plug-ins) to add features the user requested without requiring that the whole
1403 application be recompiled. This makes it very simple to add new boundary
1404 conditions, turbulence and combustion models etc. However, it also requires that
1405 FreeFOAM must be able to find these libraries at run-time. The operating system
1406 function which does the loading of the libraries (<em>dlopen</em>) usually tries to
1407 find the library with the given name in several places; namely a default search
1408 path and a search path configured by one or multiple environment variables such
1409 as <tt>LD_LIBRARY_PATH</tt> or <tt>DYLD_LIBRARY_PATH</tt> (on Mac OS X). The details vary from
1410 platform to platform, so you best consult the documentation of <em>dlopen</em> for the
1411 details.</p></div>
1412 <div class="paragraph"><p>Additionally FreeFOAM allows you to configure a custom search path for plug-ins
1413 in the <a href="#globalconfig">global <em>controlDict</em></a> file by listing the directories to
1414 be searched in the list <tt>LibrarySearchPaths</tt>. By default FreeFOAM is configured
1415 to search for plug-ins in the location where CMake installed them.</p></div>
1416 <div class="paragraph"><p>If you want to add your own plug-in libraries (e.g. you want to add your own
1417 boundary conditions class), you most probably will want to extend this search
1418 path.</p></div>
1419 </div>
1420 <h2 id="environment">8. Extending Search Paths And Setting Environment Variables Permanently</h2>
1421 <div class="sectionbody">
1422 <div class="paragraph"><p>The way one sets environment variables and extends the executable and library
1423 search paths permanently strongly depends on the shell used. Usually one has to
1424 create or change an initialization file in the users home directory. In the
1425 following this will be discussed very briefly for the popular shells <em>BASH</em> and
1426 <em>tcsh</em>.  However, if you need more help or want information on using the shell,
1427 there is an excellent tutorial available at <a href="http://linuxcommand.org">http://linuxcommand.org</a>.</p></div>
1428 <h3 id="_bash">8.1. BASH</h3><div style="clear:left"></div>
1429 <div class="paragraph"><p>The BASH shell is the default shell for most Linux/Unix distributions. Most
1430 systems configure the BASH shell such that it reads the text file
1431 <em>$HOME/.bashrc</em> when starting up, so this is the place where one appends
1432 customizations of the environment variables. On some systems this file is not
1433 processed by default (notably Mac OS X). In this case you can use
1434 <em>$HOME/.bash_profile</em>.</p></div>
1435 <h4 id="_referencing_a_variable">8.1.1. Referencing A Variable</h4>
1436 <div class="paragraph"><p>To retrieve the value stored in a shell variable or environment variable, one
1437 prefixes its name with the dollar (<tt>$</tt>) character.</p></div>
1438 <h4 id="_setting_a_variable">8.1.2. Setting A Variable</h4>
1439 <div class="paragraph"><p>The syntax for setting a variable and making it available to child-processes of
1440 the shell is the following:</p></div>
1441 <div class="listingblock">
1442 <div class="content">
1443 <pre><tt>$ export variable_name=variable_value</tt></pre>
1444 </div></div>
1445 <div class="paragraph"><p>Note that no white-space characters are allowed surrounding the <tt>=</tt> sign.</p></div>
1446 <h4 id="_extending_a_search_path">8.1.3. Extending A Search Path</h4>
1447 <div class="paragraph"><p>The shell and other Unix system facilities use environment variables to locate
1448 executables and dynamically linked libraries. These search paths consist of
1449 strings naming directories in which the executables and libraries should be
1450 searched for. The individual paths are separated by a colon (<tt>:</tt>) character. To
1451 add the e.g. the directory <em>$HOME/bin</em> to the search path for executables, one
1452 would do the following:</p></div>
1453 <div class="listingblock">
1454 <div class="content">
1455 <pre><tt>$ export PATH=$PATH:$HOME/bin</tt></pre>
1456 </div></div>
1457 <div class="paragraph"><p>which appends <em>$HOME/bin</em> to the end of the <tt>PATH</tt> variable.</p></div>
1458 <h3 id="_tcsh">8.2. TCSH</h3><div style="clear:left"></div>
1459 <div class="paragraph"><p>Some users and administrators prefer to use a <em>C-Shell</em>, such as the TCSH. Here
1460 you can use e.g. the file <em>$HOME/.tcshrc</em> to customize the environment.</p></div>
1461 <h4 id="_referencing_a_variable_2">8.2.1. Referencing A Variable</h4>
1462 <div class="paragraph"><p>As with the BASH, one retrieves the value stored in a shell variable or
1463 environment variable by prefixing its name with the dollar (<tt>$</tt>) character.
1464 Sometimes it is also necessary to protect the variable name by surrounding it
1465 with curly braces (<tt>{</tt> and <tt>}</tt>).</p></div>
1466 <h4 id="_setting_a_variable_2">8.2.2. Setting A Variable</h4>
1467 <div class="paragraph"><p>The syntax for setting a variable and making it available to child-processes of
1468 the shell is the following:</p></div>
1469 <div class="listingblock">
1470 <div class="content">
1471 <pre><tt>$ setenv variable_name variable_value</tt></pre>
1472 </div></div>
1473 <h4 id="_extending_a_search_path_2">8.2.3. Extending A Search Path</h4>
1474 <div class="paragraph"><p>The shell and other Unix system facilities use environment variables to locate
1475 executables and dynamically linked libraries. These search paths consist of
1476 strings naming directories in which the executables and libraries should be
1477 searched for. The individual paths are separated by a colon (<tt>:</tt>) character. To
1478 add the e.g. the directory <em>$HOME/bin</em> to the search path for executables, one
1479 would do the following:</p></div>
1480 <div class="listingblock">
1481 <div class="content">
1482 <pre><tt>$ setenv PATH ${PATH}:${HOME}/bin</tt></pre>
1483 </div></div>
1484 <div class="paragraph"><p>which appends <em>$HOME/bin</em> to the end of the <tt>PATH</tt> variable.  Note that
1485 <em>C-shells</em> usually require the user to type <em>rehash</em> after changing the <tt>PATH</tt>
1486 variable to update the cache of available programs.</p></div>
1487 </div>
1488 <div id="footer">
1489 <div id="footer-text">
1490 Version 0.1.0<br />
1491 Last updated 2009-05-06 08:51:57 CEST
1492 </div>
1493 </div>
1494 </body>
1495 </html>