doc/README.cmake_build

   1
   2 How to compile and run?
   3 -----------------------
   4
   5 - In WRF directory, type './configure_new' - this will create a
   6   _build/wrf_config.cmake file that has appropriate compile options for the
   7   supported computers.
   8
   9   Note: !! You must clone all submodules manually and have all code prepared   !!
  10         !! to compile. No extra steps are done to download code or sanitize it !!
  11
  12   Note: WRF requires netCDF library, but this cmake build does not require you
  13         to set any environment variables. For netCDF detection, the configuration
  14         will be detected from the `nc-config` in your path unless using
  15         netCDF_ROOT cmake variable. See more information from cmake on *_ROOT
  16         variables if you do not want to use the netCDF associated with the
  17         `nc-config` in your path
  18
  19   Follow the prompts to select your configuration. The first will be a general
  20   stanza selection, which will only show configurations for which you have the
  21   supported compilers in your path. Likewise, for partially supported stanzas
  22   a '!!' will appear next to that portion of the stanza denoting that this
  23   portion of the stanza is not supported in your environment and thus will not
  24   be selectable via the interactive dialogs.
  25
  26   Compared to previous version of `configure` this will look much more sparse
  27   and the numbering will be changed to reflect what is availble. For this
  28   reason it will be best to talk about configuration with their description
  29   or some other unique identifier from now on with this build methodology.
  30
  31   Other common options previously done during the stanza configuration selection
  32   are now broken out into y/n interactive queries. This includes usage of :
  33     * SM (OpenMP)
  34     * DM (MPI)
  35
  36   Target selection (case), core, and nesting are all done at the configuration phase.
  37
  38   Any extra configuration parameters that would normally be done through
  39   environment variables or extra command line options are under the
  40   "Configure additional options?" section
  41
  42   Advanced features of `./configure_new` are discussed later in this document
  43
  44 - Type './compile_new [any make options such as `-j 12`]'
  45   If the first argument to compile_new is a directory, it will instead use that
  46   directory as the location for building. If not the default is to build the
  47   configuration placed in _build (the default location for `./configure_new` to
  48   place a configuration)
  49
  50
  51 - If sucessful, this will create either `real` or `ideal` and `wrf` executables
  52   in the install location's bin/ directory (for default location this will be
  53   install/bin/) and the appropriate executables will be also copied into
  54   the respective test directoires under the same install directory as
  55   <install location>/test/<case_name>. Likewise, for specific test cases that
  56   have additional or modified inputs, those input files are copied from the
  57   respective source location test/<test case>
  58
  59   Note: Compared to the older compile script, executables do not have the '.exe'
  60         suffix
  61
  62 - cd to the appropriate test directory in the installation location to run
  63   ideal/real/wrf.
  64
  65 - If it is one of the idealized cases (b_wave, hill2d_x, grav2d_x, quarter_ss,
  66   squall2d_x, squall2d_y, em_les or em_heldsuarez), cd the the appropriate directory, type
  67
  68   ./ideal
  69
  70   to produce wrfinput_d01 file for wrf model. Then type
  71
  72   ./wrf
  73
  74   to run.
  75
  76 - If it is real-data case (real), place files from WPS (met_em.*)
  77   in the appropriate directory, type
  78
  79   ./real
  80
  81   to produce wrfbdy_d01 and wrfinput_d01. Then type
  82
  83   ./wrf
  84
  85   to run.
  86
  87 - If you use mpich, type
  88
  89   mpirun -np number-of-processors wrf
  90
  91 - If you want to clean your configuration use `./cleanCMake.sh`, additional
  92   options are available, see `./cleanCMake.sh -h` for more info
  93
  94
  95 Advanced Configuration
  96 -----------------------
  97
  98 - The 'configure_new' script is designed to work out-of-the-box with minimal
  99   guidance, however to take full advantage of the features this system brings
 100   one can use `./configure_new -h` to receive a help message:
 101     ./configure_new [options] [-- <CMake configuration options>]
 102     -p                  Preselect a stanza configuration with matching description
 103     -x                  Skip CMake options prompt, meant to be used in conjunction with direct pass-in options
 104     -d directory        Use as alternate build directory
 105     -i directory        Use as alternate install directory
 106     -- <CMake options>  Directly pass CMake options to configuration, equivalent to cmake <source dir> <CMake Options>
 107     -h                  Print this message
 108
 109   The '-p' option allows the preselection of a stanza based on its description
 110   without requiring knowledge about its defined number within your environment.
 111   This does require that the stanza exist within the compatible set that would
 112   be available within your environment.
 113
 114   The '-x' option allows the interactive dialogs to be suppressed, and
 115   configuration will immediately proceed with whatever options have been set or
 116   passed in. This is meant to be used with the '--' delimeter option
 117
 118   The '-d' option allows us to specify an alternative build/configuration
 119   directory. As CMake best operates with out-of-source builds, our configuration
 120   and compilation all happen within a different directory than the source. The
 121   default name of this directory is _build/, however for more fine-tuned control
 122   or housing multiple builds from the same source repo at the same time one can
 123   specify a different directory name using this option. It is recommended to use
 124   _build* as the prefix to denote this as an autogenerated directory that can be
 125   safely deleted in its entirety
 126
 127   The '-i' options allows us to specify an alternative install directory for our
 128   compiled configuration. The default value is $PWD/install. Note that the
 129   default includes '$PWD/' - directory locations provided via this option should
 130   use absolute paths as the compile command is executed inside the build
 131   directory, thus any relative paths would be from that location. The files to
 132   be placed in the install directory follows the same premises as the '-d'
 133   option meaning they are autogenerated or copies of source files. This means
 134   the install directory can be safely deleted in its entirety if this
 135   configuration is no longer desired. This also allows multiple installs of
 136   different compilations to coexist from within the same source repo
 137
 138   The '--' option is meant to be a delimeter marking all subsequent input to be
 139   fed directly to the CMake command execution. In other words, after this marker
 140   anything that you place afterwards is as if you are directly passing in
 141   command line options to `cmake`. This allows you to more effectively use the
 142   '-x' option to skip interactive dialogs and instead write the value you want
 143   beforehand, though usage of this option is not necessary. The option name and
 144   values for a given option, respectively, are always named the same as the
 145   cmake option so utilizing the same option name and value that appears in
 146   the interactive dialog will work. As an example :
 147
 148     ./configure_new -p GNU -x -- -DWRF_CORE=ARW -DWRF_NESTING=BASIC -DWRF_CASE=EM_REAL
 149
 150   Would configure immediately configure for the first GNU stanza, using "ARW" as
 151   the WRF_CORE option, "BASIC" as the WRF_NESTING option, and "EM_REAL" as the
 152   WRF_CASE option. Note that the value used is the actual name of the value, not
 153   the numeric shorthand used during interactive dialog.
 154
 155
 156 - The 'compile_new' has a complimentary feature to pair with 'configure_new'.
 157   This feature is specifying an alternate build directory to use as a compile
 158   location. The alternate install directory, if used, does not need to be
 159   specified as that is embedded into the cmake configuration files at configure
 160   time. To use this feature, specify the alternate build directory to use as the
 161   first argument ONLY into the script, like so :
 162
 163     ./configure_new _buildCustomDirectory -j 12
 164
 165   Afterwards, all standard make options apply. If no directory is provided it
 166   will be assumed that you are using the default build directory '_build'. This
 167   should be sufficient for normal usage.
 168
 169
 170 - The 'cleanCmake.sh' is a cleaning script to more easily facilitate cleaning
 171   configurations, whether configured, compiled, or installed. To see the full
 172   list of options, use `./cleanCmake.sh -h` to receive a help message:
 173
 174     ./cleanCMake.sh [options]
 175       -c            [Default if no options] Basic cmake clean functionality [make -j 1 clean]
 176       -b            Remove cmake binary installs [xargs rm < _build/install_manifest.txt]
 177       -f            Remove build & install folders (WRF) [ rm _build -r; rm install/ -r ]
 178       -a            Remove all (WRF), equivalent to -c -b -f (more specifically -c then -b then -f)"
 179     Specific builds/installs
 180       -d directory  Specify operating on particular build directory
 181       -i directory  Specify operating on particular install directory
 182
 183   Each command tells exactly or the equivalent shell commands that would be
 184   executed, but for clarity they are explained below as well.
 185
 186   The '-c' option is the default usage if no options were passed in, in other
 187   words `./cleanCmake.sh`. This effectively goes into the build directory and
 188   runs `make -j 1 clean`, removing all binary objects in the build directory.
 189   This does not remove files in the install directory.
 190
 191   The '-b' option removes the installed files from the install directory
 192   manually. This can be useful for reinstating a faulty or manually disrupted
 193   install without needing to entirely recompile. For example, imagine modifying
 194   the provided 'namelist.input' in the test case folder of the install, but not
 195   recalling what the original values were and where the file originates from.
 196   One could clean only the install and reinstall the exact same compilation with
 197   `./cleanCMake.sh -b && ./compile_new` to reobtain a pristine install.
 198
 199   The '-f' option removes the build and install directories entirely. This is
 200   quickest way to clean but also lose a configuration. It can be very useful if
 201   you find your configuration not working as expected and need a full reset.
 202   This can often happen with CMake caching, which can be a headache to clear.
 203
 204   The '-a' option can be seen as an alternative to the '-f' option which
 205   effectively in the end does the same but in a more ordered fashion. This will
 206   perform all the cleaning in a step-by-step process first doing the '-c' option,
 207   then the '-b' option, and finally the '-f'.
 208
 209
 210   Additional functionality is provided to compliment the advanced features in
 211   'configure_new' of '-d'/'-i'. These are mimicked in 'cleanCMake.sh' to have
 212   the same usage and flags, so interchanging then between the commands will work.
 213   The effects of 'cleanCMake.sh' cleaning, based on option, will
 214   correspondingly affect the newly specified directories. For example, if an
 215   alternate build directory is provided, the '-b' option will use that instead:
 216
 217     ./cleanCMake.sh -b -d _buildCustomDirectory
 218
 219   One might think we would use the install directory when specifying the '-b'
 220   option, but recall that the install location is embeded into the build
 221   configuration and thus removing the installs that cmake did without entirely
 222   removing the install directory requires going to the build directory. This
 223   can be extremely versatile when installing into common locations where other
 224   projects or installed software coexists within a single base install folder.
 225
 226
 227
 228
 229