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.2.7" />
   7 <style type="text/css">
   8 /* Debug borders */
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  10 /*
  11   border: 1px solid red;
  12 */
  13 }
  14
  15 body {
  16   margin: 1em 5% 1em 5%;
  17 }
  18
  19 a {
  20   color: blue;
  21   text-decoration: underline;
  22 }
  23 a:visited {
  24   color: fuchsia;
  25 }
  26
  27 em {
  28   font-style: italic;
  29   color: navy;
  30 }
  31
  32 strong {
  33   font-weight: bold;
  34   color: #083194;
  35 }
  36
  37 tt {
  38   color: navy;
  39 }
  40
  41 h1, h2, h3, h4, h5, h6 {
  42   color: #527bbd;
  43   font-family: sans-serif;
  44   margin-top: 1.2em;
  45   margin-bottom: 0.5em;
  46   line-height: 1.3;
  47 }
  48
  49 h1, h2, h3 {
  50   border-bottom: 2px solid silver;
  51 }
  52 h2 {
  53   padding-top: 0.5em;
  54 }
  55 h3 {
  56   float: left;
  57 }
  58 h3 + * {
  59   clear: left;
  60 }
  61
  62 div.sectionbody {
  63   font-family: serif;
  64   margin-left: 0;
  65 }
  66
  67 hr {
  68   border: 1px solid silver;
  69 }
  70
  71 p {
  72   margin-top: 0.5em;
  73   margin-bottom: 0.5em;
  74 }
  75
  76 ul, ol, li > p {
  77   margin-top: 0;
  78 }
  79
  80 pre {
  81   padding: 0;
  82   margin: 0;
  83 }
  84
  85 span#author {
  86   color: #527bbd;
  87   font-family: sans-serif;
  88   font-weight: bold;
  89   font-size: 1.1em;
  90 }
  91 span#email {
  92 }
  93 span#revision {
  94   font-family: sans-serif;
  95 }
  96
  97 div#footer {
  98   font-family: sans-serif;
  99   font-size: small;
 100   border-top: 2px solid silver;
 101   padding-top: 0.5em;
 102   margin-top: 4.0em;
 103 }
 104 div#footer-text {
 105   float: left;
 106   padding-bottom: 0.5em;
 107 }
 108 div#footer-badges {
 109   float: right;
 110   padding-bottom: 0.5em;
 111 }
 112
 113 div#preamble,
 114 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 115 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 116 div.admonitionblock {
 117   margin-right: 10%;
 118   margin-top: 1.5em;
 119   margin-bottom: 1.5em;
 120 }
 121 div.admonitionblock {
 122   margin-top: 2.5em;
 123   margin-bottom: 2.5em;
 124 }
 125
 126 div.content { /* Block element content. */
 127   padding: 0;
 128 }
 129
 130 /* Block element titles. */
 131 div.title, caption.title {
 132   color: #527bbd;
 133   font-family: sans-serif;
 134   font-weight: bold;
 135   text-align: left;
 136   margin-top: 1.0em;
 137   margin-bottom: 0.5em;
 138 }
 139 div.title + * {
 140   margin-top: 0;
 141 }
 142
 143 td div.title:first-child {
 144   margin-top: 0.0em;
 145 }
 146 div.content div.title:first-child {
 147   margin-top: 0.0em;
 148 }
 149 div.content + div.title {
 150   margin-top: 0.0em;
 151 }
 152
 153 div.sidebarblock > div.content {
 154   background: #ffffee;
 155   border: 1px solid silver;
 156   padding: 0.5em;
 157 }
 158
 159 div.listingblock {
 160   margin-right: 0%;
 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 }
 171 div.quoteblock > div.attribution {
 172   padding-top: 0.5em;
 173   text-align: right;
 174 }
 175
 176 div.verseblock {
 177   padding-left: 2.0em;
 178 }
 179 div.verseblock > div.content {
 180   white-space: pre;
 181 }
 182 div.verseblock > div.attribution {
 183   padding-top: 0.75em;
 184   text-align: left;
 185 }
 186 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 187 div.verseblock + div.attribution {
 188   text-align: left;
 189 }
 190
 191 div.admonitionblock .icon {
 192   vertical-align: top;
 193   font-size: 1.1em;
 194   font-weight: bold;
 195   text-decoration: underline;
 196   color: #527bbd;
 197   padding-right: 0.5em;
 198 }
 199 div.admonitionblock td.content {
 200   padding-left: 0.5em;
 201   border-left: 2px solid silver;
 202 }
 203
 204 div.exampleblock > div.content {
 205   border-left: 2px solid silver;
 206   padding: 0.5em;
 207 }
 208
 209 div.imageblock div.content { padding-left: 0; }
 210 div.imageblock img { border: 1px solid silver; }
 211 span.image img { border-style: none; }
 212
 213 dl {
 214   margin-top: 0.8em;
 215   margin-bottom: 0.8em;
 216 }
 217 dt {
 218   margin-top: 0.5em;
 219   margin-bottom: 0;
 220   font-style: normal;
 221 }
 222 dd > *:first-child {
 223   margin-top: 0.1em;
 224 }
 225
 226 ul, ol {
 227     list-style-position: outside;
 228 }
 229 div.olist > ol {
 230   list-style-type: decimal;
 231 }
 232 div.olist2 > ol {
 233   list-style-type: lower-alpha;
 234 }
 235
 236 div.tableblock > table {
 237   border: 3px solid #527bbd;
 238 }
 239 thead {
 240   font-family: sans-serif;
 241   font-weight: bold;
 242 }
 243 tfoot {
 244   font-weight: bold;
 245 }
 246
 247 div.hlist {
 248   margin-top: 0.8em;
 249   margin-bottom: 0.8em;
 250 }
 251 div.hlist td {
 252   padding-bottom: 15px;
 253 }
 254 td.hlist1 {
 255   vertical-align: top;
 256   font-style: normal;
 257   padding-right: 0.8em;
 258 }
 259 td.hlist2 {
 260   vertical-align: top;
 261 }
 262
 263 @media print {
 264   div#footer-badges { display: none; }
 265 }
 266
 267 div#toctitle {
 268   color: #527bbd;
 269   font-family: sans-serif;
 270   font-size: 1.1em;
 271   font-weight: bold;
 272   margin-top: 1.0em;
 273   margin-bottom: 0.1em;
 274 }
 275
 276 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 277   margin-top: 0;
 278   margin-bottom: 0;
 279 }
 280 div.toclevel2 {
 281   margin-left: 2em;
 282   font-size: 0.9em;
 283 }
 284 div.toclevel3 {
 285   margin-left: 4em;
 286   font-size: 0.9em;
 287 }
 288 div.toclevel4 {
 289   margin-left: 6em;
 290   font-size: 0.9em;
 291 }
 292 /* Workarounds for IE6's broken and incomplete CSS2. */
 293
 294 div.sidebar-content {
 295   background: #ffffee;
 296   border: 1px solid silver;
 297   padding: 0.5em;
 298 }
 299 div.sidebar-title, div.image-title {
 300   color: #527bbd;
 301   font-family: sans-serif;
 302   font-weight: bold;
 303   margin-top: 0.0em;
 304   margin-bottom: 0.5em;
 305 }
 306
 307 div.listingblock div.content {
 308   border: 1px solid silver;
 309   background: #f4f4f4;
 310   padding: 0.5em;
 311 }
 312
 313 div.quoteblock-attribution {
 314   padding-top: 0.5em;
 315   text-align: right;
 316 }
 317
 318 div.verseblock-content {
 319   white-space: pre;
 320 }
 321 div.verseblock-attribution {
 322   padding-top: 0.75em;
 323   text-align: left;
 324 }
 325
 326 div.exampleblock-content {
 327   border-left: 2px solid silver;
 328   padding-left: 0.5em;
 329 }
 330
 331 /* IE6 sets dynamically generated links as visited. */
 332 div#toc a:visited { color: blue; }
 333
 334 /* Because IE6 child selector is broken. */
 335 div.olist2 ol {
 336   list-style-type: lower-alpha;
 337 }
 338 div.olist2 div.olist ol {
 339   list-style-type: decimal;
 340 }
 341 </style>
 342 <title>FreeFOAM README for version 1.5.0-1</title>
 343 </head>
 344 <body>
 345 <div id="header">
 346 <h1>FreeFOAM README for version 1.5.0-1</h1>
 347 <span id="author">MichaelWild</span><br />
 348 <span id="email"><tt>&lt;<a href="mailto:themiwi@users.sourceforge.net">themiwi@users.sourceforge.net</a>&gt;</tt></span><br />
 349 <span id="revision">version 1.5.0-0,</span>
 350 7 Nov 2008
 351 </div>
 352 <div id="preamble">
 353 <div class="sectionbody">
 354 <div class="para"><p><a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a></p></div>
 355 </div>
 356 </div>
 357 <h2 id="_copyright">1. Copyright</h2>
 358 <div class="sectionbody">
 359 <div class="para"><p>FreeFOAM is free software; you can redistribute it and/or modify it under the
 360 terms of the GNU General Public License as published by the Free Software
 361 Foundation; either version 2 of the License, or (at your option) any later
 362 version.  See the file COPYING in this directory, for a description of the GNU
 363 General Public License terms under which you can copy the files.</p></div>
 364 </div>
 365 <h2 id="_system_requirements">2. System requirements</h2>
 366 <div class="sectionbody">
 367 <div class="para"><p>FreeFOAM is developed and tested on Linux, but should work with other Unix
 368 style systems. With some additional patching it will also work under
 369 Mac OS X. The support for Microsoft Windows is a goal, which, however, is
 370 still far off.</p></div>
 371 <h3 id="_required_software_to_build_freefoam">2.1. Required software to build FreeFOAM</h3><div style="clear:left"></div>
 372 <div class="vlist"><dl>
 373 <dt>
 374 git
 375 </dt>
 376 <dd>
 377 <p>
 378   Currently you need git to obtain the FreeFOAM source code. <a href="http://git.or.cz">http://git.or.cz</a>
 379 </p>
 380 </dd>
 381 <dt>
 382 CMake
 383 </dt>
 384 <dd>
 385 <p>
 386   In order to build FreeFOAM you need to have CMake with version 2.6.2 or
 387   newer installed. <a href="http://cmake.org">http://cmake.org</a>
 388 </p>
 389 </dd>
 390 <dt>
 391 Build system
 392 </dt>
 393 <dd>
 394 <p>
 395   CMake requires a native build system. On Unix like platforms I recomment
 396   using GNU Make. <a href="http://www.gnu.org/software/make">http://www.gnu.org/software/make</a>
 397 </p>
 398 </dd>
 399 <dt>
 400 C++ compiler
 401 </dt>
 402 <dd>
 403 <p>
 404   In order to build FreeFOAM you need a C++ compiler with good support for
 405   template expressions. The g++ compiler from GCC-4.3 and above will do
 406   fine. <a href="http://gcc.gnu.org">http://gcc.gnu.org</a>
 407 </p>
 408 </dd>
 409 <dt>
 410 flex
 411 </dt>
 412 <dd>
 413 <p>
 414   The flex lexer generator. Version 2.5.33 is known to work. For more recent
 415   versions there have been reports of problems. <a href="http://flex.sourceforge.net">http://flex.sourceforge.net</a>
 416 </p>
 417 </dd>
 418 <dt>
 419 zlib
 420 </dt>
 421 <dd>
 422 <p>
 423   zlib compression library. <a href="http://www.zlib.net">http://www.zlib.net</a>
 424 </p>
 425 </dd>
 426 <dt>
 427 METIS
 428 </dt>
 429 <dd>
 430 <p>
 431   The METIS graph partitioning library, version 5.0pre2. If your package manager
 432   doesn't contain it, you can also have FreeFOAM build it automatically for you
 433   (see the installation section). <a href="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview">http://glaros.dtc.umn.edu/gkhome/metis/metis/overview</a>
 434 </p>
 435 </dd>
 436 <dt>
 437 MGridGen
 438 </dt>
 439 <dd>
 440 <p>
 441   MGridGen grid coarsening library. FreeFOAM can build this automatically for
 442   you (refer to the installation notes below).
 443   <a href="http://glaros.dtc.umn.edu/gkhome/mgridgen/overview">http://glaros.dtc.umn.edu/gkhome/mgridgen/overview</a>
 444 </p>
 445 </dd>
 446 <dt>
 447 libccmio
 448 </dt>
 449 <dd>
 450 <p>
 451   pro-STAR input/output library. FreeFOAM can build this automatically for
 452   you (refer to the installation notes below).
 453   <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>
 454 </p>
 455 </dd>
 456 </dl></div>
 457 <h3 id="_optional_software">2.2. Optional software</h3><div style="clear:left"></div>
 458 <div class="vlist"><dl>
 459 <dt>
 460 Parallel Library
 461 </dt>
 462 <dd>
 463 <p>
 464   In order to run FreeFOAM in parallel, a communications library is required.
 465   The following list gives an overview of the available options.
 466 </p>
 467 <div class="ilist"><ul>
 468 <li>
 469 <p>
 470 MPI (<em>Message Passing Interface</em>): There are many implementations of the MPI
 471     standard. The one that has been tested and is known to work with FreeFOAM
 472     is <a href="http://www.open-mpi.org">OpenMPI</a>.
 473 </p>
 474 </li>
 475 <li>
 476 <p>
 477 PVM (<em>Parallel Virtual Machine</em>) is available from <a href="http://www.csm.ornl.gov/pvm">http://www.csm.ornl.gov/pvm</a>.
 478 </p>
 479 </li>
 480 <li>
 481 <p>
 482 GAMMA (<em>Genoa Active Message MAchine</em>) is available from <a href="http://www.disi.unige.it/project/gamma">http://www.disi.unige.it/project/gamma</a>.
 483 </p>
 484 </li>
 485 </ul></div>
 486 </dd>
 487 <dt>
 488 ParMetis
 489 </dt>
 490 <dd>
 491 <p>
 492   If you use an MPI library, the ParMetis library is required. If your package
 493   manager doesn't contain this library, FreeFOAM can build it automatically for
 494   you (refer to the installation notes below).
 495   <a href="http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview">http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview</a>
 496 </p>
 497 </dd>
 498 <dt>
 499 ParaView
 500 </dt>
 501 <dd>
 502 <p>
 503   If you want to build the <a href="http://paraview.org">ParaView</a> plugins, you need a
 504   ParaView with the development headers <strong>and</strong> the corresponding CMake configuration
 505   files (ParaViewConfig.cmake, ParaViewUse.cmake, ParaViewLibraryDepends*.cmake).
 506   Most likely this means that you have to build ParaView yourself.
 507   <a href="http://paraview.org">http://paraview.org</a>
 508 </p>
 509 </dd>
 510 <dt>
 511 M4
 512 </dt>
 513 <dd>
 514 <p>
 515   Some of the provided tutorial cases require the M4 macro processor.
 516   <a href="http://www.gnu.org/software/m4/">http://www.gnu.org/software/m4/</a>
 517 </p>
 518 </dd>
 519 </dl></div>
 520 </div>
 521 <h2 id="_installation">3. Installation</h2>
 522 <div class="sectionbody">
 523 <div class="para"><p>This section needs serious expanding, but the short version is:</p></div>
 524 <div class="ilist"><ul>
 525 <li>
 526 <p>
 527 Install the prerequisites. If your distribution does not have
 528   METIS, ParMetis, MGridGen or libccmio be not worried, FreeFOAM
 529   can handle those for you.
 530 </p>
 531 </li>
 532 <li>
 533 <p>
 534 Clone the FreeFOAM repository (here the clone is placed in $HOME/Source/FreeFOAM):
 535 </p>
 536 <div class="listingblock">
 537 <div class="content">
 538 <pre><tt>$ mkdir -p $HOME/Source
 539 $ git clone git://repo.or.cz/freefoam.git $HOME/Source/FreeFOAM
 540 $ cd $HOME/Source/FreeFOAM</tt></pre>
 541 </div></div>
 542 </li>
 543 <li>
 544 <p>
 545 Create a build tree and <em>cd</em> into it:
 546 </p>
 547 <div class="listingblock">
 548 <div class="content">
 549 <pre><tt>$ mkdir build
 550 $ cd build</tt></pre>
 551 </div></div>
 552 </li>
 553 <li>
 554 <p>
 555 Start CMake-configuration:
 556 </p>
 557 <div class="listingblock">
 558 <div class="content">
 559 <pre><tt>$ ccmake ..</tt></pre>
 560 </div></div>
 561 </li>
 562 <li>
 563 <p>
 564 Press the <tt>c</tt> key. Use the arrow keys to navigate up and down and press <tt>enter</tt> to
 565   edit a field. To commit the change, press <tt>enter</tt> again, or <tt>ESC</tt> to abandon the change.
 566   ON/OFF fields are toggled by pressing <tt>enter</tt>.
 567 </p>
 568 <div class="ilist"><ul>
 569 <li>
 570 <p>
 571 Set <tt>CMAKE_BUILD_TYPE</tt> to <tt>Release</tt> for an optimized build.
 572 </p>
 573 </li>
 574 <li>
 575 <p>
 576 If CMake complains that it can't find MPI, and you don't want to install it, disable
 577     <tt>FF_USE_MPI</tt>. If, instead, you want to use GAMMA or PVM, enable <tt>FF_USE_GAMMA</tt> or
 578     <tt>FF_USE_PVM</tt>, respectively. You can also enable more than one of the options.
 579 </p>
 580 <div class="admonitionblock">
 581 <table><tr>
 582 <td class="icon">
 583 <div class="title">Note</div>
 584 </td>
 585 <td class="content">Currently only MPI and the dummy implementation are available.</td>
 586 </tr></table>
 587 </div>
 588 </li>
 589 <li>
 590 <p>
 591 Select the default Pstream implementation by setting <tt>FF_DEFAULT_PSTREAM</tt>
 592     by setting it to one of <tt>dummy</tt>, <tt>mpi</tt>, <tt>pvm</tt> or <tt>gamma</tt>. This setting
 593     will only influence the contents of the global controlDict file.
 594 </p>
 595 </li>
 596 <li>
 597 <p>
 598 If CMake told you it couldn't find ParaView:
 599 </p>
 600 <div class="olist"><ol>
 601 <li>
 602 <p>
 603 Set <tt>ParaView_DIR</tt> to the path of the ParaView build directory if you have it.
 604 </p>
 605 </li>
 606 <li>
 607 <p>
 608 If you do not want to build the ParaView plugins, disable <tt>FF_BUILD_PARAVIEW_PLUGINS</tt>
 609 </p>
 610 </li>
 611 </ol></div>
 612 </li>
 613 <li>
 614 <p>
 615 If you do not have METIS, ParMetis, MGridGen or libccmio installed, enable
 616     <tt>FF_BUILD_PRIVATE_METIS</tt>, <tt>FF_BUILD_PRIVATE_PARMETIS</tt>, <tt>FF_BUILD_PRIVATE_PARMGRIDGEN</tt> or
 617     <tt>FF_BUILD_PRIVATE_CCMIO</tt> respectively. CMake will then try to download and build
 618     the selected libraries for you. Conversely, if you one of the libraries is provided
 619     by your system, you can turn the respective setting to <tt>OFF</tt>. Please note that if
 620     you system provides only <tt>ParMetis</tt>, you do not have to install <tt>METIS</tt>, as the
 621     former also contains <tt>METIS</tt>.
 622 </p>
 623 </li>
 624 <li>
 625 <p>
 626 If you plan on installing FreeFOAM, set <tt>CMAKE_INSTALL_PREFIX</tt> to the base directory
 627     under which FreeFOAM should reside.
 628 </p>
 629 </li>
 630 <li>
 631 <p>
 632 For more fine-grained control over what gets installed where, adjust
 633     <tt>FF_INSTALL_CONFIG_PATH</tt>, <tt>FF_INSTALL_HEADER_PATH</tt>, <tt>FF_INSTALL_LIB_PATH</tt>,
 634     <tt>FF_INSTALL_FRAMEWORK_PATH</tt>, <tt>FF_INSTALL_PV3FOAMREADER_PATH</tt>,
 635     <tt>FF_INSTALL_PVFOAMREADER_PATH</tt> and <tt>FF_INSTALL_USERDFOAM_PATH</tt>.
 636 </p>
 637 </li>
 638 <li>
 639 <p>
 640 If you want FreeFOAM to use <tt>float</tt> as the floating point type instead of
 641     <tt>double</tt>, change <tt>FF_DOUBLE_PRECISION</tt> to <tt>OFF</tt>.
 642 </p>
 643 </li>
 644 </ul></div>
 645 </li>
 646 <li>
 647 <p>
 648 Hit the <tt>c</tt> key again. If you enabled <tt>FF_BUILD_PRIVATE_CCMIO</tt>, CMake will fail
 649   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>.
 650   Please follow the instructions in the error message on how to work around this
 651   problem, or download the file manually and place it in <tt>ThirdParty/ccmio/</tt>
 652   (relative to the build directory). Then hit <tt>c</tt> again.
 653 </p>
 654 </li>
 655 <li>
 656 <p>
 657 You shouldn't get any errors anymore now. Keep pressing <tt>c</tt> until
 658   the ccmake displays "<tt>Press [g] to generate and exit</tt>" in the legend at
 659   the bottom of the interface.
 660 </p>
 661 </li>
 662 <li>
 663 <p>
 664 Press <tt>g</tt> to generate the Makefiles and exit the ccmake interface.
 665 </p>
 666 </li>
 667 <li>
 668 <p>
 669 Start the native build tool. If you used the <tt>Makefile</tt> generator
 670   (which is the default for Unix-platforms), type
 671 </p>
 672 <div class="listingblock">
 673 <div class="content">
 674 <pre><tt>$ make</tt></pre>
 675 </div></div>
 676 </li>
 677 <li>
 678 <p>
 679 If you have a multi-core/processor machine, you can speed things up
 680   significantly by telling Make to run independent jobs in parallel.
 681   A good choice for the number of parallel jobs to run is the
 682   number of CPU's/cores you have in your machine plus 1 (to compensate
 683   for disk-latency). For a typical dual-core machine, run
 684 </p>
 685 <div class="listingblock">
 686 <div class="content">
 687 <pre><tt>$ make -j3</tt></pre>
 688 </div></div>
 689 </li>
 690 <li>
 691 <p>
 692 If you want to, you can now install FreeFOAM (depending on the
 693   <tt>CMAKE_INSTALL_PREFIX</tt> and the individual <tt>FF_INSTALL_*_PATH</tt>
 694   it is possible that you have to do this as root, i.e. use
 695   <tt>su</tt> or <tt>sudo</tt>). However, this is optional and hasn't been
 696   tested thoroughly, so you might overwrite some important files
 697   of your system!
 698 </p>
 699 <div class="listingblock">
 700 <div class="content">
 701 <pre><tt>$ make install</tt></pre>
 702 </div></div>
 703 </li>
 704 </ul></div>
 705 <h3 id="_using_freefoam">3.1. Using FreeFOAM</h3><div style="clear:left"></div>
 706 <div class="ilist"><ul>
 707 <li>
 708 <p>
 709 Make sure that your shell can find the FreeFOAM executables. If you want
 710   to run FreeFOAM from the build tree (i.e. without installing), append
 711   <tt>&lt;build_dir&gt;/bin</tt> to your <tt>PATH</tt> variable:
 712 </p>
 713 <div class="listingblock">
 714 <div class="content">
 715 <pre><tt>$ export PATH=$PATH:$HOME/Source/FreeFOAM/build/bin</tt></pre>
 716 </div></div>
 717 <div class="para"><p>This assumes that your build directory is <tt>$HOME/Source/FreeFOAM/build</tt>,
 718 which should be the case if you followed above instructions. If it isn't,
 719 you will have to adjust above command appropriately.</p></div>
 720 </li>
 721 <li>
 722 <p>
 723 On some systems it might be necessary to adjust the library search
 724   path (although CMake should have taken care of this by using <tt>RPATH</tt>
 725   on Linux and <tt>install_name</tt> on Mac OS X):
 726 </p>
 727 <div class="listingblock">
 728 <div class="content">
 729 <pre><tt>$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/Source/FreeFOAM/build/lib/FreeFOAM-1.5.0</tt></pre>
 730 </div></div>
 731 <div class="para"><p>Again, this is assuming that your build tree is in <tt>$HOME/Source/FreeFOAM/build</tt>.</p></div>
 732 </li>
 733 <li>
 734 <p>
 735 Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
 736   applications require some files to be present for start-up. It finds those
 737   in the following places (in the specified order, picking the first hit):
 738 </p>
 739 <div class="olist"><ol>
 740 <li>
 741 <p>
 742 Under the directory specified in the <em>$FREEFOAM_CONFIG_DIR</em> environment variable
 743 </p>
 744 </li>
 745 <li>
 746 <p>
 747 In <em>$HOME/.FreeFOAM/1.5.0-0</em>
 748 </p>
 749 </li>
 750 <li>
 751 <p>
 752 In <em>$HOME/.FreeFOAM</em>
 753 </p>
 754 </li>
 755 <li>
 756 <p>
 757 In <em>&lt;prefix&gt;/&lt;FF_INSTALL_CONFIG_PATH&gt;</em>, where <em>&lt;prefix&gt;</em> is the
 758      installation prefix and <em>&lt;FF_INSTALL_CONFIG_PATH&gt;</em> is the value you
 759      specified for the <em>FF_INSTALL_CONFIG_PATH</em> property when configuring
 760      FreeFOAM using ccmake. The former defaults to <em>/usr/local</em>, the latter
 761      to <em>etc/FreeFOAM-1.5.0</em>.
 762 </p>
 763 </li>
 764 </ol></div>
 765 <div class="para"><p>So, if you want to run FreeFOAM from the build tree (i.e. without running
 766 <tt>make install</tt>), you have the option to place the files under your home directory
 767 or set an environment variable. The former can be achieved by:</p></div>
 768 <div class="listingblock">
 769 <div class="content">
 770 <pre><tt>$ mkdir -p $HOME/.FreeFOAM/1.5.0-0
 771 $ cp $HOME/Source/FreeFOAM/etc/controlDict $HOME/.FreeFOAM/1.5.0-0
 772 $ cp $HOME/Source/FreeFOAM/etc/cellModels $HOME/.FreeFOAM/1.5.0-0
 773 $ cp -r $HOME/Source/FreeFOAM/etc/thermoData $HOME/.FreeFOAM/1.5.0-0</tt></pre>
 774 </div></div>
 775 <div class="para"><p>Or, if you prefer setting the environment variable:</p></div>
 776 <div class="listingblock">
 777 <div class="content">
 778 <pre><tt>$ export FREEFOAM_CONFIG_DIR=$HOME/Source/FreeFOAM/etc</tt></pre>
 779 </div></div>
 780 <div class="para"><p>Notice that this time <em>$HOME/Source/FreeFOAM</em> refers to the
 781 root of the source tree, i.e. where your clone of the FreeFOAM
 782 repository is. Adjust it to your actual setup.</p></div>
 783 </li>
 784 <li>
 785 <p>
 786 Both, FreeFOAM and OpenFOAM abstract the parallel operations into
 787 the <tt>Pstream</tt> library, making it firstly rather simple to switch between
 788 parallel implementations and secondly to port the software to a new
 789 communications library. However, FreeFOAM uses a much more flexible
 790 mechanism of determining which <tt>Pstream</tt> implementation library to
 791 load than OpenFOAM. The latter did this by adjusting the <tt>LD_LIBRARY_PATH</tt>.
 792 As FreeFOAM wants to be a well behaved Linux citizen, this is not an
 793 option. Instead, FreeFOAM dynamically loads the desired <tt>Pstream</tt>
 794 library at startup. The following list details how FreeFOAM determines
 795 what library to load (if at all):
 796 </p>
 797 <div class="olist"><ol>
 798 <li>
 799 <p>
 800 If the environment variable <tt>FREEFOAM_PSTREAM_LIBRARY</tt> is set,
 801      FreeFOAM will try to load the library specified in the value of
 802      the variable.
 803 </p>
 804 </li>
 805 <li>
 806 <p>
 807 If the sub-dictionary <tt>PstreamImplementation</tt> exists in the global
 808      <tt>controlDict</tt> file (see above), it reads the value of the entry
 809      <tt>configName</tt> therein. It then expects that a sub-dictionary of
 810      <tt>PstreamImplementation</tt> with the name specified in <tt>configName</tt>
 811      exists. If that sub-dictionary contains the entry <tt>library</tt>,
 812      it will try to load a library spedified by the value of that
 813      entry.
 814 </p>
 815 </li>
 816 </ol></div>
 817 <div class="para"><p>After FreeFOAM (possibly) loaded the library, it will try to instantiate
 818 concrete implementations of the abstract base classes <tt>PstreamImpl</tt>,
 819 <tt>IPstreamImpl</tt> and <tt>OPstreamImpl</tt>. Which classes are to be instantiated
 820 is determined as follows:</p></div>
 821 <div class="olist"><ol>
 822 <li>
 823 <p>
 824 FreeFOAM queries the environment variables <tt>FREEFOAM_PSTREAM_CLASS</tt>,
 825      <tt>FREEFOAM_IPSTREAM_CLASS</tt> and <tt>FREEFOAM_OPSTREAM_CLASS</tt> for the class
 826      names to be instantiated.
 827 </p>
 828 </li>
 829 <li>
 830 <p>
 831 Otherwise it requires the sub-dictionary <tt>PstreamImplementation</tt>
 832      to be present in the global <tt>controlDict</tt>, reads the value of
 833      <tt>configName</tt> and similarly to the library loading,
 834      loads the sub-dictionary specified by that value. It then expects
 835      to find the entries <tt>Pstream</tt>, <tt>IPstream</tt> and <tt>OPstream</tt> which
 836      specify the names of the classes to load.
 837 </p>
 838 </li>
 839 </ol></div>
 840 <div class="para"><p>This means that you can create a global <tt>controlDict</tt> file containing
 841 (among other things) something like the following:</p></div>
 842 <div class="literalblock">
 843 <div class="content">
 844 <pre><tt>PstreamImplementation
 845 {
 846     //configName dummy;
 847     configName mpi;</tt></pre>
 848 </div></div>
 849 <div class="literalblock">
 850 <div class="content">
 851 <pre><tt>dummy
 852 {
 853     library libdummyPstream.so;
 854     Pstream dummyPstreamImpl;
 855     OPstream dummyOPstreamImpl;
 856     IPstream dummyIPstreamImpl;
 857 }</tt></pre>
 858 </div></div>
 859 <div class="literalblock">
 860 <div class="content">
 861 <pre><tt>    mpi
 862     {
 863         library libmpiPstream.so;
 864         Pstream mpiPstreamImpl;
 865         OPstream mpiOPstreamImpl;
 866         IPstream mpiIPstreamImpl;
 867     }
 868 }</tt></pre>
 869 </div></div>
 870 <div class="para"><p>This way the administrator can provide a glocal <tt>controlDict</tt> in
 871 the FreeFOAM installation. Every user can then override that <tt>controlDict</tt>
 872 by supplying her own file in her home directory as detailed
 873 above. In order to select a particular <tt>Pstream</tt> implementation for
 874 a specific communications library, the user can then either adjust
 875 the <tt>PstreamImplementation::configName</tt> entry in the global
 876 <tt>controlDict</tt> file, set the <tt>FREEFOAM_PSTREAM_CONFIG</tt> variable
 877 or for full control, set the variables <tt>FREEFOAM_PSTREAM_LIBRARY</tt>,
 878 <tt>FREEFOAM_PSTREAM_CLASS</tt>, <tt>FREEFOAM_IPSTREAM_CLASS</tt> and
 879 <tt>FREEFOAM_OPSTREAM_CLASS</tt>.</p></div>
 880 </li>
 881 <li>
 882 <p>
 883 Now you should be able to run the tutorial cases. For this copy the
 884   <tt>tutorials</tt> directory to some convenient place:
 885 </p>
 886 <div class="listingblock">
 887 <div class="content">
 888 <pre><tt>$ mkdir -p $HOME/FreeFOAM/$LOGNAME-1.5.0/run
 889 $ cp -r $HOME/Source/FreeFOAM/tutorials $HOME/FreeFOAM/$LOGNAME-1.5.0/run/
 890 $ cd $HOME/FreeFOAM/$LOGNAME-1.5.0/run</tt></pre>
 891 </div></div>
 892 <div class="para"><p>And try to run e.g. the <em>cavity</em> tutorial case:</p></div>
 893 <div class="listingblock">
 894 <div class="content">
 895 <pre><tt>$ cd icoFoam
 896 $ blockMesh -case cavity
 897 $ checkMesh -case cavity
 898 $ icoFoam -case cavity</tt></pre>
 899 </div></div>
 900 <div class="para"><p>Things should run smoothly and finish without an error.</p></div>
 901 </li>
 902 </ul></div>
 903 <div class="admonitionblock">
 904 <table><tr>
 905 <td class="icon">
 906 <div class="title">Warning</div>
 907 </td>
 908 <td class="content">Currently the utility <tt>paraFoam</tt> does not work, as it hasn't been
 909 adapted to FreeFOAM. You have to make sure that ParaView finds the
 910 plugins (by e.g. setting the <tt>PV_PLUGIN_PATH</tt> environment variable to
 911 the directory containing libPV3FoamReader.so) yourself. Then create an empty
 912 file called <tt>&lt;something&gt;.OpenFOAM</tt> (where <tt>&lt;something&gt;</tt> is a name of
 913 your choice) <strong>in</strong> the case directory and then start ParaView using
 914 <tt>paraview&#160;--data=&lt;casedirectory&gt;/&lt;something&gt;.OpenFOAM</tt>.
 915 Alternatively you can also start ParaView without any of the command
 916 line arguments and then open the <em>&lt;something&gt;.OpenFOAM</em> file from within ParaView.</td>
 917 </tr></table>
 918 </div>
 919 <h3 id="_configuration_reference">3.2. Configuration reference</h3><div style="clear:left"></div>
 920 <div class="vlist"><dl>
 921 <dt>
 922 <tt>CMAKE_BUILD_TYPE</tt>
 923 </dt>
 924 <dd>
 925 <p>
 926   One of <tt>&lt;empty&gt;</tt>, <tt>Debug</tt>, <tt>Release</tt>, <tt>RelWithDebInfo</tt> and <tt>MinSizeRel</tt>.
 927 </p>
 928 </dd>
 929 <dt>
 930 <tt>CMAKE_INSTALL_PREFIX</tt>
 931 </dt>
 932 <dd>
 933 <p>
 934   Installation prefix
 935 </p>
 936 </dd>
 937 <dt>
 938 <tt>FF_DOUBLE_PRECISION</tt>
 939 </dt>
 940 <dd>
 941 <p>
 942   If set to <tt>ON</tt> FreeFOAM will be compiled using <tt>double</tt> as the
 943   floating point type. If set to <tt>OFF</tt> it will use <tt>float</tt>.
 944 </p>
 945 </dd>
 946 <dt>
 947 <tt>FF_INSTALL_BIN_PATH</tt>
 948 </dt>
 949 <dd>
 950 <p>
 951   Installation path of the binaries. If not absolute, it is relative to
 952   <tt>CMAKE_INSTALL_PREFIX</tt>.
 953 </p>
 954 </dd>
 955 <dt>
 956 <tt>FF_INSTALL_CONFIG_PATH</tt>
 957 </dt>
 958 <dd>
 959 <p>
 960   Installation path of the configuration files. If not absolute, it is
 961   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
 962 </p>
 963 </dd>
 964 <dt>
 965 <tt>FF_BUILD_FRAMEWORK</tt>
 966 </dt>
 967 <dd>
 968 <p>
 969   If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
 970 </p>
 971 </dd>
 972 <dt>
 973 <tt>FF_INSTALL_HEADER_PATH</tt>
 974 </dt>
 975 <dd>
 976 <p>
 977   Installation path of the header files. If not absolute, it is
 978   relative to <tt>CMAKE_INSTALL_PREFIX</tt>. On Mac OS X, and if
 979   <tt>FF_BUILD_FRAMEWORK</tt> is enabled, this setting is ignored.
 980 </p>
 981 </dd>
 982 <dt>
 983 <tt>FF_INSTALL_LIB_PATH</tt>
 984 </dt>
 985 <dd>
 986 <p>
 987   Installation path of the libraries. If not absolute, it is
 988   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
 989 </p>
 990 </dd>
 991 <dt>
 992 <tt>FF_INSTALL_FRAMEWORK_PATH</tt>
 993 </dt>
 994 <dd>
 995 <p>
 996   Installation path of the Mac OS X frameworks. If not absolute, it is
 997   relative to <tt>CMAKE_INSTALL_PREFIX</tt>. This is only available and takes
 998   effect if FreeFOAM is compiled on Mac OS X, and if
 999   <tt>FF_BUILD_FRAMEWORK</tt> is enabled.
