From cb220b17b676b2fffebf0fc31fb98a5d200eaa7a Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 8 Dec 2021 08:40:31 -0700 Subject: Updates to Configure Context man.section. * Finish() is no longer listed in the SConf.Finish form, as it is only a context method. Same for Define(). * Added the CheckProg method, which is the only one of the default_tests set not listed in the manpage - it was already in the User Guide. * CheckTypeSize is listed together with CheckType for easier finding. * Slight rewording of a few methods. * Added some markup to make live links to referenced elements. * Added clarification that the CheckContext is not the same as the configure context after some recent user confusion on that point. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 376 +++++++++++++++++++++++++++++------------------------- 1 file changed, 203 insertions(+), 173 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 47cdfd2..1c9d86c 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -3817,7 +3817,6 @@ to avoid unnecessary test execution. - SConf.Finish(context) context.Finish() This method must be called after configuration is done. @@ -3899,11 +3898,9 @@ Returns a boolean indicating success or failure. SConf.CheckCHeader(context, header, [include_quotes]) context.CheckCHeader(header, [include_quotes]) -This is a wrapper around -SConf.CheckHeader -which checks if +Checks if header -is usable in the C language. +is usable when compiling a C language program. header may be a list, in which case the last item in the list @@ -3919,6 +3916,8 @@ must be a two character string, where the first character denotes the opening quote and the second character denotes the closing quote. By default, both characters are " (double quote). +Note this is a wrapper around +CheckHeader. Returns a boolean indicating success or failure. @@ -3927,11 +3926,9 @@ Returns a boolean indicating success or failure. SConf.CheckCXXHeader(context, header, [include_quotes]) context.CheckCXXHeader(header, [include_quotes]) -This is a wrapper around -SConf.CheckHeader -which checks if +Checks if header -is usable in the C++ language. +is usable when compiling a C++ language program. header may be a list, in which case the last item in the list @@ -3947,6 +3944,8 @@ must be a two character string, where the first character denotes the opening quote and the second character denotes the closing quote. By default, both characters are " (double quote). +Note this is a wrapper around +CheckHeader. Returns a boolean indicating success or failure. @@ -3958,8 +3957,7 @@ Returns a boolean indicating success or failure. Checks if the specified C or C++ library function is available based on the context's local environment settings (that is, using -the values of CFLAGS, -CPPFLAGS, LIBS +the values of &cv-link-CFLAGS;, &cv-link-CPPFLAGS;, &cv-link-LIBS; or other relevant &consvars;). @@ -4017,7 +4015,7 @@ If is not set or is None, then -SConf.CheckLib +CheckLib just checks if you can link against the specified library. @@ -4036,7 +4034,7 @@ Returns a boolean indicating success or failure. Provides a more sophisticated way to check against libraries then the -SConf.CheckLib call. +CheckLib call. library specifies the library or a list of libraries to check. header @@ -4093,20 +4091,61 @@ an error message on failure. + SConf.CheckTypeSize(context, type_name, [header, language, expect]) + context.CheckTypeSize(type_name, [header, language, expect]) + +Checks for the size of a type defined by +typedef. +type_name +specifies the typedef name to check for. +The optional +header +argument is a string +that will be +placed at the top +of the test file +that will be compiled +to check if the type exists; +the default is empty. +If the optional +expect, +is supplied, it should be an integer size; +&CheckTypeSize; will fail unless +type_name is actually +that size. +Returns the size in bytes, or zero if the type was not found +(or if the size did not match expect). + + +For example, + + +CheckTypeSize('short', expect=2) + + +will return the size 2 only if short is +actually two bytes. + + + + SConf.CheckCC(context) context.CheckCC() -Checks whether the C compiler (as defined by the -CC &consvar;) works +Checks whether the C compiler +(as defined by the &cv-link-CC; &consvar;) works, by trying to compile a small source file. +This provides a more rigorous check: +by default, &SCons; itself only detects if there is a program +with the correct name, not if it is a functioning compiler. Returns a boolean indicating success or failure. -By default, SCons only detects if there is a program with the correct name, not -if it is a functioning compiler. - -This uses the exact same command as the one used by the object builder for C -source files, so it can be used to detect if a particular compiler flag works or -not. +The test program will be built with the +same command line as the one used by the &b-link-Object; builder +for C source files, so by setting relevant &consvars; +it can be used to detect if particular compiler flags will +be accepted or rejected by the compiler. + @@ -4114,16 +4153,20 @@ not. SConf.CheckCXX(context) context.CheckCXX() -Checks whether the C++ compiler (as defined by the -CXX &consvar;) -works by trying to compile a small source file. By default, -SCons only detects if there is a program with the correct name, -not if it is a functioning compiler. +Checks whether the C++ compiler +(as defined by the &cv-link-CXX; &consvar;) works, +by trying to compile a small source file. +This provides a more rigorous check: +by default, &SCons; itself only detects if there is a program +with the correct name, not if it is a functioning compiler. Returns a boolean indicating success or failure. -This uses the exact same command as the one used by the object builder for -C++ source files, so it can be used to detect if a particular compiler flag -works or not. +The test program will be built with the +same command line as the one used by the &b-link-Object; builder +for C++ source files, so by setting relevant &consvars; +it can be used to detect if particular compiler flags will +be accepted or rejected by the compiler. + @@ -4132,16 +4175,21 @@ works or not. context.CheckSHCC() Checks whether the shared-object C compiler (as defined by the -SHCC &consvar;) works -by trying to compile a small source file. By default, -SCons only detects if there is a program with the correct name, -not if it is a functioning compiler. +&cv-link-SHCC; &consvar;) works +by trying to compile a small source file. +This provides a more rigorous check: +by default, &SCons; itself only detects if there is a program +with the correct name, not if it is a functioning compiler. Returns a boolean indicating success or failure. -This uses the exact same command as the one used by the object builder for C -source file, so it can be used to detect if a particular compiler flag works or -not. This does not check whether the object code can be used to build a shared -library, only that the compilation (not link) succeeds. +The test program will be built with the +same command line as the one used by the &b-link-SharedObject; builder +for C source files, so by setting relevant &consvars; +it can be used to detect if particular compiler flags will +be accepted or rejected by the compiler. +Note this does not check whether a shared library/dll can +be created. + @@ -4150,54 +4198,34 @@ library, only that the compilation (not link) succeeds. context.CheckSHCXX() Checks whether the shared-object C++ compiler (as defined by the -SHCXX &consvar;) -works by trying to compile a small source file. By default, -SCons only detects if there is a program with the correct name, -not if it is a functioning compiler. +&cv-link-SHCXX; &consvar;) +works by trying to compile a small source file. +This provides a more rigorous check: +by default, &SCons; itself only detects if there is a program +with the correct name, not if it is a functioning compiler. Returns a boolean indicating success or failure. -This uses the exact same command as the one used by the object builder for -C++ source files, so it can be used to detect if a particular compiler flag -works or not. This does not check whether the object code can be used to build -a shared library, only that the compilation (not link) succeeds. +The test program will be built with the +same command line as the one used by the &b-link-SharedObject; builder +for C++ source files, so by setting relevant &consvars; +it can be used to detect if particular compiler flags will +be accepted or rejected by the compiler. +Note this does not check whether a shared library/dll can +be created. + - SConf.CheckTypeSize(context, type_name, [header, language, expect]) - context.CheckTypeSize(type_name, [header, language, expect]) + SConf.CheckProg(context, prog_name) + context.CheckProg(prog_name) -Checks for the size of a type defined by -typedef. -type_name -specifies the typedef name to check for. -The optional -header -argument is a string -that will be -placed at the top -of the test file -that will be compiled -to check if the type exists; -the default is empty. -If the optional -expect, -is supplied, it should be an integer size; -&CheckTypeSize; will fail unless -type_name is actually -that size. -Returns the size in bytes, or zero if the type was not found -(or if the size did not match expect). - - -For example, - - -CheckTypeSize('short', expect=2) - - -will return the size 2 only if short is -actually two bytes. +Checks if +prog_name +exists in the path &SCons; will use at build time. +(context.env['ENV']['PATH']). +Returns a string containing the path to the program, +or None on failure. @@ -4218,20 +4246,25 @@ Returns a boolean indicating success or failure. - SConf.Define(context, symbol, [value, comment]) context.Define(symbol, [value, comment]) -This function does not check for anything, but defines a -preprocessor symbol that will be added to the configuration header file. -It is the equivalent of AC_DEFINE, -and defines the symbol -name -with the optional -value -and the optional comment -comment. +This method does not check for anything, but rather forces +the definition of a preprocessor macro that will be added +to the configuration header file. +name is the macro's identifier. +If value is given, +it will be be used as the macro replacement value. +If value is a string and needs to +display with quotes, the quotes need to be included, +as in '"string"' +If the optional +comment is given, +it is inserted as a comment above the macro definition +(suitable comment marks will be added automatically). +This is analagous to using AC_DEFINE in &Autoconf;. + -Define Examples: +Examples: env = Environment() @@ -4247,7 +4280,7 @@ conf.Define("A_SYMBOL", 1) -Be careful about quoting string values, though: +Examples of quoting string values: env = Environment() @@ -4263,7 +4296,7 @@ conf.Define("A_SYMBOL", '"YA"') -For comment: +Example including comment: env = Environment() @@ -4280,127 +4313,122 @@ conf.Define("A_SYMBOL", 1, "Set to 1 if you have a symbol") You can define your own custom checks -in addition to the predefined checks. -You pass a dictionary of these -to the &Configure; function -as the custom_tests argument. -This dictionary maps the names of the checks -to the user defined Python callables -(either Python functions or class instances implementing a -__call__ -method). -Each custom check will be called with a first -argument of a CheckContext, -instance followed by the arguments, +in addition to using the predefined checks. +To enable custom checks, +pass a dictionary to the &f-link-Configure; function +as the custom_tests parameter. +The dictionary maps the names of the checks +to the custom check callables +(either a Python function or an instance of a class implementing a +__call__ method). +Each custom check will be called with a +a CheckContext +instance as the first parameter followed by the remaining arguments, which must be supplied by the user of the check. -A CheckContext instance defines the following methods: +A CheckContext is not the same as +a configure context; rather it is an instance of a class +which contains a configure context +(available as chk_ctx.sconf). +A CheckContext +provides the following methods which custom checks +can make use of:: - context.Message(text) + chk_ctx.Message(text) -Displays a message, as an indicator of progess. -text -will be displayed, e.g. -Checking for library X.... +Displays text +as an indicator of progess. +For example: Checking for library X.... Usually called before the check is started. - context.Result(res) + chk_ctx.Result(res) -Displays a result message, as an indicator of progress. - -res -can be either an integer or a string. If an integer, displays -yes -(if res evaluates True) -or no -(if res evaluates False). -If a string, it is displayed as-is. +Displays a result message as an indicator of progress. +If res is an integer, +displays yes +if res evaluates true +or no if false. +If res is a string, +it is displayed as-is. Usually called after the check has completed. - context.TryCompile(text, extension='') + chk_ctx.TryCompile(text, extension='') -Checks if a file with the specified -extension -(e.g. '.c') containing -text -can be compiled using the environment's -&Object; builder. +Checks if a file containing text +and given the specified extension (e.g. +'.c') +can be compiled to an object file +using the environment's &b-link-Object; builder. Returns a boolean indicating success or failure. - context.TryLink(text, extension='') + chk_ctx.TryLink(text, extension='') -Checks, if a file with the specified -extension -(e.g. '.c') containing -text -can be compiled using the environment's &Program; builder. +Checks if a file containing text +and given the specified extension (e.g. +'.c') +can be compiled to an executable program +using the environment's &b-link-Program; builder. Returns a boolean indicating success or failure. - context.TryRun(text, extension='') + chk_ctx.TryRun(text, extension='') -Checks if a file with the specified -extension -(e.g. '.c') containing -text -can be compiled using the environment's -&Program; builder. On success, the program is run. If the program -executes successfully -(that is, its return status is 0), -a tuple -(1, outputStr) -is returned, where -outputStr -is the standard output of the -program. +Checks if a file containing text +and given the specified extension (e.g. +'.c') +can be compiled to an excutable program +using the environment's &b-link-Program; builder and subsequently executed. +Execution is only attempted if the build succeeds. +If the program executes successfully +(that is, its return status is 0), +a tuple (True, outputStr) +is returned, where outputStr +is the standard output of the program. If the program fails execution (its return status is non-zero), -then (0, '') is returned. +then (False, '') is returned. - context.TryAction(action, [text, extension='']) + chk_ctx.TryAction(action, [text, extension='']) Checks if the specified action -with an optional source file (contents -text, -extension -extension) +with an optional source file +(contents text, +given extension extension) can be executed. action -may be anything which can be converted to a -&scons; -Action. -On success, -(1, outputStr) -is returned, where -outputStr +may be anything which can be converted to an +Action Object. +On success, a tuple +(True, outputStr) +is returned, where outputStr is the content of the target file. On failure -(0, '') +(False, '') is returned. - context.TryBuild(builder[, text, extension='']) + chk_ctx.TryBuild(builder, [text, extension='']) Low level implementation for testing specific builds; the methods above are based on this method. @@ -4412,7 +4440,7 @@ of a source file with optional extension, returns a boolean indicating success or failure. In addition, -context.lastTarget +chk_ctx.lastTarget is set to the build target node if the build was successful. @@ -4420,22 +4448,24 @@ is set to the build target node if the build was successful. Example of implementing and using custom tests: -def CheckQt(context, qtdir): - context.Message( 'Checking for qt ...' ) - lastLIBS = context.env['LIBS'] - lastLIBPATH = context.env['LIBPATH'] - lastCPPPATH= context.env['CPPPATH'] - context.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtdir + '/include') - ret = context.TryLink(""" +def CheckQt(chk_ctx, qtdir): + chk_ctx.Message('Checking for qt ...') + lastLIBS = chk_ctx.env['LIBS'] + lastLIBPATH = chk_ctx.env['LIBPATH'] + lastCPPPATH = chk_ctx.env['CPPPATH'] + chk_ctx.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtdir + '/include') + ret = chk_ctx.TryLink( + """\ #include <qapp.h> int main(int argc, char **argv) { QApplication qapp(argc, argv); return 0; } -""") +""" + ) if not ret: - context.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH) - context.Result( ret ) + chkctx.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH) + chkctx.Result(ret) return ret env = Environment() -- cgit v0.12 From 31164eb92ba3e173841b3fe117b2c79288740d2d Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 8 Dec 2021 08:45:11 -0700 Subject: Drop the SConf.Foo variants for Configure checks Manpage has documented two forms of calling configure checks for a long time - as a function from the SConf module and as a method of a configure context. The former don't appear to work, so just drop them. Separate commit so it's easy to revert. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 1c9d86c..9d9d979 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -3862,7 +3862,6 @@ or c++. - SConf.CheckHeader(context, header, [include_quotes, language]) context.CheckHeader(header, [include_quotes, language]) Checks if @@ -3895,7 +3894,6 @@ Returns a boolean indicating success or failure. - SConf.CheckCHeader(context, header, [include_quotes]) context.CheckCHeader(header, [include_quotes]) Checks if @@ -3923,7 +3921,6 @@ Returns a boolean indicating success or failure. - SConf.CheckCXXHeader(context, header, [include_quotes]) context.CheckCXXHeader(header, [include_quotes]) Checks if @@ -3951,7 +3948,6 @@ Returns a boolean indicating success or failure. - SConf.CheckFunc(context, function_name, [header, language]) context.CheckFunc(function_name, [header, language]) Checks if the specified @@ -3989,7 +3985,6 @@ an error message on failure. - SConf.CheckLib(context, [library, symbol, header, language, autoadd=True]) context.CheckLib([library, symbol, header, language, autoadd=True]) Checks if @@ -4029,7 +4024,6 @@ Returns a boolean indicating success or failure. - SConf.CheckLibWithHeader(context, library, header, language, [call, autoadd=True]) context.CheckLibWithHeader(library, header, language, [call, autoadd=True]) @@ -4064,7 +4058,6 @@ Returns a boolean indicating success or failure. - SConf.CheckType(context, type_name, [includes, language]) context.CheckType(type_name, [includes, language]) Checks for the existence of a type defined by @@ -4091,7 +4084,6 @@ an error message on failure. - SConf.CheckTypeSize(context, type_name, [header, language, expect]) context.CheckTypeSize(type_name, [header, language, expect]) Checks for the size of a type defined by @@ -4129,7 +4121,6 @@ actually two bytes. - SConf.CheckCC(context) context.CheckCC() Checks whether the C compiler @@ -4150,7 +4141,6 @@ be accepted or rejected by the compiler. - SConf.CheckCXX(context) context.CheckCXX() Checks whether the C++ compiler @@ -4171,7 +4161,6 @@ be accepted or rejected by the compiler. - SConf.CheckSHCC(context) context.CheckSHCC() Checks whether the shared-object C compiler (as defined by the @@ -4194,7 +4183,6 @@ be created. - SConf.CheckSHCXX(context) context.CheckSHCXX() Checks whether the shared-object C++ compiler (as defined by the @@ -4217,7 +4205,6 @@ be created. - SConf.CheckProg(context, prog_name) context.CheckProg(prog_name) Checks if @@ -4230,7 +4217,6 @@ or None on failure. - SConf.CheckDeclaration(context, symbol, [includes, language]) context.CheckDeclaration(symbol, [includes, language]) Checks if the specified -- cgit v0.12 From f888ece8759e3a531e6c26dce6fee4e8628e0cf4 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 8 Dec 2021 09:10:18 -0700 Subject: Fixed sider-detected misspelling [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 9d9d979..517ce41 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -4247,7 +4247,7 @@ If the optional comment is given, it is inserted as a comment above the macro definition (suitable comment marks will be added automatically). -This is analagous to using AC_DEFINE in &Autoconf;. +This is analogous to using AC_DEFINE in &Autoconf;. Examples: -- cgit v0.12