mirror of
https://develop.openfoam.com/Development/openfoam.git
synced 2025-11-28 03:28:01 +00:00
Relocate unreferenced config information from source repo to wiki
Mark Olesen
@ -1,6 +1,7 @@
|
||||
<!-- --- title: Building from source -->
|
||||
|
||||
[](/home)
|
||||
[](/configuring)
|
||||
[](/modules)
|
||||
[](/precompiled)
|
||||
[][all-repos]
|
||||
|
||||
294
configuring.md
Normal file
294
configuring.md
Normal file
@ -0,0 +1,294 @@
|
||||
<!-- --- title: Configuring -->
|
||||
|
||||
[](/home)
|
||||
[](/building)
|
||||
[][all-repos]
|
||||
|
||||
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.
|
||||
|
||||
|
||||
[[_TOC_]]
|
||||
|
||||
## 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/2106
|
||||
$HOME/.OpenFOAM
|
||||
/path/OpenFOAM-v2106/site/2106/etc
|
||||
/path/OpenFOAM-v2106/site/etc
|
||||
/path/OpenFOAM-v2106/etc
|
||||
```
|
||||
|
||||
Both the *user* paths (located as `$HOME/.OpenFOAM/`) and the *group*
|
||||
paths (`/path/OpenFOAM-v2106/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-v2106 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-v2106 clang50-int64
|
||||
source /path/to/OpenFOAM-v2106 gcc82
|
||||
source /path/to/OpenFOAM-v2106 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/openfoam2106" \
|
||||
-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
|
||||
```
|
||||
|
||||
|
||||
### Additional information
|
||||
|
||||
The `bashrc` or `cshrc` files 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
|
||||
|
||||
|
||||
--------
|
||||
|
||||
Copyright (C) 2019-2021 OpenCFD Ltd.
|
||||
|
||||
[all-repos]: https://develop.openfoam.com/Development/
|
||||
3
home.md
3
home.md
@ -13,6 +13,7 @@ to the latest version of [OpenFOAM](http://www.openfoam.com).
|
||||
| [][foam-readme] [**Readme**][foam-readme] | Further cross-links in the OpenFOAM repository to _system requirements_ etc. |
|
||||
| [](/page-access-code) [**Access**](/page-access-code) the code | Locations and descriptions of repository branch names |
|
||||
| [](/building) [**Build**](/building) from source | Information about building and links to build or packaging systems |
|
||||
| [](/configuring) [**Config**](/configuring) OpenFOAM | Information about OpenFOAM configuration files |
|
||||
| [](/modules) [**Modules**](/modules) for OpenFOAM | Additional code modules (eg, [visualization](/modules/visualization)) |
|
||||
| [][upgrade-guide] [**Upgrade**][upgrade-guide] guides | User and developer information for upgrading cases and code to more recent releases |
|
||||
| [](/running) [**Run**](/running) OpenFOAM | Using the OpenFOAM environment |
|
||||
@ -72,7 +73,7 @@ latest service offerings.
|
||||
|
||||
----
|
||||
|
||||
Copyright (C) 2019-2020 OpenCFD Ltd.
|
||||
Copyright (C) 2019-2021 OpenCFD Ltd.
|
||||
|
||||
[upgrade-guide]: /upgrade/upgrade
|
||||
[code-devel]: /coding/git-workflow
|
||||
|
||||
1
icons/tool.svg
Normal file
1
icons/tool.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-tool"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"></path></svg>
|
||||
|
After Width: | Height: | Size: 386 B |
Reference in New Issue
Block a user