zhyang-dev/openfoam
1
0
Fork 0
mirror of https://develop.openfoam.com/Development/openfoam.git synced 2025-11-28 03:28:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

DOC: reorganize Requirements.md, additional note for openSUSE leap

Browse Source 
- move unreferenced Config.md to wiki content
This commit is contained in:
Mark Olesen
2021-06-08 21:35:54 +02:00
parent 853010309d
commit 7b14af4230
6 changed files with 126 additions and 378 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
META-INFO/README.md
View File

@ -3,8 +3,9 @@
Meta-information is generally for OpenFOAM internal use only. Meta-information is generally for OpenFOAM internal use only.
The format, content and meaning may be changed at anytime without The format, content and meaning may be changed at anytime without
notice. If any of these are changed, these are some of places that prior notice.
will need to be updated accordingly: If any of these are changed, these are some of places that will need
to be updated accordingly:
- bin/foamEtcFile - bin/foamEtcFile
- bin/tools/foamConfigurePaths - bin/tools/foamConfigurePaths
@ -38,7 +39,7 @@ Format: `date +%y%m`
- 4-digit year-month (YYMM) integer corresponding to the major - 4-digit year-month (YYMM) integer corresponding to the major
release or in unusual cases an intermediate release. release or in unusual cases an intermediate release.
Example, `1712` for the Dec-2017 release. Example, `2106` for the June-2021 release.
#### patch #### patch
@ -78,9 +79,9 @@ the saved information needs synchronization. The command
### Notes ### Notes
The saved information is split into two separate files. The `api-info` The saved information is split into two separate files.
contains more permanent information, whereas the `build-info` is more The `api-info` file contains more permanent information,
transient in nature. whereas the `build-info` is more transient in nature.
---- ----
2020-06-23 2021-06-09

70
README.md
View File

