darwin3 |
|
|
|
|||
Warning, /doc/phys_pkgs/packages_overview.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit bf89a37a on 2019-03-17 03:29:27 UTC31584ea246 Jeff*0001 .. _using_packages: 0002 8679f9097b Jeff*0003 Using MITgcm Packages 0004 ===================== 0005 0006 b843492ec3 Jeff*0007 The set of packages that will be used within a particular model can be 8679f9097b Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 9.
0008 configured using a combination of both “compile–time” and “run–time”** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 10.
0009 options. Compile–time options are those used to select which packages** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 11.
0010 will be “compiled in” or implemented within the program. Packages 0011 excluded at compile time are completely absent from the executable 0012 program(s) and thus cannot be later activated by any set of subsequent** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 14.
0013 run–time options. 0014 b843492ec3 Jeff*0015 Here we use the following shorthand for various forms of package names, i.e. that appear in package-related filenames, parameters etc.: 0016 all upper case ``${PKG}``, all lower case ``${pkg}``, and mixed case ``${Pkg}``. 0017 For example, for :filelink:`pkg/gmredi` these are ``GMREDI``, ``gmredi``, and ``gmRedi`` respectively. 0018 0019 .. _pkg_inclusion_exclusion: 0020 8679f9097b Jeff*0021 Package Inclusion/Exclusion 0022 --------------------------- 0023** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 25.
0024 There are numerous ways that one can specify compile–time package 0025 inclusion or exclusion and they are all implemented by the ``genmake2`` bf89a37abc Phob*0026 program which was previously described in Section :numref:`building_code`. 8679f9097b Jeff*0027 The options are as follows: 0028** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 30.
0029 #. Setting the ``genamake2`` options ``–enable PKG`` and/or** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 31.
0030 ``–disable PKG`` specifies inclusion or exclusion. This method is 0031 intended as a convenient way to perform a single (perhaps for a quick 0032 test) compilation. 0033 0034 #. By creating a text file with the name ``packages.conf`` in either the 0035 local build directory or the ``-mods=DIR`` directory, one can specify** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 37.
0036 a list of packages (one package per line, with ’\ ``#``\ ’ as the 0037 comment character) to be included. Since the ``packages.conf`` file 0038 can be saved, this is the preferred method for setting and recording 0039 (for future reference) the package configuration. 0040** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 42.
0041 #. For convenience, a list of “standard” package groups is contained in 0042 the ``pkg/pkg_groups`` file. By selecting one of the package group 0043 names in the ``packages.conf`` file, one automatically obtains all 0044 packages in that group. 0045 0046 #. By default (that is, if a ``packages.conf`` file is not found), the 0047 ``genmake2`` program will use the package group default** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 49.
0048 “``default_pkg_list``” as defined in ``pkg/pkg_groups`` file. 0049 0050 #. To help prevent users from creating unusable package groups, the 0051 ``genmake2`` program will parse the contents of the 0052 ``pkg/pkg_depend`` file to determine: 0053 0054 - whether any two requested packages cannot be simultaneously 0055 included (*eg.* *seaice* and *thsice* are mutually exclusive), 0056 0057 - whether additional packages must be included in order to satisfy 0058 package dependencies (*eg.* *rw* depends upon functionality within 0059 the *mdsio* package), and 0060 0061 - whether the set of all requested packages is compatible with the** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 63.
0062 dependencies (and producing an error if they aren’t). 0063 0064 Thus, as a result of the dependencies, additional packages may be 0065 added to those originally requested. 0066 0067 Package Activation 0068 ------------------ 0069** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 71.
0070 For run–time package control, MITgcm uses flags set through a 0071 ``data.pkg`` file. While some packages (*eg.* ``debug``, ``mnc``, 0072 ``exch2``) may have their own usage conventions, most follow a simple 0073 flag naming convention of the form: 0074 0075 :: 0076 0077 usePackageName=.TRUE. 0078 0079 where the ``usePackageName`` variable can activate or disable the 0080 package at runtime. As mentioned previously, packages must be included 0081 in order to be activated. Generally, such mistakes will be detected and 0082 reported as errors by the code. However, users should still be aware of 0083 the dependency. 0084 0085 Package Coding Standards 0086 ------------------------ 0087 0088 The following sections describe how to modify and/or create new MITgcm 0089 packages. 0090 0091 Packages are Not Libraries 0092 ++++++++++++++++++++++++++ 0093 0094 To a beginner, the MITgcm packages may resemble libraries as used in 0095 myriad software projects. While future versions are likely to implement 0096 packages as libraries (perhaps using FORTRAN90/95 syntax) the current 0097 packages (FORTRAN77) are **not** based upon any concept of libraries. 0098 0099 File Inclusion Rules 0100 ++++++++++++++++++++ 0101** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 103.
0102 Instead, packages should be viewed only as directories containing “sets** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 104.
0103 of source files” that are built using some simple mechanisms provided by 0104 ``genmake2``. Conceptually, the build process adds files as they are 0105 found and proceeds according to the following rules: 0106** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 108.
0107 #. ``genmake2`` locates a “core” or main set of source files (the 0108 ``-standarddirs`` option sets these locations and the default value 0109 contains the directories ``eesupp`` and ``model``). 0110 0111 #. ``genmake2`` then finds additional source files by inspecting the 0112 contents of each of the package directories: 0113 0114 #. As the new files are found, they are added to a list of source 0115 files. 0116** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 118.
0117 #. If there is a file name “collision” (that is, if one of the files 0118 in a package has the same name as one of the files previously 0119 encountered) then the file within the newer (more recently** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 121.
0120 visited) package will superseed (or “hide”) any previous file(s) 0121 with the same name. 0122 0123 #. Packages are visited (and thus files discovered) *in the order 0124 that the packages are enabled* within ``genmake2``. Thus, the 0125 files in ``PackB`` may superseed the files in ``PackA`` if 0126 ``PackA`` is enabled before ``PackB``. Thus, package ordering can 0127 be significant! For this reason, ``genmake2`` honors the order in 0128 which packages are specified. 0129 0130 These rules were adopted since they provide a relatively simple means** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 132.
0131 for rapidly including (or “hiding”) existing files with modified 0132 versions. 0133 0134 Conditional Compilation and ``PACKAGES_CONFIG.h`` 0135 +++++++++++++++++++++++++++++++++++++++++++++++++ 0136 0137 Given that packages are simply groups of files that may be added or 0138 removed to form a whole, one may wonder how linking (that is, FORTRAN 0139 symbol resolution) is handled. This is the second way that ``genmake2`` 0140 supports the concept of packages. Basically, ``genmake2`` creates a 0141 ``Makefile`` that, in turn, is able to create a file called** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 143.
0142 ``PACKAGES_CONFIG.h`` that contains a set of C pre-processor (or “CPP”) 0143 directives such as: 0144 0145 :: 0146 0147 #undef ALLOW_KPP 0148 #undef ALLOW_LAND 0149 ... 0150 #define ALLOW_GENERIC_ADVDIFF 0151 #define ALLOW_MDSIO 0152 ... 0153 0154 These CPP symbols are then used throughout the code to conditionally 0155 isolate variable definitions, function calls, or any other code that 0156 depends upon the presence or absence of any particular package. 0157 0158 An example illustrating the use of these defines is: 0159 0160 :: 0161 0162 #ifdef ALLOW_GMREDI 0163 IF (useGMRedi) CALL GMREDI_CALC_DIFF( 0164 I bi,bj,iMin,iMax,jMin,jMax,K, 0165 I maskUp, 0166 O KappaRT,KappaRS, 0167 I myThid) 0168 #endif 0169** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 171.
0170 which is included from the file and shows how both the compile–time** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 172.
0171 ``ALLOW_GMREDI`` flag and the run–time ``useGMRedi`` are nested. 0172 0173 There are some benefits to using the technique described here. The first 0174 is that code snippets or subroutines associated with packages can be 0175 placed or called from almost anywhere else within the code. The second 0176 benefit is related to memory footprint and performance. Since unused 0177 code can be removed, there is no performance penalty due to unnecessary 0178 memory allocation, unused function calls, or extra run-time ``IF (...)`` 0179 conditions. The major problems with this approach are the potentially 0180 difficult-to-read and difficult-to-debug code caused by an overuse of 0181 CPP statements. So while it can be done, developers should exerecise** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 183.
0182 some discipline and avoid unnecesarily “smearing” their package 0183 implementation details across numerous files. 0184 0185 Package Startup or Boot Sequence 0186 ++++++++++++++++++++++++++++++++ 0187 0188 Calls to package routines within the core code timestepping loop can** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 190.
0189 vary. However, all packages should follow a required “boot” sequence 0190 outlined here: 0191 0192 :: 0193 0194 1. S/R PACKAGES_BOOT() 0195 : 0196 CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... ) 0197 0198 0199 2. S/R PACKAGES_READPARMS() 0200 : 0201 #ifdef ALLOW_${PKG} 0202 if ( use${Pkg} ) 0203 & CALL ${PKG}_READPARMS( retCode ) 0204 #endif 0205 0206 3. S/R PACKAGES_INIT_FIXED() 0207 : 0208 #ifdef ALLOW_${PKG} 0209 if ( use${Pkg} ) 0210 & CALL ${PKG}_INIT_FIXED( retCode ) 0211 #endif 0212 0213 4. S/R PACKAGES_CHECK() 0214 : 0215 #ifdef ALLOW_${PKG} 0216 if ( use${Pkg} ) 0217 & CALL ${PKG}_CHECK( retCode ) 0218 #else 0219 if ( use${Pkg} ) 0220 & CALL PACKAGES_CHECK_ERROR('${PKG}') 0221 #endif 0222 0223 5. S/R PACKAGES_INIT_VARIABLES() 0224 : 0225 #ifdef ALLOW_${PKG} 0226 if ( use${Pkg} ) 0227 & CALL ${PKG}_INIT_VARIA( ) 0228 #endif 0229 0230 6. S/R DO_THE_MODEL_IO 0231 0232 #ifdef ALLOW_${PKG} 0233 if ( use${Pkg} ) 0234 & CALL ${PKG}_OUTPUT( ) 0235 #endif 0236 0237 7. S/R PACKAGES_WRITE_PICKUP() 0238 0239 #ifdef ALLOW_${PKG} 0240 if ( use${Pkg} ) 0241 & CALL ${PKG}_WRITE_PICKUP( ) 0242 #endif 0243 0244 Adding a package to PARAMS.h and packages\_boot() 0245 +++++++++++++++++++++++++++++++++++++++++++++++++ 0246 0247 An MITgcm package directory contains all the code needed for that 0248 package apart from one variable for each package. This variable is the bf89a37abc Phob*0249 ``use${Pkg}`` flag. This flag, which is of type logical, **must** be 0250 declared in the shared header file ``PARAMS.h`` in the ``PARM_PACKAGES`` 8679f9097b Jeff*0251 block. This convention is used to support a single runtime control file bf89a37abc Phob*0252 ``data.pkg`` which is read by the startup routine ``packages_boot()`` and 8679f9097b Jeff*0253 that sets a flag controlling the runtime use of a package. This routine 0254 needs to be able to read the flags for packages that were not built at 0255 compile time. Therefore when adding a new package, in addition to bf89a37abc Phob*0256 creating the per-package directory in the ``pkg/`` subdirectory a 0257 developer should add a ``use${Pkg}`` flag to ``PARAMS.h`` and a ``use${Pkg}`` 0258 entry to the ``packages_boot()`` ``PACKAGES`` namelist. The only other 8679f9097b Jeff*0259 package specific code that should appear outside the individual package 0260 directory are calls to the specific package API.
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated from https://github.com/darwinproject/darwin3 by the 2.3.7-MITgcm-0.1 LXR engine. The LXR team |
|