source: trunk/doc/guide/xml/portfiles/details.xml @ 8665

Last change on this file since 8665 was 8665, checked in by toby, 16 years ago

Patch from blb changing extract.sufx to extract.suffix

  • Property svn:eol-style set to native
File size: 36.6 KB
Line 
1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5<chapter id='details'>
6    <title>Portfile details</title>
7    <para> This Chapter describes in detail how each part of a portfile is
8    works and is used. </para>
9   
10    <sect1>
11        <title>General syntax</title>
12       
13        <para>A Portfile is a TCL script, so the syntax used must be valid
14        TCL or the Portfile will not work. The basic syntax of the Portfile
15        has been designed so most tasks are performed using key value(s)
16        combinations. Many people don't realise it is TCL until they want to do
17        something more advanced and realise all that power is there.</para>
18       
19                <para>All key value pairs in a Portfile are single lines so line breaks
20                must be escaped with a back slash ('\'). </para>
21                <para>Variables syntax is ${foo} for the foo variant.</para>
22        <sect2>
23                        <title>Special characters</title>
24                        <para>As the Portfile is a TCL script certain charachters are
25                        "special". These have a special meaning in TCL and if you dont
26                        want that special meaning, they must be escaped. In general a
27                        character is escaped using the back slash ('\'). The main
28                        characters you need to be careful with are
29                        <simplelist type="inline">
30                                        <member>$</member>
31                                        <member>}</member>
32                                        <member>}</member>
33                                        <member>[</member>
34                                        <member>]</member>
35                                        </simplelist></para>
36                                       
37                </sect2>
38               
39                <sect2>
40                        <title>Required keys</title>
41                       
42                        <para>There is a small set of required key/value pairs without
43                        which a Portfile cannot be correct.</para>
44                       
45                        <para>The required keys are
46                                <simplelist type="vert">
47                                        <member>PortSystem</member>
48                                        <member>name</member>
49                                        <member>version</member>
50                                        <member>platforms</member>
51                                        <member>maintainers</member>
52                                        <member>categories</member>
53                                        <member>description</member>
54                                        <member>master_sites</member>
55                                        <member>checksums</member>
56                                        <member>homepage</member>
57                                        <member>long_description</member>
58                                       
59                                </simplelist>
60                        Each of these keys is described in the following pages of
61                        the guide. </para>
62
63                               
64                </sect2>
65        </sect1>
66        <sect1>
67                <title>Useful preset variables</title>
68                <para></para>
69                <variablelist>
70                        <varlistentry id='prefix'>
71                                <term>prefix</term>
72                                <listitem>
73                                        <para>Installation prefix, set in the systemwide
74                                        configuration file /etc/ports/ports.conf. Can be
75                                        overridden on a per port basis. For example XFree86
76                                        needs to install in the /usr tree, or aqua applications
77                                        are installed in /Applications/Ports</para>
78                                       
79                                </listitem>
80                        </varlistentry>
81                       
82                        <varlistentry id='binpath'>
83                                <term>binpath</term>
84                                <listitem>
85                                        <para>Default PATH to use in finding executables. Read only.</para>
86                                       
87                                </listitem>
88                        </varlistentry>
89
90                        <varlistentry id='libpath'>
91                                <term>libpath</term>
92                                <listitem>
93                                        <para>Path to the DarwinPorts TCL libraries. Read only.</para>
94                                       
95                                </listitem>
96                        </varlistentry>
97                       
98                        <varlistentry id='portpath'>
99                                <term>portpath</term>
100                                <listitem>
101                                        <para>Path to the directory containing the downloaded
102                                        Portfiles. Read Only.</para>
103                                       
104                                </listitem>
105                        </varlistentry>
106                       
107                        <varlistentry id='filesdir'>
108                                <term>filesdir</term>
109                                <listitem>
110                                        <para>Path to port files relative to ${portpath}.
111                                        Read Only.</para>
112                                       
113                                </listitem>
114                        </varlistentry>
115                       
116                        <varlistentry id='workdir'>
117                                <term>workdir</term>
118                                <listitem>
119                                        <para>Path to work directory relative to ${portpath}.
120                                        Read Only</para>
121                                       
122                                </listitem>
123                        </varlistentry>
124                       
125                        <varlistentry id='workpath'>
126                                <term>workpath</term>
127                                <listitem>
128                                        <para>Full path to work directory. Read only.</para>
129                                       
130                                </listitem>
131                        </varlistentry>
132                                               
133                        <varlistentry id='distpath'>
134                                <term>distpath</term>
135                                <listitem>
136                                        <para>Location to store downloaded distfiles. Read
137                                        Only</para>
138                                       
139                                </listitem>
140                        </varlistentry>
141                       
142                        <varlistentry id='os.arch'>
143                                <term>os_arch</term>
144                                <listitem>
145                                        <para>Identifies hardware type (ie, "powerpc").
146                                        Read Only</para>
147                                       
148                                </listitem>
149                        </varlistentry>
150                       
151                        <varlistentry id='os.version'>
152                                <term>os_version</term>
153                                <listitem>
154                                        <para>Version number of operating system (ie "6.0").
155                                        Read Only.</para>
156                                       
157                                </listitem>
158                        </varlistentry>
159                       
160                </variablelist>
161        </sect1>
162
163        <sect1>
164                <title>Initialization phase</title>
165                <para>The first part of a Portfile deals with initialisation. Most
166                of the keys (or options) in the initialisation phase  are required
167                for all Portfiles. </para>
168
169                <variablelist>
170                        <varlistentry id='PortSystem'>
171                                <term>PortSystem</term>
172                                <listitem>
173                                        <para>Determines which version of the portsystem the
174                                        Portfile is compatible with. DarwinPorts supports
175                                        versioning of the PortSystem so if new, backwards
176                                        incompatible changes are introduced older Portfiles
177                                        can continue to use the older version of the system.
178                                        The PortSystem line wraps the loading of TCL libraries
179                                        appropriate for that version of DarwinPorts. If you
180                                        don't load the libraries, nothing else in the Portfile
181                                        will work. Thus, the PortSystem should be the top line
182                                        in the Portfile.</para>
183                                       
184                                        <para>Currently DarwinPorts only has version 1.0 so you
185                                        should put: <userinput>PortSystem 1.0</userinput> in your
186                                        Portfile.</para>
187
188                                </listitem>
189                        </varlistentry>
190                        <varlistentry id='name'>
191                                <term>name</term>
192                                <listitem>
193                                        <para>The name of the Port. By default this is used to
194                                        build the url from which the Port is fetched. The name
195                                        should be lowercase.</para>
196                                       
197                                        <para><userinput>name foo</userinput></para>
198                                       
199                                </listitem>
200                        </varlistentry>
201                        <varlistentry id='version'>
202                                <term>version</term>
203                                <listitem>
204                                        <para>The version of the Port. By default this is used to
205                                        build the url from which the Port is fetched. </para>
206                                       
207                                        <para><userinput>version 1.23.45</userinput></para>
208                                       
209                                </listitem>
210                        </varlistentry>
211                        <varlistentry id='platforms'>
212                                <term>platforms</term>
213                                <listitem>
214                                        <para>The platforms on which the port has been
215                                        tested. </para>
216                                        <para><userinput>platforms darwin freebsd</userinput></para>
217                                </listitem>
218                        </varlistentry>
219                        <varlistentry id='categories'>
220                                <term>categories</term>
221                                <listitem>
222                                        <para>The type of Port. The first category should be the
223                                        same as the directory in which the Portfile is stored
224                                        and therefore should be chosen with care. A Port may have
225                                        more that one category but is not required to.</para>
226                                       
227                                        <para><userinput>categories foo bar</userinput></para>
228                                       
229                                </listitem>
230                        </varlistentry>
231                        <varlistentry id='description'>
232                                <term>description</term>
233                                <listitem>
234                                        <para>One sentence describing what the port is, use
235                                        long_description for more detail. If you use
236                                        long_description you must still use description. </para>
237                                       
238                                        <para><userinput>description foo performs the
239                                        transformation of bar into xml</userinput> </para>
240                                       
241                                </listitem>
242                               
243                        </varlistentry>
244                        <varlistentry id='long_description'>
245                                <term>long_description</term>
246                                <listitem>
247                                        <para>Description of what the port is/does. Long lines
248                                        can be broken with escaped newlines. </para>
249                                        <para><programlisting><userinput>long_description foo
250                                        performs the transformation of bar into xml \
251This allows users to rapidly transform documentation into multiple \
252formats. </userinput></programlisting></para>
253                                </listitem>
254                        </varlistentry>
255                       
256                        <varlistentry id='maintainers'>
257                                <term>maintainers</term>
258                                <listitem>
259                                        <para>List the email address or addresses of the
260                                        Portfile maintainer(s)</para>
261                                        <para><userinput>maintainers
262                                        joeblogs@somerandom.domain.com</userinput></para>
263                                </listitem>
264                        </varlistentry>
265                        <varlistentry id='revision'>
266                                <term>revision</term>
267                                <listitem>
268                               
269                                        <para>Local revision number of portfile.  Increment
270                                        for port revisions. The default for this is 0. It
271                                        should be incremented for revisions that change the
272                                        installed port.</para>
273
274                                        <para>This key should only be used if the Portfile for the
275                                        same port version has changed significantly.  It should not be
276                                        used if the port ${version} has changed.  Most of the time,
277                                        this key is not needed at all.</para>
278
279                                        <para><userinput>revision 1.1</userinput></para>
280                                       
281                                </listitem>
282                        </varlistentry>
283                        <varlistentry id='extract.suffix'>
284                                <term>extract.suffix</term>
285                                <listitem>
286                                        <para>By default the value of ${extract.suffix} is .tar.gz.
287                                        Specifying extract.suffix is optional, only use it if the
288                                        suffix is not 'tar.gz.'. </para>
289                                       
290                                        <para><userinput>extract.suffix .tgz</userinput></para>
291                                       
292                                </listitem>
293                        </varlistentry>
294                        <varlistentry id='distname'>
295                                <term>distname</term>
296                                <listitem>
297                                        <para>By default distname is ${name}-${version}.
298                                        Specifying distname is optional, only use it if the
299                                        file that contains the port is not ${name}-${version}
300                                        (without the extract.suffix).</para>
301                                       
302                                        <para><userinput>distname ${name}_${version}</userinput></para>
303                                       
304                                </listitem>
305                        </varlistentry>
306                       
307                        <varlistentry id='distfiles'>
308                                <term>distfiles</term>
309                                <listitem>
310                                        <para>Defaults to ${distname}.${extract.suffix}. Specifying
311                                        distfiles is optional, only use it if the file that
312                                        contains the port is not ${distname}.${extract.suffix}
313                                        or more than one file needs to be retirieved. </para>
314                                       
315                                        <para><userinput>distfiles stable.${extract.suffix}
316                                        installer.sh</userinput></para>
317                                       
318                                        <para>Some ports require multiple items to be fetched
319                                        from different sites, this can be achieved using tags.
320                                        The tags are then used to identify which of the
321                                        master_sites to fetch the file from.see master_sites
322                                        below for more information. As with long_description,
323                                        long lines should be broken up with escaped
324                                        newlines. </para>
325                                        <para><userinput>distfiles
326                                        stable.${extract.suffix}:source
327                                        installer.sh:install</userinput></para>
328                                </listitem>
329                        </varlistentry>
330                       
331                        <varlistentry id='use_zip'>
332                                <term>use_zip</term>
333                                <listitem>
334                                        <para>Specifying use_zip is optional, only use it if
335                                        the file downloades is zipped rather than tarred and
336                                        gziped. use_zip set ${extract.suffix} to .zip and
337                                        extract.cmd to unzip, extract.pre_args to -q and
338                                        extract.post_args to "-d $portpath/$workdir".</para>
339                                       
340                                        <para><userinput>use_zip yes</userinput></para>
341                                       
342                                </listitem>
343                        </varlistentry>
344                        <varlistentry id='use_bzip2'>
345                                <term>use_bzip2</term>
346                                <listitem>
347                                        <para>Specifying use_bzip2 is optional, only use it
348                                        if the file downloades is bzipped rather than tarred
349                                        and gziped. use_bzip2 set ${extract.suffix} to .bzip2
350                                        and extract.cmd to bzip2.</para>
351                                       
352                                        <para><userinput>use_bzip2 yes</userinput></para>
353                                       
354                                </listitem>
355                        </varlistentry>
356                       
357                </variablelist>
358        </sect1>
359        <sect1>
360                <title>Fetch phase</title>
361         
362             
363                <variablelist> 
364                        <varlistentry id="master_sites">
365                                <term>master_sites</term>
366                                <listitem>
367                                        <para> A whitespace delimited list of urls from which the
368                                        source of the port can be retrieved. The URL should not
369                                        include the name of the file being retrieved.</para>
370                                       
371                                        <para>If you have multiple sites you should break up
372                                        long lines with escapend newlines. </para>
373               
374                <programlisting><userinput>master_sites   http://www.somesite.org/files/ \
375               http://www.somemirror.org/somesite_org/files/</userinput></programlisting>
376
377                                        <tip><para>Always put the trailing forward slash at the
378                                        end of a url, and remember to not include the filename
379                                        itself.</para></tip>
380                                       
381                                        <para>If you need to retrieve files from different
382                                        sites you can label the urls with tags.</para>
383
384                <programlisting><userinput>master_sites   http://www.somesite.org/files/:source \
385               http://www.someothersite.org/somesite_extras/:extras</userinput></programlisting>
386              </listitem>
387            </varlistentry>
388                       
389            <varlistentry id='master_sites_subdir'>
390              <term>master_sites.mirror_subdir</term>
391             
392              <listitem>
393                <para>Subdirectory to add to mirror sites taken from a
394                  mirror sites list.  Please see the section below on
395                  Mirror Site Lists for more details.</para>
396                                </listitem>
397                        </varlistentry>
398                       
399                                <varlistentry id='patchsites'>
400                                        <term>patch_sites</term>
401             
402                                        <listitem>
403                                                <para>List sites from which to download patchfiles
404                                                from, syntax is the same as master_sites. See the
405                                                Patch phase below for more information. </para>
406
407                <programlisting><userinput>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</userinput></programlisting>
408                                        </listitem>
409                                </varlistentry>
410                               
411            <varlistentry id='patchsites_subdir'>
412              <term>patch_sites.mirror_subdir</term>
413             
414              <listitem>
415                <para>Subdirectory to add to mirror sites taken from a
416                  mirror sites list.  Please see the section below on
417                  Mirror Site Lists for more details.</para>
418              </listitem>
419            </varlistentry>
420                </variablelist>
421         
422          <sect2>
423            <title>Mirror Site Lists</title>
424
425            <para>Mirror site lists are, as one might guess, predefined
426              lists of mirror sites for use in
427              <varname>master_sites</varname> or
428              <varname>patch_sites</varname>.  The basic usage of mirror
429              site lists in a <filename>Portfile</filename> is:</para>
430
431            <programlisting><userinput>master_sites                sourceforge http://distfiles.opendarwin.org/
432master_sites.mirror_subdir  ${name}</userinput></programlisting>
433
434            <para>Where '<varname>sourceforge</varname>' is the name of
435              the mirror list which specifies SourceForge mirrors.
436              <varname>master_sites.mirror_subdir</varname> is used to
437              specify the subdirectory of <emphasis>all</emphasis> sites
438              in in any mirror lists in which the file is found.  The
439              above example is equivalent to:</para>
440
441            <programlisting><userinput>master_sites  http://us.dl.sourceforge.net/${name}/ \
442              http://eu.dl.sourceforge.net/${name}/ \
443              ftp://us.dl.sourceforge.net/pub/sourceforge/${name}/ \
444              ...
445              http://distfiles.opendarwin.org/</userinput></programlisting>
446
447            <para>There are two potential problems when using mirror
448              site lists as described above.  First, if you are using
449              multiple mirror site lists, such as
450              <varname>sourceforge</varname> and <varname>gnu</varname>,
451              the subdirectory might not always be the same.  Second, if
452              you have multiple distfiles and are using distfile tags to
453              specify which site in <varname>master_sites</varname> to
454              download which file from.</para>
455           
456            <para>Fortunately DarwinPorts also provides a much more
457              powerful and flexible syntax for mirror site lists.</para>
458
459            <programlisting><userinput>distfiles                   file_one.tar.gz:tagone file_two.tar.gz:tagtwo file_three.tar.gz
460master_sites                sourceforge::tagone gnu:directory:tagtwo \
461                            http://distfiles.opendarwin.org/
462master_sites.mirror_subdir  ${name}</userinput></programlisting>
463
464            <para>At first glance, this example is probably quite
465              confusing.  Basically, the advanced syntax is
466              <varname>list:subdirectory:tag</varname>.  The above
467              example shows the many ways this can be used.  The above
468              example will:</para>
469
470            <itemizedlist>
471              <listitem>
472                <para>Look for <filename>file_one.tar.gz</filename>
473                  in:</para>
474
475                <programlisting>http://us.dl.sourceforge.net/${name}/
476http://eu.dl.sourceforge.net/${name}/
477ftp://us.dl.sourceforge.net/pub/sourceforge/${name}/
478...</programlisting>
479              </listitem>
480
481              <listitem>
482                <para>Look for <filename>file_two.tar.gz</filename>
483                  in:</para>
484
485                <programlisting>ftp://ftp.gnu.org/gnu/directory/${name}/
486ftp://gatekeeper.dec.com/pub/GNU/directory/${name}/
487ftp://ftp.uu.net/archive/systems/gnu/directory/${name}/
488...</programlisting>
489              </listitem>
490
491              <listitem>
492                <para>Look for <filename>file_three.tar.gz</filename>
493                  in:</para>
494
495                <programlisting>http://distfiles.opendarwin.org/</programlisting>
496              </listitem>
497            </itemizedlist>
498
499            <para>There are a few important points to remember when
500              using this syntax.  The subdirectory specified with the
501              list
502              (<varname>gnu:<emphasis>directory</emphasis></varname>) is
503              appended to all of the mirror sites in that list
504              <emphasis>before</emphasis> the
505              <varname>master_sites.mirror_subdir</varname>, and
506              <varname>master_sites.mirror_subdir</varname> is
507              <emphasis>always</emphasis> appended to the end of the
508              mirror site.  When using tags, you are not required to
509              specify a subdirectory
510              (<varname>sourceforge::tagone</varname>).
511              <varname>master_sites.mirror_subdir</varname> is also not
512              required when specifying a subdirectory with the
513              list.</para>
514
515            <para>The original example could also be have been written
516              using this syntax without the need of
517              <varname>master_sites.mirror_subdir</varname> like
518              this:</para>
519
520            <programlisting><userinput>master_sites   sourceforge:${name} http://distfiles.opendarwin.org/</userinput></programlisting>
521
522            <para>The mirror site lists functionality also works exactly
523              the same for <varname>patch_sites</varname> and
524              <varname>patch_sites.mirror_subdir</varname>.</para>
525
526            <para>Below is a list of the mirror site lists that can be
527              used.</para>
528
529            <itemizedlist>
530              <listitem><para><varname>apache</varname></para></listitem>
531              <listitem><para><varname>gnome</varname></para></listitem>
532              <listitem><para><varname>gnu</varname></para></listitem>
533              <listitem><para><varname>isc</varname></para></listitem>
534              <listitem><para><varname>kde</varname></para></listitem>
535              <listitem><para><varname>perl_cpan</varname></para></listitem>
536              <listitem><para><varname>ruby</varname></para></listitem>
537              <listitem><para><varname>sourceforge</varname></para></listitem>
538              <listitem><para><varname>sunsite</varname></para></listitem>
539              <listitem><para><varname>tcltk</varname></para></listitem>
540              <listitem><para><varname>xcontrib</varname></para></listitem>
541              <listitem><para><varname>xfree</varname></para></listitem>
542            </itemizedlist>
543          </sect2>
544        </sect1>
545
546        <sect1>
547                <title>Integrity checking phase</title>
548                <para>Each file downloaded is integrity checked using a checksum.
549                This is used to help prevent trojaned sources being downloaded.
550                If you do not include the checksums line, the file will be
551                downloaded and the checksum reported as a conenience to the Portfile
552                author.</para>
553               
554                <variablelist>
555                        <varlistentry id='checksums'>
556                                        <term>checksums</term>
557                                        <listitem>
558                                                <para>Currently only the md5 checksum is supported.
559                                                Specify the filename, the checksum type and the
560                                                checksum.</para>
561                                               
562                                                <para><programlisting><userinput>
563                                                ${distname}-${extract.suffix} md5 65b89365a65dcad71d4402b48 \
564                                                foo.tar.gz md5 65b89365a65dcad71d4402b44</userinput>
565                                                        </programlisting></para>
566
567                                                <tip><para>If you only have one file being fetched the
568                                                filename can be omitted. </para>
569                                               
570                                                <para><userinput>md5 65b89365a65dcad71d4402b48</userinput>
571                                                </para></tip>
572                                        </listitem>
573                                </varlistentry>
574                        </variablelist>
575        </sect1>
576        <sect1>
577                <title>Extract phase</title>
578                <para></para>
579                <variablelist>
580                        <varlistentry id='extract.only'>
581                                        <term>extract.only</term>
582                                        <listitem>
583                                                <para>List of files to extract into ${workpath},
584                                                defaults to ${distfiles}. Useful when some files
585                                                are not compressed. Only use extract.only if the
586                                                default does not do the right thing.</para>
587                                               
588                                                <para>
589                                                <userinput>extract.only foo.tar.gz bar.tar.gz</userinput>
590                                                </para>
591
592                                        </listitem>
593                                </varlistentry>
594                               
595                                <varlistentry id='extract.cmd'>
596                                        <term>extract.cmd</term>
597                                        <listitem>
598                                                <para>Command to perform extraction. Defaults to gzip. </para>
599                                                <para><userinput>extract.cmd gunzip</userinput></para>
600
601                                        </listitem>
602                                </varlistentry>
603                               
604                                <varlistentry id='extract.pre_args'>
605                                        <term>extract.pre_args</term>
606                                        <listitem>
607                                                <para>Arguments added to extract command before a
608                                                file name. Defaults to -dc. </para>
609                                                <para><userinput>extract.pre_args    -cd</userinput>
610                                                </para>
611
612                                        </listitem>
613                                </varlistentry>
614                               
615                                <varlistentry id='extract.args'>
616                                        <term>extract.args</term>
617                                        <listitem>
618                                                <para>Arguments to extract.cmd, Read Only. The value
619                                                is ${distpath}/${distfile}</para>
620
621                                        </listitem>
622                                </varlistentry>
623                               
624                                <varlistentry id='extract.post_args'>
625                                        <term>extract.post_args></term>
626                                        <listitem>
627                                                <para>Arguments added to extract command after a file
628                                                name. Defaults to "| tar -xf". </para>
629                                                <para><userinput>extract.post_args   | tar -xf
630                                                </userinput></para>
631
632                                        </listitem>
633                                </varlistentry>
634                               
635                        </variablelist>
636        </sect1>
637        <sect1>
638                <title>Patch phase</title>
639                <para></para>
640                        <variablelist>
641                                <varlistentry id='patchfiles'>
642                                        <term>patchfiles</term>
643                                        <listitem>
644                                                <para>List of patch files to apply to source. Patch
645                                                files can be supplied in a port in a directory named
646                                                files (based on the value of ${filepath}) within the
647                                                port directory or fetched from ${patchsites}. Each
648                                                patchfile supplied by the Portfile author should
649                                                patch a single file. The standard convention is to
650                                                name the patch file 'patch-&lt;filename&gt;.diff,
651                                                with one diff file per file altered in the source.
652                                                If the filename is ambiguous because there are
653                                                multiple files with that name in the distribution,
654                                                supply the path components to uniquely identify the
655                                                file being patched. Diffs should be created from the top
656                                                level of <varname>worksrcdir</varname>, the working source
657                                                directory where the port was extracted, with a command
658                                                similar to the following:</para>
659
660                                                <para><userinput>diff -u -b -w path/to/filename.org
661                                                path/to/filename >
662                                                ../../files/patch-filename.diff</userinput></para>
663
664                                                <para>If, for example the original file is
665                                                <filename>path/to/filename.orig</filename> and the file that
666                                                was changed is <filename>path/to/filename</filename>.</para>
667                                               
668                                                <para>Patches downloaded from patchsites must have
669                                                checksumes.</para>
670
671                                                <para>To specify patchfiles in a portfile:</para>
672
673                                                <para><userinput>patchfiles patch-Makefile.in
674                                                patch-source.c</userinput></para>
675
676                                        </listitem>
677                                </varlistentry>
678                               
679                        </variablelist>
680        </sect1>
681        <sect1 id='configure'>
682                <title>Configuration phase</title>
683                <para></para>
684                       
685                        <sect2>
686                                <title> Automake and autoconf</title>                                           
687                                        <variablelist>
688                                                <varlistentry id='use_automake'>
689                                                        <term>use_automake</term>
690                                                        <listitem>
691                                                                <para>If set to yes, use automake</para>
692                                                                <para><userinput>use_automake yes
693                                                                </userinput></para>
694
695                                                        </listitem>
696                                                </varlistentry>
697                                               
698                                                <varlistentry id='automake.env'>
699                                                        <term>automake.env</term>
700                                                        <listitem>
701                                                                <para>Environmental variables to pass
702                                                                to automake</para>
703                                                                <para><userinput>CFLAGS="-I'${prefix}/include'"
704                                                                </userinput></para>
705
706                                                        </listitem>
707                                                </varlistentry>
708                                               
709                                                <varlistentry id='automake.args'>
710                                                        <term>automake.args</term>
711                                                        <listitem>
712                                                                <para>Arguments to pass to automake. </para>
713                                                                <para><userinput>automake.args  --foreign
714                                                                </userinput></para>
715
716                                                        </listitem>
717                                                </varlistentry>
718                                               
719                                                <varlistentry id='automake.dir'>
720                                                        <term>automake.dir</term>
721                                                        <listitem>
722                                                                <para>Directory in which to run ${automake.cmd}.
723                                                                Defaults to ${worksrcpath}</para>
724                                                                <para><userinput>automake.dir</userinput></para>
725
726                                                        </listitem>
727                                                </varlistentry>
728                                               
729                                                <varlistentry id='use_autoconf'>
730                                                        <term>use_autoconf</term>
731                                                        <listitem>
732                                                                <para>If set to yes, run autoconf. </para>
733                                                                <para><userinput>use_autoconf   yes
734                                                                </userinput></para>
735
736                                                        </listitem>
737                                                </varlistentry>
738                                               
739                                                <varlistentry id='autoconf.env'>
740                                                        <term>autoconf.env</term>
741                                                        <listitem>
742                                                                <para>Environmental variables to pass to
743                                                                autoconf</para>
744                                                                <para><userinput>autoconf.env   
745                                                                CFLAGS=-I'${prefix}/include/gtk12'</userinput>
746                                                                </para>
747
748                                                        </listitem>
749                                                </varlistentry>
750                                               
751                                                <varlistentry id='autoconf.args'>
752                                                        <term>autoconf.args</term>
753                                                        <listitem>
754                                                                <para>Arguments to pass to autoconf. </para>
755                                                                <para><userinput>autoconf.args  -l
756                                                                src/aclocaldir</userinput></para>
757
758                                                        </listitem>
759                                                </varlistentry>
760                                               
761                                                <varlistentry id='autoconf.dir'>
762                                                        <term>autoconf.dir</term>
763                                                        <listitem>
764                                                                <para>Directory in which to run
765                                                                ${autoconf.cmd}. </para>
766                                                                <para><userinput>autoconf.dir   
767                                                                src</userinput></para>
768
769                                                        </listitem>
770                                                </varlistentry>
771                                               
772                                        </variablelist>
773                                </sect2>
774                                <sect2>
775                                        <title>configure</title>
776                                        <variablelist>
777                                                <varlistentry id='configure.env'>
778                                                        <term>configure.env</term>
779                                                        <listitem>
780                                                                <para>Set environment variables for
781                                                                configure.</para>
782                                                                <para><userinput>configure.env
783                                                                CFLAGS="-I'${prefix}/include'"</userinput>
784                                                                </para>
785
786                                                        </listitem>
787                                                </varlistentry>
788                                               
789                                                <varlistentry id='configure.pre_args'>
790                                                        <term>configure.pre_args</term>
791                                                        <listitem>
792                                                                <para>Arguments added to configure command
793                                                                before ${configure.args}. Defaults to
794                                                                --prefix=${prefix}. </para>
795                                                                <para><userinput>configure.pre_args       
796                                                                --prefix="${prefix}/apache2"</userinput></para>
797
798                                                        </listitem>
799                                                </varlistentry>
800                                               
801                                                <varlistentry id='configure.args'>
802                                                        <term>configure.args</term>
803                                                        <listitem>
804                                                                <para>Arguments to pass to configure.</para>
805                                                                <para><userinput>configure.args     
806                                                                --etcdir="${prefix}/etc"</userinput></para>
807
808                                                        </listitem>
809                                                </varlistentry>
810                                        </variablelist>
811                                </sect2>
812                               
813        </sect1>
814        <sect1>
815                <title>Build phase</title>
816                <para></para>
817               
818                <variablelist>
819                       
820                        <varlistentry id='build.cmd'>
821                                <term>build.cmd</term>
822                                <listitem>
823                                        <para>Make command to run relative to ${worksrcdir}.
824                                        Defaults to make.</para>
825                                        <para><userinput>build.cmd pbxbuild</userinput></para>
826
827                                </listitem>
828                        </varlistentry>
829                       
830                        <varlistentry id='build.type'>
831                                <term>build.type</term>
832                                <listitem>
833                                        <para>Defines which 'make' is required, either 'gnu'
834                                        or 'bsd' Sets build.cmd to either
835                                                'gnumake' or 'bsdmake' accordingly</para>
836                                               
837                                        <para><userinput>build.type     gnu</userinput></para>
838
839                                </listitem>
840                        </varlistentry>
841                       
842                        <varlistentry id='build.pre_args'>
843                                <term>build.pre_args</term>
844                                <listitem>
845                                        <para>Arguments to pass to ${build.cmd} before
846                                        ${build.args}. Read only. Set to
847                                        ${build.target.current}</para>
848
849                                </listitem>
850                        </varlistentry>
851                       
852                        <varlistentry id='build.args'>
853                                <term>build.args</term>
854                                <listitem>
855                                        <para>Arguments to pass to ${build.cmd}</para>
856                                        <para><userinput>build.args     
857                                        -DNOWARN</userinput></para>
858
859                                </listitem>
860                        </varlistentry>
861                       
862                        <varlistentry id='build.target'>
863                                <term>build.target</term>
864                                <listitem>
865                                        <para>Target to pass to make for building everything.
866                                        Defaults to all.</para>
867                                        <para><userinput>build.target.all all-src</userinput>
868                                        </para>
869
870                                </listitem>
871                        </varlistentry>
872
873                </variablelist>
874        </sect1>
875
876        <sect1>
877          <title>Destroot phase</title>
878               
879          <variablelist>
880
881            <varlistentry id='destroot.cmd'>
882              <term>destroot.cmd</term>
883              <listitem>
884                <para>Install command to run relative to ${worksrcdir}.
885                  Defaults to ${build.cmd}.</para>
886                <para><userinput>destroot.cmd pbxbuild</userinput></para>
887              </listitem>
888            </varlistentry>
889                       
890            <varlistentry id='destroot.type'>
891              <term>destroot.type</term>
892              <listitem>
893                <para>Defines which 'make' is required, either 'gnu' or
894                  'bsd' Sets install.cmd to either
895                  'gnumake' or 'bsdmake' accordingly</para>
896                <para><userinput>destroot.type     gnu</userinput></para>
897              </listitem>
898            </varlistentry>
899                       
900            <varlistentry id='destroot.pre_args'>
901              <term>destroot.pre_args</term>
902              <listitem>
903                <para>Arguments to pass to ${destroot.cmd} before
904                  ${destroot.args}. Read only. Set to  ${destroot.target}</para>
905              </listitem>
906            </varlistentry>
907                       
908            <varlistentry id='destroot.args'>
909              <term>destroot.args</term>
910              <listitem>
911                <para>Arguments to pass to ${destroot.cmd}</para>
912                <para><userinput>destroot.args     -DNOWARN</userinput></para>
913              </listitem>
914            </varlistentry>
915               
916            <varlistentry id='destroot.target'>
917              <term>destroot.target</term>
918              <listitem>
919                <para>Install target to pass to ${destroot.cmd}.</para>
920                <para><userinput>destroot.target install-src</userinput></para>
921              </listitem>
922            </varlistentry>
923
924            <varlistentry id='destroot.destdir'>
925              <term>destroot.destdir</term>
926              <listitem>
927                <para>Arguments passed to ${destroot.cmd} in order to
928                  install correctly into the destroot.</para>
929                <para>All ports must install via the 'destroot' so
930                  that the DarwinPorts infrastructure can register each
931                  file and directory a port installs. Most autoconf based
932                  build systems will behave correctly and respect DESTDIR,
933                  however some will not. Most of those that do not respect
934                  DESTDIR will install correctly if you use 'prefix', as
935                  in the example below. If your port doesn't respect either
936                  of these, you'll have to figure out what to do yourself.
937                  Some ports use another term, others require you to patch
938                  the Makefile (or other build related script). </para>
939                <para><userinput>destroot.destroot prefix=${destroot}${prefix}
940                    </userinput></para>
941              </listitem>
942            </varlistentry>
943          </variablelist>
944        </sect1>
945
946        <sect1>
947          <title>Test phase</title>
948
949          <variablelist>
950
951            <varlistentry id="test.run">
952              <term>test.run</term>
953
954              <listitem>
955                <para>Enable running test suites bundled with a
956                port</para>
957               
958                <para><userinput>test.run yes</userinput></para>
959              </listitem>
960            </varlistentry>
961
962            <varlistentry id="test.cmd">
963              <term>test.cmd</term>
964
965              <listitem>
966                <para>Test command to run relative to
967                ${worksrcdir}</para>
968
969                <para><userinput>test.cmd checks.sh</userinput></para>
970              </listitem>
971            </varlistentry>
972           
973            <varlistentry id="test.target">
974              <term>test.target</term>
975
976              <listitem>
977                <para>Test target to pass to ${test.cmd}</para>
978
979                <para><userinput>test.target
980                checks</userinput></para>
981              </listitem>
982            </varlistentry>
983             
984            <varlistentry id="test.dir">
985              <term>test.dir</term>
986
987              <listitem>
988                <para>Directory in which to run ${test.cmd}</para>
989
990                <para><userinput>test.dir
991                ${worksrcpath}/checks</userinput></para>
992              </listitem>
993            </varlistentry>
994          </variablelist>
995        </sect1>
996
997        <sect1>
998          <title>Install phase</title>
999
1000          <para>These keys have all been deprecated.  You should use the
1001            destroot keys in their place.</para>
1002        </sect1>
1003
1004        <sect1>
1005        <title>Dependencies</title>
1006        <para></para>                   
1007        <sect2>
1008                        <title>Principles</title>
1009                        <para></para>
1010                </sect2>
1011                <sect2>
1012                        <title>Dependency tests</title>
1013                        <para></para>
1014                        <variablelist>
1015                                <varlistentry>
1016                                                <term> depends_fetch </term>
1017                                                <listitem>
1018                                                <para></para>
1019                                                </listitem>
1020                                </varlistentry>
1021                                <varlistentry>
1022                                                <term> depends_extract </term>
1023                                                <listitem>
1024                                                <para></para>
1025                                                </listitem>
1026                                </varlistentry>
1027                                <varlistentry>
1028                                                <term> depends_lib </term>
1029                                                <listitem>
1030                                                <para></para>
1031                                                </listitem>
1032                                </varlistentry>
1033                                <varlistentry>
1034                                                <term> depends_build </term>
1035                                                <listitem>
1036                                                <para></para>
1037                                                </listitem>
1038                                </varlistentry>
1039                                <varlistentry>
1040                                                <term> depends_run </term>
1041                                                <listitem>
1042                                                        <para></para>
1043                                                </listitem>
1044                                </varlistentry> 
1045            </variablelist>
1046        </sect2>
1047    </sect1>
1048
1049        <sect1>
1050          <title>TCL primitives</title>
1051          <para>DarwinPorts provides several useful TCL primitives for
1052            use within Portfiles.</para>
1053
1054          <sect2>
1055            <title>adduser</title>
1056
1057            <para>Add a user to the system.</para>
1058           
1059            <para>Usage: <userinput>adduser name</userinput></para>
1060           
1061            <para>Where <userinput>name</userinput> is the username
1062              to add.  You can also override the defaults for any of the
1063              following user settings:</para>
1064
1065            <para><userinput>adduser name password={\*} uid=[nextuid]
1066              gid=[nextgid] realname=${name} home=/dev/null
1067              shell=/dev/null</userinput></para>
1068          </sect2>
1069
1070          <sect2>
1071            <title>addgroup</title>
1072           
1073            <para>Add a group to the system.</para>
1074
1075            <para>Usage: <userinput>addgroup name</userinput></para>
1076
1077            <para>Where <userinput>name</userinput> is the name of the
1078            group to add.  You can also override the defaults for any of
1079            the following group settings:</para>
1080
1081            <para><userinput>addgroup name gid=[nextgid]
1082            users=""</userinput></para>
1083          </sect2>
1084
1085          <sect2>
1086            <title>file</title>
1087
1088            <para>Manipulate file names and attributes.</para>
1089
1090            <para>Usage: <userinput>file option name ?arg arg
1091            ...?</userinput></para>
1092
1093            <para>Please see the Tcl documentation at <ulink
1094                url="http://www.tcl.tk/man/tcl8.3/TclCmd/file.htm">The
1095                Tcl/Tk Developer's Site.</ulink> for more on the options
1096                and arguments for file.</para>
1097          </sect2>
1098
1099          <sect2>
1100            <title>reinplace</title>
1101            <para>Provides "sed in place" functionality.</para>
1102            <para>Usage: <userinput>reinplace   sed_patern
1103            file</userinput></para>
1104            <para>Where <userinput>sed_patern</userinput> is a sed
1105            patern, and <userinput>file</userinput> is the name of the
1106            file to run sed on.</para>
1107          </sect2>
1108          <sect2>
1109            <title>system</title>
1110            <para>Execute a system command.</para>
1111            <para>Usage: <userinput>system  "command"</userinput></para>
1112          </sect2>             
1113        </sect1>
1114       
1115        <sect1>
1116                <title>Other</title>
1117                <para></para>
1118                <sect2>
1119                        <title>Pre and post phase steps</title>
1120                        <variablelist>
1121                                <varlistentry>
1122                                        <term>Pre-*</term>
1123                                        <listitem>
1124                                                <para></para>
1125                                        </listitem>
1126                                </varlistentry>
1127                               
1128                                <varlistentry>
1129                                        <term>Post-*</term>
1130                                        <listitem>
1131                                                <para></para>
1132
1133                                        </listitem>
1134                                </varlistentry>
1135                        </variablelist>
1136                </sect2>
1137                <sect2>
1138                        <title>Overriding a phase</title>
1139                        <para></para>
1140
1141                </sect2>
1142                       
1143    </sect1>
1144 </chapter>
1145       
1146
1147               
1148               
Note: See TracBrowser for help on using the repository browser.