@ -11,7 +11,7 @@ individual and group contributors, integrations
[governance guided activities](https://www.openfoam.com/governance/). [governance guided activities](https://www.openfoam.com/governance/).
## Copyright ## License
OpenFOAM is free software: you can redistribute it and/or modify it OpenFOAM is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the under the terms of the GNU General Public License as published by the
@ -27,10 +27,11 @@ may redistribute files.
OpenCFD Ltd grants use of its OpenFOAM trademark by Third Parties on a OpenCFD Ltd grants use of its OpenFOAM trademark by Third Parties on a
licence basis. ESI Group and OpenFOAM Foundation Ltd are currently licence basis. ESI Group and OpenFOAM Foundation Ltd are currently
permitted to use the Name and agreed Domain Name. For information on permitted to use the Name and agreed Domain Name. For information on
trademark use, please refer to the [trademark policy guidelines](http://www.openfoam.com/legal/trademark-policy.php). trademark use, please refer to the
[trademark policy guidelines][link trademark].
Please [contact OpenCFD](http://www.openfoam.com/contact) if you have Please [contact OpenCFD](http://www.openfoam.com/contact) if you have
any questions on the use of the OpenFOAM trademark. any questions about the use of the OpenFOAM trademark.
Violations of the Trademark are monitored, and will be duly prosecuted. Violations of the Trademark are monitored, and will be duly prosecuted.
@ -39,9 +40,9 @@ Violations of the Trademark are monitored, and will be duly prosecuted.
If OpenFOAM has already been compiled on your system, simply source If OpenFOAM has already been compiled on your system, simply source
the appropriate `etc/bashrc` or `etc/cshrc` file and get started. the appropriate `etc/bashrc` or `etc/cshrc` file and get started.
For example, for the OpenFOAM-v1912 version: For example, for the OpenFOAM-v2106 version:
``` ```
source /installation/path/OpenFOAM-v1912/etc/bashrc source /installation/path/OpenFOAM-v2106/etc/bashrc
``` ```
## Compiling OpenFOAM ## Compiling OpenFOAM
@ -55,6 +56,11 @@ guides:
| [ThirdParty][repo third] | [readme][link third-readme] | [system requirements][link third-require] | [build][link third-build] | | [ThirdParty][repo third] | [readme][link third-readme] | [system requirements][link third-require] | [build][link third-build] |
If you need to modify the versions or locations of ThirdParty
software, please read how the
[OpenFOAM configuration][wiki-config] is structured.
## How do I know which version I am currently using? ## How do I know which version I am currently using?
The value of the `$WM_PROJECT_DIR` or even `$WM_PROJECT_VERSION` are The value of the `$WM_PROJECT_DIR` or even `$WM_PROJECT_VERSION` are
@ -63,19 +69,19 @@ not guaranteed to have any correspondence to the OpenFOAM release
information is embedded into each application. For example, as information is embedded into each application. For example, as
displayed from `blockMesh -help`: displayed from `blockMesh -help`:
``` ```
Using: OpenFOAM-v1812.local (1812) - visit www.openfoam.com Using: OpenFOAM-com (2012) - visit www.openfoam.com
Build: 65d6551ff7-20190530 (patch=190531) Build: b830beb5ea-20210429 (patch=210414)
Arch: LSB;label=32;scalar=64 Arch: LSB;label=32;scalar=64
``` ```
This output contains all of the more interesting information that we need: This output contains all of the more interesting information that we need:
| item | value | | item | value |
|-----------------------|---------------| |-----------------------|---------------|
| version | v1812.local | | version | com (eg, local development branch) |
| api | 1812 | | api | 2012 |
| commit | 65d6551ff7 | | commit | b830beb5ea |
| author date | 20190530 | | author date | 20210429 |
| patch-level | (20)190531 | | patch-level | (20)210414 |
| label/scalar size | 32/64 bits | | label/scalar size | 32/64 bits |
The Arch information may also include the `solveScalar` size The Arch information may also include the `solveScalar` size
@ -90,19 +96,19 @@ when OpenFOAM has not yet been compiled:
``` ```
$ wmake -build-info $ wmake -build-info
make make
api = 1812 api = 2012
patch = 190531 patch = 210414
branch = master branch = master
build = 65d6551ff7-20190530 build = 308af39136-20210426
``` ```
Similar information is available with `foamEtcFile`, using the Similar information is available with `foamEtcFile`, using the
`-show-api` or `-show-patch` options. For example, `-show-api` or `-show-patch` options. For example,
``` ```
$ foamEtcFile -show-api $ foamEtcFile -show-api
1812 2012
$ foamEtcFile -show-patch $ foamEtcFile -show-patch
190531 210414
``` ```
This output will generally be the easiest to parse for scripts. This output will generally be the easiest to parse for scripts.
The `$FOAM_API` convenience environment variable may not reflect the The `$FOAM_API` convenience environment variable may not reflect the
@ -121,8 +127,8 @@ These 3rd-party sources are normally located in a directory parallel
to the OpenFOAM directory. For example, to the OpenFOAM directory. For example,
``` ```
/path/parent /path/parent
|-- OpenFOAM-v1912 |-- OpenFOAM-v2106
\-- ThirdParty-v1912 \-- ThirdParty-v2106
``` ```
There are, however, many cases where this simple convention is inadequate: There are, however, many cases where this simple convention is inadequate:
@ -130,7 +136,7 @@ There are, however, many cases where this simple convention is inadequate:
operating system or cluster installation provides it) operating system or cluster installation provides it)
* When we have changed the OpenFOAM directory name to some arbitrary * When we have changed the OpenFOAM directory name to some arbitrary
directory name, e.g. openfoam-sandbox1912, etc.. directory name, e.g. openfoam-sandbox2106, etc..
* When we would like any additional 3rd party software to be located * When we would like any additional 3rd party software to be located
inside of the OpenFOAM directory to ensure that the installation is inside of the OpenFOAM directory to ensure that the installation is
@ -150,17 +156,14 @@ when locating the ThirdParty directory with the following precedence:
2. PREFIX/ThirdParty-VERSION 2. PREFIX/ThirdParty-VERSION
* this corresponds to the traditional approach * this corresponds to the traditional approach
3. PREFIX/ThirdParty-vAPI 3. PREFIX/ThirdParty-vAPI
* allows for an updated value of VERSION, *eg*, `v1912-myCustom`, * allows for an updated value of VERSION, *eg*, `v2106-myCustom`,
without requiring a renamed ThirdParty. The API value would still without requiring a renamed ThirdParty. The API value would still
be `1912` and the original `ThirdParty-v1912/` would be found. be `2106` and the original `ThirdParty-v2106/` would be found.
4. PREFIX/ThirdParty-API 4. PREFIX/ThirdParty-API
* this is the same as the previous example, but using an unadorned * same as the previous example, but using an unadorned API value.
API value. This also makes sense if the chosen version name also
uses the unadorned API value in its naming, *eg*,
`1912-patch190131`, `1912.19W03`
5. PREFIX/ThirdParty-common 5. PREFIX/ThirdParty-common
* permits maximum reuse for various versions, for experienced user * permits maximum reuse for various versions, for experienced
who are aware of potential version incompatibilities users who are aware of potential version incompatibilities
If none of these directories are found to be suitable, it reverts to If none of these directories are found to be suitable, it reverts to
using PROJECT/ThirdParty as a dummy location (even if the directory using PROJECT/ThirdParty as a dummy location (even if the directory
@ -184,18 +187,21 @@ ThirdParty directory will contain either an `Allwmake` file or a
<!-- OpenFOAM --> <!-- OpenFOAM -->
[link trademark]: https://www.openfoam.com/opencfd-limited-trade-mark-policy
[repo openfoam]: https://develop.openfoam.com/Development/openfoam/ [repo openfoam]: https://develop.openfoam.com/Development/openfoam/
[repo third]: https://develop.openfoam.com/Development/ThirdParty-common/ [repo third]: https://develop.openfoam.com/Development/ThirdParty-common/
[link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md [link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md
[link openfoam-issues]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/BuildIssues.md [link openfoam-issues]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/BuildIssues.md
[link openfoam-config]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Config.md
[link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md [link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md
[link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md [link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md [link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md
[link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md [link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md
[link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md [link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md
[wiki-config]: https://develop.openfoam.com/Development/openfoam/-/wikis/configuring
## Useful Links ## Useful Links
@ -203,8 +209,8 @@ ThirdParty directory will contain either an `Allwmake` file or a
- [Documentation](http://www.openfoam.com/documentation) - [Documentation](http://www.openfoam.com/documentation)
- [Reporting bugs/issues/feature requests](http://www.openfoam.com/code/bug-reporting.php) - [Reporting bugs/issues/feature requests](http://www.openfoam.com/code/bug-reporting.php)
- [Issue tracker](https://develop.openfoam.com/Development/openfoam/-/issues) - [Issue tracker](https://develop.openfoam.com/Development/openfoam/-/issues)
- [Code wiki](https://develop.openfoam.com/Development/openfoam/-/wikis/) and [general wiki](http://wiki.openfoam.com/) - [Code wiki](https://develop.openfoam.com/Development/openfoam/-/wikis/) and [General wiki](http://wiki.openfoam.com/)
- [Community](http://www.openfoam.com/community/), [Governance](http://www.openfoam.com/governance/) - [Governance](http://www.openfoam.com/governance/), [Governance Projects](https://www.openfoam.com/governance/projects)
- [Contacting OpenCFD](http://www.openfoam.com/contact/) - [Contacting OpenCFD](http://www.openfoam.com/contact/)
Copyright 2016-2020 OpenCFD Ltd Copyright 2016-2021 OpenCFD Ltd

47
doc/Build.md
View File

@ -3,13 +3,13 @@
Prior to building, ensure that the [system requirements][link openfoam-require] Prior to building, ensure that the [system requirements][link openfoam-require]
are satisfied (including any special [cross-compiling][wiki-cross-compile] are satisfied (including any special [cross-compiling][wiki-cross-compile]
considerations), and source the correct OpenFOAM environment. considerations), and source the correct OpenFOAM environment.
For example, for the OpenFOAM-v2006 version: For example, for the OpenFOAM-v2106 version:
``` ```
source <installation path>/OpenFOAM-v2006/etc/bashrc source <installation path>/OpenFOAM-v2106/etc/bashrc
``` ```
e.g. if installed under the `~/OpenFOAM` directory e.g. if installed under the `~/openfoam` directory
``` ```
source ~/OpenFOAM/OpenFOAM-v2006/etc/bashrc source ~/openfoam/OpenFOAM-v2106/etc/bashrc
``` ```
@ -26,7 +26,7 @@ file.
If you need to change the default versions for third-party libraries, If you need to change the default versions for third-party libraries,
or use system libraries for some components, please some additional or use system libraries for some components, please some additional
information about the [config structure][link openfoam-config]. information about the [config structure][wiki-config].
## Compile OpenFOAM ## Compile OpenFOAM
@ -86,34 +86,37 @@ you haven't missed any error messages.
``` ```
foamInstallationTest foamInstallationTest
``` ```
- Create the user `run` directory: - test any given tutorial case. For example,
``` ```
mkdir -p $FOAM_RUN foamTestTutorial -full incompressible/simpleFoam/pitzDaily
``` ```
- Test the installation with a simple tutorial: - Note: the tutorial test can also be done manually:
``` ```
# Create the user "run" directory:
mkdir -p "$FOAM_RUN"
# Change to the user "run" directory:
run run
cp -r $FOAM_TUTORIALS/incompressible/simpleFoam/pitzDaily ./ # Copy tutorial
cd pitzDaily cp -r "$FOAM_TUTORIALS"/incompressible/simpleFoam/pitzDaily ./
blockMesh # Run the tutorial
simpleFoam ( cd pitzDaily && blockMesh && simpleFoam )
``` ```
### ParaView ### ParaView
OpenFOAM ships with ParaView sources for post-processing OpenFOAM OpenFOAM ships with ParaView sources for post-processing OpenFOAM
field results. However, the paraview version distributed with field results. However, it will [often be sufficient][FAQ ParaView]
to use the paraview version distributed with
the operating system or a [binary package][download ParaView] the operating system or a [binary package][download ParaView]
will often be sufficient, and avoids additional compilation complexity. and avoid additional compilation complexity.
If you do wish to compile ParaView from source, it is recommended If you do wish to compile ParaView from source, it is recommended
that you do so ***after*** completing an initial compilation of OpenFOAM. that you do so ***after*** completing an initial compilation of OpenFOAM.
This gets the process started much more quickly. At a later stage, This gets the process started much more quickly. At a later stage,
OpenFOAM can be updated to compile with paraview. Only the affected the OpenFOAM visualization module can be compiled for a particular
applications will be compiled (eg, the blockMesh reader module) and the ParaView version _without_ recompiling OpenFOAM itself.
balance of the OpenFOAM installation will not affected.
If you decide to compiling in two passes, you only need to execute the If you decide to compile in two passes, you only need to execute the
top-level `Allwmake` a second time. Do **not** use `wclean` to force a top-level `Allwmake` a second time. Do **not** use `wclean` to force a
complete rebuild! This is unnecessary. complete rebuild! This is unnecessary.
@ -126,6 +129,7 @@ More details in the [ThirdParty build guide][link third-build].
[page ParaView]: http://www.paraview.org/ [page ParaView]: http://www.paraview.org/
[download ParaView]: https://www.paraview.org/download/ [download ParaView]: https://www.paraview.org/download/
[FAQ ParaView]: https://discourse.paraview.org/t/i-want-to-visualize-my-openfoam-simulation-results-with-paraview-but-im-confused-which-version-should-i-use
<!-- OpenFOAM --> <!-- OpenFOAM -->
@ -135,13 +139,14 @@ More details in the [ThirdParty build guide][link third-build].
[link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md [link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md
[link openfoam-issues]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/BuildIssues.md [link openfoam-issues]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/BuildIssues.md
[link openfoam-config]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Config.md
[link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md [link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md
[wiki-cross-compile]: https://develop.openfoam.com/Development/openfoam/-/wikis/guides/build/cross-compile-mingw
[link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md [link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md [link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md
[link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md [link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md
[link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md [link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md
[wiki-cross-compile]: https://develop.openfoam.com/Development/openfoam/-/wikis/building/cross-compile-mingw
[wiki-config]: https://develop.openfoam.com/Development/openfoam/-/wikis/configuring
--- ---
Copyright 2019-2020 OpenCFD Ltd Copyright 2019-2021 OpenCFD Ltd

15
doc/BuildIssues.md
View File

@ -1,11 +1,11 @@
## Known Build Issues (OpenFOAM-v2012) ## Known Build Issues (v2012, v2106)
### Windows cross-compilation ### Windows cross-compilation
Compilation of adios, kahip, metis, ptscotch, boost/cgal do not work. Compilation of adios, kahip, metis, ptscotch, boost/cgal do not work.
## Known Build Issues (OpenFOAM-v2006) ## Known Build Issues (v2006)
### Windows cross-compilation ### Windows cross-compilation
@ -17,11 +17,11 @@ Compilation of kahip and ptscotch do not work.
### Thermo problems with Clang ### Thermo problems with Clang
Previous versions (1906, 1912) experienced some Clang builds issues Previous versions (v1906, v1912) experienced some Clang builds issues
with thermophysical libraries. These are resolved with clang-10. with thermophysical libraries. These are resolved with clang-10.
## Known Build Issues (OpenFOAM-v1912) ## Known Build Issues (v1912)
### ParaView, ParaView-Catalyst ### ParaView, ParaView-Catalyst
@ -62,7 +62,7 @@ Windows. Compile with the `-k` option to skip over these applications
for now. for now.
## Known Build Issues (OpenFOAM-v1906) ## Known Build Issues (v1906)
### Thermo problems with Clang ### Thermo problems with Clang
@ -179,12 +179,13 @@ and attempt to install a `paraview~qt` version instead.
[link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md [link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md
[link openfoam-issues]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/BuildIssues.md [link openfoam-issues]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/BuildIssues.md
[link openfoam-config]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Config.md
[link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md [link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md
[link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md [link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md [link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md
[link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md [link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md
[link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md [link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md
[wiki-config]: https://develop.openfoam.com/Development/openfoam/-/wikis/configuring
--- ---
Copyright 2019-2020 OpenCFD Ltd Copyright 2019-2021 OpenCFD Ltd

277
doc/Config.md
View File

@ -1,277 +0,0 @@
## OpenFOAM Configuration
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:
* `setup` : finalize setup of OpenFOAM environment (called by bashrc,cshrc)
* `settings` : core settings
* `aliases` : aliases for interactive shells
* `unset` : sourced to clear as many OpenFOAM environment settings as possible
* `mpi` : MPI communications library settings
* `paraview` : application settings for ParaView
* `scotch` : application settings for compiling against scotch
* `metis` : application settings for compiling against metis
The `config.{csh,sh}/example/` directories contain additional example
configuration files for the corresponding shell:
* `compiler` : an example of fine tuning ThirdParty compiler settings
* `openmpi` : an example of fine tuning openmpi settings for OpenFOAM
* `paraview` : an example of chaining to the standard config/paraview
with a different ParaView_VERSION
* `prefs.csh`, `prefs.sh`: examples 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
# 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 `etc/bashrc` file ___will be lost___ with
the next upgrade.
* Overrides should defined in the `etc/prefs.sh` instead.
See the comments section of the `etc/bashrc` file for more details.
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
```

76
doc/Requirements.md
View File

@ -56,32 +56,26 @@ sudo apt-get install build-essential autoconf autotools-dev cmake gawk gnuplot
sudo apt-get install flex libfl-dev libreadline-dev zlib1g-dev openmpi-bin libopenmpi-dev mpi-default-bin mpi-default-dev sudo apt-get install flex libfl-dev libreadline-dev zlib1g-dev openmpi-bin libopenmpi-dev mpi-default-bin mpi-default-dev
sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev
``` ```
If you intend to use system components, you can also install the following:
```
apt-get install libscotch-dev libptscotch-dev libfftw3-dev libboost-system-dev libboost-thread-dev libcgal-dev
```
Additional libraries will be required if compiling ParaView from
source, however it is recommended to skipped this initially since
it generally represent the main compilation difficulty.
In many cases, a system installation of paraview or a
[precompiled binary][download ParaView]
will be much easier.
Some libraries can be installed from the operating system, or
compiled from the ThirdParty directory.
The default configuration for OpenFOAM assumes OpenMPI from the system
and ThirdParty installations for most others (boost, CGAL, FFTW,
Kahip, Scotch). This is generally the most portable configuration
across various Linux distributions, but it may be desirable to use
more system libraries on Ubuntu.
To inspect the available system versions, use the `apt-cache show` To inspect the available system versions, use the `apt-cache show`
command. For example, command. For example,
``` ```
sudo apt-cache show libboost-dev sudo apt-cache show libopenmpi-dev
sudo apt-cache show libfftw3-dev ```
...
| Program | Ubuntu | Program version |
|-----------|-----------|-----------------|
| gcc | 20.04 | 9.3.0 |
| openmpi | 20.04 | 4.0.3 |
| cmake | 20.04 | 3.16.3 |
| flex | 20.04 | 2.6.4 |
| m4 | 20.04 | 1.4.18 |
If you intend to use system components, you can also install the following:
```
apt-get install libfftw3-dev libscotch-dev libptscotch-dev libboost-system-dev libboost-thread-dev libcgal-dev
``` ```
| Program | apt-cache show | Ubuntu | Version | | Program | apt-cache show | Ubuntu | Version |
@ -92,13 +86,13 @@ sudo apt-cache show libfftw3-dev
| scotch | libscotch-dev | 20.04 | 6.0.9 | | scotch | libscotch-dev | 20.04 | 6.0.9 |
| Program | Ubuntu | Program version | Some libraries can be installed from the operating system, or
|-----------|-----------|-----------------| compiled from the ThirdParty directory.
| gcc | 20.04 | 9.3.0 | The default configuration for OpenFOAM assumes OpenMPI from the system
| openmpi | 20.04 | 4.0.3 | and ThirdParty installations for most others (boost, CGAL, FFTW,
| cmake | 20.04 | 3.16.3 | Kahip, Scotch). This is generally the most portable configuration
| flex | 20.04 | 2.6.4 | across various Linux distributions, but it may be desirable to use
| m4 | 20.04 | 1.4.18 | more system libraries on Ubuntu.
### openSUSE (eg, Leap-15.2) ### openSUSE (eg, Leap-15.2)
@ -116,6 +110,10 @@ If you intend to use system components, you can also install the following:
sudo zypper install fftw3-devel libboost_system-devel libboost_thread-devel sudo zypper install fftw3-devel libboost_system-devel libboost_thread-devel
``` ```
but note that scotch and cgal are only available via the science repository. but note that scotch and cgal are only available via the science repository.
For boost, you may need to specify a specific version. For example,
```
sudo zypper install fftw3-devel libboost_system1_75_0-devel libboost_thread1_75_0-devel
```
This installs This installs
@ -181,26 +179,40 @@ export LD_PRELOAD="libmpi.so"
### Additional libraries ### Additional libraries
When compiled ParaView from source additional dependencies will be When compiled [ParaView][page ParaView] from source additional dependencies will be
required. required.
A partial list is given in the [ThirdParty requirements][link third-require]. A partial list is given in the [ThirdParty requirements][link third-require].
**Please help us with keeping that information up-to-date and accurate.**
However it is ***recommended*** to skipped this initially since
it generally represents the main compilation difficulty encountered.
In many cases, a system installation of paraview or a
[precompiled binary][download ParaView]
will be much easier and likely
[fully adequate for your needs][FAQ ParaView].
Since any ParaView/VTK dependencies are isolated within the
visualization module, it is always possible to compile plugins for
different ParaView versions as well as different VTK/Mesa combinations
at any later stage _without_ recompiling OpenFOAM itself.
<!-- Links --> <!-- Links -->
[page ParaView]: http://www.paraview.org/ [page ParaView]: http://www.paraview.org/
[download ParaView]: https://www.paraview.org/download/ [download ParaView]: https://www.paraview.org/download/
[FAQ ParaView]: https://discourse.paraview.org/t/i-want-to-visualize-my-openfoam-simulation-results-with-paraview-but-im-confused-which-version-should-i-use
<!-- OpenFOAM --> <!-- OpenFOAM -->
[link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md [link openfoam-readme]: https://develop.openfoam.com/Development/openfoam/blob/develop/README.md
[link openfoam-config]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Config.md
[link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md [link openfoam-build]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Build.md
[link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md [link openfoam-require]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Requirements.md
[link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md [link third-readme]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/README.md
[link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md [link third-build]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/BUILD.md
[link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md [link third-require]: https://develop.openfoam.com/Development/ThirdParty-common/blob/develop/Requirements.md
[wiki-config]: https://develop.openfoam.com/Development/openfoam/-/wikis/configuring
--- ---
Copyright 2019-2021 OpenCFD Ltd Copyright 2019-2021 OpenCFD Ltd