Hosted by SourceForge:

## Obtaining the Prerequisites

Some of the libraries FreeFOAM requires (or optionally can use) are often not readily available as an installable package and are quite tricky to install manually. FreeFOAM can automatically download and build these libraries for you, refer to below instructions. However, if you are behind a firewall or CMake is unable to download a source package, you can do so manually and place the files in the ThirdParty directory in the FreeFOAM source tree. When you run CMake, it will detect the presence of the files and not try to download them.

You can obtain the source packages from the following URLs:

zlib
METIS
ParMetis
scotch
MGRIDGEN
libccmio

## Building FreeFOAM

• Install the prerequisites documented in the README file. If your distribution does not have zlib, METIS, ParMetis, MGRIDGEN or libccmio be not worried, FreeFOAM can handle those for you.

• Download the FreeFOAM source and unpack it somewhere convenient. For the further instructions we will use $HOME/Source/. $ mkdir -p $HOME/Source$ cd $HOME/Source$ wget {tarball}
$tar xjf freefoam-{fullver}.tar.bz2 • Create a build tree and cd into it: $ mkdir $HOME/Source/freefoam-{fullver}-build$ cd $HOME/Source/freefoam-{fullver}-build • Start the CMake-configuration: $ ccmake $HOME/Source/freefoam-{fullver} • Press the c key. Use the arrow keys to navigate up and down and press enter to edit a field. To commit the change, press enter again, or ESC to abandon the change. ON/OFF fields are toggled by pressing enter. Advanced options can be displayed by hitting the t key. • Set CMAKE_BUILD_TYPE to Release for an optimized build. • If CMake complains that it can’t find MPI, and you don’t want to install it, disable FOAM_USE_MPI. • Select the default Pstream implementation by setting FOAM_DEFAULT_PSTREAM to one of dummy or mpi. This setting will only influence the contents of the global controlDict file. • If you want to use the metis and parmetis decomposition methods, make sure that FOAM_ENABLE_METIS and FOAM_ENABLE_PARMETIS are enabled, respectively. If you do not have METIS or ParMetis installed, enable FOAM_BUILD_PRIVATE_METIS or FOAM_BUILD_PRIVATE_PARMETIS, respectively. CMake will then try to download and build the selected libraries for you. Conversely, if one of the libraries is provided by your system, you can turn the respective setting to OFF. Please note that if your system provides only ParMetis, you do not have to install METIS, as the former also contains METIS in an older version. • If you want to use the MGridGen agglomeration method for the GAMG solver, you need to enable FOAM_ENABLE_MGRIDGEN and if the library is not installed on your system ensure that FOAM_BUILD_PRIVATE_MGRIDGEN is enabled. See above regarding the unknown license status of this package. • In order to build ccm26ToFoam, a conversion utility for grids generated with ProStar/ccm © version 2.6, enable the setting FOAM_ENABLE_CCMIO and if libccmio is not installed on your system, also FOAM_BUILD_PRIVATE_CCMIO. Refer to the above description of the libccmio package for the license restrictions which apply to this package. If you decide to build a private version, please read the description of +FOAM_BUILD_PRIVATE_CCMIO carefully. • If you plan on installing FreeFOAM, set CMAKE_INSTALL_PREFIX to the base directory under which FreeFOAM should reside. • For more fine-grained control over what gets installed where, adjust FOAM_INSTALL_<XXX>_PATH, where <XXX> is one of BIN, CMAKE, CONFIG, DATA, DOC, FRAMEWORK, HEADER, LIBEXEC, LIBRARY, MAN, PLUGIN, PYTHON, TUTORIALS and USERDFOAM. Refer to the glossary for the detailed meaning of each of these variables. Paths not starting with a slash (/) will be relative to CMAKE_INSTALL_PREFIX. If you include a leading slash, the paths are absolute. • If you want FreeFOAM to use float as the floating point type instead of double, change FOAM_DOUBLE_PRECISION to OFF. • Hit c again. You shouldn’t get any errors anymore now. Keep pressing c until ccmake displays "Press [g] to generate and exit" in the legend at the bottom of the interface. • Press g to generate the Makefiles and exit the ccmake interface. • Start the native build tool. If you used the Makefile generator (which is the default for Unix-platforms), type $ make
• If you have a multi-core/processor machine, you can speed things up significantly by telling Make to run independent jobs in parallel. A good choice for the number of parallel jobs to run is the number of CPU’s/cores you have in your machine plus 1 (to compensate for disk-latency). For a typical dual-core machine, run

## Using FreeFOAM

