SCons/Tool/applelink.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11         <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  12         %scons;
  13         <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  14         %builders-mod;
  15         <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  16         %functions-mod;
  17         <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  18         %tools-mod;
  19         <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  20         %variables-mod;
  21         ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27     <tool name="applelink">
  28         <summary>
  29             <para>
  30                 Sets construction variables for the Apple linker
  31                 (similar to the GNU linker).
  32             </para>
  33         </summary>
  34         <sets>
  35             <item>FRAMEWORKPATHPREFIX</item>
  36             <item>_FRAMEWORKPATH</item>
  37             <item>_FRAMEWORKS</item>
  38             <item>LINKCOM</item>
  39             <item>SHLINKFLAGS</item>
  40             <item>SHLINKCOM</item>
  41             <item>LDMODULEPREFIX</item>
  42             <item>LDMODULESUFFIX</item>
  43             <item>LDMODULEFLAGS</item>
  44             <item>LDMODULECOM</item>
  45             <item>APPLELINK_CURRENT_VERSION</item>
  46             <item>APPLELINK_COMPATIBILITY_VERSION</item>
  47             <item>APPLELINK_NO_CURRENT_VERSION</item>
  48             <item>APPLELINK_NO_COMPATIBILITY_VERSION</item>
  49             <item>_APPLELINK_CURRENT_VERSION</item>
  50             <item>_APPLELINK_COMPATIBILITY_VERSION</item>
  51         </sets>
  52         <uses>
  53             <item>FRAMEWORKSFLAGS</item>
  54         </uses>
  55     </tool>
  56
  57
  58     <cvar name="APPLELINK_COMPATIBILITY_VERSION">
  59         <summary>
  60             <para>
  61                 On Mac OS X this is used to set the linker flag:
  62
  63                 -compatibility_version
  64             </para>
  65             <para>
  66                 The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
  67                 255, Z can be omitted or between 1 and 255. This value will be derived from &cv-link-SHLIBVERSION; if
  68                 not
  69                 specified. The lowest digit will be dropped and replaced by a 0.
  70             </para>
  71             <para>
  72                 If the &cv-link-APPLELINK_NO_COMPATIBILITY_VERSION; is set then no -compatibility_version will be
  73                 output.
  74             </para>
  75             <para>See MacOS's ld manpage for more details</para>
  76         </summary>
  77     </cvar>
  78
  79     <cvar name="APPLELINK_NO_COMPATIBILITY_VERSION">
  80         <summary>
  81             <para>
  82                 Set this to any True (1|True|non-empty string) value to disable adding -compatibility_version flag when
  83                 generating versioned shared libraries.
  84             </para>
  85             <para>
  86                 This overrides &cv-link-APPLELINK_COMPATIBILITY_VERSION;.
  87             </para>
  88         </summary>
  89     </cvar>
  90
  91
  92     <cvar name="_APPLELINK_COMPATIBILITY_VERSION">
  93         <summary>
  94             <para>
  95                 A macro (by default a generator function) used to create the linker flags to specify
  96                 apple's linker's -compatibility_version flag.
  97                 The default generator uses &cv-link-APPLELINK_COMPATIBILITY_VERSION;
  98                 and &cv-link-APPLELINK_NO_COMPATIBILITY_VERSION; and  &cv-link-SHLIBVERSION;
  99                 to determine the correct flag.
 100             </para>
 101         </summary>
 102     </cvar>
 103
 104
 105     <cvar name="APPLELINK_CURRENT_VERSION">
 106         <summary>
 107             <para>
 108                 On Mac OS X this is used to set the linker flag:
 109
 110                 -current_version
 111             </para>
 112             <para>
 113                 The value is specified as X[.Y[.Z]] where X is between 1 and 65535, Y can be omitted or between 1 and
 114                 255, Z can be omitted or between 1 and 255. This value will be set to &cv-link-SHLIBVERSION; if not
 115                 specified.
 116             </para>
 117             <para>
 118                 If the &cv-link-APPLELINK_NO_CURRENT_VERSION; is set then no -current_version will be
 119                 output.
 120             </para>
 121             <para>See MacOS's ld manpage for more details</para>
 122
 123         </summary>
 124     </cvar>
 125
 126
 127     <cvar name="APPLELINK_NO_CURRENT_VERSION">
 128         <summary>
 129             <para>
 130                 Set this to any True (1|True|non-empty string) value to disable adding -current_version flag when
 131                 generating versioned shared libraries.
 132             </para>
 133             <para>
 134                 This overrides &cv-link-APPLELINK_CURRENT_VERSION;.
 135             </para>
 136         </summary>
 137     </cvar>
 138
 139     <cvar name="_APPLELINK_CURRENT_VERSION">
 140         <summary>
 141             <para>
 142                 A macro (by default a generator function) used to create the linker flags to specify apple's linker's
 143                 -current_version flag.  The default generator uses &cv-link-APPLELINK_CURRENT_VERSION; and
 144                 &cv-link-APPLELINK_NO_CURRENT_VERSION; and  &cv-link-SHLIBVERSION; to determine the correct flag.
 145             </para>
 146         </summary>
 147     </cvar>
 148
 149
 150     <cvar name="FRAMEWORKSFLAGS">">
 151         <summary>
 152             <para>
 153                 On Mac OS X with gcc,
 154                 general user-supplied frameworks options to be added at
 155                 the end of a command
 156                 line building a loadable module.
 157                 (This has been largely superseded by
 158                 the &cv-link-FRAMEWORKPATH;, &cv-link-FRAMEWORKPATHPREFIX;,
 159                 &cv-link-FRAMEWORKPREFIX; and &cv-link-FRAMEWORKS; variables
 160                 described above.)
 161             </para>
 162         </summary>
 163     </cvar>
 164
 165     <cvar name="FRAMEWORKS">
 166         <summary>
 167             <para>
 168                 On Mac OS X with gcc, a list of the framework names to be linked into a
 169                 program or shared library or bundle.
 170                 The default value is the empty list.
 171                 For example:
 172             </para>
 173
 174             <example_commands>
 175 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
 176             </example_commands>
 177
 178         </summary>
 179     </cvar>
 180
 181     <cvar name="FRAMEWORKPREFIX">
 182         <summary>
 183             <para>
 184                 On Mac OS X with gcc,
 185                 the prefix to be used for linking in frameworks
 186                 (see &cv-link-FRAMEWORKS;).
 187                 The default value is
 188                 <option>-framework</option>.
 189             </para>
 190         </summary>
 191     </cvar>
 192
 193     <cvar name="_FRAMEWORKS">
 194         <summary>
 195             <para>
 196                 On Mac OS X with gcc,
 197                 an automatically-generated construction variable
 198                 containing the linker command-line options
 199                 for linking with FRAMEWORKS.
 200             </para>
 201         </summary>
 202     </cvar>
 203
 204     <cvar name="FRAMEWORKPATH">
 205         <summary>
 206             <para>
 207                 On Mac OS X with gcc,
 208                 a list containing the paths to search for frameworks.
 209                 Used by the compiler to find framework-style includes like
 210                 #include &lt;Fmwk/Header.h&gt;.
 211                 Used by the linker to find user-specified frameworks when linking (see
 212                 &cv-link-FRAMEWORKS;).
 213                 For example:
 214             </para>
 215
 216             <example_commands>
 217 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
 218             </example_commands>
 219
 220             <para>
 221                 will add
 222             </para>
 223
 224             <example_commands>
 225 ... -Fmyframeworkdir
 226             </example_commands>
 227
 228             <para>
 229                 to the compiler and linker command lines.
 230             </para>
 231         </summary>
 232     </cvar>
 233
 234     <cvar name="FRAMEWORKPATHPREFIX">
 235         <summary>
 236             <para>
 237                 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
 238                 (see &cv-link-FRAMEWORKPATH;).
 239                 The default value is
 240                 <option>-F</option>.
 241             </para>
 242         </summary>
 243     </cvar>
 244
 245     <cvar name="_FRAMEWORKPATH">
 246         <summary>
 247             <para>
 248                 On Mac OS X with gcc, an automatically-generated construction variable
 249                 containing the linker command-line options corresponding to
 250                 &cv-link-FRAMEWORKPATH;.
 251             </para>
 252         </summary>
 253     </cvar>
 254
 255 </sconsdoc>