$ mkdir -p $HOME/Source
$ cd $HOME/Source
$ wget {tarball}
$ tar xjf freefoam-{fullver}.tar.bz2
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:
http://master.dl.sourceforge.net/project/freefoam/ThirdParty/zlib/zlib-1.2.5.tar.gz
http://master.dl.sourceforge.net/project/freefoam/ThirdParty/scotch/scotch_5.1.7.dfsg.orig.tar.gz
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
$ make -j3
If you want to, you can now install FreeFOAM. Depending on the CMAKE_INSTALL_PREFIX and the individual FOAM_INSTALL_<XXX>_PATH it is possible that you have to do this as root, i.e. use su -c or sudo.
$ make install
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.
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):
Under the directory specified in the $FREEFOAM_CONFIG_DIR environment variable
In $HOME/.FreeFOAM/0.1
In $HOME/.FreeFOAM
In the installation directory of the configuration files. There are two possible places for this:
if you specified <FOAM_INSTALL_CONFIG_PATH> as a relative path.
if you specified <FOAM_INSTALL_CONFIG_PATH> as an absolute path.
The default location is /usr/local/etc/FreeFOAM-0.1.0.
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):
If the environment variable FREEFOAM_PSTREAM_LIBRARY is set, FreeFOAM will try to load the library specified by it.
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:
FreeFOAM queries the environment variables FREEFOAM_PSTREAM_CLASS, FREEFOAM_IPSTREAM_CLASS and FREEFOAM_OPSTREAM_CLASS for the class names to be instantiated.
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.
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:
Must contain $HOME/Source/freefoam-0.1.0-build/bin
Must contain $HOME/Source/freefoam-0.1.0-build/lib/FreeFOAM-0.1.0
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.
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.
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.
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.
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.
All installation paths below, if not absolute, are relative to CMAKE_INSTALL_PREFIX.
One of <empty>, Debug, Release, RelWithDebInfo and MinSizeRel. Refer to the CMake documentation for more detail.
Installation prefix under which to install FreeFOAM.
If set to ON FreeFOAM will be compiled using double as the floating point type. If set to OFF it will use float.
If this is enabled, the libraries are built as frameworks. Only available on Mac OS X.
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.
Automatically download and build METIS.
Automatically download and build MGRIDGEN.
Automatically download and build ParMetis.
Automatically download and build the ZLIB compression library.
The default Pstream selection in the global controlDict file.
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
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
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.
Enable the use of the METIS graph partitioning library which is required to implement the metis decomposition method.
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. |
Build (and install) the help-pages in manpage format. This requires a complete Asciidoc toolchain to be present.
When FOAM_ENABLE_XHTML_GUIDES is enabled, use MathJax for the math rendering.
Enable the use of the ParMetis graph partitioning library which is required to implement the parMetis decomposition method.
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.
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.
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.
Prefix used to mangle application names. Normally this shouldn’t be changed.
Run the full tutorials as tests, don’t limit their run-time to a single time step.
Installation path of the binaries.
Installation path of the CMake development files.
Installation path of the configuration files.
Installation path of the architecture-independent files.
Installation path of the documentation files.
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.
Installation path of the header files. On Mac OS X, and if FOAM_BUILD_FRAMEWORKS is enabled, this setting is ignored.
Installation path of the binaries which should not be on the PATH.
Installation path of the libraries.
Installation path of the manpage files.
Installation base-path of plugins.
Installation path for Python modules.
Installation path of the Ensight plug-in.
Installation path of the tutorials.
Use Apache FOP instead of dblatex when building the PDF of the user guide.
If enabled, FreeFOAM will use the MPI parallel communications library. This is required in order to build some of the libraries and utilities.
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.
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).
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.
There are three possible reasons for this:
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
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:
if you specified FOAM_INSTALL_BIN_PATH as a relative 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.
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.
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:
This variable is used by all Unix like systems (e.g. Linux, Mac OS X, etc.)
This variable is used by Mac OS X.
If you installed FreeFOAM, there are (as with the executables), two possible installation directories:
if you specified FOAM_INSTALL_LIBRARY_PATH as a relative path.
if you specified FOAM_INSTALL_LIBRARY_PATH as an absolute path.
If you are trying to run from the build tree, you have to include $HOME/Source/freefoam-0.1.0-build/lib/FreeFOAM-0.1.0 in the above mentioned search paths (where you have to adjust the location of the build tree to your actual setup).
FreeFOAM (and OpenFOAM) often dynamically load libraries at run-time (a.k.a plug-ins) to add features the user requested without requiring that the whole application be recompiled. This makes it very simple to add new boundary conditions, turbulence and combustion models etc. However, it also requires that FreeFOAM must be able to find these libraries at run-time. The operating system function which does the loading of the libraries (dlopen) usually tries to find the library with the given name in several places; namely a default search path and a search path configured by one or multiple environment variables such as LD_LIBRARY_PATH or DYLD_LIBRARY_PATH (on Mac OS X). The details vary from platform to platform, so you best consult the documentation of dlopen for the details.
Additionally FreeFOAM allows you to configure a custom search path for plug-ins in the global controlDict file by listing the directories to be searched in the list LibrarySearchPaths. By default FreeFOAM is configured to search for plug-ins in the location where CMake installed them.
If you want to add your own plug-in libraries (e.g. you want to add your own boundary conditions class), you most probably will want to extend this search path.
If you get a warning message similar to the following
--> FOAM Warning :
From function dlLibraryTable::open(const dictionary& dict, const word& libsEntry, const TablePtr tablePtr)
in file XXX/src/OpenFOAM/db/dlLibraryTable/dlLibraryTableTemplates.C at line 68
library "libfieldFunctionObjects.so" did not introduce any new entries
(where XXX is the path to the FreeFOAM source code and the actual library name can be different), followed by a fatal error stating that FreeFOAM does not know a class or type, e.g.
--> FOAM FATAL ERROR: Unknown function type fieldAverage
Table of functionObjects is empty
From function functionObject::New(const word& name, const Time&, const dictionary&) in file XXX/src/OpenFOAM/db/functionObjects/functionObject/functionObject.C at line 74.
FOAM exiting
and you are absolutely sure that the named type actually exists in the library mentioned in the preceding warning message, the issue is very likely that FreeFOAM is loading the plugin library from a different binary tree than the executable belongs to.
|
Important
|
Always make sure that you never load plugins from different binary trees (where the build tree and the install tree count as such). If you want to run a binary from the build tree but already have a corresponding installation tree, use the FREEFOAM_CONFIG_DIR environment variable to point FreeFOAM to the directory <path to build tree>/etc/ containing the global controlDict file in the build tree. Otherwise the binaries are likely to be incompatible with each other. |
The way one sets environment variables and extends the executable and library search paths permanently strongly depends on the shell used. Usually one has to create or change an initialization file in the users home directory. In the following this will be discussed very briefly for the popular shells BASH and tcsh. However, if you need more help or want information on using the shell, there is an excellent tutorial available at http://linuxcommand.org.
The BASH shell is the default shell for most Linux/Unix distributions. Most systems configure the BASH shell such that it reads the text file $HOME/.bashrc when starting up, so this is the place where one appends customizations of the environment variables. On some systems this file is not processed by default (notably Mac OS X). In this case you can use $HOME/.bash_profile.
To retrieve the value stored in a shell variable or environment variable, one prefixes its name with the dollar ($) character.
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.
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.
Some users and administrators prefer to use a C-Shell, such as the TCSH. Here you can use e.g. the file $HOME/.tcshrc to customize the environment.
As with the BASH, one retrieves the value stored in a shell variable or environment variable by prefixing its name with the dollar ($) character. Sometimes it is also necessary to protect the variable name by surrounding it with curly braces ({ and }).
The syntax for setting a variable and making it available to child-processes of the shell is the following:
$ setenv variable_name variable_value
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.