var/external/crtm_2.3.0/README

   1 JCSDA CRTM v2.3.x Build Instructions
   2 ====================================
   3
   4 $Revision: 99117 $
   5
   6
   7 CRTM SUPPORT EMAIL: ncep.list.emc.jcsda_crtm.support@noaa.gov
   8
   9 If you have problems building the library please include the
  10 generated "config.log" file in your email correspondence.
  11
  12
  13
  14             Contents
  15   ===============================
  16   1. Configuration
  17     a. The easy (I hope) way
  18     b. The more flexible way
  19   2. Building the library
  20   3. Testing the library
  21   4. Installing the library
  22     a. GNU Install
  23          - Linking to the library
  24     b. NCO Install
  25          - Linking to the library
  26     c. Uninstalling the library
  27   5. Cleaning up
  28   6. Feedback and contact info
  29
  30
  31
  32
  33 1. CONFIGURATION
  34 ================
  35
  36 The CRTM tarball directory structure looks like:
  37  ./
  38   |-README  .................. this file
  39   |-configure  ............... configuration script
  40   |-Makefile.in  ............. makefile template
  41   |-config-setup/  ........... "courtesy" configuration definition scripts
  42   |-fix/  .................... coefficient datafiles
  43   `-libsrc/  ................. library source files
  44
  45
  46 The build system for the CRTM uses an autoconf-generated configure script.
  47
  48 The build makefiles now assume that environment variables (envars) will
  49 be defined that describe the compilation environment. The envars
  50 that *must* be defined are:
  51   FC:      the Fortran95/2003 compiler executable,
  52   FCFLAGS: the flags/switches provided to the Fortran compiler,
  53
  54
  55
  56 a. The easy (I hope) way...
  57 -------------------------
  58
  59 Several shell (and C shell) source files are provided for the compilers to
  60 which we have access and have tested here. These shell source files are in
  61 the "config-setup/" subdirectory of the tarball.
  62
  63 The current list of test compiler environments in the config-setup/ directory
  64 are:
  65
  66   $ ls  config-setup/
  67   ftn.setup                 ftn.setup.csh
  68   g95-debug.setup           gfortran.setup.csh     pgf95.setup
  69   g95-debug.setup.csh       ifort-debug.setup      pgf95.setup.csh
  70   g95.setup                 ifort-debug.setup.csh  xlf2003-debug.setup
  71   g95.setup.csh             ifort.setup            xlf2003-debug.setup.csh
  72   gfortran-debug.setup      ifort.setup.csh        xlf2003.setup
  73   gfortran-debug.setup.csh  pgf95-debug.setup      xlf2003.setup.csh
  74   gfortran.setup            pgf95-debug.setup.csh
  75
  76 All of the above files define values for the envars FC, FCFLAGS, LDFLAGS,
  77 and LIBS.
  78
  79 To use these files to define the CRTM build environment, you should source
  80 them. For example, if you use the sh/bash/ksh shells and you want to setup
  81 for a build using the gfortran compiler using debug options you would type:
  82
  83   $ . config-setup/gfortran-debug.setup
  84
  85 If you are a C shell aficionado, the equivalent command would be
  86
  87   % source config-setup/gfortran-debug.setup.csh
  88
  89 You can tailor you build environment by modifying the relevant build
  90 configuration setup file in the "config-setup/" subdirectory.
  91
  92 Or, if you are going to be testing library builds multiple times, create your
  93 own configuration setup file.
  94
  95 Once you've sourced the setup file, you run the configuration script like so:
  96
  97   $ ./configure --prefix=<install directory>
  98
  99 The --prefix switch sets the installation directory and defaults to /usr/local so
 100 make sure you set it to a directory in which you have write access.
 101
 102 By default, the CRTM is built for big-endian I/O. The --disable-big-endian switch
 103 builds the library and test programs for little-endian I/O:
 104
 105   $ ./configure --disable-big-endian --prefix=<install directory>
 106
 107
 108
 109 b. The more flexible way
 110 ------------------------
 111
 112 If you need more flexibility in the library build you can specify the necessary
 113 information directly to the configure script that generates the makefiles. For
 114 example, for the intel ifort compiler:
 115
 116   $ ./configure --prefix=${PWD} \
 117                 --disable-big-endian \
 118                 FC="ifort" \
 119                 FCFLAGS="-O3 -g -traceback"
 120
 121 The --prefix switch sets the installation directory and defaults to /usr/local so
 122 make sure you set it to a directory in which you have write access.
 123
 124 The --disable-big-endian switch builds the library and test programs for little-endian
 125 I/O. The default is big-endian I/O.
 126
 127 NOTE: The --disable-big-endian switch (whether it's turned on or off) modifies the
 128       compilation environment by setting (or deselecting) the compiler switches
 129       that control the endian-ness of the I/O. As such, you should be careful if
 130       you set those compiler switches directly on the command line via FCFLAGS.
 131
 132
 133
 134
 135 2. BUILDING THE LIBRARY
 136 =======================
 137
 138 To start the library build for a particular configuration, simply type
 139
 140   $ make
 141
 142
 143
 144
 145 3. CHECKING THE LIBRARY BUILD
 146 =============================
 147
 148 To run the accompanying tests using the just-built library, simply type
 149
 150   $ make check
 151
 152 This will build and run any tests. The current output from the (successful)
 153 test runs looks like:
 154
 155   ========================================
 156     Running test: big-endian I/O on little-endian platform...
 157
 158
 159        **********************************************************
 160                                check_crtm
 161
 162         Check/example program for the CRTM Forward and K-Matrix
 163         functions using big_endian coefficient datafiles
 164
 165         CRTM Version: REL-2.3.x
 166        **********************************************************
 167
 168
 169        Initializing the CRTM...
 170
 171        Processing a total of 421 channels...
 172          399 from cris399_npp
 173          22 from atms_npp
 174
 175        Calling the CRTM functions for cris399_npp...
 176
 177        Calling the CRTM functions for atms_npp...
 178
 179        Destroying the CRTM...
 180
 181     TEST SUCCESSFUL!
 182   ========================================
 183
 184
 185
 186
 187 4. INSTALLING THE LIBRARY
 188 =========================
 189
 190 Installation of the library *always* occurs into its own directory within the
 191 directory specified by the --prefix switch. The name of the installation
 192 directory follows the convention:
 193
 194   <library name>_<version>
 195
 196 So, if a library version (say, v2.3.0) build was configured with --prefix=$PWD
 197 then the installation directory will be
 198
 199   ${PWD}/crtm_v2.3.0
 200
 201
 202
 203 a. GNU Install
 204 --------------
 205
 206 To perform a GNU-type install, type:
 207
 208   $ make install
 209
 210 For a library version, say, v2.3.0, this will create a directory called
 211 "crtm_v2.3.0". That directory structure is shown below:
 212
 213   crtm_v2.3.0/
 214     |
 215     |--include/
 216     |    |
 217     |    |--accoeff_binary_io.mod
 218     |    |--accoeff_define.mod
 219     |    ...etc...
 220     |    |--zeeman_input_define.mod
 221     |    `--zeeman_utility.mod
 222     |
 223     `--lib/
 224          |
 225          `--libcrtm.a
 226
 227 Note that the only version-numbered item in this type of install is the name of
 228 the installation directory itself.
 229
 230
 231 Linking to the library
 232 ......................
 233
 234 Let's assume the above install was moved into "/usrx/local/nceplibs", to use the
 235 library in this structure in your own application, the usual environment variables
 236 would be modified something like:
 237
 238   libroot="/usrx/local/nceplibs/crtm_v2.3.0"
 239   FCFLAGS="-I${libroot}/include ${FCFLAGS}"
 240   LDFLAGS="-L${libroot}/lib ${LDFLAGS}"
 241   LIBS="-lcrtm"
 242
 243 (with appropriate syntax changes for csh)
 244
 245
 246
 247 b. NCO Install
 248 --------------
 249
 250 To install the library conforming to the NCO directory organisation and naming
 251 conventions, type:
 252
 253   $ make nco_install
 254
 255 For a library version, say, v2.3.0, this will create a directory called
 256 "crtm_v2.3.0". That directory is organised according to the current NCO structure
 257 on WCOSS in /nwprod/lib, as shown below:
 258
 259   crtm_v2.3.0/
 260     |
 261     |--libcrtm_v2.3.0.a
 262     |
 263     `--incmod/
 264          |
 265          `--crtm_v2.3.0/
 266               |
 267               |--accoeff_binary_io.mod
 268               |--accoeff_define.mod
 269               ...etc..
 270               |--zeeman_input_define.mod
 271               `--zeeman_utility.mod
 272
 273 The contents of the "crtm_v2.3.0" directory can then be moved into the official
 274 /nwprod/lib location as needed.
 275
 276 NOTE: ********** IMPORTANT - READ THIS **********
 277       To avoid installing over the top of an existing installation, this NCO-style
 278       installation *DOES NOT* install the CRTM into an existing directory. If the
 279       installation directory already exists, an error is issued and the installation
 280       process halts.
 281       ********** IMPORTANT - HAVE YOU READ IT? **********
 282
 283
 284 Linking to the library
 285 ......................
 286
 287 Let's assume the above install was moved into "/usrx/local/nceplibs", to use the
 288 library in this structure in your own application, the usual environment variables
 289 would be modified something like:
 290
 291   libroot="/usrx/local/nceplibs"
 292   FCFLAGS="-I${libroot}/incmod/crtm_v2.3.0 ${FCFLAGS}"
 293   LDFLAGS="-L${libroot} ${LDFLAGS}"
 294   LIBS="-lcrtm_v2.3.0"
 295
 296 (with appropriate syntax changes for csh)
 297
 298
 299
 300 c. Uninstalling the library
 301 ---------------------------
 302
 303 To uninstall the library (assuming you haven't moved the installation directory
 304 contents somewhere else) you can type:
 305
 306   $ make uninstall
 307
 308 This will DELETE the created installation directory. So, for a library version,
 309 say, v2.3.0, if your configure script invocation was something like
 310
 311   $ ./configure --prefix=${PWD} ...other command line arguments...
 312
 313 then the "uninstall" target will delete the "${PWD}/crtm_v2.3.0" directory.
 314
 315
 316
 317
 318 5. CLEANING UP
 319 ==============
 320
 321 Two targets are provided for cleaning up after the build. To remove all the
 322 build products type
 323
 324   $ make clean
 325
 326 To also remove all the configuration products (i.e. the makefiles) type
 327
 328   $ make distclean
 329
 330
 331
 332
 333 6. FEEDBACK AND CONTACT INFO
 334 ============================
 335
 336 That's pretty much it. Any questions or bug reports can be sent to CRTM Support.
 337
 338   CRTM SUPPORT EMAIL: ncep.list.emc.jcsda_crtm.support@noaa.gov
 339
 340 If you have problems building the library please include the generated "config.log"
 341 file in your email correspondence.