<?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">

<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>
Holds a callable object which will be invoked to transform long
command lines (string or list) into an alternate form.
Length limits on various operating systems
may cause long command lines to fail when calling out to
a shell to run the command.
Most often affects linking, when there are many object files and/or
libraries to be linked, but may also affect other
compilation steps which have many arguments.
&cv-TEMPFILE; is not called directly,
but rather is typically embedded in another
&consvar;, to be expanded when used. Example:
</para>

<example_commands>
env["TEMPFILE"] = TempFileMunge
env["LINKCOM"] = "${TEMPFILE('$LINK $TARGET $SOURCES', '$LINKCOMSTR')}"
</example_commands>

<para>
The SCons default value for &cv-TEMPFILE;,
<classname>TempFileMunge</classname>,
performs command substitution on the passed command line,
calculates whether modification is needed,
then puts all but the first word (assumed to be the command name)
of the resulting list into a temporary file
(sometimes called a response file or command file),
and returns a new command line consisting of the
the command name and an appropriately formatted reference
to the temporary file.
</para>

<para>
A replacement for the default tempfile object would need
to do fundamentally the same thing, including taking into account
the values of
&cv-link-MAXLINELENGTH;,
&cv-link-TEMPFILEPREFIX;,
&cv-link-TEMPFILESUFFIX;,
&cv-link-TEMPFILEARGJOIN;,
&cv-link-TEMPFILEDIR;
and
&cv-link-TEMPFILEARGESCFUNC;.
If a particular use case requires a different transformation
than the default, it is recommended to copy the mechanism and
define a new &consvar; and rewrite the relevant <literal>*COM</literal>
variable(s) to use it, to avoid possibly disrupting existing uses
of &cv-TEMPFILE;.
</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 prefix must include the compiler syntax to actually
include and process the file.
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 needed 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.
If unset, the &Python;
<systemitem>tempfile</systemitem> module chooses the directory
based on the <envar>TMPDIR</envar>,
<envar>TEMP</envar>
or <envar>TMP</envar> environment variables.
If the default path causes processing errors,
set &cv-TEMPFILEDIR; to a safer alternative.
For example, on Windows,
the default temporary file path contains the username.
If the username contains non-7-bit-ASCII characters,
there may decoding errors opening the path to the temporary file.
See also &cv-link-TEMPFILEENCODING;.
</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.
The function must accept a single string argument and
and return 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>

<cvar name="TEMPFILEENCODING">
<summary>
<para>
By default, the long-lines temporary file (aka "response file") created by the
&cv-link-TEMPFILE; function will be encoded in the &Python;
default encoding, UTF-8.
If the external command which reads the response file
encounters decoding errors
(usually, if that command depends on Windows legacy code pages,
and a pathname in the response file
or the response file path itself cannot
be represented in the 7-bit ASCII characer set),
set this variable to the appropriate codec.
See also &cv-link-TEMPFILEDIR;.
</para>
<para><emphasis>New in version 4.10.0</emphasis></para>
</summary>
</cvar>

</sconsdoc>
