songtianlun/openfoam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DOC: update build and config information

Browse Source
This commit is contained in:
Mark Olesen 2019-06-24 18:42:39 +02:00 committed by Andrew Heather
parent 5dd8b73933
commit e6270d127b
5 changed files with 524 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
README.md
View File

@ -2,7 +2,12 @@
OpenFOAM is a free, open source CFD software [released and developed primarily by OpenCFD Ltd](http://www.openfoam.com) since 2004. It has a large user base across most areas of engineering and science, from both commercial and academic organisations. OpenFOAM has an extensive range of features to solve anything from complex fluid flows involving chemical reactions, turbulence and heat transfer, to acoustics, solid mechanics and electromagnetics. [More...](http://www.openfoam.com/documentation)
OpenFOAM is professionally released every six months to include customer sponsored developments and contributions from the community - individual and group contributors, fork re-integrations including from FOAM-extend and OpenFOAM Foundation Ltd - in this Official Release sanctioned by the OpenFOAM Worldwide Trademark Owner aiming towards one OpenFOAM.
OpenFOAM is professionally released every six months to include
customer sponsored developments and contributions from the community -
individual and group contributors, fork re-integrations (including from
FOAM-extend and OpenFOAM Foundation Ltd) - in this Official Release
sanctioned by the OpenFOAM Worldwide Trademark Owner aiming towards
one OpenFOAM.
# Copyright
@ -17,9 +22,19 @@ Please [contact OpenCFD](http://www.openfoam.com/contact) if you have any questi
Violations of the Trademark are continuously monitored, and will be duly prosecuted.
# Using OpenFOAM
If OpenFOAM has already been compiled on your system, simply source
the appropriate `etc/bashrc` or `etc/cshrc` file and get started.
For example, for the OpenFOAM-v1906 version:
```
source /installation/path/OpenFOAM-v1906/etc/bashrc
```
# Compiling OpenFOAM
Please see the relevant guides:
If you are compiling OpenFOAM from source, please see the relevant
guides:
| Location | Readme | Requirements | Build |
|-------------|-----------|--------------|-------|
@ -27,6 +42,125 @@ Please see the relevant guides:
| [ThirdParty][repo third] | [readme][link third-readme] | [system requirements][link third-require] | [build][link third-build] |
# How do I know which version I am currently using?
The value of the `$WM_PROJECT_DIR` or even `$WM_PROJECT_VERSION` are
not guaranteed to have any correspondence to the OpenFOAM release
(API) value. If OpenFOAM has already been compiled, the build-time
information is embedded into each application. For example, as
displayed from `blockMesh -help`:
```
Using: OpenFOAM-v1812.local (1812) (see www.OpenFOAM.com)
Build: 65d6551ff7-20190530 (patch=190531)
Arch: LSB;label=32;scalar=64
```
This output contains all of the more interesting information that we need:
| item | value |
|---------------|---------------|
| version | v1812.local |
| api | 1812 |
| commit | 65d6551ff7 |
| author date | 20190530 |
| patch-level | (20)190531 |
As can be seen in this example, the git build information is
supplemented by the date when the last change was authored, which can
be helpful when the repository contains local changes. If you simply
wish to know the current API and patch levels directly, the
`wmakeBuildInfo` script provides the relevant information even
when OpenFOAM has not yet been compiled:
```
$ wmakeBuildInfo
make
api = 1812
patch = 190531
branch = master
build = 65d6551ff7-20190530
```
Similar information is available with `foamEtcFile`, using the
`-show-api` or `-show-patch` options. For example,
```
$ foamEtcFile -show-api
1812
$ foamEtcFile -show-patch
190531
```
This output will generally be the easiest to parse for scripts.
The `$FOAM_API` convenience environment variable may not reflect the
patching changes made within the currently active environment and
should be used with caution.
# ThirdParty directory
OpenFOAM normally ships with a directory of 3rd-party software and
build scripts for some 3rd-party software that is either necessary or
at least highly useful for OpenFOAM, but which are not necessarily
readily available on every operating system or cluster installation.
These 3rd-party sources are normally located in a directory parallel
to the OpenFOAM directory. For example,
```
/path/parent
|-- OpenFOAM-v1906
\-- ThirdParty-v1906
```
There are, however, many cases where this simple convention is inadequate:
* When no additional 3rd party software is actually required (ie, the
operating system or cluster installation provides it)
* When we have changed the OpenFOAM directory name to some arbitrary
directory name, e.g. openfoam-sandbox1906, etc..
* When we would like any additional 3rd party software to be located
inside of the OpenFOAM directory to ensure that the installation is
encapsulated within a single directory structure. This can be
necessary for cluster installations, or may simply be a convenient
means of performing a software rollout for individual workstations.
* When we have many different OpenFOAM directories for testing or
developing various different features but wish to use or reuse the
same 3rd party software for them all.
The solution for these problems is a newer, more intelligent discovery when locating the ThirdParty directory with the following precedence:
1. PROJECT/ThirdParty
* for single-directory installations
2. PREFIX/ThirdParty-VERSION
* this corresponds to the traditional approach
3. PREFIX/ThirdParty-vAPI
* allows for an updated value of VERSION, *eg*, `v1906-myCustom`,
without requiring a renamed ThirdParty. The API value would still
be `1906` and the original `ThirdParty-v1906/` would be found.
4. PREFIX/ThirdParty-API
* this is the same as the previous example, but using an unadorned
API value. This also makes sense if the chosen version name also
uses the unadorned API value in its naming, *eg*,
`1906-patch190131`, `1906.19W03`
5. PREFIX/ThirdParty-common
* permits maximum reuse for various versions, but only for
experienced user who are aware of potential version
incompatibilities
If none of these directories are found to be suitable, it reverts to using PROJECT/ThirdParty as a dummy location (even if the directory does not exist). This is a safe fallback value since it is within the OpenFOAM directory structure and can be trusted to have no negative side-effects.
In the above, the following notation has been used:
| name | value | meaning |
|---------------|---------------|---------------|
| PROJECT | `$WM_PROJECT_DIR` | The OpenFOAM directory |
| PREFIX | `dirname $WM_PROJECT_DIR` | The OpenFOAM parent directory |
| API | `foamEtcFiles -show-api` | The api or release version |
| VERSION | `$WM_PROJECT_VERSION` | The version we've chosen |
To reduce the potential of false positive matches (perhaps some other
software also uses ThirdParty-xxx for its naming), the directory test
is accompanied by a OpenFOAM-specific sanity test. The OpenFOAM
ThirdParty directory will contain either an `Allwmake` file or a
`platforms/` directory.
<!-- OpenFOAM -->

12
doc/Build.md
View File

@ -1,8 +1,9 @@
## OpenFOAM&reg; Quick Build Guide
Ensure that the [system requirements][link openfoam-require] are satisfied as described here,
and make sure to source the correct OpenFOAM environment. For example,
for the OpenFOAM-v1906 version:
Prior to building, ensure that the [system requirements][link openfoam-require]
are satisfied (including any special [cross-compiling][link openfoam-cross]
considerations), and source the correct OpenFOAM environment.
For example, for the OpenFOAM-v1906 version:
```
source /installation/path/OpenFOAM-v1906/etc/bashrc
```
@ -27,7 +28,7 @@ information about the [config structure][link openfoam-config].
The compilation process is self-contained and will compile and install
all OpenFOAM code and dependencies.
- Test the system readiness (optional)
- Test the system readiness (optional, not supported for cross-compilation)
```
foamSystemCheck
```
@ -73,7 +74,7 @@ you haven't missed any error messages.
- Open a new shell and source the OpenFOAM environment to see all
changes (refer to top of page).
- Validate the build by running
- Validate the build (not supported for cross-compilation) by running
```
foamInstallationTest
```
@ -128,6 +129,7 @@ More details in the [ThirdParty build guide][link third-build].
[link openfoam-issues]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/BuildIssues.md
[link openfoam-config]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Config.md
[link openfoam-build]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Build.md
[link openfoam-cross]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Cross-Compile-mingw.md
[link openfoam-require]: https://develop.openfoam.com/Development/OpenFOAM-plus/blob/develop/doc/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/README.md
[link third-build]: https://develop.openfoam.com/Development/ThirdParty-plus/blob/develop/BUILD.md

258
doc/Config.md
View File

@ -1,10 +1,9 @@
OpenFOAM Configuration
----------------------
# OpenFOAM Configuration
The main OpenFOAM settings are located in the parent `etc/` directory.
Both POSIX (bash, dash,...) and csh shells are supported.
To configure OpenFOAM, source either the `etc/bashrc` or the
`etc/cshrc` file, as appropriate for your shell.
The main OpenFOAM settings are located in the parent `etc/` directory
with both POSIX (bash, dash,...) and csh shells being supported.
To use OpenFOAM, source either the `etc/bashrc` or the
`etc/cshrc` file, as appropriate.
These source the following files in the `config.sh/` or
`config.csh/` directories:
@ -26,3 +25,250 @@ files for the corresponding shell:
* `paraview` : an example of chaining to the standard config/paraview
with a different ParaView_VERSION
* `prefs`: an example of supplying alternative site-defined settings
## OpenFOAM configuration layers
Before launching into manually adjusting the configuration, it is
useful to first understand how OpenFOAM supports different
configuration *layers*. Similar to file-system permissions, we use the
notion of **user**, **group**, **other** categories when searching for
files. The output of `foamEtcFile` can be used to obtain a quick
overview:
```
$ foamEtcFile -list
$HOME/.OpenFOAM/1906
$HOME/.OpenFOAM
/path/OpenFOAM-v1906/site/1906/etc
/path/OpenFOAM-v1906/site/etc
/path/OpenFOAM-v1906/etc
```
Both the *user* paths (located as `$HOME/.OpenFOAM/`) and the *group*
paths (`/path/OpenFOAM-v1906/site/`) support additional API versioning
to allow different settings between releases. The **other**
corresponds to the settings shipped with a particular OpenFOAM release.
Making configuration changes under the *user* or *group* directories
allows you to preserve these across upgrades and makes it easier (if
necessary) to revert to the original values.
## Making changes to the configuration
The first encounter with the OpenFOAM configuration files can be
somewhat intimidating. There are indeed quite a few different bits of
software related to using OpenFOAM, each of which could be available
in different preferred versions, in different possible locations and
with different conventions for naming their library directories.
Additionally it should allow individual users to make their own
configuration choices. Supporting cshell variants for everything adds
yet more files to the mix. Fortunately, the user often only needs to
make a few simple changes and can ignore most of the details and we
also provide a `bin/tools/foamConfigurePaths` tool to make multiple
common changes directly from the command line. The configuration files
generally contain detailed information about which values they expect,
and the user editable part is also clearly marked as such. For
example,
```
#------------------------------------------------------------------------------
# USER EDITABLE PART: Changes made here may be lost with the next upgrade
ParaView_VERSION=5.6.0
ParaView_QT=qt-system
cmake_version=cmake-system
# END OF (NORMAL) USER EDITABLE PART
#------------------------------------------------------------------------------
```
Nonetheless, before making changes it can be useful to understand
where these changes should actually be made (and why). To simplify
things, we only discuss POSIX (bash), but most points apply to cshell
variants as well.
1. The main entry point for the OpenFOAM configuration is the
`etc/bashrc` file. The initial portion of the file establishes the
version and contains some script *magic* to help us determine where
the OpenFOAM directory is located. The balance of the file contains
some general OpenFOAM-specific settings, which you can use for
guidance but in general you should note the following:
* Changes made to this `bashrc` file will be lost with the next upgrade.
* Should override via a `prefs.sh` file instead of editing this file.
2. The `etc/bashrc` file (our entry point) passes control to the
`etc/config.sh/setup` file, which dispatches the rest of the
configuration actions.
The setup of the OpenFOAM environment can be described in terms of a processing tree:
```
source etc/bashrc [args]
|
|-- constants
|-- directory discovery magic
|-- defaults
|-- define OpenFOAM directory
|
\-- setup
|-- discovery of ThirdParty locations
|-- admin overrides (prefs.sh file)
|-- user overrides (prefs.sh file)
|-- user overrides (arguments)
|-- settings (compiler, os)
|-- mpi
|-- paraview
|-- vtk / mesa (llvm)
|-- CGAL / boost
|-- scotch
|-- FFTW
\-- aliases
```
At most locations in this process it is possible for the user to
influence the values used by providing an alternative version of the
file. For example, simply creating the file
`$HOME/.OpenFOAM/config.sh/FFTW` will cause it to be found by the
`foamEtcFile` mechanism during sourcing (see `foamEtcFile -list` for a
reminder of which directories will be searched). Most fairly permanent
changes that affect the base configuration of OpenFOAM itself (choice
of compiler, mpi, data sizes, etc) should normally be defined in the
`prefs.sh` file. These type of changes are important enough that they
receive special treatment. Use the base or admin `prefs.sh` file if
available as `PROJECT/etc/prefs.sh`. This provides the system admin a
reliable location to define site-wide settings, such as for compiler
and vendor-specific MPI libraries. use the user or group prefs.sh if
it exists. For quick or temporary changes, the special interpretation
of arguments when sourcing the etc/bashrc are quite convenient. This
mechanism allows direct setting of variables without needing to edit
any files. For example, to source the OpenFOAM environment with a
different compiler:
```
source /path/to/OpenFOAM-v1906 WM_COMPILER=Clang
```
If the argument does not appear to be an assignment of a variable, it
will attempt to resolve it as a file and then source that. This
property lets the user bundle some favourite settings and temporarily
switch to them. For example, by creating a few predefined
configurations:
```
# file = $HOME/.OpenFOAM/gcc82
export WM_COMPILER_TYPE=ThirdParty
export WM_COMPILER=Gcc82
export WM_LABEL_SIZE=32
```
or
```
# file = $HOME/.OpenFOAM/clang50-int64
export WM_COMPILER_TYPE=ThirdParty
export WM_COMPILER=Clang50
export WM_LABEL_SIZE=64
```
It is then possible to easily switch between different configurations:
```
source /path/to/OpenFOAM-v1906 clang50-int64
source /path/to/OpenFOAM-v1906 gcc82
source /path/to/OpenFOAM-v1906 wingw
```
Armed with this information, the user should be able to make
adjustments to the OpenFOAM configuration with a good degree of
confidence. However, there are also times in which it can be expedient
and useful to simply change the entries directly within the OpenFOAM
directory as new permanent defaults for all users. This can also be
the case for cluster installations where the user will not require the
usual flexibility. For these cases, the `bin/tools/foamConfigurePaths`
tool can be helpful (and powerful). For example, when installing
without any OpenFOAM ThirdParty dependencies and additionally setting
the OpenFOAM directory to a fixed location (removing any bash
discovery magic):
```
bin/tools/foamConfigurePaths \
-project-path "/opt/openfoam-1906" \
-boost boost-system \
-cgal cgal-system \
-fftw fftw-system \
-kahip kahip-none \
-scotch scotch-system \
-scotch-path /usr/lib64/mpi/gcc/openmpi \
;
```
Using this tool has some restrictions:
* It must be called from the OpenFOAM project directory
* It is not available in the PATH, since it we wish to avoid any
inadvertent use
* Using this tool to change default gcc, gmp, mpfr versions is not
very precise. It will change the gcc version without distinguishing
between Gcc48, Gcc82 etc.
## Working in groups
When an OpenFOAM cluster installation is being used by several
different people or interest groups it can be highly interesting to
share common setups or custom libraries and applications. This is
where the OpenFOAM site (group) configuration can be quite helpful.
The directory location of OpenFOAM site settings is defined by the
`$WM_PROJECT_SITE` environment variable. If this is undefined, the
default is to use `PROJECT/site` (ie, a site directory located within
the OpenFOAM directory). Within this `$WM_PROJECT_SITE` directory, we
can use a directory structure that mirrors elements of the OpenFOAM
directory structure, but which also includes a degree of versioning as
well:
```
$WM_PROJECT_SITE
|
|-- API
| |-- bin
| \-- etc
|-- VERSION
| \-- platforms
| |-- bin
| \-- lib
|-- bin
\-- etc
```
Useful OpenFOAM-related scripts can be placed in the bin directory. If
the script can only work with a particular OpenFOAM version, it then
makes sense to place it into the API/bin directory accordingly.
Similarly, if particular configurations or setups are useful for
several people, it makes sense to locate them centrally as a site (or
group) resource. For example,
```
$WM_PROJECT_SITE
|
\-- etc
|-- caseDicts
\-- config.sh
|-- openmpi
\-- paraview
```
for some jointly useful caseDicts and suitable configurations for openmpi, paraview.
The `foamEtcFile -list` option provides a good overview of which
locations will be searched for configuration files, which uses the
following precedence:
* user:
* `$HOME/.OpenFOAM/API`
* `$HOME/.OpenFOAM`
* group:
* `$WM_PROJECT_SITE/API/etc`
* `$WM_PROJECT_SITE`
* other:
* `$WM_PROJECT_DIR/etc`
If applications and libraries are to be shared within a group, a
typical approach is that one person is in charge of administering the
the internal code releases. They would compile the code in their
normal user directories, which means that it would normally have the
user destinations:
```
$FOAM_USER_APPBIN
$FOAM_USER_LIBBIN
```
For distribution at the group level, these files would be synchronized to the corresponding group directories:
```
$FOAM_USER_APPBIN -> $FOAM_SITE_APPBIN
$FOAM_USER_LIBBIN -> $FOAM_SITE_LIBBIN
```

108
doc/Cross-Compile-mingw.md Normal file
View File

@ -0,0 +1,108 @@
# Notes for cross-compiling with mingw
## Minimum version
The mingw cross-compiler should be at least version 8.2.0 (tested) or
slightly older. Versions that are much older may have faultly regex
implementations.
## Host setup
On openSUSE use the packages for compilation:
```
mingw64-cross-binutils
mingw64-cross-cpp
mingw64-cross-gcc
mingw64-cross-gcc-c++
mingw64-filesystem
mingw64-headers
mingw64-runtime
mingw64-libwinpthread1
mingw64-winpthreads-devel
mingw64-libfftw3
mingw64-fftw3-devel
```
This setup is missing `zlib`, so download that manually and compile as a
*static* library.
```
CC="$(wmake -show-c)" CFLAGS="$(wmake -show-cflags)" ./configure --static
make
```
The resulting output files (zconf.h, zlib.h) and (libz.a) either need
to be installed in system locations where OpenFOAM can find them, or if
they are to be shipped directly with OpenFOAM, they can also be placed
in the `src/OpenFOAM/include` and `platforms/XXX/lib` paths.
If the header files are only needed during compilation, it can be a
fairly convenient hack to simply place copies of them in the
`src/OSspecific/MSwindows` directory.
Flex is used in a few locations within OpenFOAM for generating code.
The generated C++ code requires the `FlexLexer.h` header file, but
its `/usr/include` location will be ignored by the cross-compiler.
As another ugly hack, a copy of this file can be made in a standard
project include location. For example,
```
ln -s /usr/include/FlexLexer.h src/OSspecific/MSwindows
```
The last point to consider when cross-compiling is the behaviour of
the OpenFOAM wmake toolchain used during compilation. These are found
under `wmake/src`. If the `Makefile` is used directly, executables
will be created that work on the target platform (Windows), but *not*
on the host platform (which is what is required). This is addressed
directly by the `wmake/src/Allmake` script, which will use the system
gcc to create host binaries for the wmake toolchain. If, for some
reason, you also require target wmake toolchain binaries, you will
need invoke make manually within the `wmake/src` directory.
The settings for cross-compilation are normally defined in the
`etc/pref.sh` file with contents like this:
```
# For mingw cross-compile
export WM_COMPILER=Mingw
export WM_MPLIB=MSMPI
export WM_LABEL_SIZE=32
# other settings...
```
Additional adjustments may be required in some other places. For example
in `etc/config.sh/FFTW`
```
fftw_version=fftw-system
export FFTW_ARCH_PATH=/usr/x86_64-w64-mingw32/sys-root/mingw
```
## Run-time setup
When using the cross-compiled executables and libraries, the
corresponding runtime libraries will be required.
These will need to be copied across from the Linux host system to the
target machine.
On openSUSE these runtime libraries are provided by the packages:
```
mingw64-libgcc_s_seh1
mingw64-libstdc++6
```
When running, the `WM_PROJECT_DIR` environment must be set.
OpenFOAM will otherwise not be able to locate its files.
## Known limitations (2019-06-24)
- kahip does not build
- boost should build ok, but no CGAL support (ie, no foamyHexMesh)
- no ParaView plugin, runTimePostProcessing
- reacting EulerFoam solvers have too many interdependencies and do
not yet compile cleanly.
It is advisable to compile with the wmake `-k` option to keep going
even when the EulerFoam solvers fail to compile.

38
modules/README.md
View File

@ -1,5 +1,4 @@
OpenFOAM Modules
================
## OpenFOAM Modules
This directory is a location for additional OpenFOAM components or tools
to placed and have them built as part of the normal OpenFOAM build
@ -15,8 +14,9 @@ by script or by hand.
### git
On the first use, it will be necessary to register the submodules:
git submodule init
```
git submodule init
```
This will clone the relevant submodules from their respective
@ -24,15 +24,15 @@ repositories.
The following will indicate the current state:
git submodule status
```
git submodule status
```
On the first use, or after merging upstream changes in the OpenFOAM
repository, it will be necessary to update the submodules:
git submodule update
```
git submodule update
```
A quick overview of `git submodule` can be in this
[*blog*][blog git-submodule] with full details in the
@ -40,15 +40,19 @@ A quick overview of `git submodule` can be in this
An easy way to see which submodules are actually in use:
`cat .gitmodules`
```
cat .gitmodules
```
Which will reveal content resembling the following:
[submodule "cfmesh"]
path = modules/cfmesh
url = https://develop.openfoam.com/Community/integration-cfmesh.git
```
[submodule "catalyst"]
path = modules/catalyst
url = https://develop.openfoam.com/Community/catalyst.git
[submodule "cfmesh"]
path = modules/cfmesh
url = https://develop.openfoam.com/Community/integration-cfmesh.git
```
### doxygen