If you didn’t change CMAKE_INSTALL_PREFIX and FOAM_INSTALL_BIN_PATH chances are that you can start using FreeFOAM right after you installed it without any further steps being necessary.

### Global Configuration Files

Unfortunately the OpenFOAM library (on which FreeFOAM builds) and some applications require some files to be present for start-up. It finds those in the following places (in the specified order, picking the first hit):

1. Under the directory specified in the $FREEFOAM_CONFIG_DIR environment variable 2. In$HOME/.FreeFOAM/0.1

3. In $HOME/.FreeFOAM 4. In the installation directory of the configuration files. There are two possible places for this: <CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_CONFIG_PATH> if you specified <FOAM_INSTALL_CONFIG_PATH> as a relative path. <FOAM_INSTALL_CONFIG_PATH> if you specified <FOAM_INSTALL_CONFIG_PATH> as an absolute path. The default location is /usr/local/etc/FreeFOAM-0.1.0. ### Selecting the Parallel Communications Library Both, FreeFOAM and OpenFOAM abstract the parallel operations into the Pstream library, making it rather simple to firstly switch between parallel implementations and secondly port the software to a new communications library. However, FreeFOAM uses a much more flexible mechanism of determining which Pstream implementation library to use than OpenFOAM. The latter does this by adjusting the LD_LIBRARY_PATH environment variable. As FreeFOAM wants to be a well behaved Linux citizen, this is not an option. Instead, FreeFOAM dynamically loads the desired Pstream library at startup (i.e. as a plug-in). The following list details how FreeFOAM determines what library to load (if at all): 1. If the environment variable FREEFOAM_PSTREAM_LIBRARY is set, FreeFOAM will try to load the library specified by it. 2. If the sub-dictionary PstreamImplementation exists in the global controlDict file (see Global Configuration Files), it reads the value of the entry configName therein. It then expects that a sub-dictionary of PstreamImplementation with the name specified in configName exists. If that sub-dictionary contains the entry library, it will try to load a library specified by the value of that entry. After FreeFOAM (possibly) loaded the library, it will try to instantiate concrete implementations of the abstract base classes PstreamImpl, IPstreamImpl and OPstreamImpl. Which classes are to be instantiated is determined as follows: 1. FreeFOAM queries the environment variables FREEFOAM_PSTREAM_CLASS, FREEFOAM_IPSTREAM_CLASS and FREEFOAM_OPSTREAM_CLASS for the class names to be instantiated. 2. For any of the variables not set, it requires the sub-dictionary PstreamImplementation to be present in the global controlDict, reads the value of configName and similarly to the library loading, loads the sub-dictionary specified by that value. It then expects to find the entries Pstream, IPstream and OPstream which specify the names of the classes to load. This means that one can create a global controlDict file containing (among other things) something like the following: PstreamImplementation { //configName dummy; configName mpi; dummy { library libdummyPstream.so; Pstream dummyPstreamImpl; OPstream dummyOPstreamImpl; IPstream dummyIPstreamImpl; } mpi { library libmpiPstream.so; Pstream mpiPstreamImpl; OPstream mpiOPstreamImpl; IPstream mpiIPstreamImpl; } } This way the administrator can provide a global controlDict in the FreeFOAM installation. Every user can then override that controlDict by supplying her own file in her home directory as detailed in Global Configuration Files. In order to select a particular Pstream implementation for a specific communications library, the user can then either adjust the PstreamImplementation::configName entry in the global controlDict file, set the FREEFOAM_PSTREAM_CONFIG variable or for full control, set the variables FREEFOAM_PSTREAM_LIBRARY, FREEFOAM_PSTREAM_CLASS, FREEFOAM_IPSTREAM_CLASS and FREEFOAM_OPSTREAM_CLASS. ### Running FreeFOAM From the Build Tree You can use FreeFOAM without installing it first, directly from the build tree. However, this might take a little bit more effort to set up because most likely you will have to adjust the following environment variables: PATH Must contain$HOME/Source/freefoam-0.1.0-build/bin

LD_LIBRARY_PATH

Must contain $HOME/Source/freefoam-0.1.0-build/lib/FreeFOAM-0.1.0 FREEFOAM_CONFIG_DIR Should point to$HOME/Source/freefoam-0.1.0-build/etc

Where it is assumed that you followed the installation instructions. If you used different paths for downloading and compiling FreeFOAM, you will have to adjust these names. Refer to Extending Search Paths And Setting Environment Variables Permanently if you need help setting these variables.

## Running the tutorials

Now you should be able to run the tutorial cases. For this copy the tutorials directory to some convenient place:

