diff options
Diffstat (limited to 'src/engine/SCons/Tool/__init__.xml')
| -rw-r--r-- | src/engine/SCons/Tool/__init__.xml | 130 |
1 files changed, 110 insertions, 20 deletions
diff --git a/src/engine/SCons/Tool/__init__.xml b/src/engine/SCons/Tool/__init__.xml index 51ae8b0..deceaa3 100644 --- a/src/engine/SCons/Tool/__init__.xml +++ b/src/engine/SCons/Tool/__init__.xml @@ -1,11 +1,31 @@ +<?xml version="1.0" encoding="UTF-8"?> <!-- -Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation +Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation This file is processed by the bin/SConsDoc.py module. See its __doc__ string for a discussion of the format. --> + +<!DOCTYPE sconsdoc [ +<!ENTITY % scons SYSTEM '../../../../doc/scons.mod'> +%scons; +<!ENTITY % builders-mod SYSTEM '../../../../doc/generated/builders.mod'> +%builders-mod; +<!ENTITY % functions-mod SYSTEM '../../../../doc/generated/functions.mod'> +%functions-mod; +<!ENTITY % tools-mod SYSTEM '../../../../doc/generated/tools.mod'> +%tools-mod; +<!ENTITY % variables-mod SYSTEM '../../../../doc/generated/variables.mod'> +%variables-mod; +]> + +<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> + <builder name="CFile"> <summary> +<para> Builds a C source file given a lex (<filename>.l</filename>) or yacc (<filename>.y</filename>) input file. The suffix specified by the &cv-link-CFILESUFFIX; construction variable @@ -13,18 +33,20 @@ The suffix specified by the &cv-link-CFILESUFFIX; construction variable is automatically added to the target if it is not already present. Example: +</para> -<example> +<example_commands> # builds foo.c env.CFile(target = 'foo.c', source = 'foo.l') # builds bar.c env.CFile(target = 'bar', source = 'bar.y') -</example> +</example_commands> </summary> </builder> <builder name="CXXFile"> <summary> +<para> Builds a C++ source file given a lex (<filename>.ll</filename>) or yacc (<filename>.yy</filename>) input file. @@ -33,44 +55,52 @@ The suffix specified by the &cv-link-CXXFILESUFFIX; construction variable is automatically added to the target if it is not already present. Example: +</para> -<example> +<example_commands> # builds foo.cc env.CXXFile(target = 'foo.cc', source = 'foo.ll') # builds bar.cc env.CXXFile(target = 'bar', source = 'bar.yy') -</example> +</example_commands> </summary> </builder> <builder name="Library"> <summary> +<para> A synonym for the &b-StaticLibrary; builder method. +</para> </summary> </builder> <builder name="LoadableModule"> <summary> +<para> On most systems, this is the same as &b-SharedLibrary;. On Mac OS X (Darwin) platforms, this creates a loadable module bundle. +</para> </summary> </builder> <builder name="Object"> <summary> +<para> A synonym for the &b-StaticObject; builder method. +</para> </summary> </builder> <builder name="Program"> <summary> +<para> Builds an executable given one or more object files or C, C++, D, or Fortran source files. If any C, C++, D or Fortran source files are specified, @@ -89,15 +119,17 @@ by default, <filename>.exe</filename> on Windows systems, nothing on POSIX systems) are automatically added to the target if not already present. Example: +</para> -<example> +<example_commands> env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f']) -</example> +</example_commands> </summary> </builder> <builder name="SharedLibrary"> <summary> +<para> Builds a shared library (<filename>.so</filename> on a POSIX system, <filename>.dll</filename> on Windows) @@ -118,11 +150,13 @@ by default, <filename>.dll</filename> on Windows systems, <filename>.so</filename> on POSIX systems) are automatically added to the target if not already present. Example: +</para> -<example> +<example_commands> env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o']) -</example> +</example_commands> +<para> On Windows systems, the &b-SharedLibrary; builder method will always build an import @@ -131,7 +165,20 @@ in addition to the shared (<filename>.dll</filename>) library, adding a <filename>.lib</filename> library with the same basename if there is not already a <filename>.lib</filename> file explicitly listed in the targets. +</para> + +<para> +On Cygwin systems, the +&b-SharedLibrary; +builder method will always build an import +(<filename>.dll.a</filename>) library +in addition to the shared (<filename>.dll</filename>) library, +adding a <filename>.dll.a</filename> library with the same basename +if there is not already a <filename>.dll.a</filename> file explicitly +listed in the targets. +</para> +<para> Any object files listed in the <literal>source</literal> must have been built for a shared library @@ -140,25 +187,33 @@ must have been built for a shared library builder method). &scons; will raise an error if there is any mismatch. +</para> +<para> On some platforms, there is a distinction between a shared library (loaded automatically by the system to resolve external references) and a loadable module (explicitly loaded by user action). For maximum portability, use the &b-LoadableModule; builder for the latter. +</para> +<para> When the &cv-link-SHLIBVERSION; construction variable is defined a versioned shared library is created. This modifies the &cv-link-SHLINKFLAGS; as required, adds the version number to the library name, and creates the symlinks that are needed. &cv-link-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. +</para> +<para> 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, libbar.so.2, and libbar.so.2.3; on a Darwin (OSX) system +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. +</para> +<para> On Windows systems, specifying <literal>register=1</literal> will cause the <filename>.dll</filename> to be @@ -171,20 +226,24 @@ to prevent dialogs from popping up and requiring user attention when it is run. If you change &cv-link-REGSVRFLAGS;, be sure to include the <option>/s</option> option. For example, +</para> -<example> +<example_commands> env.SharedLibrary(target = 'bar', source = ['bar.cxx', 'foo.obj'], register=1) -</example> +</example_commands> +<para> will register <filename>bar.dll</filename> as a COM object when it is done linking it. +</para> </summary> </builder> <builder name="SharedObject"> <summary> +<para> Builds an object file for inclusion in a shared library. Source files must have one of the same set of extensions @@ -210,24 +269,28 @@ and suffix (specified by the &cv-link-SHOBJSUFFIX; construction variable) are automatically added to the target if not already present. Examples: +</para> -<example> +<example_commands> env.SharedObject(target = 'ddd', source = 'ddd.c') env.SharedObject(target = 'eee.o', source = 'eee.cpp') env.SharedObject(target = 'fff.obj', source = 'fff.for') -</example> +</example_commands> +<para> Note that the source files will be scanned according to the suffix mappings in the <literal>SourceFileScanner</literal> object. See the section "Scanner Objects," below, for more information. +</para> </summary> </builder> <builder name="StaticLibrary"> <summary> +<para> Builds a static library given one or more object files or C, C++, D or Fortran source files. If any source files are given, @@ -245,11 +308,13 @@ by default, <filename>.lib</filename> on Windows systems, <filename>.a</filename> on POSIX systems) are automatically added to the target if not already present. Example: +</para> -<example> +<example_commands> env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o']) -</example> +</example_commands> +<para> Any object files listed in the <literal>source</literal> must have been built for a static library @@ -258,16 +323,19 @@ must have been built for a static library builder method). &scons; will raise an error if there is any mismatch. +</para> </summary> </builder> <builder name="StaticObject"> <summary> +<para> Builds a static object file from one or more C, C++, D, or Fortran source files. Source files must have one of the following extensions: +</para> -<example> +<example_commands> .asm assembly language file .ASM assembly language file .c C file @@ -296,8 +364,9 @@ Source files must have one of the following extensions: POSIX: assembly language file + C pre-processor .spp assembly language file + C pre-processor .SPP assembly language file + C pre-processor -</example> +</example_commands> +<para> The target object file prefix (specified by the &cv-link-OBJPREFIX; construction variable; nothing by default) and suffix @@ -306,32 +375,38 @@ and suffix <filename>.o</filename> on POSIX systems) are automatically added to the target if not already present. Examples: +</para> -<example> +<example_commands> env.StaticObject(target = 'aaa', source = 'aaa.c') env.StaticObject(target = 'bbb.o', source = 'bbb.c++') env.StaticObject(target = 'ccc.obj', source = 'ccc.f') -</example> +</example_commands> +<para> Note that the source files will be scanned according to the suffix mappings in <literal>SourceFileScanner</literal> object. See the section "Scanner Objects," below, for more information. +</para> </summary> </builder> <cvar name="CCVERSION"> <summary> +<para> The version number of the C compiler. This may or may not be set, depending on the specific C compiler being used. +</para> </summary> </cvar> <cvar name="CFILESUFFIX"> <summary> +<para> The suffix for C source files. This is used by the internal CFile builder when generating C files from Lex (.l) or YACC (.y) input files. @@ -343,19 +418,23 @@ SCons also treats <filename>.C</filename> (upper case) files as C files. +</para> </summary> </cvar> <cvar name="CXXVERSION"> <summary> +<para> The version number of the C++ compiler. This may or may not be set, depending on the specific C++ compiler being used. +</para> </summary> </cvar> <cvar name="CXXFILESUFFIX"> <summary> +<para> The suffix for C++ source files. This is used by the internal CXXFile builder when generating C++ files from Lex (.ll) or YACC (.yy) input files. @@ -376,34 +455,45 @@ SCons also treats <filename>.C</filename> (upper case) files as C++ files. +</para> </summary> </cvar> <cvar name="LIBEMITTER"> <summary> +<para> TODO +</para> </summary> </cvar> <cvar name="SHLIBEMITTER"> <summary> +<para> TODO +</para> </summary> </cvar> <cvar name="PROGEMITTER"> <summary> +<para> TODO +</para> </summary> </cvar> <cvar name="SHLIBVERSION"> <summary> +<para> When this construction variable is defined, a versioned shared library is created. This modifies the &cv-link-SHLINKFLAGS; as required, adds the version number to the library name, and creates the symlinks that are needed. &cv-link-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. +</para> </summary> </cvar> + +</sconsdoc> |