| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
|---|
| 2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
|---|
| 3 | |
|---|
| 4 | <html xmlns="http://www.w3.org/1999/xhtml"> |
|---|
| 5 | <head> |
|---|
| 6 | <meta name="generator" content= |
|---|
| 7 | "HTML Tidy for Linux/x86 (vers 1st December 2004), see www.w3.org" /> |
|---|
| 8 | |
|---|
| 9 | <title>Annex: Declarations in FCM extract configuration file</title> |
|---|
| 10 | <meta name="author" content="FCM development team" /> |
|---|
| 11 | <meta name="descriptions" content="User Guide Annex" /> |
|---|
| 12 | <meta name="keywords" content="FCM, user guide, annex" /> |
|---|
| 13 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|---|
| 14 | <link rel="stylesheet" type="text/css" href="style.css" /> |
|---|
| 15 | <script type="text/javascript" src="fcm.js"> |
|---|
| 16 | </script> |
|---|
| 17 | </head> |
|---|
| 18 | |
|---|
| 19 | <body onload= |
|---|
| 20 | "javascript: FCM.load('doc/user_guide/', null, [['.', 'FCM User Guide']]);"> |
|---|
| 21 | <div id="document-info"> |
|---|
| 22 | <address id="fcm-js-trail"></address> |
|---|
| 23 | |
|---|
| 24 | <address id="fcm-js-maintenance"></address> |
|---|
| 25 | </div> |
|---|
| 26 | |
|---|
| 27 | <h1>Annex: Declarations in FCM extract configuration file</h1> |
|---|
| 28 | |
|---|
| 29 | <p>The following is a list of supported declarations for the configuration |
|---|
| 30 | file used by the FCM extract system. Unless otherwise stated, the fields in |
|---|
| 31 | all declaration labels are not case sensitive.</p> |
|---|
| 32 | |
|---|
| 33 | <dl> |
|---|
| 34 | <dt>CFG::TYPE</dt> |
|---|
| 35 | |
|---|
| 36 | <dd> |
|---|
| 37 | <p>The configuration file type, the value should always be |
|---|
| 38 | <samp>ext</samp> for an extract configuration file. This declaration is |
|---|
| 39 | compulsory for all extract configuration files.</p> |
|---|
| 40 | |
|---|
| 41 | <p>Example:</p> |
|---|
| 42 | <pre> |
|---|
| 43 | cfg::type ext |
|---|
| 44 | </pre> |
|---|
| 45 | </dd> |
|---|
| 46 | |
|---|
| 47 | <dt>CFG::VERSION</dt> |
|---|
| 48 | |
|---|
| 49 | <dd> |
|---|
| 50 | <p>The file format version, currently <samp>1.0</samp> - a version is |
|---|
| 51 | included so that we shall be able to read the configuration file |
|---|
| 52 | correctly should we decide to change its format in the future.</p> |
|---|
| 53 | |
|---|
| 54 | <p>Example:</p> |
|---|
| 55 | <pre> |
|---|
| 56 | cfg::version 1.0 |
|---|
| 57 | </pre> |
|---|
| 58 | </dd> |
|---|
| 59 | |
|---|
| 60 | <dt>%<name></dt> |
|---|
| 61 | |
|---|
| 62 | <dd> |
|---|
| 63 | <p><code>%<name></code> declares an internal variable |
|---|
| 64 | <var><name></var> that can later be re-used.</p> |
|---|
| 65 | |
|---|
| 66 | <p>Example:</p> |
|---|
| 67 | <pre> |
|---|
| 68 | %my_variable foo |
|---|
| 69 | src::bar::base %my_variable |
|---|
| 70 | src::egg::base %my_variable |
|---|
| 71 | src::ham::base %my_variable |
|---|
| 72 | </pre> |
|---|
| 73 | </dd> |
|---|
| 74 | |
|---|
| 75 | <dt>INC</dt> |
|---|
| 76 | |
|---|
| 77 | <dd> |
|---|
| 78 | <p>This declares the name of a file containing extract configuration. The |
|---|
| 79 | lines in the declared file will be included inline to the current |
|---|
| 80 | configuration file.</p> |
|---|
| 81 | |
|---|
| 82 | <p>Example:</p> |
|---|
| 83 | <pre> |
|---|
| 84 | inc ~frva/var_stable_22.0/cfg/ext.cfg |
|---|
| 85 | # ... and then your changes ... |
|---|
| 86 | </pre> |
|---|
| 87 | </dd> |
|---|
| 88 | |
|---|
| 89 | <dt>DEST[::ROOTDIR]</dt> |
|---|
| 90 | |
|---|
| 91 | <dd> |
|---|
| 92 | <p>The <em>root</em> path of the destination of this extract. This |
|---|
| 93 | declaration is compulsory for all extract configuration files.</p> |
|---|
| 94 | |
|---|
| 95 | <p>Example:</p> |
|---|
| 96 | <pre> |
|---|
| 97 | dest $HOME/project/my_project |
|---|
| 98 | </pre> |
|---|
| 99 | </dd> |
|---|
| 100 | |
|---|
| 101 | <dt>USE</dt> |
|---|
| 102 | |
|---|
| 103 | <dd> |
|---|
| 104 | <p>This declares the location of a previous successful extract, which the |
|---|
| 105 | current extract will inherit from. If the previous extract is also a |
|---|
| 106 | build, the subsequent invocation of the build system on the current |
|---|
| 107 | extract will automatically trigger an inherited incremental build based |
|---|
| 108 | on that build.</p> |
|---|
| 109 | |
|---|
| 110 | <p>Example:</p> |
|---|
| 111 | <pre> |
|---|
| 112 | use ~frva/var_stable_22.0 |
|---|
| 113 | # ... and then the settings for your current extract ... |
|---|
| 114 | </pre> |
|---|
| 115 | </dd> |
|---|
| 116 | |
|---|
| 117 | <dt>RDEST[::ROOTDIR]</dt> |
|---|
| 118 | |
|---|
| 119 | <dd> |
|---|
| 120 | <p>The alternate destination of this extract. This declaration is |
|---|
| 121 | compulsory if this extract requires mirroring to an alternate |
|---|
| 122 | destination.</p> |
|---|
| 123 | |
|---|
| 124 | <p>Example:</p> |
|---|
| 125 | <pre> |
|---|
| 126 | rdest /home/nwp/da/frva/project/my_project |
|---|
| 127 | </pre> |
|---|
| 128 | </dd> |
|---|
| 129 | |
|---|
| 130 | <dt>RDEST::LOGNAME</dt> |
|---|
| 131 | |
|---|
| 132 | <dd> |
|---|
| 133 | <p>The login name of the user on the alternate destination machine. If |
|---|
| 134 | not specified, the current login name of the user on the local platform |
|---|
| 135 | is assumed.</p> |
|---|
| 136 | |
|---|
| 137 | <p>Example:</p> |
|---|
| 138 | <pre> |
|---|
| 139 | rdest::logname frva |
|---|
| 140 | </pre> |
|---|
| 141 | </dd> |
|---|
| 142 | |
|---|
| 143 | <dt>RDEST::MACHINE</dt> |
|---|
| 144 | |
|---|
| 145 | <dd> |
|---|
| 146 | <p>The destination machine for this extract. If not specified, the current |
|---|
| 147 | host name is assumed.</p> |
|---|
| 148 | |
|---|
| 149 | <p>Example:</p> |
|---|
| 150 | <pre> |
|---|
| 151 | rdest::machine tx01 |
|---|
| 152 | </pre> |
|---|
| 153 | </dd> |
|---|
| 154 | |
|---|
| 155 | <dt> |
|---|
| 156 | RDEST::MIRROR_CMD<br /> |
|---|
| 157 | <del>MIRROR</del> |
|---|
| 158 | </dt> |
|---|
| 159 | |
|---|
| 160 | <dd> |
|---|
| 161 | <p>The extract system can mirror the extracted source to an alternate |
|---|
| 162 | machine. Currently, it does this using either the <code>rdist</code> or |
|---|
| 163 | the <code>rsync</code> command. The default is <samp>rsync</samp>. This |
|---|
| 164 | declaration can be used to switch to using <samp>rdist</samp>.</p> |
|---|
| 165 | |
|---|
| 166 | <p>Example:</p> |
|---|
| 167 | <pre> |
|---|
| 168 | rdest::mirror_cmd rdist |
|---|
| 169 | </pre> |
|---|
| 170 | </dd> |
|---|
| 171 | |
|---|
| 172 | <dt> |
|---|
| 173 | RDEST::RSH_MKDIR_RSH (<del>RDEST::REMOTE_SHELL</del>)<br /> |
|---|
| 174 | RDEST::RSH_MKDIR_RSHFLAGS<br /> |
|---|
| 175 | RDEST::RSH_MKDIR_MKDIR<br /> |
|---|
| 176 | RDEST::RSH_MKDIR_MKDIRFLAGS |
|---|
| 177 | </dt> |
|---|
| 178 | |
|---|
| 179 | <dd> |
|---|
| 180 | <p>If <code>rsync</code> is used to mirror an extract, the system needs to |
|---|
| 181 | issue a separate remote shell command to create the container directory of |
|---|
| 182 | the mirror destination. The default is to issue a shell command in the |
|---|
| 183 | form <samp>ssh -n -oBatchMode=yes LOGNAME@MACHINE mkdir -p DEST</samp>. |
|---|
| 184 | These declarations can be used to modify the command.</p> |
|---|
| 185 | |
|---|
| 186 | <p>Example:</p> |
|---|
| 187 | <pre> |
|---|
| 188 | # Examples using the default settings: |
|---|
| 189 | rdest::rsh_mkdir_rsh ssh |
|---|
| 190 | rdest::rsh_mkdir_rshflags -n -oBatchMode=yes |
|---|
| 191 | rdest::rsh_mkdir_mkdir mkdir |
|---|
| 192 | rdest::rsh_mkdir_mkdirflags -p |
|---|
| 193 | </pre> |
|---|
| 194 | </dd> |
|---|
| 195 | |
|---|
| 196 | <dt> |
|---|
| 197 | RDEST::RSYNC<br /> |
|---|
| 198 | RDEST::RSYNCFLAGS |
|---|
| 199 | </dt> |
|---|
| 200 | |
|---|
| 201 | <dd> |
|---|
| 202 | <p>These declarations are only useful if <code>rsync</code> is used to |
|---|
| 203 | mirror an extract. By default, the system issues the shell command |
|---|
| 204 | <samp>rsync -a --exclude='.*' --delete-excluded --timeout=900 --rsh='ssh |
|---|
| 205 | -oBatchMode=yes' SOURCE DEST</samp>. These declarations can be used to |
|---|
| 206 | modify the command.</p> |
|---|
| 207 | |
|---|
| 208 | <p>Example:</p> |
|---|
| 209 | <pre> |
|---|
| 210 | # Examples using the default settings: |
|---|
| 211 | rdest::rsync rsync |
|---|
| 212 | rdest::rsyncflags -a --exclude='.*' --delete-excluded --timeout=900 \ |
|---|
| 213 | --rsh='ssh -oBatchMode=yes' |
|---|
| 214 | </pre> |
|---|
| 215 | </dd> |
|---|
| 216 | |
|---|
| 217 | <dt>REPOS::<pck>::<branch></dt> |
|---|
| 218 | |
|---|
| 219 | <dd> |
|---|
| 220 | <p>This declares a URL or a local file system path for the container |
|---|
| 221 | <em>repository</em> of a branch named <branch> in a package named |
|---|
| 222 | <pck>. The package name <pck> must be the name of a top-level |
|---|
| 223 | package (i.e. it must not contain the double colon <code>::</code> |
|---|
| 224 | delimiter). The name <branch> is used internally within the extract |
|---|
| 225 | system, and so is independent of the branch name of the code management |
|---|
| 226 | system. However, it is usually desirable to use the same name of the |
|---|
| 227 | actual branch in the code management system. For declaration of a local |
|---|
| 228 | file system path, the convention is to name the branch <samp>user</samp>. |
|---|
| 229 | Please note that both <pck> and <branch> fields are case |
|---|
| 230 | sensitive. The declared URL must be a valid Subversion URL or a valid FCM |
|---|
| 231 | URL keyword.</p> |
|---|
| 232 | |
|---|
| 233 | <p>Example:</p> |
|---|
| 234 | <pre> |
|---|
| 235 | repos::var::base fcm:var_tr |
|---|
| 236 | repos::var::branch1 fcm:var_br/frsn/r4790_foobar |
|---|
| 237 | repos::var::user $HOME/var |
|---|
| 238 | </pre> |
|---|
| 239 | </dd> |
|---|
| 240 | |
|---|
| 241 | <dt> |
|---|
| 242 | REVISION::<pck>::<branch><br /> |
|---|
| 243 | <del>VERSION::<pck>::<branch></del> |
|---|
| 244 | </dt> |
|---|
| 245 | |
|---|
| 246 | <dd> |
|---|
| 247 | <p>The revision to be used for the URL of <branch> in the package |
|---|
| 248 | <pck>. If specified, the revision must be a revision where the |
|---|
| 249 | branch exists. If not specified, the revision defaults to last changed |
|---|
| 250 | revision at the HEAD of the branch. Please note that if the declared |
|---|
| 251 | <em>branch</em> is in the local file system, this declaration must not be |
|---|
| 252 | used. The value of the declaration can be a FCM revision keyword or any |
|---|
| 253 | revision argument acceptable by Subversion. You can use a valid revision |
|---|
| 254 | number, a date between a pair of curly brackets (e.g. <samp>{"2005-05-01 |
|---|
| 255 | 12:00"}</samp>) or the keyword HEAD. However, please do not use the |
|---|
| 256 | keywords BASE, COMMITTED or PREV as these are reserved for working copies |
|---|
| 257 | only. Again, please note that both <pck> and <branch> fields |
|---|
| 258 | are case sensitive.</p> |
|---|
| 259 | |
|---|
| 260 | <p>Example:</p> |
|---|
| 261 | <pre> |
|---|
| 262 | # Declare the revision with the FCM revision keyword "vn22.0" |
|---|
| 263 | revision::var::base vn22.0 |
|---|
| 264 | # Declare the revision with a {date} |
|---|
| 265 | revision::var::branch1 {2006-01-01} |
|---|
| 266 | </pre> |
|---|
| 267 | </dd> |
|---|
| 268 | |
|---|
| 269 | <dt>REVMATCH</dt> |
|---|
| 270 | |
|---|
| 271 | <dd> |
|---|
| 272 | <p>If set to true, the declared revision of a branch must be a changed |
|---|
| 273 | revision of that branch, (unless the keyword HEAD is used).</p> |
|---|
| 274 | |
|---|
| 275 | <p>Example:</p> |
|---|
| 276 | <pre> |
|---|
| 277 | revmatch true |
|---|
| 278 | </pre> |
|---|
| 279 | </dd> |
|---|
| 280 | |
|---|
| 281 | <dt>SRC::<pcks>::<branch></dt> |
|---|
| 282 | |
|---|
| 283 | <dd> |
|---|
| 284 | <p>This declares a source directory for the sub-package <pcks> of |
|---|
| 285 | <branch>. If the repository is declared as a URL, the source |
|---|
| 286 | directory must be quoted as a relative path to the URL. If the repository |
|---|
| 287 | is declared as a path in the local file system, the source directory can |
|---|
| 288 | be declared as either a relative path to the <em>repository</em> or a |
|---|
| 289 | full path. If the source directory is a relative path and <pcks> is |
|---|
| 290 | a top-level package, the full name of the sub-package will be determined |
|---|
| 291 | automatically using the directory names of the relative path as the names |
|---|
| 292 | of the sub-packages. If the source directory is a full path, the full |
|---|
| 293 | sub-package name must be specified. The name of the sub-package |
|---|
| 294 | determines the destination path of the source directory in the |
|---|
| 295 | extract.</p> |
|---|
| 296 | |
|---|
| 297 | <p>Example:</p> |
|---|
| 298 | <pre> |
|---|
| 299 | src::var::base code/VarMod_PF |
|---|
| 300 | src::var/code/VarMod_PF::user $HOME/var/code/VarMod_PF |
|---|
| 301 | </pre> |
|---|
| 302 | </dd> |
|---|
| 303 | |
|---|
| 304 | <dt>EXPSRC::<pcks>::<branch></dt> |
|---|
| 305 | |
|---|
| 306 | <dd> |
|---|
| 307 | <p>This declares an expandable source directory for the sub-package |
|---|
| 308 | <pcks> of <branch>. This declaration is essentially the same |
|---|
| 309 | as the SRC declaration, except that the system will attempt to search |
|---|
| 310 | recursively for sub-directories within the declared source directory.</p> |
|---|
| 311 | |
|---|
| 312 | <p>Example:</p> |
|---|
| 313 | <pre> |
|---|
| 314 | expsrc::var::base code |
|---|
| 315 | expsrc::var::user code |
|---|
| 316 | </pre> |
|---|
| 317 | </dd> |
|---|
| 318 | |
|---|
| 319 | <dt> |
|---|
| 320 | CONFLICT<br /> |
|---|
| 321 | <del>OVERRIDE</del> |
|---|
| 322 | </dt> |
|---|
| 323 | |
|---|
| 324 | <dd> |
|---|
| 325 | <p>This declaration can be used to specify the conflict mode, which is |
|---|
| 326 | relevant when a file is modified by two different branches (or more) |
|---|
| 327 | relative to the base branch. The conflict mode can be <samp>fail</samp>, |
|---|
| 328 | <samp>merge</samp> (default) or <samp>override</samp> (or 0, 1 and 2 |
|---|
| 329 | respectively). If <samp>fail</samp> is specified, the extract fails when |
|---|
| 330 | a file is modified by two branches (or more) relative to the base branch. |
|---|
| 331 | If <samp>merge</samp> is specified, the system will attempt to merge the |
|---|
| 332 | changes. It will fail only on unresolved conflicts. If |
|---|
| 333 | <samp>override</samp> is specified, the changes in the last branch takes |
|---|
| 334 | precedence and the changes in the earlier branches will be ignored. Note: |
|---|
| 335 | the old <code>override true|false</code> declaration is deprecated. If |
|---|
| 336 | declared, <code>override true</code> will be equivalent to <code>conflict |
|---|
| 337 | override</code>, and <code>override false</code> will be equivalent to |
|---|
| 338 | <code>conflict fail</code>.</p> |
|---|
| 339 | |
|---|
| 340 | <p>Example:</p> |
|---|
| 341 | <pre> |
|---|
| 342 | conflict override |
|---|
| 343 | </pre> |
|---|
| 344 | </dd> |
|---|
| 345 | |
|---|
| 346 | <dt>BLD::<fields></dt> |
|---|
| 347 | |
|---|
| 348 | <dd> |
|---|
| 349 | <p>Declare a build configuration file declaration. The label |
|---|
| 350 | <fields> is the label of the declaration. On a successful extract, |
|---|
| 351 | <fields> will be added to the build configuration file. Please note |
|---|
| 352 | that some of the <fields> may be case sensitive.</p> |
|---|
| 353 | |
|---|
| 354 | <p>Example:</p> |
|---|
| 355 | <pre> |
|---|
| 356 | bld::target VarScr_AnalysePF |
|---|
| 357 | bld::tool::fc sxmpif90 |
|---|
| 358 | bld::tool::cc sxmpic++ |
|---|
| 359 | # ... and so on ... |
|---|
| 360 | </pre> |
|---|
| 361 | </dd> |
|---|
| 362 | </dl> |
|---|
| 363 | </body> |
|---|
| 364 | </html> |
|---|
