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

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

Document worksrcpath and destroot.
Bug: 2408
Submitted by: cjr

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