From 6ef89cb024b01eee7debce6efb856437dd4e4372 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Tue, 16 Nov 2021 18:55:47 +0000 Subject: Updated docs for 4.2.0 release --- doc/generated/builders.gen | 50 ++- doc/generated/examples/caching_ex-random_1.xml | 4 +- doc/generated/examples/troubleshoot_Dump_1.xml | 6 +- doc/generated/examples/troubleshoot_Dump_2.xml | 9 +- doc/generated/examples/troubleshoot_explain1_3.xml | 2 +- .../examples/troubleshoot_stacktrace_2.xml | 2 +- doc/generated/functions.gen | 87 ++--- doc/generated/tools.gen | 89 ++++- doc/generated/variables.gen | 406 ++++++++++----------- doc/generated/variables.mod | 2 + doc/man/scons.xml | 42 ++- 11 files changed, 378 insertions(+), 321 deletions(-) diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen index 450f25b..e21c782 100644 --- a/doc/generated/builders.gen +++ b/doc/generated/builders.gen @@ -698,6 +698,27 @@ env.JavaH( JAVACLASSDIR="classes", ) + + + +Java versions starting with 10.0 no longer use the +javah command for generating JNI +headers/sources, and indeed have removed the command entirely +(see Java Enhancement Proposal +JEP 313), +making this tool harder to use for that purpose. +&SCons; may autodiscover a javah +belonging to an older release if there are multiple Java +versions on the system, which will lead to incorrect results. +To use with a newer Java, override the default values of &cv-link-JAVAH; +(to contain the path to the javac) +and &cv-link-JAVAHFLAGS; (to contain at least a +flag) and note that generating headers with +javac requires supplying source +.java files only, +not .class files. + + @@ -744,15 +765,16 @@ env.M4(target = 'foo.c', source = 'foo.c.m4') Moc() env.Moc() -Builds an output file from a moc input file. Moc input files are either -header files or cxx files. This builder is only available after using the -tool 'qt'. See the &cv-link-QTDIR; variable for more information. +Builds an output file from a moc input file. +moc input files are either header files or C++ files. +This builder is only available after using the +tool &t-link-qt;. See the &cv-link-QTDIR; variable for more information. Example: -env.Moc('foo.h') # generates moc_foo.cc -env.Moc('foo.cpp') # generates foo.moc +env.Moc('foo.h') # generates moc_foo.cc +env.Moc('foo.cpp') # generates foo.moc @@ -2678,11 +2700,11 @@ files. env.Uic() Builds a header file, an implementation file and a moc file from an ui file. -and returns the corresponding nodes in the above order. -This builder is only available after using the tool 'qt'. Note: you can -specify .ui files directly as source -files to the &b-Program;, -&b-Library; and &b-SharedLibrary; builders +and returns the corresponding nodes in the that order. +This builder is only available after using the tool &t-link-qt;. +Note: you can specify .ui files directly as source +files to the &b-link-Program;, +&b-link-Library; and &b-link-SharedLibrary; builders without using this builder. Using this builder lets you override the standard naming conventions (be careful: prefixes are always prepended to names of built files; if you don't want prefixes, you may set them to ``). @@ -2691,9 +2713,11 @@ Example: -env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] -env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), - source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] +env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] +env.Uic( + target=Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), + source='foo.ui' +) # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml index e4e863c..13e4b8d 100644 --- a/doc/generated/examples/caching_ex-random_1.xml +++ b/doc/generated/examples/caching_ex-random_1.xml @@ -1,8 +1,8 @@ % scons -Q -cc -o f1.o -c f1.c cc -o f4.o -c f4.c +cc -o f5.o -c f5.c cc -o f2.o -c f2.c +cc -o f1.o -c f1.c cc -o f3.o -c f3.c -cc -o f5.o -c f5.c cc -o prog f1.o f2.o f3.o f4.o f5.o diff --git a/doc/generated/examples/troubleshoot_Dump_1.xml b/doc/generated/examples/troubleshoot_Dump_1.xml index f099d41..64ef1ab 100644 --- a/doc/generated/examples/troubleshoot_Dump_1.xml +++ b/doc/generated/examples/troubleshoot_Dump_1.xml @@ -31,8 +31,8 @@ scons: Reading SConscript files ... 'ENV': {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin:/snap/bin'}, 'ESCAPE': <function escape at 0x700000>, 'File': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'HOST_ARCH': None, - 'HOST_OS': None, + 'HOST_ARCH': 'x86_64', + 'HOST_OS': 'posix', 'IDLSUFFIXES': ['.idl', '.IDL'], 'INSTALL': <function copyFunc at 0x700000>, 'INSTALLVERSIONEDLIB': <function copyFuncVersionedLib at 0x700000>, @@ -48,7 +48,7 @@ scons: Reading SConscript files ... 'PROGSUFFIX': '', 'PSPAWN': <function piped_env_spawn at 0x700000>, 'RDirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'SCANNERS': [<SCons.Scanner.Base object at 0x700000>], + 'SCANNERS': [<SCons.Scanner.ScannerBase object at 0x700000>], 'SHELL': 'sh', 'SHLIBPREFIX': '$LIBPREFIX', 'SHLIBSUFFIX': '.so', diff --git a/doc/generated/examples/troubleshoot_Dump_2.xml b/doc/generated/examples/troubleshoot_Dump_2.xml index 40163a0..b7f0da6 100644 --- a/doc/generated/examples/troubleshoot_Dump_2.xml +++ b/doc/generated/examples/troubleshoot_Dump_2.xml @@ -11,8 +11,7 @@ scons: Reading SConscript files ... 'CC': 'cl', 'CCCOM': <SCons.Action.FunctionAction object at 0x700000>, 'CCFLAGS': ['/nologo'], - 'CCPCHFLAGS': [ '${(PCH and "/Yu%s \\"/Fp%s\\""%(PCHSTOP or "",File(PCH))) ' - 'or ""}'], + 'CCPCHFLAGS': <function gen_ccpchflags at 0x700000>, 'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'], 'CFILESUFFIX': '.c', 'CFLAGS': [], @@ -53,7 +52,7 @@ scons: Reading SConscript files ... 'SystemRoot': 'C:\\WINDOWS'}, 'ESCAPE': <function escape at 0x700000>, 'File': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'HOST_ARCH': '', + 'HOST_ARCH': 'x86_64', 'HOST_OS': 'win32', 'IDLSUFFIXES': ['.idl', '.IDL'], 'INCPREFIX': '/I', @@ -82,7 +81,7 @@ scons: Reading SConscript files ... 'RCFLAGS': ['/nologo'], 'RCSUFFIXES': ['.rc', '.rc2'], 'RDirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'SCANNERS': [<SCons.Scanner.Base object at 0x700000>], + 'SCANNERS': [<SCons.Scanner.ScannerBase object at 0x700000>], 'SHCC': '$CC', 'SHCCCOM': <SCons.Action.FunctionAction object at 0x700000>, 'SHCCFLAGS': ['$CCFLAGS'], @@ -91,7 +90,7 @@ scons: Reading SConscript files ... 'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES ' '$SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM","$SHCXXCOMSTR")}', 'SHCXXFLAGS': ['$CXXFLAGS'], - 'SHELL': 'command', + 'SHELL': None, 'SHLIBPREFIX': '', 'SHLIBSUFFIX': '.dll', 'SHOBJPREFIX': '$OBJPREFIX', diff --git a/doc/generated/examples/troubleshoot_explain1_3.xml b/doc/generated/examples/troubleshoot_explain1_3.xml index ffe5d1a..bb5b21e 100644 --- a/doc/generated/examples/troubleshoot_explain1_3.xml +++ b/doc/generated/examples/troubleshoot_explain1_3.xml @@ -2,5 +2,5 @@ cp file.in file.oout scons: warning: Cannot find target file.out after building -File "/Users/bdbaddog/devel/scons/git/as_scons/scripts/scons.py", line 98, in <module> +File "/home/bdeegan/devel/scons/git/as_scons/scripts/scons.py", line 98, in <module> diff --git a/doc/generated/examples/troubleshoot_stacktrace_2.xml b/doc/generated/examples/troubleshoot_stacktrace_2.xml index 75dd6fb..7c3cc36 100644 --- a/doc/generated/examples/troubleshoot_stacktrace_2.xml +++ b/doc/generated/examples/troubleshoot_stacktrace_2.xml @@ -1,7 +1,7 @@ % scons -Q --debug=stacktrace scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. scons: internal stack trace: - File "SCons/Job.py", line 195, in start + File "SCons/Job.py", line 203, in start task.prepare() File "SCons/Script/Main.py", line 178, in prepare return SCons.Taskmaster.OutOfDateTask.prepare(self) diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 40de496..c982b96 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -548,9 +548,9 @@ do not make sense and a &Python; exception will be raised. -When using &f-env-Append; to modify &consvars; -which are path specifications (normally, -those names which end in PATH), +When using &f-env-Append; to modify &consvars; +which are path specifications (conventionally, +the names of such end in PATH), it is recommended to add the values as a list of strings, even if there is only a single string to add. The same goes for adding library names to &cv-LIBS;. @@ -2623,7 +2623,7 @@ Returns a list of the target Node or Nodes. Merges values from arg into &consvars; in the current &consenv;. -If +If arg is not a dictionary, it is converted to one by calling @@ -2804,7 +2804,7 @@ Interpreted options and the construction variables they affect are as specified for the &f-link-env-ParseFlags; -method (which +method (which &f-env-MergeFlags; calls). See that method's description for a table of options and corresponding construction variables. @@ -2812,13 +2812,13 @@ for a table of options and corresponding construction variables. If &f-env-MergeFlags; cannot interpret the results of -command, +command, you can suppply a custom function to do so. -function +function must accept three arguments: the &consenv; to modify, the string returned -by running command, +by running command, and the optional unique flag. @@ -2974,16 +2974,18 @@ dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1') - Platform(string) + Platform(plat) + env.Platform(plat) -The -&f-Platform; -form returns a callable object +When called as a global function, +returns a callable platform object +selected by plat +(defaults to the detected platform for the +current system) that can be used to initialize -a construction environment using the -platform keyword of the -&f-Environment; -function. +a construction environment by passing it as the +platform keyword argument to the +&f-link-Environment; function. @@ -2995,11 +2997,10 @@ env = Environment(platform=Platform('win32')) -The -&f-env-Platform; -form applies the callable object for the specified platform -string -to the environment through which the method was called. +When called as a method of an environment, +calls the platform object indicated by +plat +to update that environment. @@ -3007,22 +3008,7 @@ env.Platform('posix') -Note that the -win32 -platform adds the -SystemDrive -and -SystemRoot -variables from the user's external environment -to the construction environment's -&cv-link-ENV; -dictionary. -This is so that any executed commands -that use sockets to connect with other systems -(such as fetching source files from -external CVS repository specifications like -:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons) -will work on Windows systems. +See the manpage section "Construction Environments" for more details. @@ -4147,14 +4133,12 @@ and can be used to split a list of filenames (for example) rather than having to type them as a list of individually quoted words. If arg is a list or tuple -returns arg unchanged. -Use this form to specify strings where whitespace -should be preserved -(it is not necessary to call &f-Split; at all in this case, -but as a convenience it just works as a pass-through -so you don't have to check whether to call &f-Split; or not). +returns the list or tuple unchanged. If arg is any other type of object, returns a list containing just the object. +These non-string cases do not actually do any spliting, +but allow an argument variable to be passed to +&f-Split; without having to first check its type. @@ -4165,9 +4149,9 @@ Example: files = Split("f1.c f2.c f3.c") files = env.Split("f4.c f5.c f6.c") files = Split(""" - f7.c - f8.c - f9.c + f7.c + f8.c + f9.c """) @@ -4176,14 +4160,14 @@ files = Split(""" env.subst(input, [raw, target, source, conv]) Performs construction variable interpolation -on the specified string or sequence argument -input. +on input, +which can be a string or a sequence. By default, leading or trailing white space will -be removed from the result. +be removed from the result, and all sequences of white space will be compressed to a single space character. Additionally, any @@ -4202,9 +4186,8 @@ The raw argument may be set to 2 -if you want to strip -all characters between -any +if you want to additionally discard +all characters between any $( and $) diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen index 16d13e3..43c6531 100644 --- a/doc/generated/tools.gen +++ b/doc/generated/tools.gen @@ -822,7 +822,7 @@ Sets construction variables for the This functionality is subject to change and/or removal without deprecation cycle. - Sets: &cv-link-IMPLICIT_COMMAND_DEPENDENCIES;, &cv-link-NINJA_ALIAS_NAME;, &cv-link-NINJA_COMPDB_EXPAND;, &cv-link-NINJA_DIR;, &cv-link-NINJA_DISABLE_AUTO_RUN;, &cv-link-NINJA_ENV_VAR_CACHE;, &cv-link-NINJA_FILE_NAME;, &cv-link-NINJA_GENERATED_SOURCE_SUFFIXES;, &cv-link-NINJA_MSVC_DEPS_PREFIX;, &cv-link-NINJA_POOL;, &cv-link-NINJA_REGENERATE_DEPS;, &cv-link-NINJA_SYNTAX;, &cv-link-_NINJA_REGENERATE_DEPS_FUNC;, &cv-link-__NINJA_NO;.Uses: &cv-link-AR;, &cv-link-ARCOM;, &cv-link-ARFLAGS;, &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCFLAGS;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-ESCAPE;, &cv-link-LINK;, &cv-link-LINKCOM;, &cv-link-PLATFORM;, &cv-link-PRINT_CMD_LINE_FUNC;, &cv-link-PROGSUFFIX;, &cv-link-RANLIB;, &cv-link-RANLIBCOM;, &cv-link-SHCCCOM;, &cv-link-SHCXXCOM;, &cv-link-SHLINK;, &cv-link-SHLINKCOM;. + Sets: &cv-link-IMPLICIT_COMMAND_DEPENDENCIES;, &cv-link-NINJA_ALIAS_NAME;, &cv-link-NINJA_COMPDB_EXPAND;, &cv-link-NINJA_DIR;, &cv-link-NINJA_DISABLE_AUTO_RUN;, &cv-link-NINJA_ENV_VAR_CACHE;, &cv-link-NINJA_FILE_NAME;, &cv-link-NINJA_FORCE_SCONS_BUILD;, &cv-link-NINJA_GENERATED_SOURCE_SUFFIXES;, &cv-link-NINJA_MSVC_DEPS_PREFIX;, &cv-link-NINJA_POOL;, &cv-link-NINJA_REGENERATE_DEPS;, &cv-link-NINJA_SYNTAX;, &cv-link-_NINJA_REGENERATE_DEPS_FUNC;, &cv-link-__NINJA_NO;.Uses: &cv-link-AR;, &cv-link-ARCOM;, &cv-link-ARFLAGS;, &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCFLAGS;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-ESCAPE;, &cv-link-LINK;, &cv-link-LINKCOM;, &cv-link-PLATFORM;, &cv-link-PRINT_CMD_LINE_FUNC;, &cv-link-PROGSUFFIX;, &cv-link-RANLIB;, &cv-link-RANLIBCOM;, &cv-link-SHCCCOM;, &cv-link-SHCXXCOM;, &cv-link-SHLINK;, &cv-link-SHLINKCOM;. packaging @@ -868,9 +868,92 @@ provided to an Action that uses this environment. qt -Sets construction variables for building Qt applications. +Sets &consvars; for building Qt3 applications. -Sets: &cv-link-QTDIR;, &cv-link-QT_AUTOSCAN;, &cv-link-QT_BINPATH;, &cv-link-QT_CPPPATH;, &cv-link-QT_LIB;, &cv-link-QT_LIBPATH;, &cv-link-QT_MOC;, &cv-link-QT_MOCCXXPREFIX;, &cv-link-QT_MOCCXXSUFFIX;, &cv-link-QT_MOCFROMCXXCOM;, &cv-link-QT_MOCFROMCXXFLAGS;, &cv-link-QT_MOCFROMHCOM;, &cv-link-QT_MOCFROMHFLAGS;, &cv-link-QT_MOCHPREFIX;, &cv-link-QT_MOCHSUFFIX;, &cv-link-QT_UIC;, &cv-link-QT_UICCOM;, &cv-link-QT_UICDECLFLAGS;, &cv-link-QT_UICDECLPREFIX;, &cv-link-QT_UICDECLSUFFIX;, &cv-link-QT_UICIMPLFLAGS;, &cv-link-QT_UICIMPLPREFIX;, &cv-link-QT_UICIMPLSUFFIX;, &cv-link-QT_UISUFFIX;. + + +This tool is only suitable for building targeted to Qt3, +which is obsolete +(the tool is deprecated since 4.3). +There are contributed tools for Qt4 and Qt5, see + +https://github.com/SCons/scons-contrib. +Qt4 has also passed end of life for standard support (in Dec 2015). + + + +Note paths for these &consvars; are assembled +using the os.path.join method +so they will have the appropriate separator at runtime, +but are listed here in the various +entries only with the '/' separator +for simplicity. + + + +In addition, the &consvars; +&cv-link-CPPPATH;, +&cv-link-LIBPATH; and +&cv-link-LIBS; may be modified +and the variables +&cv-link-PROGEMITTER;, &cv-link-SHLIBEMITTER; and &cv-link-LIBEMITTER; +are modified. Because the build-performance is affected when using this tool, +you have to explicitly specify it at Environment creation: + + + +Environment(tools=['default','qt']) + + + +The &t-qt; tool supports the following operations: + + + +Automatic moc file generation from header files. +You do not have to specify moc files explicitly, the tool does it for you. +However, there are a few preconditions to do so: Your header file must have +the same filebase as your implementation file and must stay in the same +directory. It must have one of the suffixes +.h, +.hpp, +.H, +.hxx, +.hh. +You can turn off automatic moc file generation by setting +&cv-link-QT_AUTOSCAN; to False. +See also the corresponding +&b-link-Moc; Builder. + + + +Automatic moc file generation from C++ files. +As described in the Qt documentation, include the moc file at the end of +the C++ file. Note that you have to include the file, which is generated +by the transformation +${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default +<basename>.mo. A warning is generated after building the moc file if you +do not include the correct file. If you are using &f-link-VariantDir;, you may +need to specify duplicate=True. +You can turn off automatic moc file generation by setting &cv-QT_AUTOSCAN; to +False. See also the corresponding +&b-link-Moc; Builder. + + + +Automatic handling of .ui files. +The implementation files generated from .ui +files are handled much the same as yacc or lex files. +Each .ui file given as a source of &b-link-Program;, +&b-link-Library; or &b-link-SharedLibrary; +will generate three files: the declaration file, the +implementation file and a moc file. Because there are also generated headers, +you may need to specify duplicate=True in calls to +&f-link-VariantDir;. +See also the corresponding +&b-link-Uic; Builder. + +Sets: &cv-link-QTDIR;, &cv-link-QT_AUTOSCAN;, &cv-link-QT_BINPATH;, &cv-link-QT_CPPPATH;, &cv-link-QT_LIB;, &cv-link-QT_LIBPATH;, &cv-link-QT_MOC;, &cv-link-QT_MOCCXXPREFIX;, &cv-link-QT_MOCCXXSUFFIX;, &cv-link-QT_MOCFROMCXXCOM;, &cv-link-QT_MOCFROMCXXFLAGS;, &cv-link-QT_MOCFROMHCOM;, &cv-link-QT_MOCFROMHFLAGS;, &cv-link-QT_MOCHPREFIX;, &cv-link-QT_MOCHSUFFIX;, &cv-link-QT_UIC;, &cv-link-QT_UICCOM;, &cv-link-QT_UICDECLFLAGS;, &cv-link-QT_UICDECLPREFIX;, &cv-link-QT_UICDECLSUFFIX;, &cv-link-QT_UICIMPLFLAGS;, &cv-link-QT_UICIMPLPREFIX;, &cv-link-QT_UICIMPLSUFFIX;, &cv-link-QT_UISUFFIX;.Uses: &cv-link-QTDIR;. rmic diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen index 8c17084..cf7751f 100644 --- a/doc/generated/variables.gen +++ b/doc/generated/variables.gen @@ -3092,49 +3092,52 @@ is -dNOPAUSE -dBATCH -sDEVICE=pdfwrite HOST_ARCH - The name of the host hardware architecture. - Can be set when creating a &consenv; by passing as a keyword - argument in the &f-link-Environment; call; should not be - changed otherwise. - If not specified in the &f-Environment; call, will be set to - the defaults for the particular platform, which is in turn - auto-detected unless the platform - argument to &f-Environment; is given. - Note the detected value of the architecture may not be identical to - that from the &Python; platform.machine method. - - - On the Windows platform, if the Microsoft Visual C++ compiler - is available, &t-link-msvc; tool setup is done using - &cv-HOST_ARCH; and &cv-link-TARGET_ARCH;. Changing the values at - any later time will not cause the tool to be reinitialized. - Valid values for this usage are the same as for &cv-link-TARGET_ARCH;. - - - On other platforms, this &consvar; is informational and does - not currently affect construction activities. - - + The name of the host hardware architecture + used to create this &consenv;. + The platform code sets this when initializing + (see &cv-link-PLATFORM; and the + platform argument to &f-link-Environment;). + Note the detected name of the architecture may not be identical to + that returned by the &Python; + platform.machine method. + + + On the win32 platform, + if the Microsoft Visual C++ compiler is available, + &t-link-msvc; tool setup is done using + &cv-HOST_ARCH; and &cv-link-TARGET_ARCH;. + Changing the values at any later time will not cause + the tool to be reinitialized. + Valid host arch values are + x86 and arm + for 32-bit hosts and + amd64 and x86_64 + for 64-bit hosts. + + + Should be considered immutable. + &cv-HOST_ARCH; is not currently used by other platforms, + but the option is reserved to do so in future + + HOST_OS - The name of the host operating system. - Can be set when creating a &consenv; by passing as a keyword - argument in the &f-link-Environment; call; should not be - changed otherwise. - If not specified in the &f-Environment; call, will be set to - the defaults for the particular platform, which is in turn - auto-detected unless the platform - argument to &f-Environment; is given. - - - This &consvar; is informational and does not currently - affect construction activities. - - + The name of the host operating system for the platform + used to create this &consenv;. + The platform code sets this when initializing + (see &cv-link-PLATFORM; and the + platform argument to &f-link-Environment;). + + + Should be considered immutable. + &cv-HOST_OS; is not currently used by &SCons;, + but the option is reserved to do so in future + + @@ -3670,25 +3673,30 @@ for Java classes. JAVAVERSION - Specifies the Java version being used by the &b-Java; builder. - This is not currently used to select one - version of the Java compiler vs. another. - Instead, you should set this to specify the version of Java - supported by your &javac; compiler. - The default is 1.4. - - - + Specifies the Java version being used by the &b-link-Java; + builder. Set this to specify the version of Java targeted + by the &javac; compiler. This is sometimes necessary because Java 1.5 changed the file names that are created for nested anonymous inner classes, which can cause a mismatch with the files that &SCons; expects will be generated by the &javac; compiler. - Setting &cv-JAVAVERSION; to - 1.5 - (or 1.6, as appropriate) - can make &SCons; realize that a Java 1.5 or 1.6 - build is actually up to date. + Setting &cv-JAVAVERSION; to a version greater than + 1.4 makes &SCons; realize that a build + with such a compiler is actually up to date. + The default is 1.4. + + + While this is not primarily intended for + selecting one version of the Java compiler vs. another, + it does have that effect on the Windows platform. A + more precise approach is to set &cv-link-JAVAC; (and related + &consvars; for related utilities) to the path to the specific + Java compiler you want, if that is not the default compiler. + On non-Windows platforms, the + alternatives system may provide a + way to adjust the default Java compiler without + having to specify explicit paths. @@ -4755,6 +4763,7 @@ constructor; setting it later has no effect. Valid values for Windows are +14.3, 14.2, 14.1, 14.1Exp, @@ -5257,6 +5266,17 @@ Specfies the name of the project to package. + + + NINJA_FORCE_SCONS_BUILD + + + When NINJA_FORCE_SCONS_BUILD is True, this will cause the build nodes to callback to scons instead of using + ninja to build them. This is intended to be passed to the environment on the builder invocation. + It is useful if you have a build node which does something which is not easily translated into ninja. + + + NINJA_GENERATED_SOURCE_SUFFIXES @@ -5412,7 +5432,7 @@ Example: -env['PCH'] = 'StdAfx.pch' +env['PCH'] = File('StdAfx.pch') @@ -5637,20 +5657,21 @@ The default is PLATFORM -The name of the platform used to create the Environment. If no platform is -specified when the Environment is created, -&scons; -autodetects the platform. - + The name of the platform used to create this &consenv;. + &SCons; sets this when initializing the platform, + which by default is auto-detected + (see the platform + argument to &f-link-Environment;). + - -env = Environment(tools = []) + +env = Environment(tools=[]) if env['PLATFORM'] == 'cygwin': Tool('mingw')(env) else: Tool('msvc')(env) - - + + @@ -5859,8 +5880,8 @@ The prefix used for PostScript file names. QT_AUTOSCAN -Turn off scanning for mocable files. Use the Moc Builder to explicitly -specify files to run moc on. +Turn off scanning for mocable files. Use the &b-link-Moc; Builder to explicitly +specify files to run moc on. @@ -5869,8 +5890,8 @@ specify files to run moc on. QT_BINPATH -The path where the qt binaries are installed. -The default value is '&cv-link-QTDIR;/bin'. +The path where the Qt binaries are installed. +The default value is '&cv-link-QTDIR;/bin'. @@ -5879,9 +5900,9 @@ The default value is '&cv-link-QTDIR;/bin'. QT_CPPPATH -The path where the qt header files are installed. +The path where the Qt header files are installed. The default value is '&cv-link-QTDIR;/include'. -Note: If you set this variable to None, +Note: If you set this variable to None, the tool won't change the &cv-link-CPPPATH; construction variable. @@ -5901,8 +5922,10 @@ Prints lots of debugging information while scanning for moc files. QT_LIB -Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set -this variable to None, the tool won't change the &cv-link-LIBS; variable. +Default value is 'qt'. +You may want to set this to 'qt-mt'. +Note: If you set this variable to None, +the tool won't change the &cv-link-LIBS; variable. @@ -5911,9 +5934,9 @@ this variable to None, the tool won't change the &cv-link-LIBS; variable. QT_LIBPATH -The path where the qt libraries are installed. -The default value is '&cv-link-QTDIR;/lib'. -Note: If you set this variable to None, +The path where the Qt libraries are installed. +The default value is '&cv-link-QTDIR;/lib'. +Note: If you set this variable to None, the tool won't change the &cv-link-LIBPATH; construction variable. @@ -5924,7 +5947,7 @@ construction variable. QT_MOC -Default value is '&cv-link-QT_BINPATH;/moc'. +Default value is '&cv-link-QT_BINPATH;/moc'. @@ -5933,7 +5956,8 @@ Default value is '&cv-link-QT_BINPATH;/moc'. QT_MOCCXXPREFIX -Default value is ''. Prefix for moc output files, when source is a cxx file. +Default value is ''. +Prefix for moc output files when source is a C++ file. @@ -5942,8 +5966,8 @@ Default value is ''. Prefix for moc output files, when source is a cxx file. QT_MOCCXXSUFFIX -Default value is '.moc'. Suffix for moc output files, when source is a cxx -file. +Default value is '.moc'. +Suffix for moc output files when source is a C++ file. @@ -5952,7 +5976,7 @@ file. QT_MOCFROMCXXCOM -Command to generate a moc file from a cpp file. +Command to generate a moc file from a C++ file. @@ -5961,7 +5985,7 @@ Command to generate a moc file from a cpp file. QT_MOCFROMCXXCOMSTR -The string displayed when generating a moc file from a cpp file. +The string displayed when generating a moc file from a C++ file. If this is not set, then &cv-link-QT_MOCFROMCXXCOM; (the command line) is displayed. @@ -5971,8 +5995,8 @@ If this is not set, then &cv-link-QT_MOCFROMCXXCOM; (the command line) is displa QT_MOCFROMCXXFLAGS -Default value is '-i'. These flags are passed to moc, when moccing a -C++ file. +Default value is '-i'. +These flags are passed to moc when moccing a C++ file. @@ -5990,7 +6014,7 @@ Command to generate a moc file from a header. QT_MOCFROMHCOMSTR -The string displayed when generating a moc file from a cpp file. +The string displayed when generating a moc file from a C++ file. If this is not set, then &cv-link-QT_MOCFROMHCOM; (the command line) is displayed. @@ -6000,8 +6024,8 @@ If this is not set, then &cv-link-QT_MOCFROMHCOM; (the command line) is displaye QT_MOCFROMHFLAGS -Default value is ''. These flags are passed to moc, when moccing a header -file. +Default value is ''. These flags are passed to moc +when moccing a header file. @@ -6010,7 +6034,8 @@ file. QT_MOCHPREFIX -Default value is 'moc_'. Prefix for moc output files, when source is a header. +Default value is 'moc_'. +Prefix for moc output files when source is a header. @@ -6019,8 +6044,8 @@ Default value is 'moc_'. Prefix for moc output files, when source is a header. QT_MOCHSUFFIX -Default value is '&cv-link-CXXFILESUFFIX;'. Suffix for moc output files, when source is -a header. +Default value is '&cv-link-CXXFILESUFFIX;'. +Suffix for moc output files when source is a header. @@ -6029,7 +6054,7 @@ a header. QT_UIC -Default value is '&cv-link-QT_BINPATH;/uic'. +Default value is '&cv-link-QT_BINPATH;/uic'. @@ -6038,7 +6063,7 @@ Default value is '&cv-link-QT_BINPATH;/uic'. QT_UICCOM -Command to generate header files from .ui files. +Command to generate header files from .ui files. @@ -6047,7 +6072,7 @@ Command to generate header files from .ui files. QT_UICCOMSTR -The string displayed when generating header files from .ui files. +The string displayed when generating header files from .ui files. If this is not set, then &cv-link-QT_UICCOM; (the command line) is displayed. @@ -6057,8 +6082,8 @@ If this is not set, then &cv-link-QT_UICCOM; (the command line) is displayed. QT_UICDECLFLAGS -Default value is ''. These flags are passed to uic, when creating a a h -file from a .ui file. +Default value is ''. These flags are passed to uic +when creating a header file from a .ui file. @@ -6067,7 +6092,8 @@ file from a .ui file. QT_UICDECLPREFIX -Default value is ''. Prefix for uic generated header files. +Default value is ''. +Prefix for uic generated header files. @@ -6076,7 +6102,8 @@ Default value is ''. Prefix for uic generated header files. QT_UICDECLSUFFIX -Default value is '.h'. Suffix for uic generated header files. +Default value is '.h'. +Suffix for uic generated header files. @@ -6085,8 +6112,9 @@ Default value is '.h'. Suffix for uic generated header files. QT_UICIMPLFLAGS -Default value is ''. These flags are passed to uic, when creating a cxx -file from a .ui file. +Default value is ''. +These flags are passed to uic when creating a C++ +file from a .ui file. @@ -6095,7 +6123,8 @@ file from a .ui file. QT_UICIMPLPREFIX -Default value is 'uic_'. Prefix for uic generated implementation files. +Default value is 'uic_'. +Prefix for uic generated implementation files. @@ -6114,7 +6143,8 @@ files. QT_UISUFFIX -Default value is '.ui'. Suffix of designer input files. +Default value is '.ui'. +Suffix of designer input files. @@ -6123,66 +6153,11 @@ Default value is '.ui'. Suffix of designer input files. QTDIR -The qt tool tries to take this from os.environ. -It also initializes all QT_* -construction variables listed below. -(Note that all paths are constructed -with python's os.path.join() method, -but are listed here with the '/' separator -for easier reading.) -In addition, the construction environment -variables &cv-link-CPPPATH;, -&cv-link-LIBPATH; and -&cv-link-LIBS; may be modified -and the variables -&cv-link-PROGEMITTER;, &cv-link-SHLIBEMITTER; and &cv-link-LIBEMITTER; -are modified. Because the build-performance is affected when using this tool, -you have to explicitly specify it at Environment creation: - - - -Environment(tools=['default','qt']) - - - -The qt tool supports the following operations: - - - -Automatic moc file generation from header files. -You do not have to specify moc files explicitly, the tool does it for you. -However, there are a few preconditions to do so: Your header file must have -the same filebase as your implementation file and must stay in the same -directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You -can turn off automatic moc file generation by setting QT_AUTOSCAN to 0. -See also the corresponding -&b-Moc;() -builder method. - - - -Automatic moc file generation from cxx files. -As stated in the qt documentation, include the moc file at the end of -the cxx file. Note that you have to include the file, which is generated -by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default -<basename>.moc. A warning is generated after building the moc file, if you -do not include the correct file. If you are using VariantDir, you may -need to specify duplicate=1. You can turn off automatic moc file generation -by setting QT_AUTOSCAN to 0. See also the corresponding -&b-Moc; -builder method. - - - -Automatic handling of .ui files. -The implementation files generated from .ui files are handled much the same -as yacc or lex files. Each .ui file given as a source of Program, Library or -SharedLibrary will generate three files, the declaration file, the -implementation file and a moc file. Because there are also generated headers, -you may need to specify duplicate=1 in calls to VariantDir. -See also the corresponding -&b-Uic; -builder method. +The path to the Qt installation to build against. +If not already set, +&t-link-qt; tool tries to obtain this from +os.environ; +if not found there, it tries to make a guess. @@ -7912,75 +7887,64 @@ for more information). TARGET_ARCH - The name of the hardware architecture compiled objects - created by this &consenv; should target. - Can be set when creating a &consenv; by passing as a keyword - argument in the &f-link-Environment; call; should not be - changed otherwise. - If not specified in the &f-Environment; call, will be set to - the defaults for the particular platform, which is in turn - auto-detected unless the platform - argument to &f-Environment; is given. - Defaults to the same value as &cv-link-HOST_ARCH;. - - - On the Windows platform, if the Microsoft Visual C++ compiler - is available, &t-link-msvc; tool setup is done using - &cv-link-HOST_ARCH; and &cv-TARGET_ARCH;. Changing the values at - any later time will not cause the tool to be reinitialized. - Compiled objects will be in the target architecture if - the compilation system supports generating for that target. - The latest compiler which can fulfill the requirement will - be selected, unless a different version is directed by the - value of the &cv-link-MSVC_VERSION; &consvar;. - - - On the Windows/msvc combination, valid target values are - x86, - arm, - i386 - for 32-bit targets and - amd64, - arm64, - em64t, - x86_64 - and ia64 (Itanium) - for 64-bit targets. - Note that not all target architectures are - supported for all Visual Studio / MSVC versions. - Check the relevant Microsoft documentation. - - - For example, if you want to compile 64-bit binaries, you would set - TARGET_ARCH='x86_64' when creating the &consenv;. - - - On other platforms, this &consvar; is informational and does - not currently affect construction activities. - - + The name of the hardware architecture that objects + created using this &consenv; should target. + Can be set when creating a &consenv; by passing as a keyword + argument in the &f-link-Environment; call. + + + On the win32 platform, + if the Microsoft Visual C++ compiler is available, + &t-link-msvc; tool setup is done using + &cv-link-HOST_ARCH; and &cv-TARGET_ARCH;. + If a value is not specified, + will be set to the same value as &cv-link-HOST_ARCH;. + Changing the value after the environment is initialized + will not cause the tool to be reinitialized. + Compiled objects will be in the target architecture if + the compilation system supports generating for that target. + The latest compiler which can fulfill the requirement will + be selected, unless a different version is directed by the + value of the &cv-link-MSVC_VERSION; &consvar;. + + + On the win32/msvc combination, valid target arch values are + x86, + arm, + i386 + for 32-bit targets and + amd64, + arm64, + x86_64 + and ia64 (Itanium) + for 64-bit targets. + For example, if you want to compile 64-bit binaries, you would set + TARGET_ARCH='x86_64' when creating the &consenv;. + Note that not all target architectures are + supported for all Visual Studio / MSVC versions. + Check the relevant Microsoft documentation. + + + &cv-TARGET_ARCH; is not currently used by other compilation tools, + but the option is reserved to do so in future + + TARGET_OS - The name of the operating system compiled objects - created by this &consenv; should target. - Can be set when creating a &consenv; by passing as a keyword - argument in the &f-link-Environment; call; should not be - changed otherwise. - If not specified in the &f-Environment; call, will be set to - the defaults for the particular platform, which is in turn - auto-detected unless the platform - argument to &f-Environment; is given. - Defaults to the same value as &cv-HOST_OS;. - - - This &consvar; is informational and does not currently - affect construction activities. - - + The name of the operating system that objects + created using this &consenv; should target. + Can be set when creating a &consenv; by passing as a keyword + argument in the &f-link-Environment; call;. + + + &cv-TARGET_OS; is not currently used by &SCons; + but the option is reserved to do so in future + + @@ -8108,7 +8072,7 @@ or '-via' for ARM toolchain. The suffix for the name of the temporary file used to store command lines exceeding &cv-link-MAXLINELENGTH;. -The suffix shouldinclude the dot ('.') if one is wanted as +The suffix should include the dot ('.') if one is wanted as it will not be added automatically. The default is .lnk. diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod index e54b7d8..cd4e2a4 100644 --- a/doc/generated/variables.mod +++ b/doc/generated/variables.mod @@ -356,6 +356,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $NINJA_DISABLE_AUTO_RUN"> $NINJA_ENV_VAR_CACHE"> $NINJA_FILE_NAME"> +$NINJA_FORCE_SCONS_BUILD"> $NINJA_GENERATED_SOURCE_SUFFIXES"> $NINJA_MSVC_DEPS_PREFIX"> $NINJA_POOL"> @@ -1010,6 +1011,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $NINJA_DISABLE_AUTO_RUN"> $NINJA_ENV_VAR_CACHE"> $NINJA_FILE_NAME"> +$NINJA_FORCE_SCONS_BUILD"> $NINJA_GENERATED_SOURCE_SUFFIXES"> $NINJA_MSVC_DEPS_PREFIX"> $NINJA_POOL"> diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 6b5bece..d86a123 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1,26 +1,28 @@ -- cgit v0.12