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

Last change on this file since 134828 was 134828, checked in by jmr@…, 5 years ago

guide: use {*} instead of eval in xinstall examples

File size: 12.2 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.</para>
165            </listitem>
166          </varlistentry>
167        </variablelist>
168
169        <variablelist>
170          <varlistentry>
171            <term>xinstall -d [-o <replaceable>owner</replaceable>] [-g
172            <replaceable>group</replaceable>] [-m
173            <replaceable>mode</replaceable>]
174            <replaceable>directory</replaceable></term>
175
176            <listitem>
177              <para>Create a directory including parent directories if
178              necessary.</para>
179            </listitem>
180          </varlistentry>
181        </variablelist>
182
183        <para>Defaults:</para>
184
185        <itemizedlist>
186          <listitem>
187            <para>owner -</para>
188          </listitem>
189
190          <listitem>
191            <para>group -</para>
192          </listitem>
193
194          <listitem>
195            <para>mode -</para>
196          </listitem>
197        </itemizedlist>
198
199        <para>Examples:</para>
200
201        <programlisting>xinstall -m 640 ${worksrcpath}/README \
202   ${destroot}${prefix}/share/doc/${name}</programlisting>
203
204        <programlisting>xinstall -m 640 -W ${worksrcpath}/doc README INSTALL COPY \
205   ${destroot}${prefix}/share/doc/${name}</programlisting>
206
207        <programlisting>xinstall -m 640 {*}[glob ${worksrcpath}/doc/*] \
208   ${destroot}${prefix}/share/doc/${name}</programlisting>
209
210        <programlisting>xinstall -d ${destroot}${prefix}/share/doc/${name}</programlisting>
211      </listitem>
212    </varlistentry>
213
214    <varlistentry id="reference.tcl-extensions.strsed">
215        <term>strsed</term>
216
217        <listitem>
218            <para>strsed can be used for string manipulations using regular
219            expressions. It supports a small subset of the commands known
220            from sed(1).</para>
221
222            <variablelist>
223                <varlistentry>
224                    <term>strsed <replaceable>string</replaceable>
225                    s/<replaceable>regex</replaceable>/<replaceable>replacement</replaceable>/
226                    </term>
227
228                    <listitem>
229                        <para>Replaces the first instance of
230                        <replaceable>regex</replaceable> with
231                        <replaceable>replacement</replaceable>. Refer to
232                        re_format(7) for a definition of regular expression
233                        syntax.</para>
234                    </listitem>
235                </varlistentry>
236
237                <varlistentry>
238                    <term>strsed <replaceable>string</replaceable>
239                    g/<replaceable>regex</replaceable>/<replaceable>replacement</replaceable>/
240                    </term>
241
242                    <listitem>
243                        <para>The same as the previous format, except all
244                        instances of the pattern will be replaced, not only
245                        the first (mnemonic: 'g' is for global).</para>
246                    </listitem>
247                </varlistentry>
248            </variablelist>
249        </listitem>
250    </varlistentry>
251
252    <varlistentry>
253      <term>reinplace</term>
254
255      <listitem>
256        <para>Allows text specified by a regular expression to be replaced by
257        new text, in-place (the file will be updated itself, no need to place
258        output into a new file and rename).</para>
259
260        <variablelist>
261          <varlistentry>
262            <term>
263              reinplace
264              [-locale <replaceable>locale</replaceable>]
265              [-n]
266              [-W <replaceable>dir</replaceable>]
267              [--] <replaceable>command</replaceable>
268              <replaceable>file ...</replaceable>
269            </term>
270
271            <listitem>
272              <para>Replace text given by the regular expression portion of
273              the command with the replacement text, in all files
274              specified.</para>
275
276              <para>Use -locale to set the locale</para>
277
278              <para>-n is passed to sed to suppress echoing result</para>
279
280              <para>-W to set a common working directory for multiple
281              files</para>
282
283              <para>Use -E to use the extended regular expression style (see
284              re_format(7) for a description of the basic and extended
285              styles)</para>
286
287              <para>Use -- to end option processing and allow any further
288              dashes not to be treated as options.</para>
289            </listitem>
290          </varlistentry>
291        </variablelist>
292
293        <para>Examples:</para>
294
295        <programlisting>reinplace -W ${worksrcpath} "s|/usr/local|${prefix}|g" configure setup.py</programlisting>
296
297        <programlisting>reinplace "s|@@PREFIX@@|${prefix}|g" ${worksrcpath}/Makefile</programlisting>
298      </listitem>
299    </varlistentry>
300
301    <varlistentry>
302      <term>user/group</term>
303
304      <listitem>
305        <para></para>
306
307        <variablelist>
308          <varlistentry>
309            <term>adduser username [uid=<replaceable>uid</replaceable>]
310            [gid=<replaceable>gid</replaceable>]
311            [passwd=<replaceable>passwd</replaceable>]
312            [realname=<replaceable>realname</replaceable>]
313            [home=<replaceable>home</replaceable>]
314            [shell=<replaceable>shell</replaceable>]</term>
315
316            <listitem>
317              <para>Add a new local user to the system with the specified uid,
318              gid, password, real name, home directory and login shell.</para>
319            </listitem>
320          </varlistentry>
321        </variablelist>
322
323        <variablelist>
324          <varlistentry>
325            <term>existsuser <replaceable>username</replaceable></term>
326
327            <listitem>
328              <para>Check if a local user exists. Returns the uid for the
329              given user, or 0 if the user wasn't found. Checking for the root
330              user is not supported because its uid is 0, and it will always
331              exist anyway.</para>
332            </listitem>
333          </varlistentry>
334        </variablelist>
335
336        <variablelist>
337          <varlistentry>
338            <term>nextuid</term>
339
340            <listitem>
341              <para>Returns the highest used uid plus one.</para>
342            </listitem>
343          </varlistentry>
344        </variablelist>
345
346        <variablelist>
347          <varlistentry>
348            <term>addgroup <replaceable>group</replaceable>
349            [gid=<replaceable>gid</replaceable>]
350            [passwd=<replaceable>passwd</replaceable>]
351            [realname=<replaceable>realname</replaceable>]
352            [users=<replaceable>users</replaceable>]</term>
353
354            <listitem>
355              <para>Add a new local group to the system, with the specified
356              gid, password, real name, and with a list users as
357              members.</para>
358            </listitem>
359          </varlistentry>
360        </variablelist>
361
362        <variablelist>
363          <varlistentry>
364            <term>existsgroup <replaceable>group</replaceable></term>
365
366            <listitem>
367              <para>Check if a local group exists and return the corresponding
368              gid. This can be used with adduser:</para>
369
370              <programlisting>addgroup foo
371adduser foo gid=[existsgroup foo]</programlisting>
372            </listitem>
373          </varlistentry>
374        </variablelist>
375
376        <variablelist>
377          <varlistentry>
378            <term>nextgid</term>
379
380            <listitem>
381              <para>Returns the highest used gid plus one.</para>
382            </listitem>
383          </varlistentry>
384        </variablelist>
385      </listitem>
386    </varlistentry>
387
388    <varlistentry>
389      <term>External program execution</term>
390
391      <listitem>
392        <para>Use only when ....</para>
393      </listitem>
394    </varlistentry>
395  </variablelist>
396</section>
Note: See TracBrowser for help on using the repository browser.