path: root/SCons/Platform/Platform.xml

<?xml version="1.0"?>
<!--
Copyright 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 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<cvar name="ESCAPE">
<summary>
<para>
A function that will be called to escape shell special characters in
command lines. The function should take one argument: the command line
string to escape; and should return the escaped command line.
</para>
</summary>
</cvar>

<cvar name="LIBPREFIX">
<summary>
<para>
The prefix used for (static) library file names.
A default value is set for each platform
(posix, win32, os2, etc.),
but the value is overridden by individual tools
(ar, mslib, sgiar, sunar, tlib, etc.)
to reflect the names of the libraries they create.
</para>
</summary>
</cvar>

<cvar name="LIBPREFIXES">
<summary>
<para>
A list of all legal prefixes for library file names
on the current platform.
When searching for library dependencies,
SCons will look for files with these prefixes,
the base library name,
and suffixes from the &cv-link-LIBSUFFIXES; list.
</para>
</summary>
</cvar>

<cvar name="LIBSUFFIX">
<summary>
<para>
The suffix used for (static) library file names.
A default value is set for each platform
(posix, win32, os2, etc.),
but the value is overridden by individual tools
(ar, mslib, sgiar, sunar, tlib, etc.)
to reflect the names of the libraries they create.
</para>
</summary>
</cvar>

<cvar name="LIBSUFFIXES">
<summary>
<para>
A list of all legal suffixes for library file names.
on the current platform.
When searching for library dependencies,
SCons will look for files with prefixes from the &cv-link-LIBPREFIXES; list,
the base library name,
and these suffixes.
</para>
</summary>
</cvar>

<cvar name="OBJPREFIX">
<summary>
<para>
The prefix used for (static) object file names.
</para>
</summary>
</cvar>

<cvar name="OBJSUFFIX">
<summary>
<para>
The suffix used for (static) object file names.
</para>
</summary>
</cvar>

<cvar name="PLATFORM">
  <summary>
    <para>
      The name of the platform used to create this &consenv;.
      &SCons; sets this when initializing the platform,
      which by default is auto-detected
      (see the <parameter>platform</parameter>
      argument to &f-link-Environment;).
    </para>

    <example_commands>
env = Environment(tools=[])
if env['PLATFORM'] == 'cygwin':
    Tool('mingw')(env)
else:
    Tool('msvc')(env)
    </example_commands>
  </summary>
</cvar>

<cvar name="HOST_OS">
  <summary>
    <para>
      The name of the host operating system for the platform
      used to create this &consenv;.
      The platform code sets this when initializing
      (see &cv-link-PLATFORM; and the
      <parameter>platform</parameter> argument to &f-link-Environment;).
    </para>
    <para>
      Should be considered immutable.
      &cv-HOST_OS; is not currently used by &SCons;,
      but the option is reserved to do so in future
    </para>
  </summary>
</cvar>

<cvar name="TARGET_OS">
  <summary>
    <para>
      The name of the operating system that objects
      created using this &consenv; should target.
      Can be set when creating a &consenv; by passing as a keyword
      argument in the &f-link-Environment; call;.
    </para>
    <para>
      &cv-TARGET_OS; is not currently used by &SCons;
      but the option is reserved to do so in future
    </para>
  </summary>
</cvar>

<cvar name="HOST_ARCH">
  <summary>
    <para>
      The name of the host hardware architecture
      used to create this &consenv;.
      The platform code sets this when initializing
      (see &cv-link-PLATFORM; and the
      <parameter>platform</parameter> argument to &f-link-Environment;).
      Note the detected name of the architecture may not be identical to
      that returned by the &Python;
      <systemitem>platform.machine</systemitem> method.
    </para>
    <para>
      On the <literal>win32</literal> platform,
      if the &MSVC; compiler is available,
      &t-link-msvc; tool setup is done using
      &cv-HOST_ARCH; and &cv-link-TARGET_ARCH;.
      Changing the values at any later time will not cause
      the tool to be reinitialized.
      Valid host arch values are
      <literal>x86</literal> and <literal>arm</literal>
      for 32-bit hosts and
      <literal>amd64</literal>, <literal>arm64</literal>,
      and <literal>x86_64</literal> for 64-bit hosts.
    </para>
    <para>
      Should be considered immutable.
      &cv-HOST_ARCH; is not currently used by other platforms,
      but the option is reserved to do so in future
    </para>
  </summary>
</cvar>

