diff --git a/CHANGES.txt b/CHANGES.txt index a6f93defb..282c0b31e 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -146,6 +146,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER is renamed to "legacy_sched_deprecated". - Java tool recognizes all released versions, and no longer needs manual updating as new releases are made. Default is now latest LTS - v25. + - Fortran dialect *PATH and *FLAGS settings fall back to generic + dialect's settings if not explicitly set, bringing the behavior in line + with long-standing documentation claims. - Reference manual improvements: * More clarifications in Builder Methods section. * Clarify VariantDir behavior when switching from duplicate=True (the diff --git a/SCons/Defaults.py b/SCons/Defaults.py index 502f43a0e..3fbae1134 100644 --- a/SCons/Defaults.py +++ b/SCons/Defaults.py @@ -407,7 +407,6 @@ def _concat(prefix, items_iter, suffix, env, f=lambda x: x, target=None, source= list, and finally calling _concat_ixes to concatenate 'prefix' and 'suffix' onto each element of the list. """ - if not items_iter: return items_iter @@ -415,14 +414,10 @@ def _concat(prefix, items_iter, suffix, env, f=lambda x: x, target=None, source= if l is not None: items_iter = l + value = [] if affect_signature else ['$('] + value.extend(_concat_ixes(prefix, items_iter, suffix, env)) if not affect_signature: - value = ['$('] - else: - value = [] - value += _concat_ixes(prefix, items_iter, suffix, env) - - if not affect_signature: - value += ["$)"] + value.append("$)") return value # pylint: enable-msg=too-many-arguments diff --git a/SCons/Tool/FortranCommon.py b/SCons/Tool/FortranCommon.py index 50385fe28..2fb4ecbab 100644 --- a/SCons/Tool/FortranCommon.py +++ b/SCons/Tool/FortranCommon.py @@ -142,11 +142,14 @@ def DialectAddToEnv( Args: dialect: dialect name suffixes: suffixes associated with this dialect - ppsuffixes: suffixes using cpp associated with this dialect + ppsuffixes: suffixes for preprocessing associated with this dialect support_mods: whether this dialect supports modules """ ComputeFortranSuffixes(suffixes, ppsuffixes) + if dialect != "FORTRAN": + env.AppendUnique(**{f'{dialect}PATH': ['$FORTRANPATH']}) + fscan = SCons.Scanner.Fortran.FortranScan(f"{dialect}PATH") for suffix in suffixes + ppsuffixes: SCons.Tool.SourceFileScanner.add_scanner(suffix, fscan) diff --git a/SCons/Tool/f03.xml b/SCons/Tool/f03.xml index 3a0a8a218..79dda9542 100644 --- a/SCons/Tool/f03.xml +++ b/SCons/Tool/f03.xml @@ -27,7 +27,12 @@ This file is processed by the bin/SConsDoc.py module. -Set construction variables for generic POSIX Fortran 03 compilers. +Set construction variables for the Fortran 03 dialect. +A Fortran dialect lets you customize the +compilation environment for certain files, +as selected by the dialect's FILESUFFIXES variable. +By default, the Fortran 03 dialect behaves the same +as the Fortran 90, 95 and 08 dialects. @@ -53,12 +58,12 @@ Set construction variables for generic POSIX Fortran 03 compilers. -The Fortran 03 compiler. -You should normally set the &cv-link-FORTRAN; variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set &cv-link-F03; if you need to use a specific compiler -or compiler version for Fortran 03 files. +The compiler for the Fortran 03 dialect. +This dialect is selected when a source file has a suffix +specified in &cv-link-F03FILESUFFIXES; or +&cv-link-F03PPFILESUFFIXES;. +You only need to set &cv-F03; if you need to specify +a compiler different than the one auto-detected for this dialect. @@ -66,12 +71,12 @@ or compiler version for Fortran 03 files. -The command line used to compile a Fortran 03 source file to an object file. -You only need to set &cv-link-F03COM; if you need to use a specific -command line for Fortran 03 files. -You should normally set the &cv-link-FORTRANCOM; variable, -which specifies the default command line -for all Fortran versions. +The command line used to compile source files in the Fortran 03 dialect. +You only need to set &cv-F03COM; if you need to use a customized +command line for this dialect. +The default setting will be equivalent to +&cv-link-FORTRANCOM;, +but using the dialect-specific &consvars; for substitution. @@ -81,8 +86,8 @@ for all Fortran versions. If set, the string displayed when a Fortran 03 source file is compiled to an object file. -If not set, then &cv-link-F03COM; or &cv-link-FORTRANCOM; -(the command line) is displayed. +If not set, then the actual command line, +as generated from &cv-link-F03COM;, is displayed. @@ -90,8 +95,8 @@ If not set, then &cv-link-F03COM; or &cv-link-FORTRANCOM; -The list of file extensions for which the F03 dialect will be used. By -default, this is ['.f03'] +The list of file extensions for which the Fortran 03 dialect will be used. +By default, this is ['.f03'] @@ -100,7 +105,7 @@ default, this is ['.f03'] The list of file extensions for which the compilation + preprocessor pass for -F03 dialect will be used. By default, this is empty. +the Fortran 03 dialect will be used. By default, this is empty. @@ -121,11 +126,15 @@ below, for the variable that expands to those options. You only need to set &cv-link-F03FLAGS; if you need to define specific user options for Fortran 03 files. -You should normally set the &cv-link-FORTRANFLAGS; variable, +You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable, which specifies the user-specified options passed to the default Fortran compiler for all Fortran versions. +Changed in version 4.4: +&cv-link-FORTRANCOMMONFLAGS; is included by default +when commands for this dialect are expanded. + @@ -274,9 +283,11 @@ to generated shared-library objects. You only need to set &cv-link-SHF03FLAGS; if you need to define specific user options for Fortran 03 files. You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. +which holds user-specified options passed to all Fortran builds. + +Changed in version 4.4: +&cv-link-FORTRANCOMMONFLAGS; is included by default +when commands for this dialect are expanded. diff --git a/SCons/Tool/f08.xml b/SCons/Tool/f08.xml index 8fd017679..825f4993f 100644 --- a/SCons/Tool/f08.xml +++ b/SCons/Tool/f08.xml @@ -27,7 +27,12 @@ This file is processed by the bin/SConsDoc.py module. -Set construction variables for generic POSIX Fortran 08 compilers. +Set construction variables for the Fortran 08 dialect. +A Fortran dialect lets you customize the +compilation environment for certain files, +as selected by the dialect's FILESUFFIXES variable. +By default, the Fortran 08 dialect behaves the same +as the Fortran 90, 95 and 03 dialects. @@ -53,12 +58,12 @@ Set construction variables for generic POSIX Fortran 08 compilers. -The Fortran 08 compiler. -You should normally set the &cv-link-FORTRAN; variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set &cv-link-F08; if you need to use a specific compiler -or compiler version for Fortran 08 files. +The compiler for the Fortran 08 dialect. +This dialect is selected when a source file has a suffix +specified in &cv-link-F08FILESUFFIXES; or +&cv-link-F08PPFILESUFFIXES;. +You only need to set &cv-F08; if you need to specify +a compiler different than the one auto-detected for this dialect. @@ -67,11 +72,11 @@ or compiler version for Fortran 08 files. The command line used to compile a Fortran 08 source file to an object file. -You only need to set &cv-link-F08COM; if you need to use a specific -command line for Fortran 08 files. -You should normally set the &cv-link-FORTRANCOM; variable, -which specifies the default command line -for all Fortran versions. +You only need to set &cv-F08COM; if you need to use a customized +command line for this dialect. +The default setting will be equivalent to +&cv-link-FORTRANCOM;, +but using the dialect-specific &consvars; for substitution. @@ -81,8 +86,8 @@ for all Fortran versions. If set, the string displayed when a Fortran 08 source file is compiled to an object file. -If not set, then &cv-link-F08COM; or &cv-link-FORTRANCOM; -(the command line) is displayed. +If not set, then the actual command line, +as generated from &cv-link-F08COM;, is displayed. @@ -90,8 +95,8 @@ If not set, then &cv-link-F08COM; or &cv-link-FORTRANCOM; -The list of file extensions for which the F08 dialect will be used. By -default, this is ['.f08'] +The list of file extensions for which the Fortran 08 dialect will be used. +By default, this is ['.f08'] @@ -100,7 +105,7 @@ default, this is ['.f08'] The list of file extensions for which the compilation + preprocessor pass for -F08 dialect will be used. By default, this is empty. +the Fortran 08 dialect will be used. By default, this is empty. @@ -121,10 +126,8 @@ below, for the variable that expands to those options. You only need to set &cv-link-F08FLAGS; if you need to define specific user options for Fortran 08 files. -You should normally set the &cv-link-FORTRANFLAGS; variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. +You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable, +which holds user-specified options passed to all Fortran builds. diff --git a/SCons/Tool/f77.xml b/SCons/Tool/f77.xml index e6992986f..2cc204c35 100644 --- a/SCons/Tool/f77.xml +++ b/SCons/Tool/f77.xml @@ -27,7 +27,13 @@ This file is processed by the bin/SConsDoc.py module. -Set construction variables for generic POSIX Fortran 77 compilers. +Set construction variables for the Fortran 77 dialect. +A Fortran dialect lets you customize the +compilation environment for certain files, +as selected by the dialect's FILESUFFIXES variable. +By default, the Fortran 77 dialect is distinguished from the +the Fortran 90, 95, 03 and 08 dialects by the assumption +that the source files are fixed-form Fortran, rather than free. @@ -68,12 +74,12 @@ Set construction variables for generic POSIX Fortran 77 compilers. -The Fortran 77 compiler. -You should normally set the &cv-link-FORTRAN; variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set &cv-link-F77; if you need to use a specific compiler -or compiler version for Fortran 77 files. +The compiler for the Fortran 77 dialect. +This dialect is selected when a source file has a suffix +specified in &cv-link-F77FILESUFFIXES; +&cv-link-F77PPFILESUFFIXES;. +You only need to set &cv-F77; if you need to specify +a compiler different than the one auto-detected for this dialect. @@ -82,11 +88,12 @@ or compiler version for Fortran 77 files. The command line used to compile a Fortran 77 source file to an object file. -You only need to set &cv-link-F77COM; if you need to use a specific -command line for Fortran 77 files. -You should normally set the &cv-link-FORTRANCOM; variable, -which specifies the default command line -for all Fortran versions. +You only need to set &cv-F77COM; if you need to use a customized +command line for this dialect. +The default setting will be equivalent to +&cv-link-FORTRANCOM;, +but using the dialect-specific &consvars; for substitution, +excepting that Fortran module-related variables are omitted. @@ -94,8 +101,8 @@ for all Fortran versions. -The list of file extensions for which the F77 dialect will be used. By -default, this is ['.f77'] +The list of file extensions for which the Fortran 77 dialect will be used. +By default, this is ['.f77'] @@ -104,7 +111,7 @@ default, this is ['.f77'] The list of file extensions for which the compilation + preprocessor pass for -F77 dialect will be used. By default, this is empty. +the Fortran 77 dialect will be used. By default, this is empty. @@ -114,8 +121,8 @@ F77 dialect will be used. By default, this is empty. If set, the string displayed when a Fortran 77 source file is compiled to an object file. -If not set, then &cv-link-F77COM; or &cv-link-FORTRANCOM; -(the command line) is displayed. +If not set, then the actual command line, +as generated from &cv-link-F77COM;, is displayed. @@ -137,9 +144,7 @@ for the variable that expands to those options. You only need to set &cv-link-F77FLAGS; if you need to define specific user options for Fortran 77 files. You should normally set the &cv-link-FORTRANFLAGS; variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. +which holds user-specified options passed to all Fortran builds. diff --git a/SCons/Tool/f90.xml b/SCons/Tool/f90.xml index 89c5ddced..d770faac1 100644 --- a/SCons/Tool/f90.xml +++ b/SCons/Tool/f90.xml @@ -27,7 +27,12 @@ This file is processed by the bin/SConsDoc.py module. -Set construction variables for generic POSIX Fortran 90 compilers. +Set &consvars; for the Fortran 90 dialect. +A Fortran dialect lets you customize the +compilation environment for certain files, +as selected by the dialect's FILESUFFIXES variables. +By default, the Fortran 90 dialect behaves the same +as the Fortran 95, 03 and 08 dialects. @@ -53,12 +58,12 @@ Set construction variables for generic POSIX Fortran 90 compilers. -The Fortran 90 compiler. -You should normally set the &cv-link-FORTRAN; variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set &cv-link-F90; if you need to use a specific compiler -or compiler version for Fortran 90 files. +The compiler for the Fortran 90 dialect. +This dialect is selected when a source file has a suffix +specified in &cv-link-F90FILESUFFIXES; or +&cv-link-F90PPFILESUFFIXES;. +You only need to set &cv-F90; if you need to specify +a compiler different than the one auto-detected for this dialect. @@ -67,11 +72,11 @@ or compiler version for Fortran 90 files. The command line used to compile a Fortran 90 source file to an object file. -You only need to set &cv-link-F90COM; if you need to use a specific -command line for Fortran 90 files. -You should normally set the &cv-link-FORTRANCOM; variable, -which specifies the default command line -for all Fortran versions. +You only need to set &cv-F90COM; if you need to use a customized +command line for this dialect. +The default setting will be equivalent to +&cv-link-FORTRANCOM;, +but using the dialect-specific &consvars; for substitution. @@ -81,8 +86,8 @@ for all Fortran versions. If set, the string displayed when a Fortran 90 source file is compiled to an object file. -If not set, then &cv-link-F90COM; or &cv-link-FORTRANCOM; -(the command line) is displayed. +If not set, then the actual command line, +as generated from &cv-link-F90COM;, is displayed. @@ -90,8 +95,8 @@ If not set, then &cv-link-F90COM; or &cv-link-FORTRANCOM; -The list of file extensions for which the F90 dialect will be used. By -default, this is ['.f90'] +The list of file extensions for which the Fortran 90 dialect will be used. +By default, this is ['.f90'] @@ -100,7 +105,7 @@ default, this is ['.f90'] The list of file extensions for which the compilation + preprocessor pass for -F90 dialect will be used. By default, this is empty. +the Fortran 90 dialect will be used. By default, this is empty. @@ -108,23 +113,16 @@ F90 dialect will be used. By default, this is empty. -General user-specified options that are passed to the Fortran 90 compiler. -Note that this variable does -not -contain - -(or similar) include search path options -that scons generates automatically from &cv-link-F90PATH;. -See -&cv-link-_F90INCFLAGS; -below, -for the variable that expands to those options. +General user-specified options that are passed to the compiler +for the Fortran 90 dialect. You only need to set &cv-link-F90FLAGS; if you need to define specific -user options for Fortran 90 files. -You should normally set the &cv-link-FORTRANFLAGS; variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. +user options for Fortran 90 dialect files. +You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable, +which holds user-specified options passed to all Fortran builds. + +Changed in version 4.4: +&cv-link-FORTRANCOMMONFLAGS; is included by default +when command lines for this dialect are expanded. @@ -132,13 +130,13 @@ for all Fortran versions. -An automatically-generated construction variable +An automatically-generated &consvar; containing the Fortran 90 compiler command-line options for specifying directories to be searched for include files. -The value of &cv-link-_F90INCFLAGS; is created -by appending &cv-link-INCPREFIX; and &cv-link-INCSUFFIX; -to the beginning and end -of each directory in &cv-link-F90PATH;. +The value of &cv-link-_F90INCFLAGS; is created by +prepending &cv-link-INCPREFIX; +and appending &cv-link-INCSUFFIX; +to each directory in &cv-link-F90PATH;. @@ -147,14 +145,14 @@ of each directory in &cv-link-F90PATH;. The list of directories that the Fortran 90 compiler will search for include -directories. The implicit dependency scanner will search these -directories for include files. Don't explicitly put include directory -arguments in &cv-link-F90FLAGS; because the result will be non-portable -and the directories will not be searched by the dependency scanner. Note: -directory names in &cv-link-F90PATH; will be looked-up relative to the SConscript -directory when they are used in a command. To force -&scons; -to lookup a directory relative to the root of the source tree, use #: +files. The implicit dependency scanner will also search these +directories for include files. +Do not include compiler search path syntax +(such as the option), +as this will make the result not portable +between different systems, +and will cause the directory not to be searched by the +dependency scanner. You only need to set &cv-link-F90PATH; if you need to define a specific include path for Fortran 90 files. You should normally set the &cv-link-FORTRANPATH; variable, @@ -162,6 +160,14 @@ which specifies the include path for the default Fortran compiler for all Fortran versions. + +Note: +directory names in &cv-link-F90PATH; are looked up relative to the SConscript +directory when they are used in a command. To force +&scons; +to look up a directory relative to the root of the source tree, +use a top-relative path (starts with #): + env = Environment(F90PATH='#/include') @@ -169,8 +175,7 @@ env = Environment(F90PATH='#/include') The directory lookup can also be forced using the -&Dir;() -function: +&f-link-Dir; function: @@ -181,17 +186,11 @@ env = Environment(F90PATH=include) The directory list will be added to command lines through the automatically-generated -&cv-link-_F90INCFLAGS; -construction variable, -which is constructed by -appending the values of the -&cv-link-INCPREFIX; and &cv-link-INCSUFFIX; -construction variables -to the beginning and end -of each directory in &cv-link-F90PATH;. +&cv-link-_F90INCFLAGS; &consvar;. Any command lines you define that need -the F90PATH directory list should -include &cv-link-_F90INCFLAGS;: +the &cv-F90PATH; directory list should +include &cv-link-_F90INCFLAGS;, +for example: @@ -203,15 +202,14 @@ env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE") -The command line used to compile a Fortran 90 source file to an object file -after first running the file through the C preprocessor. -Any options specified in the &cv-link-F90FLAGS; and &cv-link-CPPFLAGS; construction variables -are included on this command line. -You only need to set &cv-link-F90PPCOM; if you need to use a specific -C-preprocessor command line for Fortran 90 files. -You should normally set the &cv-link-FORTRANPPCOM; variable, -which specifies the default C-preprocessor command line -for all Fortran versions. +The command line used to compile a Fortran 90 source file to an object file, +including options such as &cv-link-F90FLAGS; and &cv-link-CPPFLAGS; +needed for the preprocessor. +You only need to set &cv-F90PPCOM; if you need to use a customized +command line for this dialect. +The default setting will be equivalent to +&cv-link-FORTRANPPCOM;, +but using the dialect-specific &consvars; for substitution. @@ -220,9 +218,9 @@ for all Fortran versions. If set, the string displayed when a Fortran 90 source file -is compiled after first running the file through the C preprocessor. -If not set, then &cv-link-F90PPCOM; or &cv-link-FORTRANPPCOM; -(the command line) is displayed. +is compiled to an object file, including preprocessing. +If not set, then the actual command line, +as generated from &cv-link-F90PPCOM;, is displayed. @@ -230,12 +228,12 @@ If not set, then &cv-link-F90PPCOM; or &cv-link-FORTRANPPCOM; -The Fortran 90 compiler used for generating shared-library objects. -You should normally set the &cv-link-SHFORTRAN; variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set &cv-link-SHF90; if you need to use a specific compiler -or compiler version for Fortran 90 files. +The compiler for the Fortran 90 dialect for generating shared-library objects. +This dialect is selected when a source file has a suffix +specified in &cv-link-F90FILESUFFIXES; or +&cv-link-F90PPFILESUFFIXES; and compiling shared objects. +You only need to set &cv-SHF90; if you need to specify +a compiler different than the one auto-detected for this dialect. @@ -243,13 +241,13 @@ or compiler version for Fortran 90 files. -The command line used to compile a Fortran 90 source file -to a shared-library object file. -You only need to set &cv-link-SHF90COM; if you need to use a specific -command line for Fortran 90 files. -You should normally set the &cv-link-SHFORTRANCOM; variable, -which specifies the default command line -for all Fortran versions. +The command line used to compile a Fortran 90 source file to a +shared object file. +You only need to set &cv-SHF90COM; if you need to use a customized +command line for this dialect. +The default setting will be equivalent to +&cv-link-SHFORTRANCOM;, +but using the dialect-specific &consvars; for substitution. @@ -258,9 +256,9 @@ for all Fortran versions. If set, the string displayed when a Fortran 90 source file -is compiled to a shared-library object file. -If not set, then &cv-link-SHF90COM; or &cv-link-SHFORTRANCOM; -(the command line) is displayed. +is compiled to a shared object file. +If not set, then the actual command line, +as generated from &cv-link-SHF90COM;, is displayed. @@ -269,13 +267,15 @@ If not set, then &cv-link-SHF90COM; or &cv-link-SHFORTRANCOM; Options that are passed to the Fortran 90 compiler -to generated shared-library objects. +when compiling shared-library objects. You only need to set &cv-link-SHF90FLAGS; if you need to define specific user options for Fortran 90 files. You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. +which holds user-specified options passed to all Fortran builds. + +Changed in version 4.4: +&cv-link-FORTRANCOMMONFLAGS; is included by default +when command lines for this dialect are expanded. @@ -284,15 +284,14 @@ for all Fortran versions. The command line used to compile a Fortran 90 source file to a -shared-library object file -after first running the file through the C preprocessor. -Any options specified in the &cv-link-SHF90FLAGS; and &cv-link-CPPFLAGS; construction variables -are included on this command line. -You only need to set &cv-link-SHF90PPCOM; if you need to use a specific -C-preprocessor command line for Fortran 90 files. -You should normally set the &cv-link-SHFORTRANPPCOM; variable, -which specifies the default C-preprocessor command line -for all Fortran versions. +shared object file, +including options such as &cv-link-SHF90FLAGS; and &cv-link-CPPFLAGS; +needed for the preprocessor. +You only need to set &cv-SHF90PPCOM; if you need to use a customized +command line for this dialect. +The default setting will be equivalent to +&cv-link-SHFORTRANPPCOM;, +but using the dialect-specific &consvars; for substitution. @@ -301,10 +300,9 @@ for all Fortran versions. If set, the string displayed when a Fortran 90 source file -is compiled to a shared-library object file -after first running the file through the C preprocessor. -If not set, then &cv-link-SHF90PPCOM; or &cv-link-SHFORTRANPPCOM; -(the command line) is displayed. +is compiled to a shared-library object file, including preprocessing. +If not set, then the actual command line, +as generated from &cv-link-SHF90PPCOM;, is displayed. diff --git a/SCons/Tool/f95.xml b/SCons/Tool/f95.xml index 5dd55d943..453c8a4d2 100644 --- a/SCons/Tool/f95.xml +++ b/SCons/Tool/f95.xml @@ -27,7 +27,12 @@ This file is processed by the bin/SConsDoc.py module. -Set construction variables for generic POSIX Fortran 95 compilers. +Set construction variables for the Fortran 95 dialect. +A Fortran dialect lets you customize the +compilation environment for certain files, +as selected by the dialect's FILESUFFIXES variable. +By default, the Fortran 95 dialect behaves the same +as the Fortran 90, 03 and 08 dialects. @@ -53,12 +58,12 @@ Set construction variables for generic POSIX Fortran 95 compilers. -The Fortran 95 compiler. -You should normally set the &cv-link-FORTRAN; variable, -which specifies the default Fortran compiler -for all Fortran versions. -You only need to set &cv-link-F95; if you need to use a specific compiler -or compiler version for Fortran 95 files. +The compiler for the Fortran 95 dialect. +This dialect is selected when a source file has a suffix +specified in &cv-link-F95FILESUFFIXES; or +&cv-link-F95PPFILESUFFIXES;. +You only need to set &cv-F95; if you need to specify +a compiler different than the one auto-detected for this dialect. @@ -67,11 +72,11 @@ or compiler version for Fortran 95 files. The command line used to compile a Fortran 95 source file to an object file. -You only need to set &cv-link-F95COM; if you need to use a specific -command line for Fortran 95 files. -You should normally set the &cv-link-FORTRANCOM; variable, -which specifies the default command line -for all Fortran versions. +You only need to set &cv-F95COM; if you need to use a customized +command line for this dialect. +The default setting will be equivalent to +&cv-link-FORTRANCOM;, +but using the dialect-specific &consvars; for substitution. @@ -81,8 +86,8 @@ for all Fortran versions. If set, the string displayed when a Fortran 95 source file is compiled to an object file. -If not set, then &cv-link-F95COM; or &cv-link-FORTRANCOM; -(the command line) is displayed. +If not set, then the actual command line, +as generated from &cv-link-F95COM;, is displayed. @@ -90,8 +95,8 @@ If not set, then &cv-link-F95COM; or &cv-link-FORTRANCOM; -The list of file extensions for which the F95 dialect will be used. By -default, this is ['.f95'] +The list of file extensions for which the Fortran 95 dialect will be used. +By default, this is ['.f95'] @@ -100,7 +105,7 @@ default, this is ['.f95'] The list of file extensions for which the compilation + preprocessor pass for -F95 dialect will be used. By default, this is empty. +the Fortran 95 dialect will be used. By default, this is empty. @@ -121,10 +126,8 @@ below, for the variable that expands to those options. You only need to set &cv-link-F95FLAGS; if you need to define specific user options for Fortran 95 files. -You should normally set the &cv-link-FORTRANFLAGS; variable, -which specifies the user-specified options -passed to the default Fortran compiler -for all Fortran versions. +You should normally set the &cv-link-FORTRANCOMMONFLAGS; variable, +which holds user-specified options passed to all Fortran builds. diff --git a/SCons/Tool/fortran.xml b/SCons/Tool/fortran.xml index 2b62f0500..8f6b372b0 100644 --- a/SCons/Tool/fortran.xml +++ b/SCons/Tool/fortran.xml @@ -27,7 +27,7 @@ This file is processed by the bin/SConsDoc.py module. -Set &consvars; for generic POSIX Fortran compilers. +Set &consvars; for generic Fortran compilers. @@ -53,7 +53,7 @@ Set &consvars; for generic POSIX Fortran compilers. The default Fortran compiler -for all versions of Fortran. +for all Fortran dialects. @@ -63,8 +63,10 @@ for all versions of Fortran. The command line used to compile a Fortran source file to an object file. By default, any options specified -in the &cv-link-FORTRANFLAGS;, -&cv-link-_FORTRANMODFLAG;, and +in the +&cv-link-FORTRANCOMMONFLAGS; +&cv-link-FORTRANFLAGS;, +&cv-link-_FORTRANMODFLAG; and &cv-link-_FORTRANINCFLAGS; &consvars; are included on this command line. @@ -76,8 +78,8 @@ in the &cv-link-FORTRANFLAGS;, If set, the string displayed when a Fortran source file is compiled to an object file. -If not set, then &cv-link-FORTRANCOM; -(the command line) is displayed. +If not set, then the actual command line, +as generated from &cv-link-FORTRANCOM;, is displayed. @@ -95,7 +97,8 @@ default, this is ['.f', '.for', '.ftn'] The list of file extensions for which the compilation + preprocessor pass for -FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP'] +the FORTRAN dialect will be used. +By default, this is ['.fpp', '.FPP'] @@ -122,8 +125,9 @@ for the &consvars; that expand those options. General user-specified options that are passed to the Fortran compiler. -Similar to &cv-link-FORTRANFLAGS;, -but this &consvar; is applied to all dialects. +Serves the same purpose as the dialect-specific flags variables +(see, for example, &cv-link-FORTRANFLAGS;) +but applies to all Fortran builds, regardless of dialect. New in version 4.4. @@ -232,14 +236,15 @@ module file name as scons attempts to resolve dependencies. The list of directories that the Fortran compiler will search for include files and (for some compilers) module files. The Fortran implicit dependency scanner will search these directories for include files (but -not module files since they are autogenerated and, as such, may not +not for module files since they are autogenerated and, as such, may not actually exist at the time the scan takes place). Don't explicitly put -include directory arguments in FORTRANFLAGS because the result will be +include directory arguments in &cv-FORTRANFLAGS; because the result will be non-portable and the directories will not be searched by the dependency -scanner. Note: directory names in FORTRANPATH will be looked-up relative +scanner. Note: directory names in &cv-FORTRANPATH; will be looked up relative to the SConscript directory when they are used in a command. To force &scons; -to lookup a directory relative to the root of the source tree, use #: +to look up a directory relative to the root of the source tree, +use a top-relative path starting with #: @@ -247,7 +252,7 @@ env = Environment(FORTRANPATH='#/include') -The directory look-up can also be forced using the +The directory lookup can also be forced using the &Dir;() function: @@ -267,9 +272,9 @@ respectively prepending and appending the values of the &cv-link-INCPREFIX; and &cv-link-INCSUFFIX; &consvars; to the beginning and end -of each directory in &cv-link-FORTRANPATH;. +of each directory in &cv-FORTRANPATH;. Any command lines you define that need -the FORTRANPATH directory list should +the &cv-FORTRANPATH; directory list should include &cv-link-_FORTRANINCFLAGS;: diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 1d2d3b232..524463d75 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -8341,34 +8341,36 @@ in &t-link-fortran;; (&consvars; start with FORTRAN) While &SCons; recognizes multiple internal dialects based on filename suffixes, -the convention of various available Fortran compilers is +the convention of many popular Fortran compilers is to assign an actual meaning to only two of these suffixes: .f -(as well as .for and .ftn) -refers to the fixed-format source -code that was the only available option in FORTRAN 77 and earlier, -and .f90 refers to free-format source code +(with .for and .ftn +usually given the same meaning), +interpreted as fixed-format source +code that was the only available option in Fortran 77 and earlier; +.f90, +interpreted as free-format source code which became available as of the Fortran 90 standard. Some compilers recognize suffixes which correspond to Fortran specifications later than F90 as equivalent to .f90 for this purpose, while some do not - check the documentation for your compiler. -An occasionally suggested policy suggestion is to use only +An occasionally suggested policy is to use only .f and .f90 as Fortran filename suffixes. The fixed/free form determination can usually be controlled explicitly with compiler flags -(e.g. for gfortran), +(e.g. for GNU Fortran), overriding any assumption that may be made based on the source file suffix. -The source file suffix does not imply conformance +A source file suffix does not imply conformance with the similarly-named Fortran standard - a suffix of .f08 does not mean you are compiling specifically for Fortran 2008. Normally, compilers provide command-line options for making this selection -(e.g. for gfortran). +(e.g. for GNU Fortran). @@ -8377,9 +8379,9 @@ a suffix of .mod is recognized for Fortran modules. These files are a side effect of compiling a Fortran source file containing module declarations, and must be available when other code which declares -that it uses the module is processed. -&SCons; does not currently have integrated support for submodules, -introduced in the Fortran 2008 standard - +it uses the module is processed. +&SCons; does not currently have integrated support for submodules +(introduced in the Fortran 2008 standard) - the invoked compiler will produce results, but &SCons; will not recognize .smod files as tracked objects. @@ -8395,33 +8397,43 @@ a file with a an upper-cased suffix from the set .F95, .F03 and .F08 -is treated as a Fortran source file -which shall first be run through -the standard C preprocessor. -The lower-cased versions of these suffixes do not -trigger this behavior. -On systems which do not distinguish between upper -and lower case in filenames, -this behavior is not available, -but files suffixed with either -.FPP -or .fpp -are always passed to the preprocessor first. -This matches the convention of gfortran -from the GNU Compiler Collection, -and also followed by certain other Fortran compilers. -For these two suffixes, -the generic FORTRAN dialect will be selected. - - - -&SCons; itself does not invoke the preprocessor, -that is handled by the compiler, -but it adds &consvars; which are applicable to the preprocessor run. -You can see this difference by examining -&cv-link-FORTRANPPCOM; and &cv-link-FORTRANPPCOMSTR; +is assumed to be a Fortran source file +which may contain macros and conditional compilation directives. +Most popular Fortran compilers will first pass such +a source file through a Fortran preprocssor +(fpp, which in some implementations +may be the same as the C preprocessor); +the lower-cased suffixes do not trigger this behavior. +On systems which do not distinguish between +upper and lower case in filenames, +this scheme cannot be used, +but you can usually use the .fpp +suffix to force this behavior +(.FPP is a synonym). +Since this suffix-driven behavior is convention, +not mandated by standards, +consult the compiler's documentation to be sure. + + + +Although &SCons; itself is not responsible for invoking the preprocessor, +it does add &consvars; which are applicable to the preprocessor. +You can see this difference by examining, for example, +&cv-link-FORTRANPPCOM; and &cv-link-FORTRANPPCOMSTR;, which are used instead of -&cv-link-FORTRANCOM; and &cv-link-FORTRANCOMSTR; for that dialect. +&cv-link-FORTRANCOM; and &cv-link-FORTRANCOMSTR; +for the generic compiler dialect if a preprocessor suffix is detected. +The .fpp suffix indicates a +Fortran 90+ (free-form) source file without implying a dialect, +so &SCons; selects the generic FORTRAN dialect in this case. +Otherwise, if the suffix matches one of the dialects, +&SCons; selects that dialect for the settings. +Compilers typically also have a flag available +to indicate preprocessing is required +(e.g. for GNU Fortran), +but using such an option will not trigger &SCons; +to use the alternate &consvars; in building command lines +so you are responsible for that setup yourself.