SCons/Tool/yacc.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="yacc">
  28 <summary>
  29 <para>
  30 Sets construction variables for the &yacc; parser generator.
  31 </para>
  32 </summary>
  33 <sets>
  34 <item>YACC</item>
  35 <item>YACCFLAGS</item>
  36 <item>YACCCOM</item>
  37 <item>YACCHFILESUFFIX</item>
  38 <item>YACCHXXFILESUFFIX</item>
  39 <item>YACCVCGFILESUFFIX</item>
  40 <item>YACC_GRAPH_FILE_SUFFIX</item>
  41 </sets>
  42 <uses>
  43 <item>YACCCOMSTR</item>
  44 <item>YACCFLAGS</item>
  45 <item>YACC_HEADER_FILE</item>
  46 <item>YACC_GRAPH_FILE</item>
  47 </uses>
  48 </tool>
  49
  50 <cvar name="YACC">
  51 <summary>
  52 <para>
  53 The parser generator.
  54 </para>
  55 </summary>
  56 </cvar>
  57
  58 <cvar name="YACCCOM">
  59 <summary>
  60 <para>
  61 The command line used to call the parser generator
  62 to generate a source file.
  63 </para>
  64 </summary>
  65 </cvar>
  66
  67 <cvar name="YACCCOMSTR">
  68 <summary>
  69 <para>
  70 The string displayed when generating a source file
  71 using the parser generator.
  72 If this is not set, then &cv-link-YACCCOM; (the command line) is displayed.
  73 </para>
  74
  75 <example_commands>
  76 env = Environment(YACCCOMSTR="Yacc'ing $TARGET from $SOURCES")
  77 </example_commands>
  78 </summary>
  79 </cvar>
  80
  81 <cvar name="YACCFLAGS">
  82 <summary>
  83 <para>
  84 General options passed to the parser generator.
  85 In addition to passing the value on during invocation,
  86 the &t-link-yacc; tool also examines this &consvar; for options
  87 which cause additional output files to be generated,
  88 and adds those to the target list.
  89 </para>
  90
  91 <para>
  92 If the <option>-d</option> option is present in &cv-YACCFLAGS;
  93 &scons; assumes that the call will also create a header file
  94 with the suffix defined by &cv-link-YACCHFILESUFFIX;
  95 if the yacc source file ends in a <filename>.y</filename> suffix,
  96 or a file with the suffix defined by &cv-link-YACCHXXFILESUFFIX;
  97 if the yacc source file ends in a <filename>.yy</filename> suffix.
  98 The header will have the same base name as the requested target.
  99 This is only correct if the executable is <command>bison</command>
 100 (or <command>win_bison</command>).
 101 If using Berkeley yacc (<command>byacc</command>),
 102 <filename>y.tab.h</filename> is always written -
 103 avoid the <option>-d</option> in this case and
 104 use &cv-link-YACC_HEADER_FILE; instead.
 105 </para>
 106
 107 <para>
 108 If a <option>-g</option> option is present,
 109 &scons; assumes that the call will also create a graph file
 110 with the suffix defined by &cv-link-YACCVCGFILESUFFIX;.
 111 </para>
 112
 113 <para>
 114 If a <option>-v</option> option is present,
 115 &scons; assumes that the call will also create an output debug file
 116 with the suffix <filename>.output</filename>.
 117 </para>
 118
 119 <para>
 120 Also recognized are GNU &bison; options
 121 <option>--header</option>
 122 (and its deprecated synonym <option>--defines</option>),
 123 which is similar to
 124 <option>-d</option>
 125 but gives the option to explicitly name the output header file
 126 through an option argument;
 127 and <option>--graph</option>,
 128 which is similar to
 129 <option>-g</option>
 130 but gives the option to explicitly name the output graph file
 131 through an option argument.
 132 The file suffixes described for
 133 <option>-d</option> and <option>-g</option> above
 134 are not applied if these are used in the option=argument form.
 135 </para>
 136
 137 <para>
 138 Note that files specified by <option>--header=</option> and
 139 <option>--graph=</option> may not be properly handled
 140 by &SCons; in all situations, and using those in &cv-YACCFLAGS;
 141 should be considered legacy support only.
 142 Consider using &cv-link-YACC_HEADER_FILE;
 143 and &cv-link-YACC_GRAPH_FILE; instead
 144 if the files need to be explicitly named
 145 (<emphasis>new in version 4.4.0</emphasis>).
 146 </para>
 147 </summary>
 148 </cvar>
 149
 150 <cvar name="YACC_HEADER_FILE">
 151 <summary>
 152 <para>
 153 If supplied, generate a header file with the name taken from this variable.
 154 Will be emitted as a <option>--header=</option>
 155 command-line option. Use this in preference to including
 156 <option>--header=</option> in &cv-link-YACCFLAGS; directly.
 157 </para>
 158 <para><emphasis>New in version 4.4.0.</emphasis></para>
 159 </summary>
 160 </cvar>
 161
 162 <cvar name="YACC_GRAPH_FILE">
 163 <summary>
 164 <para>
 165 If supplied, write a graph of the automaton to a file with the name
 166 taken from this variable.
 167 Will be emitted as a <option>--graph=</option>
 168 command-line option. Use this in preference to including
 169 <option>--graph=</option> in &cv-link-YACCFLAGS; directly.
 170 </para>
 171 <para><emphasis>New in version 4.4.0.</emphasis></para>
 172 </summary>
 173 </cvar>
 174
 175 <cvar name="YACCHFILESUFFIX">
 176 <summary>
 177 <para>
 178 The suffix of the C
 179 header file generated by the parser generator
 180 when the <option>-d</option> option
 181 (or <option>--header</option> without an option-argument)
 182 is used in &cv-link-YACCFLAGS;.
 183 Note that setting this variable informs &SCons;
 184 how to construct the header filename for tracking purposes,
 185 it does not affect the actual generated filename.
 186 Set this to match what your parser generator produces.
 187 The default value is
 188 <filename>.h</filename>.
 189 </para>
 190 </summary>
 191 </cvar>
 192
 193 <cvar name="YACCHXXFILESUFFIX">
 194 <summary>
 195 <para>
 196 The suffix of the C++
 197 header file generated by the parser generator
 198 when the <option>-d</option> option
 199 (or <option>--header</option> without an option-argument)
 200 is used in &cv-link-YACCFLAGS;.
 201 Note that setting this variable informs &SCons;
 202 how to construct the header filename for tracking purposes,
 203 it does not affect the actual generated filename.
 204 Set this to match what your parser generator produces.
 205 The default value is <filename>.hpp</filename>.
 206 </para>
 207 </summary>
 208 </cvar>
 209
 210 <cvar name="YACCVCGFILESUFFIX">
 211 <summary>
 212 <para>
 213 Obsoleted. Use &cv-link-YACC_GRAPH_FILE_SUFFIX; instead.
 214 The value is used only if &cv-YACC_GRAPH_FILE_SUFFIX; is not set.
 215 The default value is <filename>.gv</filename>.
 216 </para>
 217 <para>
 218 <emphasis>Changed in version 4.6.0</emphasis>: deprecated. The default value
 219 changed from <filename>.vcg</filename> (&bison; stopped generating
 220 <filename>.vcg</filename> output with version 2.4, in 2006).
 221 </para>
 222 </summary>
 223 </cvar>
 224
 225 <cvar name="YACC_GRAPH_FILE_SUFFIX">
 226 <summary>
 227 <para>
 228 Previously specified by &cv-link-YACCVCGFILESUFFIX;.
 229 </para>
 230 <para>
 231 The suffix of the file
 232 containing a graph of the grammar automaton
 233 when the <option>-g</option> option
 234 (or <option>--graph=</option> without an option-argument)
 235 is used in &cv-link-YACCFLAGS;.
 236 Note that setting this variable informs &SCons;
 237 how to construct the graph filename for tracking purposes,
 238 it does not affect the actual generated filename.
 239 Various yacc tools have emitted various formats
 240 at different times.
 241 Set this to match what your parser generator produces.
 242 </para>
 243 <para><emphasis>New in version 4.6.0</emphasis>. </para>
 244 </summary>
 245 </cvar>
 246
 247 </sconsdoc>