From 140d836e9cd54fb67b969fd82ef7ed19ba574d40 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 26 Apr 2014 15:11:58 +0200 Subject: Imported Upstream version 2.3.1 --- doc/user/sconf.in | 486 ------------------------------------------------------ 1 file changed, 486 deletions(-) delete mode 100644 doc/user/sconf.in (limited to 'doc/user/sconf.in') diff --git a/doc/user/sconf.in b/doc/user/sconf.in deleted file mode 100644 index 31b7fcc..0000000 --- a/doc/user/sconf.in +++ /dev/null @@ -1,486 +0,0 @@ - - - - - &SCons; has integrated support for multi-platform build configuration - similar to that offered by GNU &Autoconf;, - such as - figuring out what libraries or header files - are available on the local system. - This section describes how to use - this &SCons; feature. - - - - - - This chapter is still under development, - so not everything is explained as well as it should be. - See the &SCons; man page for additional information. - - - -
- &Configure_Contexts; - - - - The basic framework for multi-platform build configuration - in &SCons; is to attach a &configure_context; to a - construction environment by calling the &Configure; function, - perform a number of checks for - libraries, functions, header files, etc., - and to then call the configure context's &Finish; method - to finish off the configuration: - - - - - env = Environment() - conf = Configure(env) - # Checks for libraries, header files, etc. go here! - env = conf.Finish() - - - - - &SCons; provides a number of basic checks, - as well as a mechanism for adding your own custom checks. - - - - - - Note that &SCons; uses its own dependency - mechanism to determine when a check - needs to be run--that is, - &SCons; does not run the checks - every time it is invoked, - but caches the values returned by previous checks - and uses the cached values unless something has changed. - This saves a tremendous amount - of developer time while working on - cross-platform build issues. - - - - - - The next sections describe - the basic checks that &SCons; supports, - as well as how to add your own custom checks. - - - -
- -
- Checking for the Existence of Header Files - - - - Testing the existence of a header file - requires knowing what language the header file is. - A configure context has a &CheckCHeader; method - that checks for the existence of a C header file: - - - - - env = Environment() - conf = Configure(env) - if not conf.CheckCHeader('math.h'): - print 'Math.h must be installed!' - Exit(1) - if conf.CheckCHeader('foo.h'): - conf.env.Append('-DHAS_FOO_H') - env = conf.Finish() - - - - - Note that you can choose to terminate - the build if a given header file doesn't exist, - or you can modify the construction environment - based on the existence of a header file. - - - - - - If you need to check for the existence - a C++ header file, - use the &CheckCXXHeader; method: - - - - - env = Environment() - conf = Configure(env) - if not conf.CheckCXXHeader('vector.h'): - print 'vector.h must be installed!' - Exit(1) - env = conf.Finish() - - -
- -
- Checking for the Availability of a Function - - - - Check for the availability of a specific function - using the &CheckFunc; method: - - - - - env = Environment() - conf = Configure(env) - if not conf.CheckFunc('strcpy'): - print 'Did not find strcpy(), using local version' - conf.env.Append(CPPDEFINES = '-Dstrcpy=my_local_strcpy') - env = conf.Finish() - - -
- -
- Checking for the Availability of a Library - - - - Check for the availability of a library - using the &CheckLib; method. - You only specify the basename of the library, - you don't need to add a lib - prefix or a .a or .lib suffix: - - - - - env = Environment() - conf = Configure(env) - if not conf.CheckLib('m'): - print 'Did not find libm.a or m.lib, exiting!' - Exit(1) - env = conf.Finish() - - - - - Because the ability to use a library successfully - often depends on having access to a header file - that describes the library's interface, - you can check for a library - and a header file - at the same time by using the - &CheckLibWithHeader; method: - - - - - env = Environment() - conf = Configure(env) - if not conf.CheckLibWithHeader('m', 'math.h', 'c'): - print 'Did not find libm.a or m.lib, exiting!' - Exit(1) - env = conf.Finish() - - - - - This is essentially shorthand for - separate calls to the &CheckHeader; and &CheckLib; - functions. - - - -
- -
- Checking for the Availability of a &typedef; - - - - Check for the availability of a &typedef; - by using the &CheckType; method: - - - - - env = Environment() - conf = Configure(env) - if not conf.CheckType('off_t'): - print 'Did not find off_t typedef, assuming int' - conf.env.Append(CCFLAGS = '-Doff_t=int') - env = conf.Finish() - - - - - You can also add a string that will be - placed at the beginning of the test file - that will be used to check for the &typedef;. - This provide a way to specify - files that must be included to find the &typedef;: - - - - - env = Environment() - conf = Configure(env) - if not conf.CheckType('off_t', '#include <sys/types.h>\n'): - print 'Did not find off_t typedef, assuming int' - conf.env.Append(CCFLAGS = '-Doff_t=int') - env = conf.Finish() - - -
- -
- Adding Your Own Custom Checks - - - - A custom check is a Python function - that checks for a certain condition to exist - on the running system, - usually using methods that &SCons; - supplies to take care of the details - of checking whether a compilation succeeds, - a link succeeds, - a program is runnable, - etc. - A simple custom check for the existence of - a specific library might look as follows: - - - - - mylib_test_source_file = """ - #include <mylib.h> - int main(int argc, char **argv) - { - MyLibrary mylib(argc, argv); - return 0; - } - """ - - def CheckMyLibrary(context): - context.Message('Checking for MyLibrary...') - result = context.TryLink(mylib_test_source_file, '.c') - context.Result(result) - return result - - - - - The &Message; and &Result; methods - should typically begin and end a custom check to - let the user know what's going on: - the &Message; call prints the - specified message (with no trailing newline) - and the &Result; call prints - yes if the check succeeds and - no if it doesn't. - The &TryLink; method - actually tests for whether the - specified program text - will successfully link. - - - - - - (Note that a custom check can modify - its check based on any arguments you - choose to pass it, - or by using or modifying the configure context environment - in the context.env attribute.) - - - - - - This custom check function is - then attached to the &configure_context; - by passing a dictionary - to the &Configure; call - that maps a name of the check - to the underlying function: - - - - - env = Environment() - conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) - - - - - You'll typically want to make - the check and the function name the same, - as we've done here, - to avoid potential confusion. - - - - - - We can then put these pieces together - and actually call the CheckMyLibrary check - as follows: - - - - - mylib_test_source_file = """ - #include <mylib.h> - int main(int argc, char **argv) - { - MyLibrary mylib(argc, argv); - return 0; - } - """ - - def CheckMyLibrary(context): - context.Message('Checking for MyLibrary... ') - result = context.TryLink(mylib_test_source_file, '.c') - context.Result(result) - return result - - env = Environment() - conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) - if not conf.CheckMyLibrary(): - print 'MyLibrary is not installed!' - Exit(1) - env = conf.Finish() - - # We would then add actual calls like Program() to build - # something using the "env" construction environment. - - - - - If MyLibrary is not installed on the system, - the output will look like: - - - - - % scons - scons: Reading SConscript file ... - Checking for MyLibrary... failed - MyLibrary is not installed! - - - - - If MyLibrary is installed, - the output will look like: - - - - - % scons - scons: Reading SConscript file ... - Checking for MyLibrary... failed - scons: done reading SConscript - scons: Building targets ... - . - . - . - - -
- -
- Not Configuring When Cleaning Targets - - - - Using multi-platform configuration - as described in the previous sections - will run the configuration commands - even when invoking - scons -c - to clean targets: - - - - - % scons -Q -c - Checking for MyLibrary... yes - Removed foo.o - Removed foo - - - - - Although running the platform checks - when removing targets doesn't hurt anything, - it's usually unnecessary. - You can avoid this by using the - &GetOption; method to - check whether the (clean) - option has been invoked on the command line: - - - - - env = Environment() - if not env.GetOption('clean'): - conf = Configure(env, custom_tests = {'CheckMyLibrary' : CheckMyLibrary}) - if not conf.CheckMyLibrary(): - print 'MyLibrary is not installed!' - Exit(1) - env = conf.Finish() - - - - % scons -Q -c - Removed foo.o - Removed foo - - -
- - -- cgit v1.2.3