<cvar name="TARGET_ARCH">
  <summary>
    <para>
      The name of the hardware architecture that objects
      created using this &consenv; should target.
      Can be set when creating a &consenv; by passing as a keyword
      argument in the &f-link-Environment; call.
    </para>
    <para>
      On the <literal>win32</literal> platform,
      if the &MSVC; compiler is available,
      &t-link-msvc; tool setup is done using
      &cv-link-HOST_ARCH; and &cv-TARGET_ARCH;.
      If a value is not specified,
      will be set to the same value as &cv-link-HOST_ARCH;.
      Changing the value after the environment is initialized
      will not cause the tool to be reinitialized.
      Compiled objects will be in the target architecture if
      the compilation system supports generating for that target.
      The latest compiler which can fulfill the requirement will
      be selected, unless a different version is directed by the
      value of the &cv-link-MSVC_VERSION; &consvar;.
    </para>
    <para>
      On the win32/msvc combination, valid target arch values are
      <literal>x86</literal>,
      <literal>arm</literal>,
      <literal>i386</literal>
      for 32-bit targets and
      <literal>amd64</literal>,
      <literal>arm64</literal>,
      <literal>x86_64</literal>
      and <literal>ia64</literal> (Itanium)
      for 64-bit targets.
      For example, if you want to compile 64-bit binaries, you would set
      <literal>TARGET_ARCH='x86_64'</literal> when creating the &consenv;.
      Note that not all target architectures are
      supported for all Visual Studio / MSVC versions.
      Check the relevant Microsoft documentation.
    </para>
    <para>
      &cv-TARGET_ARCH; is not currently used by other compilation tools,
      but the option is reserved to do so in future
    </para>
  </summary>
</cvar>

<cvar name="PROGPREFIX">
<summary>
<para>
The prefix used for executable file names.
</para>
</summary>
</cvar>

<cvar name="PROGSUFFIX">
<summary>
<para>
The suffix used for executable file names.
</para>
</summary>
</cvar>

<cvar name="SHELL">
<summary>
<para>
A string naming the shell program that will be passed to the
&cv-SPAWN;
function.
See the
&cv-SPAWN;
construction variable for more information.
</para>
</summary>
</cvar>

<cvar name="SHLIBPREFIX">
<summary>
<para>
The prefix used for shared library file names.
</para>
</summary>
</cvar>

<cvar name="SHLIBSUFFIX">
<summary>
<para>
The suffix used for shared library file names.
</para>
</summary>
</cvar>

<cvar name="SHOBJPREFIX">
<summary>
<para>
The prefix used for shared object file names.
</para>
</summary>
</cvar>

<cvar name="SHOBJSUFFIX">
<summary>
<para>
The suffix used for shared object file names.
</para>
</summary>
</cvar>

<cvar name="TEMPFILE">
<summary>
<para>
A callable object used to handle overly long command line strings,
since operations which call out to a shell will fail
if the line is longer than the shell can accept.
This tends to particularly impact linking.
The tempfile object stores the command line in a temporary
file in the appropriate format, and returns
an alternate command line so the invoked tool will make
use of the contents of the temporary file.
If you need to replace the default tempfile object,
the callable should take into account the settings of
&cv-link-MAXLINELENGTH;,
&cv-link-TEMPFILEPREFIX;,
&cv-link-TEMPFILESUFFIX;,
&cv-link-TEMPFILEARGJOIN;,
&cv-link-TEMPFILEDIR;
and
&cv-link-TEMPFILEARGESCFUNC;.
</para>
</summary>
</cvar>

<cvar name="TEMPFILEPREFIX">
<summary>
<para>
The prefix for the name of the temporary file used
to store command lines exceeding &cv-link-MAXLINELENGTH;.
The default prefix is <literal>'@'</literal>, which works for the &MSVC;
and GNU toolchains on Windows.
Set this appropriately for other toolchains,
for example <literal>'-@'</literal> for the diab compiler
or <literal>'-via'</literal> for ARM toolchain.
</para>
</summary>
</cvar>

<cvar name="TEMPFILESUFFIX">
<summary>
<para>
The suffix for the name of the temporary file used
to store command lines exceeding &cv-link-MAXLINELENGTH;.
The suffix should include the dot ('.') if one is wanted as
it will not be added automatically.
The default is <filename>.lnk</filename>.
</para>
</summary>
</cvar>

<cvar name="TEMPFILEARGJOIN">
<summary>
<para>
The string to use to join the arguments passed to
&cv-link-TEMPFILE; when the command line exceeds the limit set by
&cv-link-MAXLINELENGTH;.
The default value is a space.
However for MSVC, MSLINK the default is a line separator
as defined by <systemitem>os.linesep</systemitem>.
Note this value is used literally and not expanded by the subst logic.
</para>
</summary>
</cvar>

<cvar name="TEMPFILEDIR">
<summary>
<para>
The directory to create the long-lines temporary file in.
</para>
</summary>
</cvar>

<cvar name="TEMPFILEARGESCFUNC">
<summary>
<para>
The default argument escape function is
<function>SCons.Subst.quote_spaces</function>.
If you need to apply extra operations on a command argument
(to fix Windows slashes, normalize paths, etc.)
before writing to the temporary file,
you can set the &cv-TEMPFILEARGESCFUNC; variable to a custom function.
Such a function takes a single string argument and returns
a new string with any modifications applied.
Example:
</para>

<example_commands>
import sys
import re
from SCons.Subst import quote_spaces

WINPATHSEP_RE = re.compile(r"\\([^\"'\\]|$)")

def tempfile_arg_esc_func(arg):
    arg = quote_spaces(arg)
    if sys.platform != "win32":
        return arg
    # GCC requires double Windows slashes, let's use UNIX separator
    return WINPATHSEP_RE.sub(r"/\1", arg)

env["TEMPFILEARGESCFUNC"] = tempfile_arg_esc_func
</example_commands>
</summary>
</cvar>

</sconsdoc>