summaryrefslogtreecommitdiff
path: root/src/engine/SCons/Tool/xgettext.xml
blob: 0b68c14dbd4041d19a28650e28f140f47dd85750 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2001 - 2017 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">

<tool name="xgettext">
<summary>
<para>
This scons tool is a part of scons &t-link-gettext; toolset. It provides
scons interface to <command>xgettext(1)</command>
program, which extracts internationalized messages from source code. The tool
provides &b-POTUpdate; builder to make  <literal>PO</literal>
<emphasis>Template</emphasis> files. 
</para>
</summary>
<sets>
<item>POTSUFFIX</item>
<item>POTUPDATE_ALIAS</item>
<item>XGETTEXTCOM</item>
<item>XGETTEXTCOMSTR</item>
<item>XGETTEXTFLAGS</item>
<item>XGETTEXTFROM</item>
<item>XGETTEXTFROMPREFIX</item>
<item>XGETTEXTFROMSUFFIX</item>
<item>XGETTEXTPATH</item>
<item>XGETTEXTPATHPREFIX</item>
<item>XGETTEXTPATHSUFFIX</item>
<item>_XGETTEXTDOMAIN</item>
<item>_XGETTEXTFROMFLAGS</item>
<item>_XGETTEXTPATHFLAGS</item>
</sets>
<uses>
<item>POTDOMAIN</item>
</uses>
</tool>

<builder name="POTUpdate">
<summary>
<para>
The builder belongs to &t-link-xgettext; tool. The builder updates target
<literal>POT</literal> file if exists or creates one if it doesn't. The node is
not built by default (i.e. it is <literal>Ignore</literal>d from
<literal>'.'</literal>), but only on demand (i.e.  when given
<literal>POT</literal> file is required or when special alias is invoked). This
builder adds its targe node (<filename>messages.pot</filename>, say) to a
special alias (<literal>pot-update</literal> by default, see
&cv-link-POTUPDATE_ALIAS;) so you can update/create them easily with
<command>scons pot-update</command>. The file is not written until there is no
real change in internationalized messages (or in comments that enter
<literal>POT</literal> file). 
</para>

<para>
<note> <para>You may see <command>xgettext(1)</command> being invoked by the
&t-link-xgettext; tool even if there is no real change in internationalized
messages (so the <literal>POT</literal> file is not being updated).  This
happens every time  a source file has changed. In such case we invoke
<command>xgettext(1)</command> and compare its output with the content of
<literal>POT</literal> file to decide whether the file should be updated or
not.</para></note>
</para>

<para>
<emphasis>Example 1.</emphasis>
Let's create <filename>po/</filename> directory and place following
<filename>SConstruct</filename> script there:
</para>
<example_commands>
  # SConstruct in 'po/' subdir
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
  env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
</example_commands>      
<para>
Then invoke scons few times:
</para>
<example_commands>
  user@host:$ scons             # Does not create foo.pot nor bar.pot
  user@host:$ scons foo.pot     # Updates or creates foo.pot
  user@host:$ scons pot-update  # Updates or creates foo.pot and bar.pot
  user@host:$ scons -c          # Does not clean foo.pot nor bar.pot.
</example_commands>
<para>
the results shall be as the comments above say.
</para>

<para>
<emphasis>Example 2.</emphasis>
The &b-POTUpdate; builder may be used with no target specified, in which
case default target <filename>messages.pot</filename> will be used. The
default target may also be overridden by setting &cv-link-POTDOMAIN; construction
variable or providing it as an override to &b-POTUpdate; builder:
</para>
<example_commands>    
  # SConstruct script
  env = Environment( tools = ['default', 'xgettext'] )
  env['POTDOMAIN'] = "foo"
  env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
  env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
</example_commands>

<para>
<emphasis>Example 3.</emphasis>
The sources may be specified within separate file, for example
<filename>POTFILES.in</filename>:
</para>
<example_commands>      
  # POTFILES.in in 'po/' subdirectory
  ../a.cpp
  ../b.cpp
  # end of file
</example_commands>    
<para>
The name of the file (<filename>POTFILES.in</filename>) containing the list of
sources is provided via &cv-link-XGETTEXTFROM;:
</para>
<example_commands>      
  # SConstruct file in 'po/' subdirectory
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
</example_commands>    

<para>
<emphasis>Example 4.</emphasis>
You may use &cv-link-XGETTEXTPATH; to define source search path. Assume, for
example, that you have files <filename>a.cpp</filename>,
<filename>b.cpp</filename>, <filename>po/SConstruct</filename>,
<filename>po/POTFILES.in</filename>. Then your <literal>POT</literal>-related
files could look as below:
</para>
<example_commands>
  # POTFILES.in in 'po/' subdirectory
  a.cpp
  b.cpp
  # end of file
