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_PV3FOAMREADER_PATH</tt>, <tt>FF_INSTALL_PVFOAMREADER_PATH</tt> and <tt>FF_INSTALL_USERDFOAM_PATH</tt>.
 635 </p>
 636 </li>
 637 <li>
 638 <p>
 639 If you want FreeFOAM to use <tt>float</tt> as the floating point type instead of
 640     <tt>double</tt>, change <tt>FF_DOUBLE_PRECISION</tt> to <tt>OFF</tt>.
 641 </p>
 642 </li>
 643 </ul></div>
 644 </li>
 645 <li>
 646 <p>
 647 Hit the <tt>c</tt> key again. If you enabled <tt>FF_BUILD_PRIVATE_CCMIO</tt>, CMake will fail
 648   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>.
 649   Please follow the instructions in the error message on how to work around this
 650   problem, or download the file manually and place it in <tt>ThirdParty/ccmio/</tt>
 651   (relative to the build directory). Then hit <tt>c</tt> again.
 652 </p>
 653 </li>
 654 <li>
 655 <p>
 656 You shouldn't get any errors anymore now. Keep pressing <tt>c</tt> until
 657   the ccmake displays "<tt>Press [g] to generate and exit</tt>" in the legend at
 658   the bottom of the interface.
 659 </p>
 660 </li>
 661 <li>
 662 <p>
 663 Press <tt>g</tt> to generate the Makefiles and exit the ccmake interface.
 664 </p>
 665 </li>
 666 <li>
 667 <p>
 668 Start the native build tool. If you used the <tt>Makefile</tt> generator
 669   (which is the default for Unix-platforms), type
 670 </p>
 671 <div class="listingblock">
 672 <div class="content">
 673 <pre><tt>$ make</tt></pre>
 674 </div></div>
 675 </li>
 676 <li>
 677 <p>
 678 If you have a multi-core/processor machine, you can speed things up
 679   significantly by telling Make to run independent jobs in parallel.
 680   A good choice for the number of parallel jobs to run is the
 681   number of CPU's/cores you have in your machine plus 1 (to compensate
 682   for disk-latency). For a typical dual-core machine, run
 683 </p>
 684 <div class="listingblock">
 685 <div class="content">
 686 <pre><tt>$ make -j3</tt></pre>
 687 </div></div>
 688 </li>
 689 <li>
 690 <p>
 691 If you want to, you can now install FreeFOAM (depending on the
 692   <tt>CMAKE_INSTALL_PREFIX</tt> and the individual <tt>FF_INSTALL_*_PATH</tt>
 693   it is possible that you have to do this as root, i.e. use
 694   <tt>su</tt> or <tt>sudo</tt>). However, this is optional and hasn't been
 695   tested thoroughly, so you might overwrite some important files
 696   of your system!
 697 </p>
 698 <div class="listingblock">
 699 <div class="content">
 700 <pre><tt>$ make install</tt></pre>
 701 </div></div>
 702 </li>
 703 </ul></div>
 704 <h3 id="_using_freefoam">3.1. Using FreeFOAM</h3><div style="clear:left"></div>
 705 <div class="ilist"><ul>
 706 <li>
 707 <p>
 708 Make sure that your shell can find the FreeFOAM executables. If you want
 709   to run FreeFOAM from the build tree (i.e. without installing), append
 710   <tt>&lt;build_dir&gt;/bin</tt> to your <tt>PATH</tt> variable:
 711 </p>
 712 <div class="listingblock">
 713 <div class="content">
 714 <pre><tt>$ export PATH=$PATH:$HOME/Source/FreeFOAM/build/bin</tt></pre>
 715 </div></div>
 716 <div class="para"><p>This assumes that your build directory is <tt>$HOME/Source/FreeFOAM/build</tt>,
 717 which should be the case if you followed above instructions. If it isn't,
 718 you will have to adjust above command appropriately.</p></div>
 719 </li>
 720 <li>
 721 <p>
 722 On some systems it might be necessary to adjust the library search
 723   path (although CMake should have taken care of this by using <tt>RPATH</tt>
 724   on Linux and <tt>install_name</tt> on Mac OS X):
 725 </p>
 726 <div class="listingblock">
 727 <div class="content">
 728 <pre><tt>$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/Source/FreeFOAM/build/lib/FreeFOAM-1.5.0</tt></pre>
 729 </div></div>
 730 <div class="para"><p>Again, this is assuming that your build tree is in <tt>$HOME/Source/FreeFOAM/build</tt>.</p></div>
 731 </li>
 732 <li>
 733 <p>
 734 Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some
 735   applications require some files to be present for start-up. It finds those
 736   in the following places (in the specified order, picking the first hit):
 737 </p>
 738 <div class="olist"><ol>
 739 <li>
 740 <p>
 741 Under the directory specified in the <em>$FREEFOAM_CONFIG_DIR</em> environment variable
 742 </p>
 743 </li>
 744 <li>
 745 <p>
 746 In <em>$HOME/.FreeFOAM/1.5.0-0</em>
 747 </p>
 748 </li>
 749 <li>
 750 <p>
 751 In <em>$HOME/.FreeFOAM</em>
 752 </p>
 753 </li>
 754 <li>
 755 <p>
 756 In <em>&lt;prefix&gt;/&lt;FF_INSTALL_CONFIG_PATH&gt;</em>, where <em>&lt;prefix&gt;</em> is the
 757      installation prefix and <em>&lt;FF_INSTALL_CONFIG_PATH&gt;</em> is the value you
 758      specified for the <em>FF_INSTALL_CONFIG_PATH</em> property when configuring
 759      FreeFOAM using ccmake. The former defaults to <em>/usr/local</em>, the latter
 760      to <em>etc/FreeFOAM-1.5.0</em>.
 761 </p>
 762 </li>
 763 </ol></div>
 764 <div class="para"><p>So, if you want to run FreeFOAM from the build tree (i.e. without running
 765 <tt>make install</tt>), you have the option to place the files under your home directory
 766 or set an environment variable. The former can be achieved by:</p></div>
 767 <div class="listingblock">
 768 <div class="content">
 769 <pre><tt>$ mkdir -p $HOME/.FreeFOAM/1.5.0-0
 770 $ cp $HOME/Source/FreeFOAM/etc/controlDict $HOME/.FreeFOAM/1.5.0-0
 771 $ cp $HOME/Source/FreeFOAM/etc/cellModels $HOME/.FreeFOAM/1.5.0-0
 772 $ cp -r $HOME/Source/FreeFOAM/etc/thermoData $HOME/.FreeFOAM/1.5.0-0</tt></pre>
 773 </div></div>
 774 <div class="para"><p>Or, if you prefer setting the environment variable:</p></div>
 775 <div class="listingblock">
 776 <div class="content">
 777 <pre><tt>$ export FREEFOAM_CONFIG_DIR=$HOME/Source/FreeFOAM/etc</tt></pre>
 778 </div></div>
 779 <div class="para"><p>Notice that this time <em>$HOME/Source/FreeFOAM</em> refers to the
 780 root of the source tree, i.e. where your clone of the FreeFOAM
 781 repository is. Adjust it to your actual setup.</p></div>
 782 </li>
 783 <li>
 784 <p>
 785 Both, FreeFOAM and OpenFOAM abstract the parallel operations into
 786 the <tt>Pstream</tt> library, making it firstly rather simple to switch between
 787 parallel implementations and secondly to port the software to a new
 788 communications library. However, FreeFOAM uses a much more flexible
 789 mechanism of determining which <tt>Pstream</tt> implementation library to
 790 load than OpenFOAM. The latter did this by adjusting the <tt>LD_LIBRARY_PATH</tt>.
 791 As FreeFOAM wants to be a well behaved Linux citizen, this is not an
 792 option. Instead, FreeFOAM dynamically loads the desired <tt>Pstream</tt>
 793 library at startup. The following list details how FreeFOAM determines
 794 what library to load (if at all):
 795 </p>
 796 <div class="olist"><ol>
 797 <li>
 798 <p>
 799 If the environment variable <tt>FREEFOAM_PSTREAM_LIBRARY</tt> is set,
 800      FreeFOAM will try to load the library specified in the value of
 801      the variable.
 802 </p>
 803 </li>
 804 <li>
 805 <p>
 806 If the sub-dictionary <tt>PstreamImplementation</tt> exists in the global
 807      <tt>controlDict</tt> file (see above), it reads the value of the entry
 808      <tt>configName</tt> therein. It then expects that a sub-dictionary of
 809      <tt>PstreamImplementation</tt> with the name specified in <tt>configName</tt>
 810      exists. If that sub-dictionary contains the entry <tt>library</tt>,
 811      it will try to load a library spedified by the value of that
 812      entry.
 813 </p>
 814 </li>
 815 </ol></div>
 816 <div class="para"><p>After FreeFOAM (possibly) loaded the library, it will try to instantiate
 817 concrete implementations of the abstract base classes <tt>PstreamImpl</tt>,
 818 <tt>IPstreamImpl</tt> and <tt>OPstreamImpl</tt>. Which classes are to be instantiated
 819 is determined as follows:</p></div>
 820 <div class="olist"><ol>
 821 <li>
 822 <p>
 823 FreeFOAM queries the environment variables <tt>FREEFOAM_PSTREAM_CLASS</tt>,
 824      <tt>FREEFOAM_IPSTREAM_CLASS</tt> and <tt>FREEFOAM_OPSTREAM_CLASS</tt> for the class
 825      names to be instantiated.
 826 </p>
 827 </li>
 828 <li>
 829 <p>
 830 Otherwise it requires the sub-dictionary <tt>PstreamImplementation</tt>
 831      to be present in the global <tt>controlDict</tt>, reads the value of
 832      <tt>configName</tt> and similarly to the library loading,
 833      loads the sub-dictionary specified by that value. It then expects
 834      to find the entries <tt>Pstream</tt>, <tt>IPstream</tt> and <tt>OPstream</tt> which
 835      specify the names of the classes to load.
 836 </p>
 837 </li>
 838 </ol></div>
 839 <div class="para"><p>This means that you can create a global <tt>controlDict</tt> file containing
 840 (among other things) something like the following:</p></div>
 841 <div class="literalblock">
 842 <div class="content">
 843 <pre><tt>PstreamImplementation
 844 {
 845     //configName dummy;
 846     configName mpi;</tt></pre>
 847 </div></div>
 848 <div class="literalblock">
 849 <div class="content">
 850 <pre><tt>dummy
 851 {
 852     library libdummyPstream.so;
 853     Pstream dummyPstreamImpl;
 854     OPstream dummyOPstreamImpl;
 855     IPstream dummyIPstreamImpl;
 856 }</tt></pre>
 857 </div></div>
 858 <div class="literalblock">
 859 <div class="content">
 860 <pre><tt>    mpi
 861     {
 862         library libmpiPstream.so;
 863         Pstream mpiPstreamImpl;
 864         OPstream mpiOPstreamImpl;
 865         IPstream mpiIPstreamImpl;
 866     }
 867 }</tt></pre>
 868 </div></div>
 869 <div class="para"><p>This way the administrator can provide a glocal <tt>controlDict</tt> in
 870 the FreeFOAM installation. Every user can then override that <tt>controlDict</tt>
 871 by supplying her own file in her home directory as detailed
 872 above. In order to select a particular <tt>Pstream</tt> implementation for
 873 a specific communications library, the user can then either adjust
 874 the <tt>PstreamImplementation::configName</tt> entry in the global
 875 <tt>controlDict</tt> file, set the <tt>FREEFOAM_PSTREAM_CONFIG</tt> variable
 876 or for full control, set the variables <tt>FREEFOAM_PSTREAM_LIBRARY</tt>,
 877 <tt>FREEFOAM_PSTREAM_CLASS</tt>, <tt>FREEFOAM_IPSTREAM_CLASS</tt> and
 878 <tt>FREEFOAM_OPSTREAM_CLASS</tt>.</p></div>
 879 </li>
 880 <li>
 881 <p>
 882 Now you should be able to run the tutorial cases. For this copy the
 883   <tt>tutorials</tt> directory to some convenient place:
 884 </p>
 885 <div class="listingblock">
 886 <div class="content">
 887 <pre><tt>$ mkdir -p $HOME/FreeFOAM/$LOGNAME-1.5.0/run
 888 $ cp -r $HOME/Source/FreeFOAM/tutorials $HOME/FreeFOAM/$LOGNAME-1.5.0/run/
 889 $ cd $HOME/FreeFOAM/$LOGNAME-1.5.0/run</tt></pre>
 890 </div></div>
 891 <div class="para"><p>And try to run e.g. the <em>cavity</em> tutorial case:</p></div>
 892 <div class="listingblock">
 893 <div class="content">
 894 <pre><tt>$ cd icoFoam
 895 $ blockMesh -case cavity
 896 $ checkMesh -case cavity
 897 $ icoFoam -case cavity</tt></pre>
 898 </div></div>
 899 <div class="para"><p>Things should run smoothly and finish without an error.</p></div>
 900 </li>
 901 </ul></div>
 902 <div class="admonitionblock">
 903 <table><tr>
 904 <td class="icon">
 905 <div class="title">Warning</div>
 906 </td>
 907 <td class="content">Currently the utility <tt>paraFoam</tt> does not work, as it hasn't been
 908 adapted to FreeFOAM. You have to make sure that ParaView finds the
 909 plugins (by e.g. setting the <tt>PV_PLUGIN_PATH</tt> environment variable to
 910 the directory containing libPV3FoamReader.so) yourself. Then create an empty
 911 file called <tt>&lt;something&gt;.OpenFOAM</tt> (where <tt>&lt;something&gt;</tt> is a name of
 912 your choice) <strong>in</strong> the case directory and then start ParaView using
 913 <tt>paraview&#160;--data=&lt;casedirectory&gt;/&lt;something&gt;.OpenFOAM</tt>.
 914 Alternatively you can also start ParaView without any of the command
 915 line arguments and then open the <em>&lt;something&gt;.OpenFOAM</em> file from within ParaView.</td>
 916 </tr></table>
 917 </div>
 918 <h3 id="_configuration_reference">3.2. Configuration reference</h3><div style="clear:left"></div>
 919 <div class="vlist"><dl>
 920 <dt>
 921 <tt>CMAKE_BUILD_TYPE</tt>
 922 </dt>
 923 <dd>
 924 <p>
 925   One of <tt>&lt;empty&gt;</tt>, <tt>Debug</tt>, <tt>Release</tt>, <tt>RelWithDebInfo</tt> and <tt>MinSizeRel</tt>.
 926 </p>
 927 </dd>
 928 <dt>
 929 <tt>CMAKE_INSTALL_PREFIX</tt>
 930 </dt>
 931 <dd>
 932 <p>
 933   Installation prefix
 934 </p>
 935 </dd>
 936 <dt>
 937 <tt>FF_DOUBLE_PRECISION</tt>
 938 </dt>
 939 <dd>
 940 <p>
 941   If set to <tt>ON</tt> FreeFOAM will be compiled using <tt>double</tt> as the
 942   floating point type. If set to <tt>OFF</tt> it will use <tt>float</tt>.
 943 </p>
 944 </dd>
 945 <dt>
 946 <tt>FF_INSTALL_BIN_PATH</tt>
 947 </dt>
 948 <dd>
 949 <p>
 950   Installation path of the binaries. If not absolute, it is relative to
 951   <tt>CMAKE_INSTALL_PREFIX</tt>.
 952 </p>
 953 </dd>
 954 <dt>
 955 <tt>FF_INSTALL_CONFIG_PATH</tt>
 956 </dt>
 957 <dd>
 958 <p>
 959   Installation path of the configuration files. If not absolute, it is
 960   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
 961 </p>
 962 </dd>
 963 <dt>
 964 <tt>FF_BUILD_FRAMEWORK</tt>
 965 </dt>
 966 <dd>
 967 <p>
 968   If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
 969 </p>
 970 </dd>
 971 <dt>
 972 <tt>FF_INSTALL_HEADER_PATH</tt>
 973 </dt>
 974 <dd>
 975 <p>
 976   Installation path of the header files. If not absolute, it is
 977   relative to <tt>CMAKE_INSTALL_PREFIX</tt>. On Mac OS X, and if
 978   <tt>FF_BUILD_FRAMEWORK</tt> is enabled, this setting is ignored.
 979 </p>
 980 </dd>
 981 <dt>
 982 <tt>FF_INSTALL_LIB_PATH</tt>
 983 </dt>
 984 <dd>
 985 <p>
 986   Installation path of the libraries. If not absolute, it is
 987   relative to <tt>CMAKE_INSTALL_PREFIX</tt>. On Mac OS X, and if
 988   <tt>FF_BUILD_FRAMEWORK</tt> is enabled, this is the framework installation
 989   path.
 990 </p>
 991 </dd>
 992 <dt>
 993 <tt>FF_INSTALL_PV3FOAMREADER_PATH</tt>
 994 </dt>
 995 <dd>
 996 <p>
 997   Installation path of the ParaView3 plugins. If not absolute, it is
 998   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
 999 </p>