1000 </p>
1001 </dd>
1002 <dt>
1003 <tt>FF_INSTALL_PV3FOAMREADER_PATH</tt>
1004 </dt>
1005 <dd>
1006 <p>
1007   Installation path of the ParaView3 plugins. If not absolute, it is
1008   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
1009 </p>
1010 </dd>
1011 <dt>
1012 <tt>FF_INSTALL_PVFOAMREADER_PATH</tt>
1013 </dt>
1014 <dd>
1015 <p>
1016   Installation path of the ParaView2 plugins. If not absolute, it is
1017   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
1018 </p>
1019 </dd>
1020 <dt>
1021 <tt>FF_INSTALL_USERDFOAM_PATH</tt>
1022 </dt>
1023 <dd>
1024 <p>
1025   Installation path of the Ensight plugin. If not absolute, it is
1026   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
1027 </p>
1028 </dd>
1029 <dt>
1030 <tt>FF_USE_GAMMA</tt>
1031 </dt>
1032 <dd>
1033 <p>
1034   If enabled, FreeFOAM will use the GAMMA parallel communications library.
1035 </p>
1036 </dd>
1037 <dt>
1038 <tt>FF_USE_MPI</tt>
1039 </dt>
1040 <dd>
1041 <p>
1042   If enabled, FreeFOAM will use the MPI parallel communications library.
1043   This is required in order to build some of the libraries and utilities.
1044 </p>
1045 </dd>
1046 <dt>
1047 <tt>FF_USE_PVM</tt>
1048 </dt>
1049 <dd>
1050 <p>
1051   If enabled, FreeFOAM will use the PVM parallel communications library.
1052 </p>
1053 </dd>
1054 <dt>
1055 <tt>FF_DEFAULT_PSTREAM</tt>
1056 </dt>
1057 <dd>
1058 <p>
1059   The default Pstream selection in the global controlDict file.
1060 </p>
1061 </dd>
1062 <dt>
1063 <tt>FF_BUILD_PARAVIEW_PLUGINS</tt>
1064 </dt>
1065 <dd>
1066 <p>
1067   Whether to build the ParaView plugins. If enabled, FreeFOAM requires a
1068   ParaView build tree and the <tt>ParaView_DIR</tt> variable set to the path of it.
1069 </p>
1070 </dd>
1071 <dt>
1072 <tt>FF_BUILD_PRIVATE_CCMIO</tt>
1073 </dt>
1074 <dd>
1075 <p>
1076   Automatically download and build libccmio. Unfortunately this process will
1077   fail in the download step, since CMake currently does not support <tt>https</tt>
1078   URLs. But you will get specific instructions from the build system on how to
1079   get around this problem.
1080 </p>
1081 </dd>
1082 <dt>
1083 <tt>FF_BUILD_PRIVATE_METIS</tt>
1084 </dt>
1085 <dd>
1086 <p>
1087   Automatically download and build METIS.
1088 </p>
1089 </dd>
1090 <dt>
1091 <tt>FF_BUILD_PRIVATE_PARMETIS</tt>
1092 </dt>
1093 <dd>
1094 <p>
1095   Automatically download and build ParMetis.
1096 </p>
1097 </dd>
1098 <dt>
1099 <tt>FF_BUILD_PRIVATE_PARMGRIDGEN</tt>
1100 </dt>
1101 <dd>
1102 <p>
1103   Automaticall download and build ParMGridGen/MGridgen.
1104 </p>
1105 </dd>
1106 <dt>
1107 <tt>FF_BUILD_DOXYGEN_DOCS</tt>
1108 </dt>
1109 <dd>
1110 <p>
1111   Enable building of the Doxygen API documentation. To actually build it,
1112   execute <tt>make doc</tt>.
1113 </p>
1114 </dd>
1115 </dl></div>
1116 </div>
1117 <h2 id="_documentation">4. Documentation</h2>
1118 <div class="sectionbody">
1119 <div class="para"><p><a href="http://www.OpenFOAM.org/doc">http://www.OpenFOAM.org/doc</a></p></div>
1120 </div>
1121 <h2 id="_help">5. Help</h2>
1122 <div class="sectionbody">
1123 <div class="ilist"><ul>
1124 <li>
1125 <p>
1126 <a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a>
1127 </p>
1128 </li>
1129 <li>
1130 <p>
1131 <a href="https://lists.sourceforge.net/lists/listinfo/freefoam-user">https://lists.sourceforge.net/lists/listinfo/freefoam-user</a>
1132 </p>
1133 </li>
1134 <li>
1135 <p>
1136 <a href="http://www.OpenFOAM.org/discussion.html">http://www.OpenFOAM.org/discussion.html</a> <strong>please only ask questions related
1137   to <em>OpenFOAM</em> there</strong>.
1138 </p>
1139 </li>
1140 </ul></div>
1141 </div>
1142 <h2 id="_reporting_bugs_in_freefoam">6. Reporting Bugs in FreeFOAM</h2>
1143 <div class="sectionbody">
1144 <div class="para"><p><a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a></p></div>
1145 </div>
1146 <div id="footer">
1147 <div id="footer-text">
1148 Version 1.5.0-0<br />
1149 Last updated 2009-02-23 20:32:02 CEST
1150 </div>
1151 </div>
1152 </body>
1153 </html>