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

Last change on this file since 4478 was 4478, checked in by fkr, 17 years ago

Bug:
Submitted by:
Reviewed by:
Approved by:
Obtained from:

big guide-update from wbb@. Thanks Will!

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