<?xml version="1.0"?>
<!--
SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
SPDX-License-Identifier: MIT
SPDX-FileType: DOCUMENTATION

This file is processed by the bin/SConsDoc.py module.
-->

<!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 http://www.scons.org/dbxsd/v1.0/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; &consvar;
(<filename>.c</filename> by default)
is automatically added to the target
if it is not already present.
Example:
</para>

<example_commands>
# builds foo.c
env.CFile(target='foo.c', source='foo.l')

# builds bar.c
env.CFile(target='bar', source='bar.y')
</example_commands>

<!--para>  ** Left here for reference, does not need to be user-visible. **
Note that for yacc files,
the output file name is derived from <parameter>target</parameter>,
or from the source file name if a target is not specified;
the traditional yacc default name
<filename>y.tab.c</filename> is not used.
</para-->
</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.
The suffix specified by the &cv-link-CXXFILESUFFIX; &consvar;
(<filename>.cc</filename> by default)
is automatically added to the target
if it is not already present.
Example:
</para>

<example_commands>
# builds foo.cc
env.CXXFile(target='foo.cc', source='foo.ll')

# builds bar.cc
env.CXXFile(target='bar', source='bar.yy')
</example_commands>

<!--para>  ** Left here for reference, does not need to be user-visible. **
Note that for yacc files,
the output file name is derived from <parameter>target</parameter>,
or from the source file name if a target is not specified;
the traditional yacc default name
<filename>y.tab.cc</filename> is not used.
</para -->
</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,
then they will be automatically
compiled to object files using the
&b-Object;
builder method;
see that builder method's description for
a list of legal source file suffixes
and how they are interpreted.
The target executable file prefix,
specified by the &cv-link-PROGPREFIX; &consvar;
(nothing by default),
and suffix,
specified by the &cv-link-PROGSUFFIX; &consvar;
(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_commands>
env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
</example_commands>
</summary>
</builder>

<builder name="SharedLibrary">
<summary>
<para>
Builds a shared library
given one or more object files
and/or C, C++, D or Fortran source files.
Any source files listed in the
<parameter>source</parameter> parameter
will be automatically
compiled to object files suitable
for use in a shared library.
Any object files listed in the
<parameter>source</parameter> parameter
must have been built for a shared library
(that is, using the
&b-SharedObject;
builder method).
&scons;
will raise an error if there is any mismatch.
</para>

<para>
The target library file prefix,
specified by the &cv-link-SHLIBPREFIX; &consvar;
(by default, <filename>lib</filename> on POSIX systems,
nothing on Windows systems),
and suffix,
specified by the &cv-link-SHLIBSUFFIX; &consvar;
(by default, <filename>.dll</filename> on Windows systems,
<filename>.so</filename> on POSIX systems),
are automatically added (if not already present)
to the target name to make up the library filename.
On a POSIX system, if the &cv-link-SHLIBVERSION; &consvar; is set,
it is appended (following a period) to the resulting library name.
</para>

<para>
Example:
</para>

<example_commands>
env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
</example_commands>

<para>
On Windows systems, the
&b-SharedLibrary;
builder method will always build an import library
(<filename>.lib</filename>)
in addition to the shared library (<filename>.dll</filename>),
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 library
(<filename>.dll.a</filename>)
in addition to the shared library (<filename>.dll</filename>),
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>
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-link-LoadableModule; builder for the latter.
</para>

<para>
If &cv-link-SHLIBVERSION; is defined, a versioned
shared library is created. This modifies &cv-link-SHLINKFLAGS; as required,
adds the version number to the library name, and creates any
symbolic links that are needed.
</para>

<example_commands>
env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
</example_commands>

<para>
On a POSIX system, supplying a simple version string (no dots)
creates exactly one symbolic link: <literal>SHLIBVERSION="1"</literal>
would create (for example) library <filename>libbar.so.1</filename>
and symbolic link <filename>libbar.so</filename>.
Supplying a dotted version string will create two symbolic links
(irrespective of the number of segments in the version):
<literal>SHLIBVERSION="1.5.2"</literal> for the same library
would create library <filename>libbar.so.1.5.2</filename>
and symbolic links <filename>libbar.so</filename> and
<filename>libbar.so.1</filename>. A Darwin (OSX)
system creates one symlink in either case,
for the second example the library would be
<filename>libbar.1.5.2.dylib</filename>
and the link would be <filename>libbar.dylib</filename>.
</para>

<para>
On Windows systems, specifying the
<parameter>register=1</parameter> keyword argument
will cause the <filename>.dll</filename> to be
registered after it is built.
The command that is run is determined by the &cv-link-REGSVR; &consvar;
(<command>regsvr32</command> by default),
and the flags passed are determined by &cv-link-REGSVRFLAGS;.  By
default, &cv-link-REGSVRFLAGS; includes the <option>/s</option> option,
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_commands>
env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
</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 intended for
inclusion in a shared library.
Source files must have one of the same set of extensions
specified for the
&b-link-StaticObject;
builder method.
The target object file prefix,
specified by the &cv-link-SHOBJPREFIX; &consvar;
(by default, the same as &cv-link-OBJPREFIX;),
and suffix,
specified by the &cv-link-SHOBJSUFFIX; &consvar;,
are automatically added to the target if not already present.
&b-SharedObject; is a single-source builder.
Examples:
</para>

<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')
env.SharedObject(source=Glob('*.c'))
</example_commands>

<para>
On some platforms building a shared object requires additional
compiler option(s)
(e.g. <option>-fPIC</option> for <command>gcc</command>)
in addition to those needed to build a
normal (static) object.
If shared and static objects differ,
&SCons; will allow only shared objects
to be linked into a shared library,
and will use a different suffix for shared objects
to help indicate and track the difference.
</para>

<para>
Source files will be scanned
according to the suffix mappings in the
<classname>SourceFileScanner</classname>
object.
See the manpage section "Scanner Objects"
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,
then they will be automatically
compiled to object files.
The static library file prefix,
specified by the &cv-link-LIBPREFIX; &consvar;
(by default, <filename>lib</filename> on POSIX systems,
nothing on Windows systems),
and suffix,
specified by the &cv-link-LIBSUFFIX; &consvar;
(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_commands>
env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
</example_commands>

<para>
Any object files listed in the
<parameter>source</parameter>
must have been built for a static library
(that is, using the
&b-StaticObject;
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.
The file extension mapping is shown in the table:
</para>

<literallayout><literal>
  .asm    assembly language file
  .ASM    assembly language file
  .c      C file
  .C      Windows:  C file
          POSIX:  C++ file
  .cc     C++ file
  .cpp    C++ file
  .cxx    C++ file
  .cxx    C++ file
  .c++    C++ file
  .C++    C++ file
  .d      D file
  .f      Fortran file
  .F      Windows:  Fortran file
          POSIX:  Fortran file + C pre-processor
  .for    Fortran file
  .FOR    Fortran file
  .fpp    Fortran file + C pre-processor
  .FPP    Fortran file + C pre-processor
  .m      Object C file
  .mm     Object C++ file
  .s      assembly language file
  .S      Windows:  assembly language file
          ARM: CodeSourcery Sourcery Lite
  .sx     assembly language file + C pre-processor
          POSIX:  assembly language file + C pre-processor
  .spp    assembly language file + C pre-processor
  .SPP    assembly language file + C pre-processor
</literal></literallayout>

<para>
The target object file prefix,
specified by the &cv-link-OBJPREFIX; &consvar;
(empty string by default),
and suffix,
specified by the &cv-link-OBJSUFFIX; &consvar;
(<filename>.obj</filename> on Windows systems,
<filename>.o</filename> on POSIX systems),
are automatically added to the target if not already present.
&b-StaticObject; is a single-source builder.
Examples:
</para>

<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')
env.StaticObject(source=Glob('*.c'))
</example_commands>

<para>
Source files will be scanned
according to the suffix mappings in the
<classname>SourceFileScanner</classname>
object.
See the manpage section "Scanner Objects"
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.
The default suffix, of course, is
<filename>.c</filename>
(lower case).
On case-insensitive systems (like Windows),
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.
The default suffix is
<filename>.cc</filename>.
SCons also treats files with the suffixes
<filename>.cpp</filename>,
<filename>.cxx</filename>,
<filename>.c++</filename>,
and
<filename>.C++</filename>
as C++ files,
and files with
<filename>.mm</filename>
suffixes as Objective-C++ files.
On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
SCons also treats
<filename>.C</filename>
(upper case) files
as C++ files.
</para>
</summary>
</cvar>

<cvar name="IMPLIBVERSION">
<summary>
<para>
Used to override &cv-link-SHLIBVERSION;/&cv-link-LDMODULEVERSION; when
generating versioned import library for a shared library/loadable module. If
undefined, the &cv-link-SHLIBVERSION;/&cv-link-LDMODULEVERSION; is used to
determine the version of versioned import library.
</para>
</summary>
</cvar>

<cvar name="LIBEMITTER">
<summary>
<para>
Contains the emitter specification for the
&b-link-StaticLibrary; builder.
The manpage section "Builder Objects" contains
general information on specifying emitters.
</para>
</summary>
</cvar>

<cvar name="LDMODULEVERSION">
<summary>
<para>
When this &consvar; is defined, a versioned loadable module
is created by &b-link-LoadableModule; builder. This activates the
&cv-link-_LDMODULEVERSIONFLAGS; and thus modifies the &cv-link-LDMODULECOM; as
required, adds the version number to the library name, and creates the symlinks
that are needed. &cv-link-LDMODULEVERSION; versions should exist in the same
format as &cv-link-SHLIBVERSION;.
</para>
</summary>
</cvar>

<cvar name="LDMODULEEMITTER">
<summary>
<para>
Contains the emitter specification for the
&b-link-LoadableModule; builder.
The manpage section "Builder Objects" contains
general information on specifying emitters.
</para>
</summary>
</cvar>

<cvar name="SHLIBEMITTER">
<summary>
<para>
Contains the emitter specification for the
&b-link-SharedLibrary; builder.
The manpage section "Builder Objects" contains
general information on specifying emitters.
</para>
</summary>
</cvar>

<cvar name="PROGEMITTER">
<summary>
<para>
Contains the emitter specification for the
&b-link-Program; builder.
The manpage section "Builder Objects" contains
general information on specifying emitters.
</para>
</summary>
</cvar>

<cvar name="SHLIBVERSION">
<summary>
<para>
When this &consvar; is defined, a versioned shared library
is created by the &b-link-SharedLibrary; builder. This activates the
&cv-link-_SHLIBVERSIONFLAGS; and thus modifies the &cv-link-SHLINKCOM; as
required, adds the version number to the library name, and creates the symlinks
that are needed.  &cv-link-SHLIBVERSION; versions should exist as alphanumeric,
decimal-delimited values as defined by the regular expression "\w+[\.\w+]*".
Example &cv-link-SHLIBVERSION; values include '1', '1.2.3', and '1.2.gitaa412c8b'.
</para>
</summary>
</cvar>

</sconsdoc>
