SCons/Tool/xgettext.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="xgettext">
  28 <summary>
  29 <para>
  30 This tool is a part of the &t-link-gettext; toolset. It provides
  31 &SCons; an interface to the <command>xgettext(1)</command>
  32 program, which extracts internationalized messages from source code.
  33 The tool sets up the &b-POTUpdate; builder to make  <literal>PO</literal>
  34 <emphasis>Template</emphasis> files.
  35 </para>
  36 </summary>
  37 <sets>
  38 <item>POTSUFFIX</item>
  39 <item>POTUPDATE_ALIAS</item>
  40 <item>XGETTEXTCOM</item>
  41 <item>XGETTEXTCOMSTR</item>
  42 <item>XGETTEXTFLAGS</item>
  43 <item>XGETTEXTFROM</item>
  44 <item>XGETTEXTFROMPREFIX</item>
  45 <item>XGETTEXTFROMSUFFIX</item>
  46 <item>XGETTEXTPATH</item>
  47 <item>XGETTEXTPATHPREFIX</item>
  48 <item>XGETTEXTPATHSUFFIX</item>
  49 <item>_XGETTEXTDOMAIN</item>
  50 <item>_XGETTEXTFROMFLAGS</item>
  51 <item>_XGETTEXTPATHFLAGS</item>
  52 </sets>
  53 <uses>
  54 <item>POTDOMAIN</item>
  55 </uses>
  56 </tool>
  57
  58 <builder name="POTUpdate">
  59 <summary>
  60 <para>
  61 The builder is set up by the &t-link-xgettext; tool,
  62 part of the &t-link-gettext; toolset.
  63 The builder updates the target
  64 <literal>POT</literal> file if exists or creates it if it doesn't.
  65 The target node is <emphasis>not</emphasis>
  66 selected for building by default (e.g. <userinput>scons .</userinput>),
  67 but only on demand (i.e.  when the given
  68 <literal>POT</literal> file is required or when special alias is invoked).
  69 This builder adds its target node (<filename>messages.pot</filename>, say) to a
  70 special alias (<literal>pot-update</literal> by default, see
  71 &cv-link-POTUPDATE_ALIAS;) so you can update/create them easily with
  72 <userinput>scons pot-update</userinput>. The file is not written until there is no
  73 real change in internationalized messages (or in comments that enter
  74 <literal>POT</literal> file).
  75 </para>
  76
  77 <para>
  78 <note> <para>You may see <command>xgettext(1)</command> being invoked by the
  79 &t-link-xgettext; tool even if there is no real change in internationalized
  80 messages (so the <literal>POT</literal> file is not being updated).  This
  81 happens every time  a source file has changed. In such case we invoke
  82 <command>xgettext(1)</command> and compare its output with the content of
  83 <literal>POT</literal> file to decide whether the file should be updated or
  84 not.</para></note>
  85 </para>
  86
  87 <para>
  88 <emphasis>Example 1.</emphasis>
  89 Let's create <filename>po/</filename> directory and place following
  90 <filename>SConstruct</filename> script there:
  91 </para>
  92 <programlisting language="python">
  93 # SConstruct in 'po/' subdir
  94 env = Environment(tools=['default', 'xgettext'])
  95 env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
  96 env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
  97 </programlisting>
  98 <para>
  99 Then invoke scons few times:
 100 </para>
 101 <screen>
 102 $ scons             # Does not create foo.pot nor bar.pot
 103 $ scons foo.pot     # Updates or creates foo.pot
 104 $ scons pot-update  # Updates or creates foo.pot and bar.pot
 105 $ scons -c          # Does not clean foo.pot nor bar.pot.
 106 </screen>
 107 <para>
 108 the results shall be as the comments above say.
 109 </para>
 110
 111 <para>
 112 <emphasis>Example 2.</emphasis>
 113 The <parameter>target</parameter> argument can be omitted, in which
 114 case the default target name <filename>messages.pot</filename> is used.
 115 The target may also be overridden by setting the &cv-link-POTDOMAIN;
 116 &consvar; or providing it as an override to the &b-POTUpdate; builder:
 117 </para>
 118 <programlisting language="python">
 119 # SConstruct script
 120 env = Environment(tools=['default', 'xgettext'])
 121 env['POTDOMAIN'] = "foo"
 122 env.POTUpdate(source=["a.cpp", "b.cpp"])  # Creates foo.pot ...
 123 env.POTUpdate(POTDOMAIN="bar", source=["c.cpp", "d.cpp"])  # and bar.pot
 124 </programlisting>
 125
 126 <para>
 127 <emphasis>Example 3.</emphasis>
 128 The <parameter>source</parameter> parameter may also be omitted,
 129 if it is specified in a separate file, for example
 130 <filename>POTFILES.in</filename>:
 131 </para>
 132 <programlisting>
 133 # POTFILES.in in 'po/' subdirectory
 134 ../a.cpp
 135 ../b.cpp
 136 # end of file
 137 </programlisting>
 138 <para>
 139 The name of the file (<filename>POTFILES.in</filename>) containing the list of
 140 sources is provided via &cv-link-XGETTEXTFROM;:
 141 </para>
 142 <programlisting language="python">
 143 # SConstruct file in 'po/' subdirectory
 144 env = Environment(tools=['default', 'xgettext'])
 145 env.POTUpdate(XGETTEXTFROM='POTFILES.in')
 146 </programlisting>
 147
 148 <para>
 149 <emphasis>Example 4.</emphasis>
 150 You can use &cv-link-XGETTEXTPATH; to define the source search path.
 151 Assume, for example, that you have files <filename>a.cpp</filename>,
 152 <filename>b.cpp</filename>, <filename>po/SConstruct</filename>,
 153 <filename>po/POTFILES.in</filename>.
 154 Then your <literal>POT</literal>-related files could look like this:
 155 </para>
 156 <programlisting>
 157 # POTFILES.in in 'po/' subdirectory
 158 a.cpp
 159 b.cpp
 160 # end of file
 161 </programlisting>
 162
 163 <programlisting language="python">
 164 # SConstruct file in 'po/' subdirectory
 165 env = Environment(tools=['default', 'xgettext'])
 166 env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH='../')
 167 </programlisting>
 168
 169 <para>
 170 <emphasis>Example 5.</emphasis>
 171 Multiple search directories may be defined as a list, i.e.
 172 <literal>XGETTEXTPATH=['dir1', 'dir2', ...]</literal>. The order in the list
 173 determines the search order of source files. The path to the first file found
 174 is used.
 175 </para>
 176
 177 <para>
 178 Let's create <filename>0/1/po/SConstruct</filename> script:
 179 </para>
 180 <programlisting language="python">
 181 # SConstruct file in '0/1/po/' subdirectory
 182 env = Environment(tools=['default', 'xgettext'])
 183 env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../', '../../'])
 184 </programlisting>
 185 <para>
 186 and <filename>0/1/po/POTFILES.in</filename>:
 187 </para>
 188 <programlisting>
 189 # POTFILES.in in '0/1/po/' subdirectory
 190 a.cpp
 191 # end of file
 192 </programlisting>
 193 <para>
 194 Write two <filename>*.cpp</filename> files, the first one is
 195 <filename>0/a.cpp</filename>:
 196 </para>
 197 <programlisting language="c++">
 198 /* 0/a.cpp */
 199 gettext("Hello from ../../a.cpp")
 200 </programlisting>
 201 <para>
 202 and the second is <filename>0/1/a.cpp</filename>:
 203 </para>
 204 <programlisting language="c++">
 205 /* 0/1/a.cpp */
 206 gettext("Hello from ../a.cpp")
 207 </programlisting>
 208 <para>
 209 then run scons. You'll obtain <literal>0/1/po/messages.pot</literal> with the
 210 message <literal>"Hello from ../a.cpp"</literal>. When you reverse order in
 211 <varname>$XGETTEXTFOM</varname>, i.e. when you write SConscript as
 212 </para>
 213 <programlisting language="python">
 214 # SConstruct file in '0/1/po/' subdirectory
 215 env = Environment(tools=['default', 'xgettext'])
 216 env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../../', '../'])
 217 </programlisting>
 218 <para>
 219 then the <filename>messages.pot</filename> will contain
 220 <literal>msgid "Hello from ../../a.cpp"</literal> line and not
 221 <literal>msgid "Hello from ../a.cpp"</literal>.
 222 </para>
 223
 224 </summary>
 225 </builder>
 226
 227 <cvar name="POTSUFFIX">
 228 <summary>
 229 <para>
 230 Suffix used for PO Template files (default: <literal>'.pot'</literal>).
 231 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 232 </para>
 233 </summary>
 234 </cvar>
 235
 236 <cvar name="POTUPDATE_ALIAS">
 237 <summary>
 238 <para>
 239 Name of the common phony target for all PO Templates created with
 240 &b-link-POUpdate; (default: <literal>'pot-update'</literal>).
 241 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 242 </para>
 243 </summary>
 244 </cvar>
 245
 246 <cvar name="XGETTEXT">
 247 <summary>
 248 <para>
 249 Path to <command>xgettext(1)</command> program (found via
 250 <function>Detect()</function>).
 251 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 252 </para>
 253 </summary>
 254 </cvar>
 255
 256 <cvar name="XGETTEXTCOM">
 257 <summary>
 258 <para>
 259 Complete xgettext command line.
 260 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 261 </para>
 262 </summary>
 263 </cvar>
 264
 265 <cvar name="XGETTEXTCOMSTR">
 266 <summary>
 267 <para>
 268 A string that is shown when <command>xgettext(1)</command> command is invoked
 269 (default: <literal>''</literal>, which means "print &cv-link-XGETTEXTCOM;").
 270 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 271 </para>
 272 </summary>
 273 </cvar>
 274
 275 <cvar name="XGETTEXTFLAGS">
 276 <summary>
 277 <para>
 278 Additional flags to <command>xgettext(1)</command>.
 279 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 280 </para>
 281 </summary>
 282 </cvar>
 283
 284 <cvar name="XGETTEXTFROM">
 285 <summary>
 286 <para>
 287 Name of file containing list of <command>xgettext(1)</command>'s source
 288 files. Autotools' users know this as <filename>POTFILES.in</filename> so they
 289 will in most cases set <literal>XGETTEXTFROM="POTFILES.in"</literal> here.
 290 The &cv-XGETTEXTFROM; files have same syntax and semantics as the well known
 291 GNU <filename>POTFILES.in</filename>.
 292 See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 293 </para>
 294 </summary>
 295 </cvar>
 296
 297 <cvar name="XGETTEXTPATH">
 298 <summary>
 299 <para>
 300 List of directories, there <command>xgettext(1)</command> will look for
 301 source files (default: <literal>[]</literal>).
 302 <note><para>
 303 This variable works only together with &cv-link-XGETTEXTFROM;
 304 </para></note>
 305 See also &t-link-xgettext; tool and &b-link-POTUpdate; builder.
 306 </para>
 307 </summary>
 308 </cvar>
 309
 310 <cvar name="XGETTEXTPATHPREFIX">
 311 <summary>
 312 <para>
 313 This flag is used to add single search path to
 314 <command>xgettext(1)</command>'s commandline (default:
 315 <literal>'-D'</literal>).
 316 </para>
 317 </summary>
 318 </cvar>
 319
 320 <cvar name="XGETTEXTPATHSUFFIX">
 321 <summary>
 322 <para>
 323 (default: <literal>''</literal>)
 324 </para>
 325 </summary>
 326 </cvar>
 327
 328 <cvar name="XGETTEXTFROMPREFIX">
 329 <summary>
 330 <para>
 331 This flag is used to add single &cv-link-XGETTEXTFROM; file to
 332 <command>xgettext(1)</command>'s commandline (default:
 333 <literal>'-f'</literal>).
 334 </para>
 335 </summary>
 336 </cvar>
 337
 338 <cvar name="XGETTEXTFROMSUFFIX">
 339 <summary>
 340 <para>
 341 (default: <literal>''</literal>)
 342 </para>
 343 </summary>
 344 </cvar>
 345
 346 <cvar name="_XGETTEXTDOMAIN">
 347 <summary>
 348 <para>
 349 Internal "macro". Generates <command>xgettext</command> domain name
 350 form source and target (default: <literal>'${TARGET.filebase}'</literal>).
 351 </para>
 352 </summary>
 353 </cvar>
 354
 355 <cvar name="_XGETTEXTFROMFLAGS">
 356 <summary>
 357 <para>
 358 Internal "macro". Genrates list of <literal>-D&lt;dir&gt;</literal> flags
 359 from the &cv-link-XGETTEXTPATH; list.
 360 </para>
 361 </summary>
 362 </cvar>
 363
 364 <cvar name="_XGETTEXTPATHFLAGS">
 365 <summary>
 366 <para>
 367 Internal "macro". Generates list of <literal>-f&lt;file&gt;</literal> flags
 368 from &cv-link-XGETTEXTFROM;.
 369 </para>
 370 </summary>
 371 </cvar>
 372
 373 </sconsdoc>