[version 12][version 11][version 10][version 9][version 8][version 7][version 6]
3.2 Compiling applications and libraries
Compilation is an integral part of application development that requires careful management since every piece of code requires its own set instructions to access dependent components of the OpenFOAM library. In UNIX/Linux systems these instructions are often organised and delivered to the compiler using the standard UNIXmake utility. OpenFOAM uses its own wmake compilation script that is based on make but is considerably more versatile and easier to use (wmake can be used on any code, not only the OpenFOAM library). To understand the compilation process, we first need to explain certain aspects of C++ and its file structure, shown schematically in Figure 3.1. A class is defined through a set of instructions such as object construction, data storage and class member functions. The file that defines these functions — the class definition — takes a .C extension, e.g. a class nc would be written in the file nc.C. This file can be compiled independently of other code into a binary executable library file known as a shared object library with the .so file extension, i.e.nc.so. When compiling a piece of code, say newApp.C, that uses the nc class, nc.C need not be recompiled, rather newApp.C calls the nc.so library at runtime. This is known as dynamic linking.
3.2.1 Header .H files
As a means of checking errors, the piece of code being compiled must know that the classes it uses and the operations they perform actually exist. Therefore each class requires a class declaration, contained in a header file with a .H file extension, e.g. nc.H, that includes the names of the class and its functions. This file is included at the beginning of any piece of code using the class, using the #include directive described below, including the class declaration code itself. Any piece of .C code can resource any number of classes and must begin by including all the .H files required to declare these classes. Those classes in turn can resource other classes and so also begin by including the relevant .H files. By searching recursively down the class hierarchy we can produce a complete list of header files for all the classes on which the top level .C code ultimately depends; these .H files are known as the dependencies. With a dependency list, a compiler can check whether the source files have been updated since their last compilation and selectively compile only those that need to be.
Header files are included in the code using the # include directive, e.g.
# include "otherHeader.H";
It is wmake that performs the task of maintaining file dependency lists amongst other functions listed below.
- Automatic generation and maintenance of file dependency lists, i.e. lists of files which are included in the source files and hence on which they depend.
- Multi-platform compilation and linkage, handled through appropriate directory structure.
- Multi-language compilation and linkage, e.g. C, C++, Java.
- Multi-option compilation and linkage, e.g. debug, optimised, parallel and profiling.
- Support for source code generation programs, e.g. lex, yacc, IDL, MOC.
- Simple syntax for source file lists.
- Automatic creation of source file lists for new codes.
- Simple handling of multiple shared or static libraries.
- Extensible to new machine types.
- Extremely portable, works on any machine with: make; sh, ksh or csh; lex, cc.
3.2.2 Compiling with wmake
OpenFOAM applications are organised using a standard convention that the source code of each application is placed in a directory whose name is that of the application. The top level source file then takes the application name with the .C extension. For example, the source code for an application called newApp would reside is a directory newApp and the top level file would be newApp.C as shown in Figure 3.2.
wmake then requires the directory must contain a Make subdirectory containing 2 files, options and files, that are described in the following sections.
3.2.2.1 Including headers
The compiler searches for the included header files in the following order, specified with the -I option in wmake:
- the $WM_PROJECT_DIR/src/OpenFOAM/lnInclude directory;
- a local lnInclude directory, i.e.newApp/lnInclude;
- the local directory, i.e.newApp;
- platform dependent paths set in files in the $WM_PROJECT_DIR/wmake/rules/$WM_ARCH/ directory, e.g./usr/X11/include and $(MPICH_ARCH_PATH)/include;
- other directories specified explicitly in the Make/options file with the -I option.
The Make/options file contains the full directory paths to locate header files using the syntax:
EXE_INC = \
-I<directoryPath1> \
-I<directoryPath2> \
… \
-I<directoryPathN>
3.2.2.2 Linking to libraries
The compiler links to shared object library files in the following directory paths, specified with the -L option in wmake:
- the $FOAM_LIBBIN directory;
- platform dependent paths set in files in the $WM_DIR/rules/$WM_ARCH/ directory, e.g./usr/X11/lib and $(MPICH_ARCH_PATH)/lib;
- other directories specified in the Make/options file.
The actual library files to be linked must be specified using the -l option and removing the lib prefix and .so extension from the library file name, e.g. libnew.so is included with the flag -lnew. By default, wmake loads the following libraries:
- the libOpenFOAM.so library from the $FOAM_LIBBIN directory;
- platform dependent libraries specified in set in files in the $WM_DIR/rules/$WM_ARCH/ directory, e.g. libm.so from /usr/X11/lib and liblam.so from $(LAM_ARCH_PATH)/lib;
- other libraries specified in the Make/options file.
The Make/options file contains the full directory paths and library names using the syntax:
EXE_LIBS = \
-L<libraryPath> \
-l<library1> \
-l<library2> \
… \
-l<libraryN>
3.2.2.3 Source files to be compiled
The compiler requires a list of .C source files that must be compiled. The list must contain the main .C file but also any other source files that are created for the specific application but are not included in a class library. For example, users may create a new class or some new functionality to an existing class for a particular application. The full list of .C source files must be included in the Make/files file. For many applications the list only includes the name of the main .C file, e.g. newApp.C in the case of our earlier example.
The Make/files file also includes a full path and name of the compiled executable, specified by the EXE = syntax. Standard convention stipulates the name is that of the application, i.e.newApp in our example. The OpenFOAM release offers two useful choices for path: standard release applications are stored in $FOAM_APPBIN; applications developed by the user are stored in $FOAM_USER_APPBIN.
If the user is developing their own applications, we recommend they create an applications subdirectory in their $WM_PROJECT_USER_DIR directory containing the source code for personal OpenFOAM applications. As with standard applications, the source code for each OpenFOAM application should be stored within its own directory. The only difference between a user application and one from the standard release is that the Make/files file should specify that the user’s executables are written into their $FOAM_USER_APPBIN directory. The Make/files file for our example would appear as follows:
newApp.C
EXE = $(FOAM_USER_APPBIN)/newApp
3.2.2.4 Running wmake
The wmake script is generally executed by typing:
wmake <optionalDirectory>
3.2.2.5 wmake environment variables
For information, the environment variable settings used by wmake are listed in Table 3.1.
Main paths
| |
Full path to installation directory, e.g.$HOME/OpenFOAM |
|
Name of the project being compiled: OpenFOAM |
|
Version of the project being compiled: 6 |
|
Full path to locate binary executables of OpenFOAM release, e.g. $HOME/OpenFOAM/OpenFOAM-6 |
|
Full path to locate binary executables of the user e.g. $HOME/OpenFOAM/${USER}-6 |
|
Full path to the ThirdParty software directory e.g. $HOME/OpenFOAM/ThirdParty-6 |
|
|
|
Other paths/settings
| |
Machine architecture: linux, linux64, linuxIa64, linuxARM7, linuxPPC64, linuxPPC64le |
|
32 or 64 bit architecture |
|
Compiler being used: Gcc - gcc, ICC - Intel, Clang - LLVM Clang |
|
Compilation option: Debug - debugging, Opt optimisation. |
|
Choice of compiler: system, ThirdParty - compiled in ThirdParty directory |
|
Full path of the wmake directory |
|
32 or 64 bit size for labels (integers) |
|
Int32 or Int64 compilation of labels |
|
Compiler used to link libraries and executables c++. |
|
Parallel communications library: SYSTEMOPENMPI - system version of openMPI, OPENMPI, SYSTEMMPI, MPICH, MPICH-GM, HPMPI, MPI, QSMPI, SGIMPI. |
|
= $WM_ARCH… |
|
Precision of the compiled binares, SP, single precision or DP, double precision |
|
|
|
3.2.3 Removing dependency lists: wclean
On execution, wmake builds a dependency list file with a .dep file extension, e.g. newApp.C.dep in our example, in a $WM_OPTIONS sub-directory of the Make directory, e.g. Make/linuxGccDPInt64Opt. If the user wishes to remove these files, e.g. after making code changes, the user can run the wclean script by typing:
wclean <optionalDirectory>
3.2.4 Compiling libraries
When compiling a library, there are 2 critical differences in the configuration of the file in the Make directory:
- in the files file, EXE = is replaced by LIB = and the target directory for the compiled entity changes from $FOAM_APPBIN to $FOAM_LIBBIN (and an equivalent $FOAM_USER_LIBBIN directory);
- in the options file, EXE_LIBS = is replaced by LIB_LIBS = to indicate libraries linked to library being compiled.
When wmake is executed it additionally creates a directory named lnInclude that contains soft links to all the files in the library. The lnInclude directory is deleted by the wclean script when cleaning library source code.
3.2.5 Compilation example: the pisoFoam application
The source code for application pisoFoam is in the $FOAM_APP/solvers/incompressible/pisoFoam directory and the top level source file is named pisoFoam.C. The pisoFoam.C source code is:
2 ========= |
3 \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4 \\ / O peration |
5 \\ / A nd | Copyright (C) 2011-2018 OpenFOAM Foundation
6 \\/ M anipulation |
7 -------------------------------------------------------------------------------
8 License
9 This file is part of OpenFOAM.
10
11 OpenFOAM is free software: you can redistribute it and/or modify it
12 under the terms of the GNU General Public License as published by
13 the Free Software Foundation, either version 3 of the License, or
14 (at your option) any later version.
15
16 OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
17 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19 for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
23
24 Application
25 pisoFoam
26
27 Description
28 Transient solver for incompressible, turbulent flow, using the PISO
29 algorithm.
30
31 Sub-models include:
32 - turbulence modelling, i.e. laminar, RAS or LES
33 - run-time selectable MRF and finite volume options, e.g. explicit porosity
34
35 \*---------------------------------------------------------------------------*/
36
37 #include "fvCFD.H"
38 #include "singlePhaseTransportModel.H"
39 #include "turbulentTransportModel.H"
40 #include "pisoControl.H"
41 #include "fvOptions.H"
42
43 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
44
45 int main(int argc, char *argv[])
46 {
47 #include "postProcess.H"
48
49 #include "setRootCaseLists.H"
50 #include "createTime.H"
51 #include "createMesh.H"
52 #include "createControl.H"
53 #include "createFields.H"
54 #include "initContinuityErrs.H"
55
56 turbulence->validate();
57
58 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
59
60 Info<< "\nStarting time loop\n" << endl;
61
62 while (runTime.loop())
63 {
64 Info<< "Time = " << runTime.timeName() << nl << endl;
65
66 #include "CourantNo.H"
67
68 // Pressure-velocity PISO corrector
69 {
70 #include "UEqn.H"
71
72 // --- PISO loop
73 while (piso.correct())
74 {
75 #include "pEqn.H"
76 }
77 }
78
79 laminarTransport.correct();
80 turbulence->correct();
81
82 runTime.write();
83
84 Info<< "ExecutionTime = " << runTime.elapsedCpuTime() << " s"
85 << " ClockTime = " << runTime.elapsedClockTime() << " s"
86 << nl << endl;
87 }
88
89 Info<< "End\n" << endl;
90
91 return 0;
92 }
93
94
95 // ************************************************************************* //
The code begins with a brief description of the application contained within comments over 1 line (//) and multiple lines (/*…*/). Following that, the code contains several # include statements, e.g. # include "fvCFD.H", which causes the compiler to suspend reading from the current file, pisoFoam.C to read the fvCFD.H.
pisoFoam resources the turbulence and transport model libraries and therefore requires the necessary header files, specified by the EXE_INC = -I… option, and links to the libraries with the EXE_LIBS = -l… option. The Make/options therefore contains the following:
2 -I$(LIB_SRC)/TurbulenceModels/turbulenceModels/lnInclude \
3 -I$(LIB_SRC)/TurbulenceModels/incompressible/lnInclude \
4 -I$(LIB_SRC)/transportModels \
5 -I$(LIB_SRC)/transportModels/incompressible/singlePhaseTransportModel \
6 -I$(LIB_SRC)/finiteVolume/lnInclude \
7 -I$(LIB_SRC)/meshTools/lnInclude \
8 -I$(LIB_SRC)/sampling/lnInclude
9
10 EXE_LIBS = \
11 -lturbulenceModels \
12 -lincompressibleTurbulenceModels \
13 -lincompressibleTransportModels \
14 -lfiniteVolume \
15 -lmeshTools \
16 -lfvOptions \
17 -lsampling
pisoFoam contains only the pisoFoam.C source and the executable is written to the $FOAM_APPBIN directory as all standard applications are. The Make/files therefore contains:
Following the recommendations of section 3.2.2.3, the user can compile a separate version of pisoFoam into their local $FOAM_USER_DIR directory by the following:
- copying the pisoFoam source code to a local directory, e.g. $FOAM_RUN;
cd $FOAM_RUN
cp -r $FOAM_SOLVERS/incompressible/pisoFoam .
cd pisoFoam - editing the Make/files file as follows;
- executing wmake. wmake
The code should compile and produce a message similar to the following
Making dependency list for source file pisoFoam.C
g++ -std=c++0x -m32…
…
-o ... platforms/linuxGccDPInt64Opt/bin/pisoFoam
make: …/bin/pisoFoam is up to date.
wclean
3.2.6 Debug messaging and optimisation switches
OpenFOAM provides a system of messaging that is written during runtime, most of which are to help debugging problems encountered during running of a OpenFOAM case. The switches are listed in the $WM_PROJECT_DIR/etc/controlDict file; should the user wish to change the settings they should make a copy to their $HOME directory, i.e. $HOME/.OpenFOAM/6/controlDict file. The list of possible switches is extensive and can be viewed by running the foamDebugSwitches application. Most of the switches correspond to a class or range of functionality and can be switched on by their inclusion in the controlDict file, and by being set to 1. For example, OpenFOAM can perform the checking of dimensional units in all calculations by setting the dimensionSet switch to 1. There are some switches that control messaging at a higher level than most, listed in Table 3.2.
In addition, there are some switches that control certain operational and optimisation issues. These switches are also listed in Table 3.2. Of particular importance is fileModificationSkew. OpenFOAM scans the write time of data files to check for modification. When running over a NFS with some disparity in the clock settings on different machines, field data files appear to be modified ahead of time. This can cause a problem if OpenFOAM views the files as newly modified and attempting to re-read this data. The fileModificationSkew keyword is the time in seconds that OpenFOAM will subtract from the file write time when assessing whether the file has been newly modified.
3.2.7 Linking new user-defined libraries to existing applications
The situation may arise that a user creates a new library, say new, and wishes the features within that library to be available across a range of applications. For example, the user may create a new boundary condition, compiled into new, that would need to be recognised by a range of solver applications, pre- and post-processing utilities, mesh tools, etc. Under normal circumstances, the user would need to recompile every application with the new linked to it.
Instead there is a simple mechanism to link one or more shared object libraries dynamically at run-time in OpenFOAM. Simply add the optional keyword entry libs to the controlDict file for a case and enter the full names of the libraries within a list (as quoted string entries). For example, if a user wished to link the libraries new1 and new2 at run-time, they would simply need to add the following to the case controlDict file:
libs
(
"libnew1.so"
"libnew2.so"
);