diff --git a/.gitmodules b/.gitmodules index b6c563fa58..d15f331dd6 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,8 +1,8 @@ [submodule "cfmesh"] - path = modules/cfmesh + path = plugins/cfmesh url = https://develop.openfoam.com/Community/integration-cfmesh.git [submodule "avalanche"] - path = modules/avalanche + path = plugins/avalanche url = https://develop.openfoam.com/Community/avalanche.git [submodule "adios"] path = modules/adios @@ -18,5 +18,5 @@ path = modules/external-solver url = https://develop.openfoam.com/Modules/external-solver.git [submodule "turbulence-community"] - path = modules/turbulence-community + path = plugins/turbulence-community url = https://gitlab.com/openfoam/community/tc-turbulence/turbulence-community.git diff --git a/plugins/Allwmake b/plugins/Allwmake new file mode 100755 index 0000000000..be14fcecb5 --- /dev/null +++ b/plugins/Allwmake @@ -0,0 +1,42 @@ +#!/bin/sh +cd "${0%/*}" || exit # Run from this directory +targetType=libso +. "${WM_PROJECT_DIR:?}"/wmake/scripts/AllwmakeParseArguments + +#------------------------------------------------------------------------------ +# Default build into OpenFOAM project locations unless specified with +# -prefix or FOAM_MODULE_PREFIX env varable + +# Long form to avoid dash 0.5.8 error (issue #1757) +[ -n "$FOAM_MODULE_PREFIX" ] || FOAM_MODULE_PREFIX="${FOAM_LIBBIN%/*}" +export FOAM_MODULE_PREFIX + +echo "========================================" +case "$FOAM_MODULE_PREFIX" in +(false | none) + echo "OpenFOAM modules disabled (prefix=${FOAM_MODULE_PREFIX})" + echo + exit 0 +esac + +echo "prefix = $FOAM_MODULE_PREFIX" +echo +echo " ignoring possible compilation errors" +echo " make certain to check the output file" +echo +set +e +export WM_CONTINUE_ON_ERROR=true + +#------------------------------------------------------------------------------ + +for name in $(./list-plugins) +do + if [ -d "$name" ] + then + # Use wmake -all instead of Allwmake to allow for overrides + ( cd "$name" && wmake -all $targetType ) + fi +done + + +#------------------------------------------------------------------------------ diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 0000000000..46e44b7c7d --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,134 @@ +[[_TOC_]] + +## OpenFOAM Plugins + +This directory is a location for additional OpenFOAM components or +tools to placed and have them built as part of the normal OpenFOAM +build process. It is assumed that each subdirectory contain an +appropriate `Allwmake` (or `Allwmake.override`) file. + +### How to use + +On the first use, you need to register the submodules, and then update them. +You can execute both steps for all the available submodules (including the +nested ones) as follows while you are at `$WM_PROJECT_DIR`: + +```bash +cd $WM_PROJECT_DIR + +git submodule update --init --recursive +``` + +Executing this single-line command clones all the submodules from their +respective repositories and prepares them for compilation. Note that you can +also make only a certain group of submodules ready by explicitly specifying the +requested submodules' names at the end of the command above. For example, if +you would like to use only the `turbulence-community` submodule, you specify: + +```bash +git submodule update --init --recursive plugins/turbulence-community +``` + +You can display information about the status of submodules as follows: + +```bash +git submodule status --recursive +``` + +An easy way to see which submodules are actually in use: + +```bash +cat .gitmodules +``` + +Which will reveal content resembling the following: +``` +[submodule "xyz"] + path = plugins/xyz + url = ... +... +``` + +If you need to remove a specific submodule or wish to restart the process, +you can simply carry out the task as follows: + +```bash +git submodule deinit plugins/turbulence-community +``` + +This command deregisters the specified submodule and clears the +`plugins/turbulence-community` directory. + +A quick overview of `git submodules` can be found in this +[*blog*][blog git-submodule] with full details in the +[*manpage*][man git-submodule]. + +### Build locations + +Any individual _plugin_ will normally also be able to exist outside of +the plugins directory structure and will typically build into user +locations (`$FOAM_USER_APPBIN`, `$FOAM_USER_LIBBIN`). + +When compiled from the top-level OpenFOAM `Allwmake` or the +`plugins/Allwmake`, they should build into OpenFOAM project locations +(`$FOAM_APPBIN`, `$FOAM_LIBBIN`). This can be adjusted by +supplying an alternative `-prefix=` to the corresponding Allwmake +command. + +| Command | Install location | +|------------|------------------| +| ./Allwmake -prefix=user | `$FOAM_USER_APPBIN`, `$FOAM_USER_LIBBIN` | +| ./Allwmake -prefix=group | `$FOAM_SITE_APPBIN`, `$FOAM_SITE_LIBBIN` | +| ./Allwmake -prefix=openfoam | `$FOAM_APPBIN`, `$FOAM_LIBBIN` | +| ./Allwmake -prefix=/some/pathname | `/some/pathname/bin`, `/some/pathname/lib` | + +### Documentation (doxygen) + +To build the doxygen information for the components, it is also +necessary to link the directories to the doc/ subdirectory. +This is a purely manual operation. + +### Developer Information + +#### Build locations + +To accomodate building into various locations, the plugin code should +be adapted with the following changes: + +- ***Make/files*** + ``` + ... + EXE = $(FOAM_MODULE_APPBIN)/someExecutable + + LIB = $(FOAM_MODULE_LIBBIN)/libSomeLibrary + ``` + +- `Make/options` should include this + ``` + include $(GENERAL_RULES)/module-path-user + ... + ``` + +The following changes to `Make/options` are universally applicable +(ie, work with older or other versions of OpenFOAM), but more verbose. + +- `Make/options` with the following + ``` + sinclude $(GENERAL_RULES)/module-path-user + + /* Failsafe - user locations */ + ifeq (,$(FOAM_MODULE_APPBIN)) + FOAM_MODULE_APPBIN = $(FOAM_USER_APPBIN) + endif + ifeq (,$(FOAM_MODULE_LIBBIN)) + FOAM_MODULE_LIBBIN = $(FOAM_USER_LIBBIN) + endif + ... + ``` + + + +[man git-submodule]: https://git-scm.com/docs/git-submodule +[blog git-submodule]: http://blog.joncairns.com/2011/10/how-to-use-git-submodules/ + +--- diff --git a/modules/avalanche b/plugins/avalanche similarity index 100% rename from modules/avalanche rename to plugins/avalanche diff --git a/modules/cfmesh b/plugins/cfmesh similarity index 100% rename from modules/cfmesh rename to plugins/cfmesh diff --git a/plugins/list-plugins b/plugins/list-plugins new file mode 100755 index 0000000000..27dba5068f --- /dev/null +++ b/plugins/list-plugins @@ -0,0 +1,85 @@ +#!/bin/sh +#------------------------------------------------------------------------------ +# ========= | +# \\ / F ield | OpenFOAM: The Open Source CFD Toolbox +# \\ / O peration | +# \\ / A nd | www.openfoam.com +# \\/ M anipulation | +#------------------------------------------------------------------------------ +# Copyright (C) 2020 OpenCFD Ltd. +#------------------------------------------------------------------------------ +# SPDX-License-Identifier: (GPL-3.0-or-later) +# +# Script +# list-modules +# +# Description +# List module directories +# - each first-level directory with an Allwmake file +# +#------------------------------------------------------------------------------ +cd "${0%/*}" || exit # Run from this directory + +printHelp() { + cat<< HELP 1>&2 + +Usage: ${0##*/} [OPTION] +options: + -help Display help and exit + +List module directories - each first-level directory with an Allwmake file + +HELP + + exit 0 # A clean exit +} + +# Report error and exit +die() +{ + exec 1>&2 + echo + echo "Error encountered:" + while [ "$#" -ge 1 ]; do echo " $1"; shift; done + echo + echo "See '${0##*/} -help' for usage" + echo + exit 1 +} + +#------------------------------------------------------------------------------ + +# Parse options +while [ "$#" -gt 0 ] +do + case "$1" in + -h | -help*) # Short help + printHelp + ;; + + *) + die "Unknown option/argument: '$1'" + ;; + esac + shift +done + + +# Each first-level directory with an Allwmake file +for moduleName in * +do + if [ -f "$moduleName/Allwmake" ] + then + case "$moduleName" in + # Skip some directory names + (build | doc | platform*) + ;; + (*) + echo "$moduleName" + ;; + esac + fi +done + + +#------------------------------------------------------------------------------ diff --git a/modules/turbulence-community b/plugins/turbulence-community similarity index 100% rename from modules/turbulence-community rename to plugins/turbulence-community