From 898fa44b70ce4998801db843dbe5b263f4d34a18 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Mon, 28 Sep 2015 13:57:59 -0700 Subject: Added help for pull request #226 --- doc/generated/builders.gen | 35 ++-- doc/generated/examples/caching_ex-random_1.xml | 4 +- .../examples/commandline_Variables_Help_1.xml | 2 + doc/generated/examples/output_ex1_1.xml | 2 + doc/generated/examples/output_ex2_1.xml | 2 + doc/generated/examples/output_ex2_2.xml | 2 + doc/generated/examples/troubleshoot_Dump_1.xml | 4 + doc/generated/examples/troubleshoot_Dump_2.xml | 4 + doc/generated/examples/troubleshoot_explain1_3.xml | 2 +- doc/generated/functions.gen | 18 +- doc/generated/tools.gen | 16 +- doc/generated/tools.mod | 2 + doc/generated/variables.gen | 184 ++++++++++++++++++++- doc/generated/variables.mod | 32 ++++ doc/user/output.xml | 22 +++ src/engine/SCons/Script/SConscript.xml | 16 +- 16 files changed, 302 insertions(+), 45 deletions(-) diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen index 02dc04b..d49156f 100644 --- a/doc/generated/builders.gen +++ b/doc/generated/builders.gen @@ -505,20 +505,13 @@ env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'], -Installs a versioned shared library. The $SHLIBVERSION -construction variable should be defined in the environment -to confirm the version number in the library name. -If $SHLIBVERSION is not defined a warning will be issued -and the name of the library will be parsed to derive the version. -The symlinks appropriate to the architecture will be generated. +Installs a versioned shared library. The symlinks appropriate to the +architecture will be generated based on symlinks of the source library. env.InstallVersionedLib(target = '/usr/local/bin/foo', source = 'libxyz.1.5.2.so') -env.InstallVersionedLib(target = '/usr/local/bin/foo', - source = 'libxyz.1.5.2.so', - SHLIBVERSION='1.5.2') @@ -1257,7 +1250,7 @@ file as the second element. Normally the object file is ignored. This builder method is only provided when Microsoft Visual C++ is being used as the compiler. The PCH builder method is generally used in -conjuction with the PCH construction variable to force object files to use +conjunction with the PCH construction variable to force object files to use the precompiled header: @@ -1490,7 +1483,7 @@ the results shall be as the comments above say. Example 2. The POTUpdate builder may be used with no target specified, in which case default target messages.pot will be used. The -default target may also be overriden by setting $POTDOMAIN construction +default target may also be overridden by setting $POTDOMAIN construction variable or providing it as an override to POTUpdate builder: @@ -1623,7 +1616,7 @@ Target nodes defined through P (they're Ignored from '.' node). Instead, they are added automatically to special Alias ('po-update' by default). The alias name may be changed -through the $POUPDATE_ALIAS construction variable. You can easilly +through the $POUPDATE_ALIAS construction variable. You can easily update PO files in your project by scons po-update. @@ -1995,22 +1988,20 @@ For maximum portability, use the $SHLIBVERSION construction variable is defined a versioned shared library is created. This modifies the $SHLINKFLAGS as required, adds the version number to the library name, and creates the symlinks that -are needed. $SHLIBVERSION needs to be of the form X.Y.Z, where X -and Y are numbers, and Z is a number but can also contain letters to designate -alpha, beta, or release candidate patch levels. +are needed. env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'], SHLIBVERSION='1.5.2') - -This builder may create multiple links to the library. On a POSIX system, -for the shared library libbar.so.2.3.1, the links created would be -libbar.so and libbar.so.2; on a Darwin (OSX) system -the library would be libbar.2.3.1.dylib and the link would be -libbar.dylib. +On a POSIX system, versions with a single token create exactly one symlink: +libbar.so.6 would have symlinks libbar.so only. +On a POSIX system, versions with two or more +tokens create exactly two symlinks: libbar.so.2.3.1 would have symlinks +libbar.so and libbar.so.2; on a Darwin (OSX) system the library would be +libbar.2.3.1.dylib and the link would be libbar.dylib. @@ -2564,7 +2555,7 @@ running scons '.'. Builds a Windows type library (.tlb) file from an input IDL file (.idl). -In addition, it will build the associated inteface stub and +In addition, it will build the associated interface stub and proxy source files, naming them according to the base name of the .idl file. For example, diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml index e7aa631..904e1dd 100644 --- a/doc/generated/examples/caching_ex-random_1.xml +++ b/doc/generated/examples/caching_ex-random_1.xml @@ -1,9 +1,9 @@ % scons -Q -cc -o f4.o -c f4.c -cc -o f5.o -c f5.c cc -o f2.o -c f2.c +cc -o f5.o -c f5.c cc -o f3.o -c f3.c +cc -o f4.o -c f4.c cc -o f1.o -c f1.c cc -o prog f1.o f2.o f3.o f4.o f5.o diff --git a/doc/generated/examples/commandline_Variables_Help_1.xml b/doc/generated/examples/commandline_Variables_Help_1.xml index db171eb..76f13c5 100644 --- a/doc/generated/examples/commandline_Variables_Help_1.xml +++ b/doc/generated/examples/commandline_Variables_Help_1.xml @@ -1,6 +1,8 @@ % scons -Q -h +Local Build Variables: + RELEASE: Set to 1 to build for release default: 0 actual: 0 diff --git a/doc/generated/examples/output_ex1_1.xml b/doc/generated/examples/output_ex1_1.xml index 535960b..2607243 100644 --- a/doc/generated/examples/output_ex1_1.xml +++ b/doc/generated/examples/output_ex1_1.xml @@ -3,6 +3,8 @@ scons: Reading SConscript files ... scons: done reading SConscript files. +Local Build Variables: + Type: 'scons program' to build the production program, 'scons debug' to build the debug version. diff --git a/doc/generated/examples/output_ex2_1.xml b/doc/generated/examples/output_ex2_1.xml index e951c3a..74d7192 100644 --- a/doc/generated/examples/output_ex2_1.xml +++ b/doc/generated/examples/output_ex2_1.xml @@ -3,6 +3,8 @@ scons: Reading SConscript files ... scons: done reading SConscript files. +Local Build Variables: + Type: 'scons program' to build the production program. Type: 'scons windebug' to build the Windows debug version. diff --git a/doc/generated/examples/output_ex2_2.xml b/doc/generated/examples/output_ex2_2.xml index 8dca6c3..9130d5a 100644 --- a/doc/generated/examples/output_ex2_2.xml +++ b/doc/generated/examples/output_ex2_2.xml @@ -3,6 +3,8 @@ scons: Reading SConscript files ... scons: done reading SConscript files. +Local Build Variables: + Type: 'scons program' to build the production program. Use scons -H for help about command-line options. diff --git a/doc/generated/examples/troubleshoot_Dump_1.xml b/doc/generated/examples/troubleshoot_Dump_1.xml index 248e85c..bf141a0 100644 --- a/doc/generated/examples/troubleshoot_Dump_1.xml +++ b/doc/generated/examples/troubleshoot_Dump_1.xml @@ -64,7 +64,11 @@ scons: Reading SConscript files ... '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', '__DRPATH': '$_DRPATH', + '__DSHLIBVERSIONFLAGS': '${__libversionflags(__env__,"DSHLIBVERSION","_DSHLIBVERSIONFLAGS")}', + '__LDMODULEVERSIONFLAGS': '${__libversionflags(__env__,"LDMODULEVERSION","_LDMODULEVERSIONFLAGS")}', '__RPATH': '$_RPATH', + '__SHLIBVERSIONFLAGS': '${__libversionflags(__env__,"SHLIBVERSION","_SHLIBVERSIONFLAGS")}', + '__libversionflags': <function __libversionflags at 0x700000&gt;, '_concat': <function _concat at 0x700000&gt;, '_defines': <function _defines at 0x700000&gt;, '_stripixes': <function _stripixes at 0x700000&gt;} diff --git a/doc/generated/examples/troubleshoot_Dump_2.xml b/doc/generated/examples/troubleshoot_Dump_2.xml index d6fa404..0ae8fe1 100644 --- a/doc/generated/examples/troubleshoot_Dump_2.xml +++ b/doc/generated/examples/troubleshoot_Dump_2.xml @@ -97,6 +97,10 @@ scons: Reading SConscript files ... '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', '_MSVC_OUTPUT_FLAG': <function msvc_output_flag at 0x700000&gt;, + '__DSHLIBVERSIONFLAGS': '${__libversionflags(__env__,"DSHLIBVERSION","_DSHLIBVERSIONFLAGS")}', + '__LDMODULEVERSIONFLAGS': '${__libversionflags(__env__,"LDMODULEVERSION","_LDMODULEVERSIONFLAGS")}', + '__SHLIBVERSIONFLAGS': '${__libversionflags(__env__,"SHLIBVERSION","_SHLIBVERSIONFLAGS")}', + '__libversionflags': <function __libversionflags at 0x700000&gt;, '_concat': <function _concat at 0x700000&gt;, '_defines': <function _defines at 0x700000&gt;, '_stripixes': <function _stripixes at 0x700000&gt;} diff --git a/doc/generated/examples/troubleshoot_explain1_3.xml b/doc/generated/examples/troubleshoot_explain1_3.xml index 246ee56..9763efe 100644 --- a/doc/generated/examples/troubleshoot_explain1_3.xml +++ b/doc/generated/examples/troubleshoot_explain1_3.xml @@ -3,5 +3,5 @@ cp file.in file.oout scons: warning: Cannot find target file.out after building -File "/home/bdbaddog/scons/as_scons/bootstrap/src/script/scons.py", line 199, in <module> +File "/home/bdbaddog/scons/scons/bootstrap/src/script/scons.py", line 199, in <module> diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 3ad36e5..e80c1c9 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -2565,10 +2565,10 @@ sources = Glob('*.cpp', exclude=['os_*_specific_*.cpp']) + Glob('os_%s_specific_ - Help(text) + Help(text, append=False) - env.Help(text) + env.Help(text, append=False) @@ -2576,12 +2576,18 @@ This specifies help text to be printed if the argument is given to scons. -If +If Help -is called multiple times, the text is appended together in the order -that +is called multiple times, the text is appended together in the order that Help -is called. +is called. With append set to False, any +Help +text generated with +AddOption +is clobbered. If append is True, the AddOption help is prepended to the help +string, thus preserving the + +message. diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen index db89475..fcb7587 100644 --- a/doc/generated/tools.gen +++ b/doc/generated/tools.gen @@ -129,6 +129,14 @@ Sets construction variables for generic POSIX C++ compilers. Sets: &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-CXXFILESUFFIX;, &cv-link-CXXFLAGS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-OBJSUFFIX;, &cv-link-SHCXX;, &cv-link-SHCXXCOM;, &cv-link-SHCXXFLAGS;, &cv-link-SHOBJSUFFIX;.Uses: &cv-link-CXXCOMSTR;. + + cyglink + + +Set construction variables for cygwin linker/loader. + +Sets: &cv-link-IMPLIBPREFIX;, &cv-link-IMPLIBSUFFIX;, &cv-link-LDMODULEVERSIONFLAGS;, &cv-link-LINKFLAGS;, &cv-link-RPATHPREFIX;, &cv-link-RPATHSUFFIX;, &cv-link-SHLIBPREFIX;, &cv-link-SHLIBSUFFIX;, &cv-link-SHLIBVERSIONFLAGS;, &cv-link-SHLINKCOM;, &cv-link-SHLINKFLAGS;, &cv-link-_LDMODULEVERSIONFLAGS;, &cv-link-_SHLIBVERSIONFLAGS;. + default @@ -395,7 +403,7 @@ Sets construction variables for the D language compiler GDC. This is actually a toolset, which supports internationalization and -localization of sofware being constructed with SCons. The toolset loads +localization of software being constructed with SCons. The toolset loads following tools: @@ -454,7 +462,7 @@ Sets construction variables for the GNU F95/F2003 GNU compiler. Set construction variables for GNU linker/loader. -Sets: &cv-link-RPATHPREFIX;, &cv-link-RPATHSUFFIX;, &cv-link-SHLINKFLAGS;. +Sets: &cv-link-LDMODULEVERSIONFLAGS;, &cv-link-RPATHPREFIX;, &cv-link-RPATHSUFFIX;, &cv-link-SHLIBVERSIONFLAGS;, &cv-link-SHLINKFLAGS;, &cv-link-_LDMODULESONAME;, &cv-link-_SHLIBSONAME;. gs @@ -623,7 +631,7 @@ Sets construction variables for the Sets construction variables for generic POSIX linkers. -Sets: &cv-link-LDMODULE;, &cv-link-LDMODULECOM;, &cv-link-LDMODULEFLAGS;, &cv-link-LDMODULEPREFIX;, &cv-link-LDMODULESUFFIX;, &cv-link-LIBDIRPREFIX;, &cv-link-LIBDIRSUFFIX;, &cv-link-LIBLINKPREFIX;, &cv-link-LIBLINKSUFFIX;, &cv-link-LINK;, &cv-link-LINKCOM;, &cv-link-LINKFLAGS;, &cv-link-SHLIBSUFFIX;, &cv-link-SHLINK;, &cv-link-SHLINKCOM;, &cv-link-SHLINKFLAGS;.Uses: &cv-link-LDMODULECOMSTR;, &cv-link-LINKCOMSTR;, &cv-link-SHLINKCOMSTR;. +Sets: &cv-link-LDMODULE;, &cv-link-LDMODULECOM;, &cv-link-LDMODULEFLAGS;, &cv-link-LDMODULENOVERSIONSYMLINKS;, &cv-link-LDMODULEPREFIX;, &cv-link-LDMODULESUFFIX;, &cv-link-LDMODULEVERSION;, &cv-link-LDMODULEVERSIONFLAGS;, &cv-link-LIBDIRPREFIX;, &cv-link-LIBDIRSUFFIX;, &cv-link-LIBLINKPREFIX;, &cv-link-LIBLINKSUFFIX;, &cv-link-LINK;, &cv-link-LINKCOM;, &cv-link-LINKFLAGS;, &cv-link-SHLIBSUFFIX;, &cv-link-SHLINK;, &cv-link-SHLINKCOM;, &cv-link-SHLINKFLAGS;, &cv-link-__LDMODULEVERSIONFLAGS;, &cv-link-__SHLIBVERSIONFLAGS;.Uses: &cv-link-LDMODULECOMSTR;, &cv-link-LINKCOMSTR;, &cv-link-SHLINKCOMSTR;. linkloc @@ -901,7 +909,7 @@ Sets construction variables for the SGI linker. Sets construction variables for the Sun library archiver. -Sets: &cv-link-AR;, &cv-link-ARCOM;, &cv-link-ARFLAGS;, &cv-link-LIBPREFIX;, &cv-link-LIBSUFFIX;, &cv-link-SHLINK;, &cv-link-SHLINKCOM;, &cv-link-SHLINKFLAGS;.Uses: &cv-link-ARCOMSTR;, &cv-link-SHLINKCOMSTR;. +Sets: &cv-link-AR;, &cv-link-ARCOM;, &cv-link-ARFLAGS;, &cv-link-LIBPREFIX;, &cv-link-LIBSUFFIX;.Uses: &cv-link-ARCOMSTR;. sunc++ diff --git a/doc/generated/tools.mod b/doc/generated/tools.mod index 5a5795a..1191e6a 100644 --- a/doc/generated/tools.mod +++ b/doc/generated/tools.mod @@ -22,6 +22,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. cvf"> CVS"> cXX"> +cyglink"> default"> dmd"> docbook"> @@ -132,6 +133,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. cvf"> CVS"> cXX"> +cyglink"> default"> dmd"> docbook"> diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen index 04c3efe..3d8a87a 100644 --- a/doc/generated/variables.gen +++ b/doc/generated/variables.gen @@ -13,6 +13,24 @@ ]> + + __LDMODULEVERSIONFLAGS + + +This construction variable automatically introduces $_LDMODULEVERSIONFLAGS +if $LDMODULEVERSION is set. Othervise it evaluates to an empty string. + + + + + __SHLIBVERSIONFLAGS + + +This construction variable automatically introduces $_SHLIBVERSIONFLAGS +if $SHLIBVERSION is set. Othervise it evaluates to an empty string. + + + AR @@ -2874,6 +2892,52 @@ The default list is: + + IMPLIBNOVERSIONSYMLINKS + + +Used to override $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS when +creating versioned import library for a shared library/loadable module. If not defined, +then $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS is used to determine +whether to disable symlink generation or not. + + + + + IMPLIBPREFIX + + +The prefix used for import library names. For example, cygwin uses import +libraries (libfoo.dll.a) in pair with dynamic libraries +(cygfoo.dll). The cyglink linker sets +$IMPLIBPREFIX to 'lib' and $SHLIBPREFIX +to 'cyg'. + + + + + IMPLIBSUFFIX + + +The suffix used for import library names. For example, cygwin uses import +libraries (libfoo.dll.a) in pair with dynamic libraries +(cygfoo.dll). The cyglink linker sets +$IMPLIBSUFFIX to '.dll.a' and $SHLIBSUFFIX +to '.dll'. + + + + + IMPLIBVERSION + + +Used to override $SHLIBVERSION/$LDMODULEVERSION when +generating versioned import library for a shared library/loadable module. If +undefined, the $SHLIBVERSION/$LDMODULEVERSION is used to +determine the version of versioned import library. + + + IMPLICIT_COMMAND_DEPENDENCIES @@ -3408,6 +3472,15 @@ General user options passed to the linker for building loadable modules. + + LDMODULENOVERSIONSYMLINKS + + +Instructs the LoadableModule builder to not automatically create symlinks +for versioned modules. Defaults to $SHLIBNOVERSIONSYMLINKS + + + LDMODULEPREFIX @@ -3419,6 +3492,16 @@ the same as + _LDMODULESONAME + + +A macro that automatically generates loadable module's SONAME based on $TARGET, +$LDMODULEVERSION and $LDMODULESUFFIX. Used by LoadableModule builder +when the linker tool supports SONAME (e.g. gnulink). + + + LDMODULESUFFIX @@ -3430,6 +3513,42 @@ the same as $SHLIBSUFFIX. + + LDMODULEVERSION + + +When this construction variable is defined, a versioned loadable module +is created by LoadableModule builder. This activates the +$_LDMODULEVERSIONFLAGS and thus modifies the $LDMODULECOM as +required, adds the version number to the library name, and creates the symlinks +that are needed. $LDMODULEVERSION versions should exist in the same +format as $SHLIBVERSION. + + + + + LDMODULEVERSIONFLAGS + + +Extra flags added to $LDMODULECOM when building versioned +LoadableModule. These flags are only used when $LDMODULEVERSION is +set. + + + + + _LDMODULEVERSIONFLAGS + + +This macro automatically introduces extra flags to $LDMODULECOM when +building versioned LoadableModule (that is when +$LDMODULEVERSION is set). _LDMODULEVERSIONFLAGS +usually adds $SHLIBVERSIONFLAGS and some extra dynamically generated +options (such as -Wl,-soname=$_LDMODULESONAME). It is unused +by plain (unversioned) loadable modules. + + + LEX @@ -6385,6 +6504,15 @@ TODO + + SHLIBNOVERSIONSYMLINKS + + +Instructs the SharedLibrary builder to not create symlinks for versioned +shared libraries. + + + SHLIBPREFIX @@ -6393,6 +6521,16 @@ The prefix used for shared library file names. + + _SHLIBSONAME + + +A macro that automatically generates shared library's SONAME based on $TARGET, +$SHLIBVERSION and $SHLIBSUFFIX. Used by SharedLibrary builder when +the linker tool supports SONAME (e.g. gnulink). + + + SHLIBSUFFIX @@ -6406,11 +6544,35 @@ The suffix used for shared library file names. When this construction variable is defined, a versioned shared library -is created. This modifies the $SHLINKFLAGS as required, adds -the version number to the library name, and creates the symlinks that -are needed. $SHLIBVERSION needs to be of the form X.Y.Z, -where X and Y are numbers, and Z is a number but can also contain -letters to designate alpha, beta, or release candidate patch levels. +is created by SharedLibrary builder. This activates the +$_SHLIBVERSIONFLAGS and thus modifies the $SHLINKCOM as +required, adds the version number to the library name, and creates the symlinks +that are needed. $SHLIBVERSION versions should exist as alpha-numeric, +decimal-delimited values as defined by the regular expression "\w+[\.\w+]*". +Example $SHLIBVERSION values include '1', '1.2.3', and '1.2.gitaa412c8b'. + + + + + SHLIBVERSIONFLAGS + + +Extra flags added to $SHLINKCOM when building versioned +SharedLibrary. These flags are only used when $SHLIBVERSION is +set. + + + + + _SHLIBVERSIONFLAGS + + +This macro automatically introduces extra flags to $SHLINKCOM when +building versioned SharedLibrary (that is when $SHLIBVERSION +is set). _SHLIBVERSIONFLAGS usually adds $SHLIBVERSIONFLAGS +and some extra dynamically generated options (such as +-Wl,-soname=$_SHLIBSONAME. It is unused by "plain" +(unversioned) shared libraries. @@ -6484,6 +6646,18 @@ The suffix used for shared object file names. + + SONAME + + +Variable used to hard-code SONAME for versioned shared library/loadable module. + +env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2') + +The variable is used, for example, by gnulink linker tool. + + + SOURCE diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod index fc12a92..f7303f2 100644 --- a/doc/generated/variables.mod +++ b/doc/generated/variables.mod @@ -8,6 +8,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. --> +$__LDMODULEVERSIONFLAGS"> +$__SHLIBVERSIONFLAGS"> $AR"> $ARCHITECTURE"> $ARCOM"> @@ -216,6 +218,10 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $HOST_ARCH"> $HOST_OS"> $IDLSUFFIXES"> +$IMPLIBNOVERSIONSYMLINKS"> +$IMPLIBPREFIX"> +$IMPLIBSUFFIX"> +$IMPLIBVERSION"> $IMPLICIT_COMMAND_DEPENDENCIES"> $INCPREFIX"> $INCSUFFIX"> @@ -253,8 +259,13 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $LDMODULECOM"> $LDMODULECOMSTR"> $LDMODULEFLAGS"> +$LDMODULENOVERSIONSYMLINKS"> $LDMODULEPREFIX"> +$_LDMODULESONAME"> $LDMODULESUFFIX"> +$LDMODULEVERSION"> +$LDMODULEVERSIONFLAGS"> +$_LDMODULEVERSIONFLAGS"> $LEX"> $LEXCOM"> $LEXCOMSTR"> @@ -505,15 +516,20 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $SHFORTRANPPCOM"> $SHFORTRANPPCOMSTR"> $SHLIBEMITTER"> +$SHLIBNOVERSIONSYMLINKS"> $SHLIBPREFIX"> +$_SHLIBSONAME"> $SHLIBSUFFIX"> $SHLIBVERSION"> +$SHLIBVERSIONFLAGS"> +$_SHLIBVERSIONFLAGS"> $SHLINK"> $SHLINKCOM"> $SHLINKCOMSTR"> $SHLINKFLAGS"> $SHOBJPREFIX"> $SHOBJSUFFIX"> +$SONAME"> $SOURCE"> $SOURCE_URL"> $SOURCES"> @@ -646,6 +662,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. --> +$__LDMODULEVERSIONFLAGS"> +$__SHLIBVERSIONFLAGS"> $AR"> $ARCHITECTURE"> $ARCOM"> @@ -854,6 +872,10 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $HOST_ARCH"> $HOST_OS"> $IDLSUFFIXES"> +$IMPLIBNOVERSIONSYMLINKS"> +$IMPLIBPREFIX"> +$IMPLIBSUFFIX"> +$IMPLIBVERSION"> $IMPLICIT_COMMAND_DEPENDENCIES"> $INCPREFIX"> $INCSUFFIX"> @@ -891,8 +913,13 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $LDMODULECOM"> $LDMODULECOMSTR"> $LDMODULEFLAGS"> +$LDMODULENOVERSIONSYMLINKS"> $LDMODULEPREFIX"> +$_LDMODULESONAME"> $LDMODULESUFFIX"> +$LDMODULEVERSION"> +$LDMODULEVERSIONFLAGS"> +$_LDMODULEVERSIONFLAGS"> $LEX"> $LEXCOM"> $LEXCOMSTR"> @@ -1143,15 +1170,20 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $SHFORTRANPPCOM"> $SHFORTRANPPCOMSTR"> $SHLIBEMITTER"> +$SHLIBNOVERSIONSYMLINKS"> $SHLIBPREFIX"> +$_SHLIBSONAME"> $SHLIBSUFFIX"> $SHLIBVERSION"> +$SHLIBVERSIONFLAGS"> +$_SHLIBVERSIONFLAGS"> $SHLINK"> $SHLINKCOM"> $SHLINKCOMSTR"> $SHLINKFLAGS"> $SHOBJPREFIX"> $SHOBJSUFFIX"> +$SONAME"> $SOURCE"> $SOURCE_URL"> $SOURCES"> diff --git a/doc/user/output.xml b/doc/user/output.xml index cdb28d7..78dcca4 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -83,6 +83,21 @@ Type: 'scons program' to build the production program, + Optionally, one can specify the append flag: + + + + + +Help(""" +Type: 'scons program' to build the production program, + 'scons debug' to build the debug version. +""", append=True) + + + + + (Note the above use of the Python triple-quote syntax, which comes in very handy for specifying multi-line strings like help text.) @@ -120,6 +135,13 @@ Type: 'scons program' to build the production program, + When used with &AddOption; Help("text", append=False) will clobber any help output associated with AddOption(). + To preserve the help output from AddOption(), set append=True. + + + + + Another use would be to make the help text conditional on some variable. For example, suppose you only want to display diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml index c74ad5e..8553fbe 100644 --- a/src/engine/SCons/Script/SConscript.xml +++ b/src/engine/SCons/Script/SConscript.xml @@ -240,7 +240,7 @@ file is found. -(text) +(text, append=False) @@ -248,12 +248,18 @@ This specifies help text to be printed if the argument is given to &scons;. -If +If &f-Help; -is called multiple times, the text is appended together in the order -that +is called multiple times, the text is appended together in the order that &f-Help; -is called. +is called. With append set to False, any +&f-Help; +text generated with +&f-AddOption; +is clobbered. If append is True, the AddOption help is prepended to the help +string, thus preserving the + +message. -- cgit v0.12