</example_commands>

<example_commands>
  # SConstruct file in 'po/' subdirectory
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
</example_commands>

<para>
<emphasis>Example 5.</emphasis>
Multiple search directories may be defined within a list, i.e.
<literal>XGETTEXTPATH = ['dir1', 'dir2', ...]</literal>. The order in the list
determines the search order of source files. The path to the first file found
is used.
</para>

<para>
Let's create <filename>0/1/po/SConstruct</filename> script:
</para>
<example_commands>
  # SConstruct file in '0/1/po/' subdirectory
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
</example_commands>
<para>
and <filename>0/1/po/POTFILES.in</filename>:
</para>
<example_commands>
  # POTFILES.in in '0/1/po/' subdirectory
  a.cpp
  # end of file
</example_commands>
<para>
Write two <filename>*.cpp</filename> files, the first one is
<filename>0/a.cpp</filename>:
</para>
<example_commands>
  /* 0/a.cpp */
  gettext("Hello from ../../a.cpp")
</example_commands>
<para>
and the second is <filename>0/1/a.cpp</filename>:
</para>
<example_commands>
  /* 0/1/a.cpp */
  gettext("Hello from ../a.cpp")
</example_commands>
<para>
then run scons. You'll obtain <literal>0/1/po/messages.pot</literal> with the
message <literal>"Hello from ../a.cpp"</literal>. When you reverse order in
<varname>$XGETTEXTFOM</varname>, i.e. when you write SConscript as
</para>
<example_commands>
  # SConstruct file in '0/1/po/' subdirectory
  env = Environment( tools = ['default', 'xgettext'] )
  env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
</example_commands> 
<para>
then the <filename>messages.pot</filename> will contain
<literal>msgid "Hello from ../../a.cpp"</literal> line and not 
<literal>msgid "Hello from ../a.cpp"</literal>.
</para>

</summary>
</builder>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="POTSUFFIX">
<summary>
<para>
Suffix used for PO Template files (default: <literal>'.pot'</literal>).
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="POTUPDATE_ALIAS">
<summary>
<para>
Name of the common phony target for all PO Templates created with
&b-link-POUpdate; (default: <literal>'pot-update'</literal>).
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXT">
<summary>
<para>
Path to <command>xgettext(1)</command> program (found via
<function>Detect()</function>).
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTCOM">
<summary>
<para>
Complete xgettext command line.
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTCOMSTR">
<summary>
<para>
A string that is shown when <command>xgettext(1)</command> command is invoked
(default: <literal>''</literal>, which means "print &cv-link-XGETTEXTCOM;").
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTFLAGS">
<summary>
<para>
Additional flags to <command>xgettext(1)</command>.
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTFROM">
<summary>
<para>
Name of file containing list of <command>xgettext(1)</command>'s source
files. Autotools' users know this as <filename>POTFILES.in</filename> so they
will in most cases set <literal>XGETTEXTFROM="POTFILES.in"</literal> here.
The &cv-XGETTEXTFROM; files have same syntax and semantics as the well known
GNU <filename>POTFILES.in</filename>.
See &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTPATH">
<summary>
<para>
List of directories, there <command>xgettext(1)</command> will look for
source files (default: <literal>[]</literal>).
<note><para>
This variable works only together with &cv-link-XGETTEXTFROM;
</para></note>
See also &t-link-xgettext; tool and &b-link-POTUpdate; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTPATHPREFIX">
<summary>
<para>
This flag is used to add single search path to
<command>xgettext(1)</command>'s commandline (default:
<literal>'-D'</literal>).
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTPATHSUFFIX">
<summary>
<para>
(default: <literal>''</literal>)
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTFROMPREFIX">
<summary>
<para>
This flag is used to add single &cv-link-XGETTEXTFROM; file to
<command>xgettext(1)</command>'s commandline (default:
<literal>'-f'</literal>).
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="XGETTEXTFROMSUFFIX">
<summary>
<para>
(default: <literal>''</literal>)
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="_XGETTEXTDOMAIN">
<summary>
<para>
Internal "macro". Generates <command>xgettext</command> domain name
form source and target (default: <literal>'${TARGET.filebase}'</literal>).
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="_XGETTEXTFROMFLAGS">
<summary>
<para>
Internal "macro". Genrates list of <literal>-D&lt;dir&gt;</literal> flags
from the &cv-link-XGETTEXTPATH; list.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="_XGETTEXTPATHFLAGS">
<summary>
<para>
Internal "macro". Generates list of <literal>-f&lt;file&gt;</literal> flags
from &cv-link-XGETTEXTFROM;.
</para>
</summary>
</cvar>

<!--

-->

</sconsdoc>