source: trunk/doc-new/guide/xml/portfile-tcl.xml @ 144444

Last change on this file since 144444 was 144444, checked in by dstrubbe@…, 4 years ago

doc-new: Fix and further clarifications on -locale for reinplace.

File size: 12.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<section id="reference.tcl-extensions">
5  <title>Tcl Extensions</title>
6
7  <para>A MacPorts Portfile is a Tcl script, so it may contain any arbitrary
8  Tcl code you may learn about in a <ulink
9  url="http://tmml.sourceforge.net/doc/tcl/">Tcl reference manual</ulink>.
10  However, few authors will use arbitrary Tcl code; the vast majority will use
11  Tcl extensions that are coded within MacPorts for performing the most common
12  tasks needed for Portfiles. The list below is a list of Tcl extensions
13  provided by MacPorts base.</para>
14
15  <variablelist>
16    <varlistentry>
17      <term>file</term>
18
19      <listitem>
20        <para>Description.</para>
21
22        <variablelist>
23          <varlistentry>
24            <term>file copy</term>
25
26            <listitem>
27              <para></para>
28            </listitem>
29          </varlistentry>
30        </variablelist>
31
32        <variablelist>
33          <varlistentry>
34            <term>file rename</term>
35
36            <listitem>
37              <para></para>
38            </listitem>
39          </varlistentry>
40        </variablelist>
41
42        <variablelist>
43          <varlistentry>
44            <term>file delete [-force]</term>
45
46            <listitem>
47              <para></para>
48            </listitem>
49          </varlistentry>
50        </variablelist>
51
52        <variablelist>
53          <varlistentry>
54            <term>file mkdir</term>
55
56            <listitem>
57              <para></para>
58            </listitem>
59          </varlistentry>
60        </variablelist>
61      </listitem>
62    </varlistentry>
63
64    <varlistentry>
65      <term>macros</term>
66
67      <listitem>
68        <para>Description.</para>
69
70        <variablelist>
71          <varlistentry>
72            <term>copy</term>
73
74            <listitem>
75              <para>Shorthand alternative to <code>file copy</code>.</para>
76            </listitem>
77          </varlistentry>
78        </variablelist>
79
80        <variablelist>
81          <varlistentry>
82            <term>move</term>
83
84            <listitem>
85              <para>Shorthand alternative to <code>file rename</code>.</para>
86            </listitem>
87          </varlistentry>
88
89          <varlistentry>
90            <term>delete file ...</term>
91
92            <listitem>
93              <para>Deletes each of the given files/directories. Behaves
94              similarly to file delete -force except that file delete -force
95              will fail to delete directories properly on 10.3 systems.</para>
96            </listitem>
97          </varlistentry>
98
99          <varlistentry>
100            <term>touch</term>
101
102            <listitem>
103              <para>Mimics the BSD touch command.</para>
104            </listitem>
105          </varlistentry>
106
107          <varlistentry>
108            <term>ln</term>
109
110            <listitem>
111              <para>Mimics the BSD ln command.</para>
112            </listitem>
113          </varlistentry>
114        </variablelist>
115      </listitem>
116    </varlistentry>
117
118    <varlistentry>
119      <term>xinstall</term>
120
121      <listitem>
122        <para>xinstall copies files and creates directories; it is intended to
123        be compatible with install(1).</para>
124
125        <variablelist>
126          <varlistentry>
127            <term>xinstall [-o <replaceable>owner</replaceable>] [-g
128            <replaceable>group</replaceable>] [-m
129            <replaceable>mode</replaceable>] [<replaceable>file1 file2
130            ...</replaceable>] <replaceable>directory</replaceable></term>
131
132            <listitem>
133              <para>Install the specified file(s) to a destination
134              directory.</para>
135            </listitem>
136          </varlistentry>
137        </variablelist>
138
139        <variablelist>
140          <varlistentry>
141            <term>xinstall [-o <replaceable>owner</replaceable>] [-g
142            <replaceable>group</replaceable>] [-m
143            <replaceable>mode</replaceable>] [-W
144            <replaceable>dir</replaceable>] [<replaceable>file1 file2
145            ...</replaceable>] <replaceable>directory</replaceable></term>
146
147            <listitem>
148              <para>Change to <option>dir</option> and install file(s) to a
149              destination directory.</para>
150            </listitem>
151          </varlistentry>
152        </variablelist>
153
154        <variablelist>
155          <varlistentry>
156            <term>xinstall [-o <replaceable>owner</replaceable>] [-g
157            <replaceable>group</replaceable>] [-m
158            <replaceable>mode</replaceable>] {*}[glob
159            <replaceable>pattern</replaceable>]
160            <replaceable>directory</replaceable></term>
161
162            <listitem>
163              <para>Install the file(s) matching the glob pattern to a
164              destination directory. Note the use of the <option>{*}</option>
165              operator to convert the list returned by <command>glob</command>
166              into separate arguments to <command>xinstall</command>.</para>
167            </listitem>
168          </varlistentry>
169        </variablelist>
170
171        <variablelist>
172          <varlistentry>
173            <term>xinstall -d [-o <replaceable>owner</replaceable>] [-g
174            <replaceable>group</replaceable>] [-m
175            <replaceable>mode</replaceable>]
176            <replaceable>directory</replaceable></term>
177
178            <listitem>
179              <para>Create a directory including parent directories if
180              necessary.</para>
181            </listitem>
182          </varlistentry>
183        </variablelist>
184
185        <para>Defaults:</para>
186
187        <itemizedlist>
188          <listitem>
189            <para>owner -</para>
190          </listitem>
191
192          <listitem>
193            <para>group -</para>
194          </listitem>
195
196          <listitem>
197            <para>mode - <option>0755</option></para>
198          </listitem>
199        </itemizedlist>
200
201        <para>Examples:</para>
202
203        <programlisting>xinstall -m 640 ${worksrcpath}/README \
204   ${destroot}${prefix}/share/doc/${name}</programlisting>
205
206        <programlisting>xinstall -m 640 -W ${worksrcpath}/doc README INSTALL COPY \
207   ${destroot}${prefix}/share/doc/${name}</programlisting>
208
209        <programlisting>xinstall -m 640 {*}[glob ${worksrcpath}/doc/*] \
210   ${destroot}${prefix}/share/doc/${name}</programlisting>
211
212        <programlisting>xinstall -d ${destroot}${prefix}/share/doc/${name}</programlisting>
213      </listitem>
214    </varlistentry>
215
216    <varlistentry id="reference.tcl-extensions.strsed">
217        <term>strsed</term>
218
219        <listitem>
220            <para>strsed can be used for string manipulations using regular
221            expressions. It supports a small subset of the commands known
222            from sed(1).</para>
223
224            <variablelist>
225                <varlistentry>
226                    <term>strsed <replaceable>string</replaceable>
227                    s/<replaceable>regex</replaceable>/<replaceable>replacement</replaceable>/
228                    </term>
229
230                    <listitem>
231                        <para>Replaces the first instance of
232                        <replaceable>regex</replaceable> with
233                        <replaceable>replacement</replaceable>. Refer to
234                        re_format(7) for a definition of regular expression
235                        syntax.</para>
236                    </listitem>
237                </varlistentry>
238
239                <varlistentry>
240                    <term>strsed <replaceable>string</replaceable>
241                    g/<replaceable>regex</replaceable>/<replaceable>replacement</replaceable>/
242                    </term>
243
244                    <listitem>
245                        <para>The same as the previous format, except all
246                        instances of the pattern will be replaced, not only
247                        the first (mnemonic: 'g' is for global).</para>
248                    </listitem>
249                </varlistentry>
250            </variablelist>
251        </listitem>
252    </varlistentry>
253
254    <varlistentry>
255      <term>reinplace</term>
256
257      <listitem>
258        <para>Allows text specified by a regular expression to be replaced by
259        new text, in-place (the file will be updated itself, no need to place
260        output into a new file and rename).</para>
261
262        <variablelist>
263          <varlistentry>
264            <term>
265              reinplace
266              [-locale <replaceable>locale</replaceable>]
267              [-n]
268              [-W <replaceable>dir</replaceable>]
269              [--] <replaceable>command</replaceable>
270              <replaceable>file ...</replaceable>
271            </term>
272
273            <listitem>
274              <para>Replace text given by the regular expression portion of
275              the command with the replacement text, in all files
276              specified.</para>
277
278              <para>Use -locale to set the locale. The default locale is <code>en_US.UTF-8</code>.
279              For example, <code>-locale C</code> will allow a non-UTF-8 file to be modified (which
280              may otherwise give the error "sed: RE error: illegal byte sequence"), but only operating
281              on ASCII characters. If you need it to work on non-ASCII characters you need to set a
282              locale with the correct charset for the file, e.g. "en_US.ISO8859-1".</para>
283
284              <para>-n is passed to sed to suppress echoing result</para>
285
286              <para>-W to set a common working directory for multiple
287              files</para>
288
289              <para>Use -E to use the extended regular expression style (see
290              re_format(7) for a description of the basic and extended
291              styles)</para>
292
293              <para>Use -- to end option processing and allow any further
294              dashes not to be treated as options.</para>
295            </listitem>
296          </varlistentry>
297        </variablelist>
298
299        <para>Examples:</para>
300
301        <programlisting>reinplace -W ${worksrcpath} "s|/usr/local|${prefix}|g" configure setup.py</programlisting>
302
303        <programlisting>reinplace "s|@@PREFIX@@|${prefix}|g" ${worksrcpath}/Makefile</programlisting>
304      </listitem>
305    </varlistentry>
306
307    <varlistentry>
308      <term>user/group</term>
309
310      <listitem>
311        <para></para>
312
313        <variablelist>
314          <varlistentry>
315            <term>adduser username [uid=<replaceable>uid</replaceable>]
316            [gid=<replaceable>gid</replaceable>]
317            [passwd=<replaceable>passwd</replaceable>]
318            [realname=<replaceable>realname</replaceable>]
319            [home=<replaceable>home</replaceable>]
320            [shell=<replaceable>shell</replaceable>]</term>
321
322            <listitem>
323              <para>Add a new local user to the system with the specified uid,
324              gid, password, real name, home directory and login shell.</para>
325            </listitem>
326          </varlistentry>
327        </variablelist>
328
329        <variablelist>
330          <varlistentry>
331            <term>existsuser <replaceable>username</replaceable></term>
332
333            <listitem>
334              <para>Check if a local user exists. Returns the uid for the
335              given user, or 0 if the user wasn't found. Checking for the root
336              user is not supported because its uid is 0, and it will always
337              exist anyway.</para>
338            </listitem>
339          </varlistentry>
340        </variablelist>
341
342        <variablelist>
343          <varlistentry>
344            <term>nextuid</term>
345
346            <listitem>
347              <para>Returns the highest used uid plus one.</para>
348            </listitem>
349          </varlistentry>
350        </variablelist>
351
352        <variablelist>
353          <varlistentry>
354            <term>addgroup <replaceable>group</replaceable>
355            [gid=<replaceable>gid</replaceable>]
356            [passwd=<replaceable>passwd</replaceable>]
357            [realname=<replaceable>realname</replaceable>]
358            [users=<replaceable>users</replaceable>]</term>
359
360            <listitem>
361              <para>Add a new local group to the system, with the specified
362              gid, password, real name, and with a list users as
363              members.</para>
364            </listitem>
365          </varlistentry>
366        </variablelist>
367
368        <variablelist>
369          <varlistentry>
370            <term>existsgroup <replaceable>group</replaceable></term>
371
372            <listitem>
373              <para>Check if a local group exists and return the corresponding
374              gid. This can be used with adduser:</para>
375
376              <programlisting>addgroup foo
377adduser foo gid=[existsgroup foo]</programlisting>
378            </listitem>
379          </varlistentry>
380        </variablelist>
381
382        <variablelist>
383          <varlistentry>
384            <term>nextgid</term>
385
386            <listitem>
387              <para>Returns the highest used gid plus one.</para>
388            </listitem>
389          </varlistentry>
390        </variablelist>
391      </listitem>
392    </varlistentry>
393
394    <varlistentry>
395      <term>External program execution</term>
396
397      <listitem>
398        <para>Use only when ....</para>
399      </listitem>
400    </varlistentry>
401  </variablelist>
402</section>
Note: See TracBrowser for help on using the repository browser.