SCons/Tool/fortran.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27 <tool name="fortran">
  28 <summary>
  29 <para>
  30 Set &consvars; for generic POSIX Fortran compilers.
  31 </para>
  32 </summary>
  33 <sets>
  34 <item>FORTRAN</item>
  35 <item>FORTRANFLAGS</item>
  36 <item>FORTRANCOM</item>
  37 <item>SHFORTRAN</item>
  38 <item>SHFORTRANFLAGS</item>
  39 <item>SHFORTRANCOM</item>
  40 <item>SHFORTRANPPCOM</item>
  41 </sets>
  42 <uses>
  43 <item>FORTRANCOMSTR</item>
  44 <item>FORTRANPPCOMSTR</item>
  45 <item>SHFORTRANCOMSTR</item>
  46 <item>SHFORTRANPPCOMSTR</item>
  47 <item>CPPFLAGS</item>
  48 <item>_CPPDEFFLAGS</item>
  49 </uses>
  50 </tool>
  51
  52 <cvar name="FORTRAN">
  53 <summary>
  54 <para>
  55 The default Fortran compiler
  56 for all versions of Fortran.
  57 </para>
  58 </summary>
  59 </cvar>
  60
  61 <cvar name="FORTRANCOM">
  62 <summary>
  63 <para>
  64 The command line used to compile a Fortran source file to an object file.
  65 By default, any options specified
  66 in the &cv-link-FORTRANFLAGS;,
  67 &cv-link-_FORTRANMODFLAG;, and
  68 &cv-link-_FORTRANINCFLAGS;
  69 &consvars; are included on this command line.
  70 </para>
  71 </summary>
  72 </cvar>
  73
  74 <cvar name="FORTRANCOMSTR">
  75 <summary>
  76 <para>
  77 If set, the string displayed when a Fortran source file
  78 is compiled to an object file.
  79 If not set, then &cv-link-FORTRANCOM;
  80 (the command line) is displayed.
  81 </para>
  82 </summary>
  83 </cvar>
  84
  85 <cvar name="FORTRANFILESUFFIXES">
  86 <summary>
  87 <para>
  88 The list of file extensions for which the FORTRAN dialect will be used. By
  89 default, this is <literal>['.f', '.for', '.ftn']</literal>
  90 </para>
  91 </summary>
  92 </cvar>
  93
  94 <cvar name="FORTRANPPFILESUFFIXES">
  95 <summary>
  96 <para>
  97 The list of file extensions for which the compilation + preprocessor pass for
  98 FORTRAN dialect will be used. By default, this is <literal>['.fpp', '.FPP']</literal>
  99 </para>
 100 </summary>
 101 </cvar>
 102
 103 <cvar name="FORTRANFLAGS">
 104 <summary>
 105 <para>
 106 General user-specified options for the FORTRAN dialect
 107 that are passed to the Fortran compiler.
 108 Note that this variable does
 109 <emphasis>not</emphasis>
 110 contain
 111 <option>-I</option>
 112 (or similar) include or module search path options
 113 that scons generates automatically from &cv-link-FORTRANPATH;.
 114 See
 115 &cv-link-_FORTRANINCFLAGS; and &cv-link-_FORTRANMODFLAG;
 116 for the &consvars; that expand those options.
 117 </para>
 118 </summary>
 119 </cvar>
 120
 121 <cvar name="FORTRANCOMMONFLAGS">
 122 <summary>
 123 <para>
 124 General user-specified options that are passed to the Fortran compiler.
 125 Similar to &cv-link-FORTRANFLAGS;,
 126 but this &consvar; is applied to all dialects.
 127 </para>
 128 <para><emphasis>New in version 4.4.</emphasis></para>
 129 </summary>
 130 </cvar>
 131
 132 <cvar name="_FORTRANINCFLAGS">
 133 <summary>
 134 <para>
 135 An automatically-generated &consvar;
 136 containing the Fortran compiler command-line options
 137 for specifying directories to be searched for include
 138 files and module files.
 139 The value of &cv-link-_FORTRANINCFLAGS; is created
 140 by respectively prepending and appending
 141 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
 142 to the beginning and end
 143 of each directory in &cv-link-FORTRANPATH;.
 144 </para>
 145 </summary>
 146 </cvar>
 147
 148 <cvar name="FORTRANMODDIR">
 149 <summary>
 150 <para>
 151 Directory location where the Fortran compiler should place
 152 any module files it generates.  This variable is empty, by default. Some
 153 Fortran compilers will internally append this directory in the search path
 154 for module files, as well.
 155 </para>
 156 </summary>
 157 </cvar>
 158
 159 <cvar name="FORTRANMODDIRPREFIX">
 160 <summary>
 161 <para>
 162 The prefix used to specify a module directory on the Fortran compiler command
 163 line.
 164 This will be prepended to the beginning of the directory
 165 in the &cv-link-FORTRANMODDIR; &consvars;
 166 when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
 167 </para>
 168 </summary>
 169 </cvar>
 170
 171 <cvar name="FORTRANMODDIRSUFFIX">
 172 <summary>
 173 <para>
 174 The suffix used to specify a module directory on the Fortran compiler command
 175 line.
 176 This will be appended to the end of the directory
 177 in the &cv-link-FORTRANMODDIR; &consvars;
 178 when the &cv-link-_FORTRANMODFLAG; variables is automatically generated.
 179 </para>
 180 </summary>
 181 </cvar>
 182
 183 <cvar name="_FORTRANMODFLAG">
 184 <summary>
 185 <para>
 186 An automatically-generated &consvar;
 187 containing the Fortran compiler command-line option
 188 for specifying the directory location where the Fortran
 189 compiler should place any module files that happen to get
 190 generated during compilation.
 191 The value of &cv-link-_FORTRANMODFLAG; is created
 192 by respectively prepending and appending
 193 &cv-link-FORTRANMODDIRPREFIX; and &cv-link-FORTRANMODDIRSUFFIX;
 194 to the beginning and end of the directory in &cv-link-FORTRANMODDIR;.
 195 </para>
 196 </summary>
 197 </cvar>
 198
 199 <cvar name="FORTRANMODPREFIX">
 200 <summary>
 201 <para>
 202 The module file prefix used by the Fortran compiler.  SCons assumes that
 203 the Fortran compiler follows the quasi-standard naming convention for
 204 module files of
 205 <filename>module_name.mod</filename>.
 206 As a result, this variable is left empty, by default.  For situations in
 207 which the compiler does not necessarily follow the normal convention,
 208 the user may use this variable.  Its value will be appended to every
 209 module file name as scons attempts to resolve dependencies.
 210 </para>
 211 </summary>
 212 </cvar>
 213
 214 <cvar name="FORTRANMODSUFFIX">
 215 <summary>
 216 <para>
 217 The module file suffix used by the Fortran compiler.  SCons assumes that
 218 the Fortran compiler follows the quasi-standard naming convention for
 219 module files of
 220 <filename>module_name.mod</filename>.
 221 As a result, this variable is set to ".mod", by default.  For situations
 222 in which the compiler does not necessarily follow the normal convention,
 223 the user may use this variable.  Its value will be appended to every
 224 module file name as scons attempts to resolve dependencies.
 225 </para>
 226 </summary>
 227 </cvar>
 228
 229 <cvar name="FORTRANPATH">
 230 <summary>
 231 <para>
 232 The list of directories that the Fortran compiler will search for
 233 include files and (for some compilers) module files. The Fortran implicit
 234 dependency scanner will search these directories for include files (but
 235 not module files since they are autogenerated and, as such, may not
 236 actually exist at the time the scan takes place). Don't explicitly put
 237 include directory arguments in FORTRANFLAGS because the result will be
 238 non-portable and the directories will not be searched by the dependency
 239 scanner. Note: directory names in FORTRANPATH will be looked-up relative
 240 to the SConscript directory when they are used in a command. To force
 241 &scons;
 242 to look-up a directory relative to the root of the source tree use #:
 243 </para>
 244
 245 <example_commands>
 246 env = Environment(FORTRANPATH='#/include')
 247 </example_commands>
 248
 249 <para>
 250 The directory look-up can also be forced using the
 251 &Dir;()
 252 function:
 253 </para>
 254
 255 <example_commands>
 256 include = Dir('include')
 257 env = Environment(FORTRANPATH=include)
 258 </example_commands>
 259
 260 <para>
 261 The directory list will be added to command lines
 262 through the automatically-generated
 263 &cv-link-_FORTRANINCFLAGS;
 264 &consvar;,
 265 which is constructed by
 266 respectively prepending and appending the values of the
 267 &cv-link-INCPREFIX; and &cv-link-INCSUFFIX;
 268 &consvars;
 269 to the beginning and end
 270 of each directory in &cv-link-FORTRANPATH;.
 271 Any command lines you define that need
 272 the FORTRANPATH directory list should
 273 include &cv-link-_FORTRANINCFLAGS;:
 274 </para>
 275
 276 <example_commands>
 277 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
 278 </example_commands>
 279 </summary>
 280 </cvar>
 281
 282 <cvar name="FORTRANPPCOM">
 283 <summary>
 284 <para>
 285 The command line used to compile a Fortran source file to an object file
 286 after first running the file through the C preprocessor.
 287 By default, any options specified in the &cv-link-FORTRANFLAGS;,
 288 &cv-link-CPPFLAGS;,
 289 &cv-link-_CPPDEFFLAGS;,
 290 &cv-link-_FORTRANMODFLAG;, and
 291 &cv-link-_FORTRANINCFLAGS;
 292 &consvars; are included on this command line.
 293 </para>
 294 </summary>
 295 </cvar>
 296
 297 <cvar name="FORTRANPPCOMSTR">
 298 <summary>
 299 <para>
 300 If set, the string displayed when a Fortran source file
 301 is compiled to an object file
 302 after first running the file through the C preprocessor.
 303 If not set, then &cv-link-FORTRANPPCOM;
 304 (the command line) is displayed.
 305 </para>
 306 </summary>
 307 </cvar>
 308
 309 <cvar name="FORTRANSUFFIXES">
 310 <summary>
 311 <para>
 312 The list of suffixes of files that will be scanned
 313 for Fortran implicit dependencies
 314 (INCLUDE lines and USE statements).
 315 The default list is:
 316 </para>
 317
 318 <example_commands>
 319 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
 320 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
 321 </example_commands>
 322 </summary>
 323 </cvar>
 324
 325 <cvar name="SHFORTRAN">
 326 <summary>
 327 <para>
 328 The default Fortran compiler used for generating shared-library objects.
 329 </para>
 330 </summary>
 331 </cvar>
 332
 333 <cvar name="SHFORTRANCOM">
 334 <summary>
 335 <para>
 336 The command line used to compile a Fortran source file
 337 to a shared-library object file.
 338 By default, any options specified
 339 in the &cv-link-SHFORTRANFLAGS;,
 340 &cv-link-_FORTRANMODFLAG;, and
 341 &cv-link-_FORTRANINCFLAGS;
 342 &consvars; are included on this command line.
 343 See also &cv-link-FORTRANCOM;.
 344 </para>
 345 </summary>
 346 </cvar>
 347
 348 <cvar name="SHFORTRANCOMSTR">
 349 <summary>
 350 <para>
 351 If set, the string displayed when a Fortran source file
 352 is compiled to a shared-library object file.
 353 If not set, then &cv-link-SHFORTRANCOM;
 354 (the command line) is displayed.
 355 </para>
 356 </summary>
 357 </cvar>
 358
 359 <cvar name="SHFORTRANFLAGS">
 360 <summary>
 361 <para>
 362 Options that are passed to the Fortran compiler
 363 to generate shared-library objects.
 364 </para>
 365 </summary>
 366 </cvar>
 367
 368 <cvar name="SHFORTRANPPCOM">
 369 <summary>
 370 <para>
 371 The command line used to compile a Fortran source file to a
 372 shared-library object file
 373 after first running the file through the C preprocessor.
 374 By default, any options specified in the &cv-link-SHFORTRANFLAGS;,
 375 &cv-link-CPPFLAGS;,
 376 &cv-link-_CPPDEFFLAGS;,
 377 &cv-link-_FORTRANMODFLAG;, and
 378 &cv-link-_FORTRANINCFLAGS;
 379 &consvars; are included on this command line.
 380 See also &cv-link-SHFORTRANCOM;.
 381 </para>
 382 </summary>
 383 </cvar>
 384
 385 <cvar name="SHFORTRANPPCOMSTR">
 386 <summary>
 387 <para>
 388 If set, the string displayed when a Fortran source file
 389 is compiled to a shared-library object file
 390 after first running the file through the C preprocessor.
 391 If not set, then &cv-link-SHFORTRANPPCOM;
 392 (the command line) is displayed.
 393 </para>
 394 </summary>
 395 </cvar>
 396
 397 </sconsdoc>