summaryrefslogtreecommitdiff
path: root/src/engine/SCons/Tool/__init__.xml
diff options
context:
space:
mode:
authorLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
committerLuca Falavigna <dktrkranz@debian.org>2014-04-26 15:11:58 +0200
commit140d836e9cd54fb67b969fd82ef7ed19ba574d40 (patch)
tree0df3e32ee39603d43f9b90fd2f2e1f7cce4249d4 /src/engine/SCons/Tool/__init__.xml
parentcb3425abe0bc2d05caf401ca24b82a25a81f009d (diff)
Imported Upstream version 2.3.1upstream/2.3.1
Diffstat (limited to 'src/engine/SCons/Tool/__init__.xml')
-rw-r--r--src/engine/SCons/Tool/__init__.xml130
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>