1000 </dd>
1001 <dt>
1002 <tt>FF_INSTALL_PVFOAMREADER_PATH</tt>
1003 </dt>
1004 <dd>
1005 <p>
1006   Installation path of the ParaView2 plugins. If not absolute, it is
1007   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
1008 </p>
1009 </dd>
1010 <dt>
1011 <tt>FF_INSTALL_USERDFOAM_PATH</tt>
1012 </dt>
1013 <dd>
1014 <p>
1015   Installation path of the Ensight plugin. If not absolute, it is
1016   relative to <tt>CMAKE_INSTALL_PREFIX</tt>.
1017 </p>
1018 </dd>
1019 <dt>
1020 <tt>FF_USE_GAMMA</tt>
1021 </dt>
1022 <dd>
1023 <p>
1024   If enabled, FreeFOAM will use the GAMMA parallel communications library.
1025 </p>
1026 </dd>
1027 <dt>
1028 <tt>FF_USE_MPI</tt>
1029 </dt>
1030 <dd>
1031 <p>
1032   If enabled, FreeFOAM will use the MPI parallel communications library.
1033   This is required in order to build some of the libraries and utilities.
1034 </p>
1035 </dd>
1036 <dt>
1037 <tt>FF_USE_PVM</tt>
1038 </dt>
1039 <dd>
1040 <p>
1041   If enabled, FreeFOAM will use the PVM parallel communications library.
1042 </p>
1043 </dd>
1044 <dt>
1045 <tt>FF_DEFAULT_PSTREAM</tt>
1046 </dt>
1047 <dd>
1048 <p>
1049   The default Pstream selection in the global controlDict file.
1050 </p>
1051 </dd>
1052 <dt>
1053 <tt>FF_BUILD_PARAVIEW_PLUGINS</tt>
1054 </dt>
1055 <dd>
1056 <p>
1057   Whether to build the ParaView plugins. If enabled, FreeFOAM requires a
1058   ParaView build tree and the <tt>ParaView_DIR</tt> variable set to the path of it.
1059 </p>
1060 </dd>
1061 <dt>
1062 <tt>FF_BUILD_PRIVATE_CCMIO</tt>
1063 </dt>
1064 <dd>
1065 <p>
1066   Automatically download and build libccmio. Unfortunately this process will
1067   fail in the download step, since CMake currently does not support <tt>https</tt>
1068   URLs. But you will get specific instructions from the build system on how to
1069   get around this problem.
1070 </p>
1071 </dd>
1072 <dt>
1073 <tt>FF_BUILD_PRIVATE_METIS</tt>
1074 </dt>
1075 <dd>
1076 <p>
1077   Automatically download and build METIS.
1078 </p>
1079 </dd>
1080 <dt>
1081 <tt>FF_BUILD_PRIVATE_PARMETIS</tt>
1082 </dt>
1083 <dd>
1084 <p>
1085   Automatically download and build ParMetis.
1086 </p>
1087 </dd>
1088 <dt>
1089 <tt>FF_BUILD_PRIVATE_PARMGRIDGEN</tt>
1090 </dt>
1091 <dd>
1092 <p>
1093   Automaticall download and build ParMGridGen/MGridgen.
1094 </p>
1095 </dd>
1096 <dt>
1097 <tt>FF_BUILD_DOXYGEN_DOCS</tt>
1098 </dt>
1099 <dd>
1100 <p>
1101   Enable building of the Doxygen API documentation. To actually build it,
1102   execute <tt>make doc</tt>.
1103 </p>
1104 </dd>
1105 </dl></div>
1106 </div>
1107 <h2 id="_documentation">4. Documentation</h2>
1108 <div class="sectionbody">
1109 <div class="para"><p><a href="http://www.OpenFOAM.org/doc">http://www.OpenFOAM.org/doc</a></p></div>
1110 </div>
1111 <h2 id="_help">5. Help</h2>
1112 <div class="sectionbody">
1113 <div class="ilist"><ul>
1114 <li>
1115 <p>
1116 <a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a>
1117 </p>
1118 </li>
1119 <li>
1120 <p>
1121 <a href="https://lists.sourceforge.net/lists/listinfo/freefoam-user">https://lists.sourceforge.net/lists/listinfo/freefoam-user</a>
1122 </p>
1123 </li>
1124 <li>
1125 <p>
1126 <a href="http://www.OpenFOAM.org/discussion.html">http://www.OpenFOAM.org/discussion.html</a> <strong>please only ask questions related
1127   to <em>OpenFOAM</em> there</strong>.
1128 </p>
1129 </li>
1130 </ul></div>
1131 </div>
1132 <h2 id="_reporting_bugs_in_freefoam">6. Reporting Bugs in FreeFOAM</h2>
1133 <div class="sectionbody">
1134 <div class="para"><p><a href="http://freefoam.sourceforge.net">http://freefoam.sourceforge.net</a></p></div>
1135 </div>
1136 <div id="footer">
1137 <div id="footer-text">
1138 Version 1.5.0-0<br />
1139 Last updated 2009-02-23 20:29:17 CEST
1140 </div>
1141 </div>
1142 </body>
1143 </html>