From 7b14af4230f2ab18393347ad4de1465ab582614c Mon Sep 17 00:00:00 2001 From: Mark Olesen Date: Tue, 8 Jun 2021 21:35:54 +0200 Subject: [PATCH] DOC: reorganize Requirements.md, additional note for openSUSE leap - move unreferenced Config.md to wiki content --- META-INFO/README.md | 15 +-- README.md | 70 ++++++----- doc/Build.md | 49 ++++---- doc/BuildIssues.md | 15 +-- doc/Config.md | 277 -------------------------------------------- doc/Requirements.md | 78 +++++++------ 6 files changed, 126 insertions(+), 378 deletions(-) delete mode 100644 doc/Config.md diff --git a/META-INFO/README.md b/META-INFO/README.md index d8fe14e37d..7c97198231 100644 --- a/META-INFO/README.md +++ b/META-INFO/README.md @@ -3,8 +3,9 @@ Meta-information is generally for OpenFOAM internal use only. The format, content and meaning may be changed at anytime without -notice. If any of these are changed, these are some of places that -will need to be updated accordingly: +prior notice. +If any of these are changed, these are some of places that will need +to be updated accordingly: - bin/foamEtcFile - bin/tools/foamConfigurePaths @@ -38,7 +39,7 @@ Format: `date +%y%m` - 4-digit year-month (YYMM) integer corresponding to the major release or in unusual cases an intermediate release. - Example, `1712` for the Dec-2017 release. + Example, `2106` for the June-2021 release. #### patch @@ -78,9 +79,9 @@ the saved information needs synchronization. The command ### Notes -The saved information is split into two separate files. The `api-info` -contains more permanent information, whereas the `build-info` is more -transient in nature. +The saved information is split into two separate files. +The `api-info` file contains more permanent information, +whereas the `build-info` is more transient in nature. ---- -2020-06-23 +2021-06-09 diff --git a/README.md b/README.md index a0ca46990f..cbfa00c661 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ individual and group contributors, integrations [governance guided activities](https://www.openfoam.com/governance/). -## Copyright +## License 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 @@ -27,10 +27,11 @@ may redistribute files. OpenCFD Ltd grants use of its OpenFOAM trademark by Third Parties on a licence basis. ESI Group and OpenFOAM Foundation Ltd are currently 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 -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. @@ -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 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 @@ -55,6 +56,11 @@ guides: | [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? 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 displayed from `blockMesh -help`: ``` -Using: OpenFOAM-v1812.local (1812) - visit www.openfoam.com -Build: 65d6551ff7-20190530 (patch=190531) +Using: OpenFOAM-com (2012) - visit www.openfoam.com +Build: b830beb5ea-20210429 (patch=210414) 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 | +| version | com (eg, local development branch) | +| api | 2012 | +| commit | b830beb5ea | +| author date | 20210429 | +| patch-level | (20)210414 | | label/scalar size | 32/64 bits | The Arch information may also include the `solveScalar` size @@ -90,19 +96,19 @@ when OpenFOAM has not yet been compiled: ``` $ wmake -build-info make - api = 1812 - patch = 190531 + api = 2012 + patch = 210414 branch = master - build = 65d6551ff7-20190530 + build = 308af39136-20210426 ``` Similar information is available with `foamEtcFile`, using the `-show-api` or `-show-patch` options. For example, ``` $ foamEtcFile -show-api -1812 +2012 $ foamEtcFile -show-patch -190531 +210414 ``` This output will generally be the easiest to parse for scripts. 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, ``` /path/parent -|-- OpenFOAM-v1912 -\-- ThirdParty-v1912 +|-- OpenFOAM-v2106 +\-- ThirdParty-v2106 ``` 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) * 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 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 * this corresponds to the traditional approach 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 - be `1912` and the original `ThirdParty-v1912/` would be found. + be `2106` and the original `ThirdParty-v2106/` 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*, - `1912-patch190131`, `1912.19W03` + * same as the previous example, but using an unadorned API value. 5. PREFIX/ThirdParty-common - * permits maximum reuse for various versions, for experienced user - who are aware of potential version incompatibilities + * permits maximum reuse for various versions, for experienced + users 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 @@ -184,18 +187,21 @@ ThirdParty directory will contain either an `Allwmake` file or a +[link trademark]: https://www.openfoam.com/opencfd-limited-trade-mark-policy + [repo openfoam]: https://develop.openfoam.com/Development/openfoam/ [repo third]: https://develop.openfoam.com/Development/ThirdParty-common/ [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-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-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-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 +[wiki-config]: https://develop.openfoam.com/Development/openfoam/-/wikis/configuring + ## Useful Links @@ -203,8 +209,8 @@ ThirdParty directory will contain either an `Allwmake` file or a - [Documentation](http://www.openfoam.com/documentation) - [Reporting bugs/issues/feature requests](http://www.openfoam.com/code/bug-reporting.php) - [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/) -- [Community](http://www.openfoam.com/community/), [Governance](http://www.openfoam.com/governance/) +- [Code wiki](https://develop.openfoam.com/Development/openfoam/-/wikis/) and [General wiki](http://wiki.openfoam.com/) +- [Governance](http://www.openfoam.com/governance/), [Governance Projects](https://www.openfoam.com/governance/projects) - [Contacting OpenCFD](http://www.openfoam.com/contact/) -Copyright 2016-2020 OpenCFD Ltd +Copyright 2016-2021 OpenCFD Ltd diff --git a/doc/Build.md b/doc/Build.md index f5786b2873..7853943b80 100644 --- a/doc/Build.md +++ b/doc/Build.md @@ -3,13 +3,13 @@ Prior to building, ensure that the [system requirements][link openfoam-require] are satisfied (including any special [cross-compiling][wiki-cross-compile] considerations), and source the correct OpenFOAM environment. -For example, for the OpenFOAM-v2006 version: +For example, for the OpenFOAM-v2106 version: ``` -source /OpenFOAM-v2006/etc/bashrc +source /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, 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 @@ -86,34 +86,37 @@ you haven't missed any error messages. ``` 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 -cp -r $FOAM_TUTORIALS/incompressible/simpleFoam/pitzDaily ./ -cd pitzDaily -blockMesh -simpleFoam +# Copy tutorial +cp -r "$FOAM_TUTORIALS"/incompressible/simpleFoam/pitzDaily ./ +# Run the tutorial +( cd pitzDaily && blockMesh && simpleFoam ) ``` ### ParaView 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] -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 that you do so ***after*** completing an initial compilation of OpenFOAM. This gets the process started much more quickly. At a later stage, -OpenFOAM can be updated to compile with paraview. Only the affected -applications will be compiled (eg, the blockMesh reader module) and the -balance of the OpenFOAM installation will not affected. +the OpenFOAM visualization module can be compiled for a particular +ParaView version _without_ recompiling OpenFOAM itself. -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 complete rebuild! This is unnecessary. @@ -124,8 +127,9 @@ 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/ +[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 @@ -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-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 -[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 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-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 diff --git a/doc/BuildIssues.md b/doc/BuildIssues.md index 769170855e..ba7cd8e99a 100644 --- a/doc/BuildIssues.md +++ b/doc/BuildIssues.md @@ -1,11 +1,11 @@ -## Known Build Issues (OpenFOAM-v2012) +## Known Build Issues (v2012, v2106) ### Windows cross-compilation Compilation of adios, kahip, metis, ptscotch, boost/cgal do not work. -## Known Build Issues (OpenFOAM-v2006) +## Known Build Issues (v2006) ### Windows cross-compilation @@ -17,11 +17,11 @@ Compilation of kahip and ptscotch do not work. ### 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. -## Known Build Issues (OpenFOAM-v1912) +## Known Build Issues (v1912) ### ParaView, ParaView-Catalyst @@ -62,7 +62,7 @@ Windows. Compile with the `-k` option to skip over these applications for now. -## Known Build Issues (OpenFOAM-v1906) +## Known Build Issues (v1906) ### 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-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-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-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 +[wiki-config]: https://develop.openfoam.com/Development/openfoam/-/wikis/configuring + --- -Copyright 2019-2020 OpenCFD Ltd +Copyright 2019-2021 OpenCFD Ltd diff --git a/doc/Config.md b/doc/Config.md deleted file mode 100644 index 6bc78be382..0000000000 --- a/doc/Config.md +++ /dev/null @@ -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 -``` diff --git a/doc/Requirements.md b/doc/Requirements.md index b73b4c0919..03cefeb9d4 100644 --- a/doc/Requirements.md +++ b/doc/Requirements.md @@ -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 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` command. For example, ``` -sudo apt-cache show libboost-dev -sudo apt-cache show libfftw3-dev -... +sudo apt-cache show libopenmpi-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 | @@ -92,13 +86,13 @@ sudo apt-cache show libfftw3-dev | scotch | libscotch-dev | 20.04 | 6.0.9 | -| 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 | +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. ### 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 ``` 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 @@ -181,26 +179,40 @@ export LD_PRELOAD="libmpi.so" ### Additional libraries -When compiled ParaView from source additional dependencies will be +When compiled [ParaView][page ParaView] from source additional dependencies will be required. 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. + -[page ParaView]: http://www.paraview.org/ +[page ParaView]: http://www.paraview.org/ [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 [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-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-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 +[wiki-config]: https://develop.openfoam.com/Development/openfoam/-/wikis/configuring + --- Copyright 2019-2021 OpenCFD Ltd