diff --git a/building.md b/building.md index c6bc085..083ee49 100644 --- a/building.md +++ b/building.md @@ -1,6 +1,7 @@ [![home](/icons/home.svg "wiki home")](/home) +[![config](/icons/tool.svg "config")](/configuring) [![modules](/icons/layers.svg "modules")](/modules) [![packages](/icons/package.svg "packages")](/precompiled) [![repos](/icons/gitlab.svg "repos")][all-repos] diff --git a/configuring.md b/configuring.md new file mode 100644 index 0000000..c05f31d --- /dev/null +++ b/configuring.md @@ -0,0 +1,294 @@ + + +[![home](/icons/home.svg "wiki home")](/home) +[![build](/icons/cpu.svg "build")](/building) +[![repos](/icons/gitlab.svg "repos")][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/ diff --git a/home.md b/home.md index 323a442..9154477 100644 --- a/home.md +++ b/home.md @@ -13,6 +13,7 @@ to the latest version of [OpenFOAM](http://www.openfoam.com). | [![readme](/icons/book-open.svg "readme")][foam-readme] [**Readme**][foam-readme] | Further cross-links in the OpenFOAM repository to _system requirements_ etc. | | [![access](/icons/info.svg "access")](/page-access-code) [**Access**](/page-access-code) the code | Locations and descriptions of repository branch names | | [![build](/icons/cpu.svg "build")](/building) [**Build**](/building) from source | Information about building and links to build or packaging systems | +| [![config](/icons/tool.svg "config")](/configuring) [**Config**](/configuring) OpenFOAM | Information about OpenFOAM configuration files | | [![modules](/icons/layers.svg "modules")](/modules) [**Modules**](/modules) for OpenFOAM | Additional code modules (eg, [visualization](/modules/visualization)) | | [![upgrade](/icons/chevrons-up.svg "upgrade guide")][upgrade-guide] [**Upgrade**][upgrade-guide] guides | User and developer information for upgrading cases and code to more recent releases | | [![run](/icons/play.svg "run")](/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 diff --git a/icons/tool.svg b/icons/tool.svg new file mode 100644 index 0000000..f3cbf3d --- /dev/null +++ b/icons/tool.svg @@ -0,0 +1 @@ + \ No newline at end of file