$mkdir -p$HOME/{project}/$LOGNAME-{shortver}/run$ cp -r $HOME/Source/freefoam-{fullver}-build/tutorials \$HOME/{project}/$LOGNAME-{shortver}/run/$ cd $HOME/{project}/$LOGNAME-{shortver}/run/tutorials

And try to run e.g. the cavity tutorial case:

$cd incompressible/icoFoam$ freefoam blockMesh -case cavity
$freefoam checkMesh -case cavity$ freefoam ico -case cavity

Things should run smoothly and finish without an error.

All the tutorials contain a script for automatic execution since some of the cases are quite intricate and it is not obvious how to run them. Also, these scripts are used for automated testing. The scripts are called Allrun, where the one located in the tutorials directory is a driver script to run all the other tutorials.

## Obtaining the Source Code from the GIT repository

• Clone the FreeFOAM repository (here the clone is placed in $HOME/Source/FreeFOAM): $ mkdir -p $HOME/Source$ git clone git://repo.or.cz/freefoam.git $HOME/Source/{project} • Proceed in the same way (replacing the path names appropriately) as in the above build instructions. ## Shell completion scripts FreeFOAM comes with completions scripts for the BASH and ZSH shells. The former is quite simplistic and only offers very basic completion of the available application names. The ZSH completion, however, is quite complete and also completes options and arguments for all applications. These completion functions are not installed by make install, because no two systems have the same locations for these kinds of scripts. You find them for manual installation in the FreeFOAM sources in the directory data/shellFunctions/bashCompletion and data/shellFunctions/zshCompletion respectively. Please refer to the documentation of your system/shell on where to place them. ## Emacs mode FreeFOAM includes a rudimentary major mode for the Emacs programming editor. If you want to use this mode, place the file data/editor-modes/foamdict-mode.el in a directory where your Emacs installation finds it. Please refer to the Emacs documentation for further instructions. ## Build Configuration Reference All installation paths below, if not absolute, are relative to CMAKE_INSTALL_PREFIX. CMAKE_BUILD_TYPE One of <empty>, Debug, Release, RelWithDebInfo and MinSizeRel. Refer to the CMake documentation for more detail. CMAKE_INSTALL_PREFIX Installation prefix under which to install FreeFOAM. FOAM_DOUBLE_PRECISION If set to ON FreeFOAM will be compiled using double as the floating point type. If set to OFF it will use float. FOAM_BUILD_FRAMEWORKS If this is enabled, the libraries are built as frameworks. Only available on Mac OS X. FOAM_BUILD_PRIVATE_CCMIO Automatically download and build libccmio. Unfortunately this process may fail in the download step if CMake cannot find either wget or curl on your system, since CMake itself currently does not support https URLs. If this happens, the build process will abort. To fix the issue, Download the file http://freefoam.sf.net/nonfree/libccmio-2.6.1.tar.gz manually and place it in ThirdParty/ccmio/src (relative to the build directory). It is important that you re-run CMake before restarting the build in order to notify the build system that the file is now there. FOAM_BUILD_PRIVATE_METIS Automatically download and build METIS. FOAM_BUILD_PRIVATE_MGRIDGEN Automatically download and build MGRIDGEN. FOAM_BUILD_PRIVATE_PARMETIS Automatically download and build ParMetis. FOAM_BUILD_PRIVATE_ZLIB Automatically download and build the ZLIB compression library. FOAM_DEFAULT_PSTREAM The default Pstream selection in the global controlDict file. FOAM_DOXYDOCS_FOR_SF This setting is for the maintainers of the FreeFOAM and indicates whether the Doxygen documentation should be built for deployment on http://freefoam.sourceforge.net FOAM_ENABLE_CCMIO Enable the use of libccmio. This is required to build the grid conversion utility ccm26ToFoam.  Warning The license of libccmio © is proprietary and requires the consent of the copyright holders (CD-adapco) to download and use the library. Further it is not allowed to redistribute it in any form. The request for permission of inclusion with Debian was answered as follows by Geoffrey Prewett: Gerber, Sorry for the delay in response. I checked back with our development director, and he felt that it would be best to not include libccmio with Debian. Instead, we would prefer to continue our current policy and keep it on our web/FTP and have people ask for it. There are three reasons for this: 1) We don't support STAR on Debian, and don't want to give the impression that we do. 2) We would like to keep a list of people that we give the library to. 3) This is not a general purpose library; its sole purpose is to communicate between our products. Accepting outside changes risks committing a change that would break our own software in possibly subtle ways. So I regret to tell you that my company has declined to permit libccmio to be distributed as part of Debian. Regards, Geoff Prewett FOAM_ENABLE_DOXYGEN_DOCS Enable building of the Doxygen API documentation. The documentation will only be built once and is not updated automatically. This is because it depends on a huge number of files and would make dependency tracking very slow and difficult to maintain. To force the re-generation of the API documentation execute make apidoc. FOAM_ENABLE_METIS Enable the use of the METIS graph partitioning library which is required to implement the metis decomposition method. FOAM_ENABLE_MGRIDGEN Enable the use of MGRIDGEN which is required to build MGridGenGamgAgglomeration providing the MGridGen agglomeration method for the GAMG solver.  Warning The license of MGRIDGEN is unknown and the upstream authors so far have not answered any inquiries to resolve the issue. If you enable the use of MGRIDGEN you alone are responsible for ensuring that you don’t violate any license conditions applying to these libraries. The authors of FreeFOAM will and cannot take any responsibility for your actions. FOAM_ENABLE_MANPAGE_HELP Build (and install) the help-pages in manpage format. This requires a complete Asciidoc toolchain to be present. FOAM_ENABLE_MATHJAX When FOAM_ENABLE_XHTML_GUIDES is enabled, use MathJax for the math rendering. FOAM_ENABLE_PARMETIS Enable the use of the ParMetis graph partitioning library which is required to implement the parMetis decomposition method. FOAM_ENABLE_PDF_GUIDES Build a PDF version of the user guide. In addition to a complete Asciidoc toolchain, this requires either dblatex (for better results) or Apache FOP to be installed. If FOP is used, LaTeX and dvipng are required. FOAM_ENABLE_XHTML_GUIDES Build a XHTML version of the user guide. This requires a complete Asciidoc toolchain. If FOAM_ENABLE_MATHJAX is disabled, this also requires LaTeX and dvipng to be available. FOAM_ENABLE_XHTML_HELP Build (and install) the help-pages in XHTML format for the display in a web browser. The requirements are the same as for FOAM_ENABLE_MANPAGE_HELP. FOAM_EXE_PREFIX Prefix used to mangle application names. Normally this shouldn’t be changed. FOAM_ENABLE_FULL_TUTORIAL_TESTS Run the full tutorials as tests, don’t limit their run-time to a single time step. FOAM_INSTALL_BIN_PATH Installation path of the binaries. FOAM_INSTALL_CMAKE_PATH Installation path of the CMake development files. FOAM_INSTALL_CONFIG_PATH Installation path of the configuration files. FOAM_INSTALL_DATA_PATH Installation path of the architecture-independent files. FOAM_INSTALL_DOC_PATH Installation path of the documentation files. FOAM_INSTALL_FRAMEWORK_PATH Installation path of the Mac OS X frameworks. This is only available and takes effect if FreeFOAM is compiled on Mac OS X, and if FOAM_BUILD_FRAMEWORKS is enabled. FOAM_INSTALL_HEADER_PATH Installation path of the header files. On Mac OS X, and if FOAM_BUILD_FRAMEWORKS is enabled, this setting is ignored. FOAM_INSTALL_LIBEXEC_PATH Installation path of the binaries which should not be on the PATH. FOAM_INSTALL_LIBRARY_PATH Installation path of the libraries. FOAM_INSTALL_MAN_PATH Installation path of the manpage files. FOAM_INSTALL_PLUGIN_PATH Installation base-path of plugins. FOAM_INSTALL_PYTHON_PATH Installation path for Python modules. FOAM_INSTALL_USERDFOAM_PATH Installation path of the Ensight plug-in. FOAM_INSTALL_TUTORIALS_PATH Installation path of the tutorials. FOAM_USE_FOP Use Apache FOP instead of dblatex when building the PDF of the user guide. FOAM_USE_MPI If enabled, FreeFOAM will use the MPI parallel communications library. This is required in order to build some of the libraries and utilities. FOAM_USE_LOCAL_DOXYGEN_DOCS This setting influences the location in which the Doxygen source code documentation is looked for if any of the FreeFOAM applications is invoked with the -doc or -srcDoc options. If it is disabled, the documentation will be loaded over the network from http://freefoam.sourceforge.net/doc/v0.1.0/API. If you enable it, the documentation will be loaded locally. This requires that you either build and install the documentation by enabling FOAM_ENABLE_DOXYGEN_DOCS, or provide the required HTML files otherwise. HTML_DOC_BROWSER This is the program used to display the Doxygen source code documentation if any of the FreeFOAM applications is invoked with the -doc or -srcDoc options. The special value of ECHO changes the behaviour to just write the location of the HTML file to the output. This is a good setting if you’re system doesn’t have any kind of HTML browser installed (such as on a cluster). FOAM_HTML_DOC_BROWSER_COMMAND This is the command with which to invoke the HTML browser. By default it calls the program named in HTML_DOC_BROWSER and passes it the name/URL of the documentation file to be displayed. You shouldn’t have to change this unless your HTML browser requires some unusual options or arguments. ## Troubleshooting ### The FreeFOAM Executables Are Not Found By The Shell There are three possible reasons for this: 1. Your shell (notably csh, tcsh and zsh) requires you to refresh the cache of available executables. You can do so by entering the command: $ rehash
2. If rehashing didn’t solve the problem, the problem most likely is that you installed FreeFOAM into a non-standard location by changing the configuration variables CMAKE_INSTALL_PREFIX or FOAM_INSTALL_BIN_PATH in which case the executables where installed into a directory not searched by the shell. In this case you have to add the installation directory of the executables to the PATH variable. There are two possible locations:

<CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_BIN_PATH>

if you specified FOAM_INSTALL_BIN_PATH as a relative path

<FOAM_INSTALL_BIN_PATH>

if you specified FOAM_INSTALL_BIN_PATH as an absolute path

After extending the PATH variable with the installation directory of the executables, you should be able to run all FreeFOAM applications as any other binary available on the system. See Extending Search Paths And Setting Environment Variables Permanently for instructions on how to extend the search path.

3. This option is similar to the previous solution and applies if you want to run FreeFOAM from the build tree (i.e. without running make install). In this case you again have to make sure that your shell finds the executables built by CMake by extending the PATH variable. Further, you have to tell FreeFOAM where to find the global configuration files (see Global Configuration Files). Here, you have the option to place the files under your home directory or set an environment variable. The former can be achieved by:

$mkdir -p$HOME/.{project}/{shortver}
$cp$HOME/Source/freefoam-{fullver}-build/etc/controlDict \
$HOME/.{project}/{shortver}$ cp $HOME/Source/freefoam-{fullver}-build/etc/cellModels \$HOME/.{project}/{shortver}
$cp -r$HOME/Source/freefoam-{fullver}-build/etc/thermoData \
$HOME/.{project}/{shortver} The latter (and recommended) method is to set the environment variable FREEFOAM_CONFIG_DIR to$HOME/Source/freefoam-0.1.0-build/etc. Adjust the paths to match the build tree to your actual setup.

