211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries yvyGone saa CFD Direct HB TheArchitects of OpenFOAM Search Q Home OpenFOAM Cloud Training Support Contact OpenFOAM User Guide: 3.2 Compiling applications & libraries [Table of Contents][Index][Version 4 | Version 3] OpenFOAM [prev] [next] Training 3.2 Compiling applications and libraries 26 Feb Houston, USA Compilation is an integral part of application development that requires careful management since every piece of code requires its own set instructions to access 19 Mar Virtual, Americas dependent components of the OpenFOAM library. In uxrx/ninux systems these instructions are often organised and delivered to the compiler using the standard 20 Mar Virtual, uNTxmake utility. OpenFOAM uses its own make compilation script that is based on Europe can be used on any . 23 Apr Berlin, Germany make but is considerably more versatile and easier to use (wma. 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 aset of instructions such as 15 May Virtual, Asi object construction, data storage and class member functions. The file that defines Pacific these functions — the class derinition —takesa .c extension,e.g. aclass ne would be written in the file nc. c. This file can be compiled independently of other code into a binary executable library file known asa shared object library with the .so file extension, i.e. nc. so. When compilinga piece of code, say newapp.c, 19 Jun Virtual, that uses the ne class, ne.c need not be recompiled, rather newapp.c callsthe Americas 22 May Virtual, Americas library at runtime. This is known as dynamic linking. 03 JulLondon, UK hitpse4.crocvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 ans.211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries Main code rc class 03 Jul Virtual, newApp.C nc London eal Definition... 05 Jul London, UK int main() { 05 Jul Virtual, nae London return(0) ; #include "nc. H" } Code... Recent Posts Compiled Compiled. —————— LL Cloud CFD Course | new ‘ nes FI PP [_——_taet _ OpenFOAM Executable =1 option Library Sustainable Figure 3.1: Header files, source files, compilation and linking ‘OpenFOAM Development 3.2.1 Header .: files Learn Effective CFD ‘As ameans of checking errors, the piece of code being compiled must know that the QpenFOAM v5 classes it uses and the operations they perform actually exist. Therefore each class Training requires a class declaration, contained ina header file witha .1 file extension, e.g. _ne.#, that includes the names of the class and its functions. This file is, CFDDFC Command included at the beginning of any piece of code using the class, using the Line Interface 4inetude directive described below, including the class declaration code itself. Any Water Waves in piece of .c code can resource any number of classes and must begin by including QpenFOAM all the .# files required to declare these classes. Those classes in turn can resource other classes and so also begin by including the relevant . # files. By searching recursively down the class hierarchy we can produce a complete list of header files OpenFOAM Barycentric Tracking for all the classes on which the top level .c code ultimately depends; these . files CFD Direct Year 2: are known as the dependencies. With a dependency list, a compiler can check 2016-2017 whether the source files have been updated since their last compilation and selectively compile only those that need to be. CFD Direct Year 2: Development Header files are included in the code using the # include directive, e.g. CFD Direct Year 2: Maintenance This causes the compiler to suspend reading from the current file, to read the included file. This mechanism allows any self-contained piece of code tobe putinto a header file and included at the relevant location in the main code in order to improve code readability. For example, in most OpenFOAM applications the code fdcirec YouTube 837 hitpse4.crocvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 ans211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries for creating fields and reading field input data is included in a file elds.# which is called at the beginning of the code. In this way, header files are not solely used as class declarations. Itis wake 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.. debug, optimised, parallel and profiling, = Support for source code generation programs, ¢.9. 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 OF eshj Lex, co 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 newarp would reside isa directory newapp and the top level file would be newapp.c as shown in Figure 3.2. newApp newApp.C otherHeader.H Make t files options Figure 3.2: Directory structure for an application hipse4.crocopenfoanuser-quideleompiing-applcatonsix10-800003.2.4 Monthly Newsletter First Name Last Name Email Address Type of C ¥ Country ¥ Subscribe! Latest News on Twitter Learn from experts to write quality, C++ code in #OpenFOAM with our acclaimed virtual #Programming #CFD course... https://t.co/NVLWVZ ‘ATw67 hours ago The cost our #OpenFOAM trainings a small fraction of a single core, commercial CFD licence - That's real value. https://t.co/A6wzJbq 7wG14 hours ago sits211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries 3.2.2.1 Including headers The compiler searches for the included header files in the following order, specified with the -2 option in umake: 1. the sim_PRoEcT R/sre/OpenFoaM/inInclude directory; 2alocal intnclude directory, i.e. newApp/InInclude; 3. the localdirectory, i.e. neware: 4. platform dependent paths set in files in the SHM_PROJECT_DIR/wmake/rules/ShM_ARCH/ directory, eg. / ARCH_PATH) ude} 5. other directories specified explicitly in the wake/options file with the -1 option The ake/options file contains the full directory paths to locate header files using the syntax: XB_LINC = \ -I \ -I \ \ -I Notice first that the directory names are preceeded by the -r flag and that the syntax uses the \ to continue the sxE_1Nc across several lines, with no \ after the final entry. 3.2.2.2 Linking to libraries The compiler links to shared object library files in the following directory paths, specified with the 1. option in wnaxe: Lthe sroay_n1eaiw directory; 2. platform dependent paths set in files in the es/ShM_aRcH/ directory,e.g. /usr/x1 $ (MPICH_ARCH_PATH) /1ib, sum_pr ipand 3. other directories specified in the Make/options file. hitpse4.crocvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 Residual controls can now be used on multi-region cases, e.g. conjugate heat transfer in #OpenFOAM-dev #CFD: https://t.co/TonZ8uu SKL17 hours ago ans2nsr018 ‘OpenFOAM User Guide: 3.2 Compling application &Ibres The actual library files to be linked must be specified using the -1 option and removing the 1ib prefixand .so extension from the library file name, eg .s0 isincluded with the flag -inew. By default, smaxe loads the following libraries: L the 1/nopenFoam. so library from the $roam_urasrw directory; 2. platform dependent libraries specified in set in files in the SHM_DIR/rules/SwM_ARCH/ directory, e.g. 1ibm.so from /usz/x11/1ib and liblam.so from $(DAM_ARCH PATH) /1ikt 3. other libraries specified in the wake/options file. The Make/options file contains the full directory paths and library names using the syntax: yPath> \ -1SLibraryl> \ -1 \ To summarise: the directory paths are preceeded by the-1. flag, the library names are preceeded by the-1 flag. 3.2.2.3 Source files to be compiled The compiler requires alist 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 nake/sites file. For many applications the list only includes the name of the main .c file, e.g. newapp.c inthe case of our earlier example. The uake/#i 1es 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 sroam_ares. applications developed by the user are stored in sroam_uszR_ Apps. If the user is developing their own applications, we recommend they create an applications subdirectory in their sim ProsneT_usER_pTR directory containing hitpse4.crocvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 sts211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries 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 wake/riles file should specify that the user's executables are written into their sroam_v: :_apparndirectory. The Make/files file for our example would appear as follows: SIN) /newApp 3.2.2.4 Running wmake The wmake script is generally executed by typing: wnake The is the directory path of the application that is being compiled. Typically, wirake is executed from within the directory of the application being compiled, in which case can be omitted. 3.2.2.5 wmaxe environment variables For information, the environment variable settings used by wnake are listed in Table 3.1. Main paths swm_rogscr_tus?_p1r Full path to installation directory, e.g. $HOME/OpenFOAM $iM_PROJECT Name of the project being compiled: nPOAM gims_PRoJsCT_vERSTON Version of the project being compiled: 5.0 Full path to locate binary executables of OpenFOAM release, e.g. $fi0Ms/ ypenFOAM/OpenFOAM-5. 0 ecutables of the user hips. crocopenfoanvuser-quideleompiing-applcatonsix10-800003.2.4 eins211612018 Other paths/settings SWM_ARCH $iM_ARCH_OPTTON $WM_COMPILER SWM_LABE $M LABEL OPTION $WM_LINK, \ANGUAGE $iam_o. IONS (OpenFOAM User Guide: 3.2 Compiling applications & libraries Fullpathtothe rhirdparty software directory hirdParty-5.0 Machine architecture: 1 inux, 1inux64, Tinuxta64, LinuxARMT, 1inuxPPC64, LinuxPPCé41e 32 or 64 bitarchitecture Compiler being used: cee - - LLVM Clang Clan Compilation option: vebug - debugging, opt optimisation. Choice of compiler: system, thizdarty - compiled in thirdparty directory Full path of the wake directory 32 or 64 bitsize for labels (integers) Int32 oF inté4 compilation of labels Compiler used to link libraries and executables o++. MOPENMPT ~ Parallel communications library: syst=™ system version of openMPr, oPENMPI, S¥STEMMPT, MPICH, MPICH-GM, HPMPT, MPI, QSMPT, SGIMPI. COMPILE! $WM_PRECISTOM_OPTTON, ‘SWM_LABEL_OPPION, COMPILE OPTION e.g. LinuxGceDPInt 640p Precision of the compiled binares, se, single precision or ne, double precision hips. crocopenfoanvuser-quideleompiing-applcatonsix10-800003.2.4 ms.211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries Table 3.1: Environment variable settings for wmaxe. 3.2.3 Removing dependency lists: wolean On execution, is a dependency list fle with a. cep file extension, ep inour example, ina giv s sub-directory of the wake uxGceDPIn’ 64ope. If the user wishes to remove these rake buil e.g. newapE directory, ¢.¢. files,c.g. after making code changes, the user can run the wtean : uclean 5 Again, the isa path to the directory of the application that is being compiled. Typically, wc2ean is executed from within the directory of the application, in which case the path can be omitted. 3.2.4 Compi ng libraries ‘When compiling a library, there are 2 critical differences in the configuration of the filein the waxe directory: = inthe is replaced by iz ~and the target directory for the compiled entity changes from roam _APPStN to $FoaM_ursStN (and an equivalent sroam_usz2_11RB1N directory); les file, =x= = inthe options file, 2xe_uras =is replaced by i18_LrEs = toindicate libraries linked to library being compiled. When wmake is executed it additionally creates a directory named intnciuce that contains soft links to all the files in the library. The 1ntnclude 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 pisofoan isin the inconpress ndirectory and the top level un. ¢. The pisofeam.csource code is: OpenFOAM: The Open Source CFD Tool ght (C) 2011-2016 hosed. crecvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 ans211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries ‘6 7 9 10 a 2 13 4 15 16 v7 18 19 20 2 2 23 24 25 26 27 28 29 30 31 22 33 34 35 36 37 38 39 40 a 42 43 44 45 46 47 48 49 50 st Ww M anipulation 8 License This file is part of OpenFoaM. OpenFOAM is free software: you can redistribute it and/or m under the terms of the GNU General Public License as publis! the Free Software Foundation, either version 3 of the Licen: (at your option) any later version. OpenFOAM is distributed in the hope that it will be useful, ANY WARRANTY; without even the implied warranty of MERCHANT) FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Pub: for more details. You should have received a copy of the GNU General Public L: along with OpenFOAM. If not, see validate (); [LRA Info<< "\nStarting time loop\n” << endl; while (runTime.loop(}) ( Infoc< “Time = " << runTime Yinclude “CourantNo.H" // Pressure-velocity PISO corr ‘ finclade “UEqn.H” Jf -=- PISO Loop while (piso.correct (}) i #include “pEqn.k” laminarTransport..correct (); turbulence->correct (); runTime.write (); Infoc< “ExecutionTime - ” << runTime.elapsedCpuTime() < <<" ClockTime = " << runTime,elapsedClockTime() < << nl << endl; Info<< "End\n” << endl; return 0; [1 POSS ORICON GURUS ERG IN USER SINUSES INDO EIN Gri hitpse4.crocvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 0152nsr018 ‘OpenFOAM User Guide: 3.2 Compling application &Ibres 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. 4 include "evceo.u", which causes the compiler to suspend reading from the current file, pisoroan.c toread the £vcrp. m, pisoFoam resources the turbulence and transport model libraries and therefore requires the necessary header files, specified by the EXE_INC = -1.. option, and links to the libraries with the 2x=_LtEs = -1... option. The sake /opt-ions therefore contains the following: 1 EXE_ING = \ 2 --18(LTB_SRC) /TurbulenceNodels/turbulenceModels/intnelude \ 3 --18(LIB_SRC) /Turaulencexodels/incompressible/Ininclude \ 4-18 (11B_SRC) /eransportwodels \ 5 _~15 (LTR_SRC) /transportMode!s/inconpressible/singlePhaseTransx, ‘ 7 8 9 I$ (LIB SRC) /finiteVolume/InInclude \ -1$ (LIB_SRC) /meshTools/InInclude \ -1$ (LTB_SRC) /sampling/1nInclude 40 EX#_LIBS = \ a -LturbulenceMedels \ 12 ~Lincompressibleturbulencetfodels \ 19 -LincompressibleTransportModels \ 14 -LfiniteVolume \ 18 -ImeshTools \ -Lfvoptions \ -Lsampling -isoFean contains only the pisofoam.c source and the executable is written to the s#0am_areaz directory as all standard applications are. The ake/ri tes therefore contains: 1 pisoFoam, 2 3. EXE = $(FOAM_APPBIN) /pisoFoam Following the recommendations of section 3.2.2.3, the user can compile a separate version of pisoFoam into their local sroam_vssR_pre directory by the following: = copying the pisofean source code to allocal directory, e.g. $fOAM RUN; cd $POAM_RUN op -r SFOAM SOLVERS/incompressible/pisoFoam . cd pisoFeam hitpse4.crocvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 ans211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries les file as follows; = executing sake. ce file pisoFoam.c 40pt/pin/pisoFoam The user can now try recompiling and will receive a message similar to the following to say that the executable is up to date and compiling is not necessary: | make: ../bin/pisoFoam is up to date. : The user can compile the application from scratch by removing the dependency list with 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 $it_PROJECT_DIR/etc/contro1Dict file; should the user wish to change the settings they should make a copy to their sou directory, i.e. $HOME/. QpenFOaM, o/controtpict file. The list of possible switches is extensive and can be viewed by running the £o: 12s application. Most of the switches correspond to a class or range of functionality and can be switched on by their inclusion in the nDebugSwi ‘01Dict file, and by being set to 1. For example, hitpse4.crocvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 yas2nsr018 ‘OpenFOAM User Guide: 3.2 Compling application &Ibres OpenFOAM can perform the checking of dimensional units in all calculations by setting the dimensioaset 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 £i1eModi ficationSxew, 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 ci leModicicationskew keyword is the time in seconds that OpenFOAM will subtract from the file write time when assessing, whether the file has been newly modified. High level debugging switches - sub-dictionary vebucswi tches level Overall level of debugging messaging for OpenFOAM- - 3levels 0, 1,2 LduNatrix Messaging for solver convergence during arun ~ 3levels 0,1, 2 Optimisation switches - sub-dictionary opt imicationswitches fileModi ficationskew Atime in seconds that should be set higher than the maximum delay in NFS updates and clock difference for running OpenFOAM over a NFS. fileMedificationChecking | Method of checking whether files have been modified during a simulation, either reading the ‘timeStamp or using inot fy; versions that read only master-node data exist, times: Master. connsType Parallel communications type: nonBiocking, scheduled, blocking, floatTranster If 1, will compact numbers to s1oae precision before transfer; default is 0 hips. crocopenfoanvuser-quideleompiing-applcatonsix10-800003.2.4 sss211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries Optimises global sum for parallel processing; sets number of processors above which hierarchical sum is performed rather than a linear sum (default 16) Table 3.2: Runtime message switches. 3.2.7 Linking new user-defined libraries to existing applications The situation may arise that a user creates anew 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, exc. 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 controlpict file for a case and enter the full names of the libraries within alist (as quoted string entries). For example, if a user wished to link the libraries new and new2 at run-time, they would simply need to add the following tothe case controipict file: [prev] [next] © 2011-2016 OpenFOAM Foundation & ChrisGreenshields ff} 2ndMarch2017 @ User Guide <— OpenFOAM v5 User Guide: 3.1 Programming language, OpenFOAM hitpse4.crocvopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 sans211612018 (OpenFOAM User Guide: 3.2 Compiling applications & libraries OpenFOAM V5 User Guide: 3.3 Running applications Copyright © 2015-2018 CFD Direct Ltd ContactUs Google+ Twitter Linkedin YouTube Website Terms of Use Privacy hips. crecopenfoanvuser-guideleompiing-applcatonsix10-800003.2.4 ssi