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

Last change on this file since 4925 was 4925, checked in by jkh, 16 years ago

Add a binpath variable for setting the default PATH in order to avoid
"binary polution" in users PATHs (and also eliminated the dreaded
"Directory not found" error). For users who specifically want something
other than the default path, they can set it in ports.conf

  • Property svn:eol-style set to native
File size: 36.1 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='filedir'>
108                                <term>filedir</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, "Power Macintosh").
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.sufx'>
284                                <term>extract.sufx</term>
285                                <listitem>
286                                        <para>By default the value of ${extract.sufx} is .tar.gz.
287                                        Specifying extract.sufx is optional, only use it if the
288                                        suffix is not 'tar.gz.'. </para>
289                                       
290                                        <para><userinput>extract.sufx .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.sufx).</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.sufx}. Specifying
311                                        distfiles is optional, only use it if the file that
312                                        contains the port is not ${distname}.${extract.sufx}
313                                        or more than one file needs to be retirieved. </para>
314                                       
315                                        <para><userinput>distfiles stable.${extract.sufx}
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.sufx}: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.sufx} 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.sufx} 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.sufx} 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 with
656                                                <userinput>diff -u file1
657                                                file2 >../../files/patch-file.diff</userinput>.
658                                                Patches downloaded from patchsites must have
659                                                checksumes.</para>
660                                                <para><userinput>patchfiles patch-Makefile.in
661                                                patch-source.c</userinput></para>
662
663                                        </listitem>
664                                </varlistentry>
665                               
666                        </variablelist>
667        </sect1>
668        <sect1 id='configure'>
669                <title>Configuration phase</title>
670                <para></para>
671                       
672                        <sect2>
673                                <title> Automake and autoconf</title>                                           
674                                        <variablelist>
675                                                <varlistentry id='use_automake'>
676                                                        <term>use_automake</term>
677                                                        <listitem>
678                                                                <para>If set to yes, use automake</para>
679                                                                <para><userinput>use_automake yes
680                                                                </userinput></para>
681
682                                                        </listitem>
683                                                </varlistentry>
684                                               
685                                                <varlistentry id='automake.env'>
686                                                        <term>automake.env</term>
687                                                        <listitem>
688                                                                <para>Environmental variables to pass
689                                                                to automake</para>
690                                                                <para><userinput>CFLAGS="-I'${prefix}/include'"
691                                                                </userinput></para>
692
693                                                        </listitem>
694                                                </varlistentry>
695                                               
696                                                <varlistentry id='automake.args'>
697                                                        <term>automake.args</term>
698                                                        <listitem>
699                                                                <para>Arguments to pass to automake. </para>
700                                                                <para><userinput>automake.args  --foreign
701                                                                </userinput></para>
702
703                                                        </listitem>
704                                                </varlistentry>
705                                               
706                                                <varlistentry id='automake.dir'>
707                                                        <term>automake.dir</term>
708                                                        <listitem>
709                                                                <para>Directory in which to run ${automake.cmd}.
710                                                                Defaults to ${worksrcpath}</para>
711                                                                <para><userinput>automake.dir</userinput></para>
712
713                                                        </listitem>
714                                                </varlistentry>
715                                               
716                                                <varlistentry id='use_autoconf'>
717                                                        <term>use_autoconf</term>
718                                                        <listitem>
719                                                                <para>If set to yes, run autoconf. </para>
720                                                                <para><userinput>use_autoconf   yes
721                                                                </userinput></para>
722
723                                                        </listitem>
724                                                </varlistentry>
725                                               
726                                                <varlistentry id='autoconf.env'>
727                                                        <term>autoconf.env</term>
728                                                        <listitem>
729                                                                <para>Environmental variables to pass to
730                                                                autoconf</para>
731                                                                <para><userinput>autoconf.env   
732                                                                CFLAGS=-I'${prefix}/include/gtk12'</userinput>
733                                                                </para>
734
735                                                        </listitem>
736                                                </varlistentry>
737                                               
738                                                <varlistentry id='autoconf.args'>
739                                                        <term>autoconf.args</term>
740                                                        <listitem>
741                                                                <para>Arguments to pass to autoconf. </para>
742                                                                <para><userinput>autoconf.args  -l
743                                                                src/aclocaldir</userinput></para>
744
745                                                        </listitem>
746                                                </varlistentry>
747                                               
748                                                <varlistentry id='autoconf.dir'>
749                                                        <term>autoconf.dir</term>
750                                                        <listitem>
751                                                                <para>Directory in which to run
752                                                                ${autoconf.cmd}. </para>
753                                                                <para><userinput>autoconf.dir   
754                                                                src</userinput></para>
755
756                                                        </listitem>
757                                                </varlistentry>
758                                               
759                                        </variablelist>
760                                </sect2>
761                                <sect2>
762                                        <title>configure</title>
763                                        <variablelist>
764                                                <varlistentry id='configure.env'>
765                                                        <term>configure.env</term>
766                                                        <listitem>
767                                                                <para>Set environment variables for
768                                                                configure.</para>
769                                                                <para><userinput>configure.env
770                                                                CFLAGS="-I'${prefix}/include'"</userinput>
771                                                                </para>
772
773                                                        </listitem>
774                                                </varlistentry>
775                                               
776                                                <varlistentry id='configure.pre_args'>
777                                                        <term>configure.pre_args</term>
778                                                        <listitem>
779                                                                <para>Arguments added to configure command
780                                                                before ${configure.args}. Defaults to
781                                                                --prefix=${prefix}. </para>
782                                                                <para><userinput>configure.pre_args       
783                                                                --prefix="${prefix}/apache2"</userinput></para>
784
785                                                        </listitem>
786                                                </varlistentry>
787                                               
788                                                <varlistentry id='configure.args'>
789                                                        <term>configure.args</term>
790                                                        <listitem>
791                                                                <para>Arguments to pass to configure.</para>
792                                                                <para><userinput>configure.args     
793                                                                --etcdir="${prefix}/etc"</userinput></para>
794
795                                                        </listitem>
796                                                </varlistentry>
797                                        </variablelist>
798                                </sect2>
799                               
800        </sect1>
801        <sect1>
802                <title>Build phase</title>
803                <para></para>
804               
805                <variablelist>
806                       
807                        <varlistentry id='build.cmd'>
808                                <term>build.cmd</term>
809                                <listitem>
810                                        <para>Make command to run relative to ${worksrcdir}.
811                                        Defaults to make.</para>
812                                        <para><userinput>build.cmd pbxbuild</userinput></para>
813
814                                </listitem>
815                        </varlistentry>
816                       
817                        <varlistentry id='build.type'>
818                                <term>build.type</term>
819                                <listitem>
820                                        <para>Defines which 'make' is required, either 'gnu'
821                                        or 'bsd' Sets build.cmd to either
822                                                'gnumake' or 'bsdmake' accordingly</para>
823                                               
824                                        <para><userinput>build.type     gnu</userinput></para>
825
826                                </listitem>
827                        </varlistentry>
828                       
829                        <varlistentry id='build.pre_args'>
830                                <term>build.pre_args</term>
831                                <listitem>
832                                        <para>Arguments to pass to ${build.cmd} before
833                                        ${build.args}. Read only. Set to
834                                        ${build.target.current}</para>
835
836                                </listitem>
837                        </varlistentry>
838                       
839                        <varlistentry id='build.args'>
840                                <term>build.args</term>
841                                <listitem>
842                                        <para>Arguments to pass to ${build.cmd}</para>
843                                        <para><userinput>build.args     
844                                        -DNOWARN</userinput></para>
845
846                                </listitem>
847                        </varlistentry>
848                       
849                        <varlistentry id='build.target'>
850                                <term>build.target</term>
851                                <listitem>
852                                        <para>Target to pass to make for building everything.
853                                        Defaults to all.</para>
854                                        <para><userinput>build.target.all all-src</userinput>
855                                        </para>
856
857                                </listitem>
858                        </varlistentry>
859
860                </variablelist>
861        </sect1>
862
863        <sect1>
864          <title>Destroot phase</title>
865               
866          <variablelist>
867
868            <varlistentry id='destroot.cmd'>
869              <term>destroot.cmd</term>
870              <listitem>
871                <para>Install command to run relative to ${worksrcdir}.
872                  Defaults to ${build.cmd}.</para>
873                <para><userinput>destroot.cmd pbxbuild</userinput></para>
874              </listitem>
875            </varlistentry>
876                       
877            <varlistentry id='destroot.type'>
878              <term>destroot.type</term>
879              <listitem>
880                <para>Defines which 'make' is required, either 'gnu' or
881                  'bsd' Sets install.cmd to either
882                  'gnumake' or 'bsdmake' accordingly</para>
883                <para><userinput>destroot.type     gnu</userinput></para>
884              </listitem>
885            </varlistentry>
886                       
887            <varlistentry id='destroot.pre_args'>
888              <term>destroot.pre_args</term>
889              <listitem>
890                <para>Arguments to pass to ${destroot.cmd} before
891                  ${destroot.args}. Read only. Set to  ${destroot.target}</para>
892              </listitem>
893            </varlistentry>
894                       
895            <varlistentry id='destroot.args'>
896              <term>destroot.args</term>
897              <listitem>
898                <para>Arguments to pass to ${destroot.cmd}</para>
899                <para><userinput>destroot.args     -DNOWARN</userinput></para>
900              </listitem>
901            </varlistentry>
902               
903            <varlistentry id='destroot.target'>
904              <term>destroot.target</term>
905              <listitem>
906                <para>Install target to pass to ${destroot.cmd}.</para>
907                <para><userinput>destroot.target install-src</userinput></para>
908              </listitem>
909            </varlistentry>
910
911            <varlistentry id='destroot.destroot'>
912              <term>destroot.destroot</term>
913              <listitem>
914                <para>Arguments passed to ${destroot.cmd} in order to
915                  install correctly into the destroot.</para>
916                <para>All ports must install via the 'destroot' so
917                  that the DarwinPorts infrastructure can register each
918                  file and directory a port installs. Most autoconf based
919                  build systems will behave correctly and respect DESTDIR,
920                  however some will not. Most of those that do not respect
921                  DESTDIR will install correctly if you use 'prefix', as
922                  in the example below. If your port doesn't respect either
923                  of these, you'll have to figure out what to do yourself.
924                  Some ports use another term, others require you to patch
925                  the Makefile (or other build related script). </para>
926                <para><userinput>destroot.destroot prefix=${destroot}${prefix}
927                    </userinput></para>
928              </listitem>
929            </varlistentry>
930          </variablelist>
931        </sect1>
932
933        <sect1>
934          <title>Test phase</title>
935
936          <variablelist>
937
938            <varlistentry id="test.run">
939              <term>test.run</term>
940
941              <listitem>
942                <para>Enable running test suites bundled with a
943                port</para>
944               
945                <para><userinput>test.run yes</userinput></para>
946              </listitem>
947            </varlistentry>
948
949            <varlistentry id="test.cmd">
950              <term>test.cmd</term>
951
952              <listitem>
953                <para>Test command to run relative to
954                ${worksrcdir}</para>
955
956                <para><userinput>test.cmd checks.sh</userinput></para>
957              </listitem>
958            </varlistentry>
959           
960            <varlistentry id="test.target">
961              <term>test.target</term>
962
963              <listitem>
964                <para>Test target to pass to ${test.cmd}</para>
965
966                <para><userinput>test.target
967                checks</userinput></para>
968              </listitem>
969            </varlistentry>
970             
971            <varlistentry id="test.dir">
972              <term>test.dir</term>
973
974              <listitem>
975                <para>Directory in which to run ${test.cmd}</para>
976
977                <para><userinput>test.dir
978                ${worksrcpath}/checks</userinput></para>
979              </listitem>
980            </varlistentry>
981          </variablelist>
982        </sect1>
983
984        <sect1>
985          <title>Install phase</title>
986
987          <para>These keys have all been deprecated.  You should use the
988            destroot keys in their place.</para>
989        </sect1>
990
991        <sect1>
992        <title>Dependencies</title>
993        <para></para>                   
994        <sect2>
995                        <title>Principles</title>
996                        <para></para>
997                </sect2>
998                <sect2>
999                        <title>Dependency tests</title>
1000                        <para></para>
1001                        <variablelist>
1002                                <varlistentry>
1003                                                <term> depends_fetch </term>
1004                                                <listitem>
1005                                                <para></para>
1006                                                </listitem>
1007                                </varlistentry>
1008                                <varlistentry>
1009                                                <term> depends_extract </term>
1010                                                <listitem>
1011                                                <para></para>
1012                                                </listitem>
1013                                </varlistentry>
1014                                <varlistentry>
1015                                                <term> depends_lib </term>
1016                                                <listitem>
1017                                                <para></para>
1018                                                </listitem>
1019                                </varlistentry>
1020                                <varlistentry>
1021                                                <term> depends_build </term>
1022                                                <listitem>
1023                                                <para></para>
1024                                                </listitem>
1025                                </varlistentry>
1026                                <varlistentry>
1027                                                <term> depends_run </term>
1028                                                <listitem>
1029                                                        <para></para>
1030                                                </listitem>
1031                                </varlistentry> 
1032            </variablelist>
1033        </sect2>
1034    </sect1>
1035
1036        <sect1>
1037          <title>TCL primitives</title>
1038          <para>DarwinPorts provides several useful TCL primitives for
1039            use within Portfiles.</para>
1040
1041          <sect2>
1042            <title>adduser</title>
1043
1044            <para>Add a user to the system.</para>
1045           
1046            <para>Usage: <userinput>adduser name</userinput></para>
1047           
1048            <para>Where <userinput>name</userinput> is the username
1049              to add.  You can also override the defaults for any of the
1050              following user settings:</para>
1051
1052            <para><userinput>adduser name password={\*} uid=[nextuid]
1053              gid=[nextgid] realname=${name} home=/dev/null
1054              shell=/dev/null</userinput></para>
1055          </sect2>
1056
1057          <sect2>
1058            <title>addgroup</title>
1059           
1060            <para>Add a group to the system.</para>
1061
1062            <para>Usage: <userinput>addgroup name</userinput></para>
1063
1064            <para>Where <userinput>name</userinput> is the name of the
1065            group to add.  You can also override the defaults for any of
1066            the following group settings:</para>
1067
1068            <para><userinput>addgroup name gid=[nextgid]
1069            users=""</userinput></para>
1070          </sect2>
1071
1072          <sect2>
1073            <title>file</title>
1074
1075            <para>Manipulate file names and attributes.</para>
1076
1077            <para>Usage: <userinput>file option name ?arg arg
1078            ...?</userinput></para>
1079
1080            <para>Please see the Tcl documentation at <ulink
1081                url="http://www.tcl.tk/man/tcl8.3/TclCmd/file.htm">The
1082                Tcl/Tk Developer's Site.</ulink> for more on the options
1083                and arguments for file.</para>
1084          </sect2>
1085
1086          <sect2>
1087            <title>reinplace</title>
1088            <para>Provides "sed in place" functionality.</para>
1089            <para>Usage: <userinput>reinplace   sed_patern
1090            file</userinput></para>
1091            <para>Where <userinput>sed_patern</userinput> is a sed
1092            patern, and <userinput>file</userinput> is the name of the
1093            file to run sed on.</para>
1094          </sect2>
1095          <sect2>
1096            <title>system</title>
1097            <para>Execute a system command.</para>
1098            <para>Usage: <userinput>system  "command"</userinput></para>
1099          </sect2>             
1100        </sect1>
1101       
1102        <sect1>
1103                <title>Other</title>
1104                <para></para>
1105                <sect2>
1106                        <title>Pre and post phase steps</title>
1107                        <variablelist>
1108                                <varlistentry>
1109                                        <term>Pre-*</term>
1110                                        <listitem>
1111                                                <para></para>
1112                                        </listitem>
1113                                </varlistentry>
1114                               
1115                                <varlistentry>
1116                                        <term>Post-*</term>
1117                                        <listitem>
1118                                                <para></para>
1119
1120                                        </listitem>
1121                                </varlistentry>
1122                        </variablelist>
1123                </sect2>
1124                <sect2>
1125                        <title>Overriding a phase</title>
1126                        <para></para>
1127
1128                </sect2>
1129                       
1130    </sect1>
1131 </chapter>
1132       
1133
1134               
1135               
Note: See TracBrowser for help on using the repository browser.