### Starting Any FreeFOAM Application Fails Because Some Libraries Cannot Be Found

Although CMake should have taken care of this by using RPATH on Linux and install_name on Mac OS X, it might be necessary on some systems to adjust the library search paths:

LD_LIBRARY_PATH

This variable is used by all Unix like systems (e.g. Linux, Mac OS X, etc.)

DYLD_LIBRARY_PATH

This variable is used by Mac OS X.

If you installed FreeFOAM, there are (as with the executables), two possible installation directories:

<CMAKE_INSTALL_PREFIX>/<FOAM_INSTALL_LIBRARY_PATH>

if you specified FOAM_INSTALL_LIBRARY_PATH as a relative path.

<FOAM_INSTALL_LIBRARY_PATH>

if you specified FOAM_INSTALL_LIBRARY_PATH as an absolute path.

#### Setting A Variable

The syntax for setting a variable and making it available to child-processes of the shell is the following:

$export variable_name=variable_value Note that no white-space characters are allowed surrounding the = sign. #### Extending A Search Path The shell and other Unix system facilities use environment variables to locate executables and dynamically linked libraries. These search paths consist of strings naming directories in which the executables and libraries should be searched for. The individual paths are separated by a colon (:) character. To add the e.g. the directory$HOME/bin to the search path for executables, one would do the following:

$export PATH=$PATH:$HOME/bin which appends$HOME/bin to the end of the PATH variable.

### TCSH

#### Setting A Variable

The syntax for setting a variable and making it available to child-processes of the shell is the following:

$setenv variable_name variable_value #### Extending A Search Path The shell and other Unix system facilities use environment variables to locate executables and dynamically linked libraries. These search paths consist of strings naming directories in which the executables and libraries should be searched for. The individual paths are separated by a colon (:) character. To add the e.g. the directory$HOME/bin to the search path for executables, one would do the following:

$setenv PATH${PATH}:${HOME}/bin which appends$HOME/bin to the end of the PATH variable. Note that C-shells usually require the user to type rehash after changing the PATH variable to update the cache of available programs.