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

Last change on this file since 26766 was 26766, checked in by afb@…, 13 years ago

fix spelling, bz2 confusion

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 39.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3                "http://www.oasis-open.org/docbook/xml/4.5/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 ${prefix}/etc/macports/macports.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/MacPorts</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 MacPorts 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. MacPorts 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 MacPorts. 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 MacPorts 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 downloads are zipped rather than tarred and
354                                        gzipped. use_zip sets ${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 downloads are tarred and bzipped rather
367                                        than gzipped. use_bzip2 sets ${extract.suffix} to
368                                        .tar.bz2 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 MacPorts 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>afterstep</varname></para></listitem>
549              <listitem><para><varname>apache</varname></para></listitem>
550              <listitem><para><varname>freebsd</varname></para></listitem>
551              <listitem><para><varname>gnome</varname></para></listitem>
552              <listitem><para><varname>gnu</varname></para></listitem>
553              <listitem><para><varname>isc</varname></para></listitem>
554              <listitem><para><varname>kde</varname></para></listitem>
555              <listitem><para><varname>openbsd</varname></para></listitem>
556              <listitem><para><varname>perl_cpan</varname></para></listitem>
557              <listitem><para><varname>postgresql</varname></para></listitem>
558              <listitem><para><varname>ruby</varname></para></listitem>
559              <listitem><para><varname>sourceforge</varname></para></listitem>
560              <listitem><para><varname>sunsite</varname></para></listitem>
561              <listitem><para><varname>tcltk</varname></para></listitem>
562              <listitem><para><varname>xcontrib</varname></para></listitem>
563              <listitem><para><varname>xfree</varname></para></listitem>
564            </itemizedlist>
565          </sect2>
566        </sect1>
567
568        <sect1>
569                <title>Integrity checking phase</title>
570                <para>Each file downloaded is integrity checked using a checksum.
571                This is used to help prevent trojaned sources being downloaded.
572                If you do not include the checksums line, the file will be
573                downloaded and the checksum reported as a conenience to the Portfile
574                author.</para>
575               
576                <variablelist>
577                        <varlistentry id='checksums'>
578                                        <term>checksums</term>
579                                        <listitem>
580                                                <para>Currently only the md5 checksum is supported.
581                                                Specify the filename, the checksum type and the
582                                                checksum.</para>
583                                               
584                                                <para><userinput>
585                                                ${distname}-${extract.sufx} md5 65b89365a65dcad71d4402b48 \
586                                                foo.tar.gz md5 65b89365a65dcad71d4402b44</userinput>
587                                                </para>
588
589                                                <tip><para>If you only have one file being fetched the
590                                                filename can be omitted. </para>
591                                               
592                                                <para><userinput>md5 65b89365a65dcad71d4402b48</userinput>
593                                                </para></tip>
594                                        </listitem>
595                                </varlistentry>
596                        </variablelist>
597        </sect1>
598        <sect1>
599                <title>Extract phase</title>
600                <para></para>
601                <variablelist>
602                        <varlistentry id='extract.only'>
603                                        <term>extract.only</term>
604                                        <listitem>
605                                                <para>List of files to extract into ${workpath},
606                                                defaults to ${distfiles}. Useful when some files
607                                                are not compressed. Only use extract.only if the
608                                                default does not do the right thing.</para>
609                                               
610                                                <para>
611                                                <userinput>extract.only foo.tar.gz bar.tar.gz</userinput>
612                                                </para>
613
614                                        </listitem>
615                                </varlistentry>
616                               
617                                <varlistentry id='extract.cmd'>
618                                        <term>extract.cmd</term>
619                                        <listitem>
620                                                <para>Command to perform extraction. Defaults to gzip. </para>
621                                                <para><userinput>extract.cmd gunzip</userinput></para>
622
623                                        </listitem>
624                                </varlistentry>
625                               
626                                <varlistentry id='extract.pre_args'>
627                                        <term>extract.pre_args</term>
628                                        <listitem>
629                                                <para>Arguments added to extract command before a
630                                                file name. Defaults to -dc. </para>
631                                                <para><userinput>extract.pre_args    -cd</userinput>
632                                                </para>
633
634                                        </listitem>
635                                </varlistentry>
636                               
637                                <varlistentry id='extract.args'>
638                                        <term>extract.args</term>
639                                        <listitem>
640                                                <para>Arguments to extract.cmd, Read Only. The value
641                                                is ${distpath}/${distfile}</para>
642
643                                        </listitem>
644                                </varlistentry>
645                               
646                                <varlistentry id='extract.post_args'>
647                                        <term>extract.post_args></term>
648                                        <listitem>
649                                                <para>Arguments added to extract command after a file
650                                                name. Defaults to "| tar -xf". </para>
651                                                <para><userinput>extract.post_args   | tar -xf
652                                                </userinput></para>
653
654                                        </listitem>
655                                </varlistentry>
656                               
657                        </variablelist>
658        </sect1>
659        <sect1>
660                <title>Patch phase</title>
661                <para></para>
662                        <variablelist>
663                                <varlistentry id='patchfiles'>
664                                        <term>patchfiles</term>
665                                        <listitem>
666                                                <para>List of patch files to apply to source. Patch
667                                                files can be supplied in a port in a directory named
668                                                files (based on the value of ${filepath}) within the
669                                                port directory or fetched from ${patchsites}. Each
670                                                patchfile supplied by the Portfile author should
671                                                patch a single file. The standard convention is to
672                                                name the patch file 'patch-&lt;filename&gt;.diff,
673                                                with one diff file per file altered in the source.
674                                                If the filename is ambiguous because there are
675                                                multiple files with that name in the distribution,
676                                                supply the path components to uniquely identify the
677                                                file being patched. Diffs should be created from the top
678                                                level of <varname>worksrcdir</varname>, the working source
679                                                directory where the port was extracted, with a command
680                                                similar to the following:</para>
681
682                                                <para><userinput>diff -u -b -w path/to/filename.orig
683                                                path/to/filename >
684                                                ../../files/patch-filename.diff</userinput></para>
685
686                                                <para>If, for example the original file is
687                                                <filename>path/to/filename.orig</filename> and the file that
688                                                was changed is <filename>path/to/filename</filename>.</para>
689                                               
690                                                <para>Patches downloaded from patchsites must have
691                                                checksumes.</para>
692
693                                                <para>To specify patchfiles in a portfile:</para>
694
695                                                <para><userinput>patchfiles patch-Makefile.in
696                                                patch-source.c</userinput></para>
697
698                                        </listitem>
699                                </varlistentry>
700                               
701                        </variablelist>
702        </sect1>
703        <sect1 id='configure'>
704                <title>Configuration phase</title>
705                <para></para>
706                       
707                        <sect2>
708                                <title> Automake and autoconf</title>                                           
709                                        <variablelist>
710                                                <varlistentry id='use_automake'>
711                                                        <term>use_automake</term>
712                                                        <listitem>
713                                                                <para>If set to yes, use automake</para>
714                                                                <para><userinput>use_automake yes
715                                                                </userinput></para>
716
717                                                        </listitem>
718                                                </varlistentry>
719                                               
720                                                <varlistentry id='automake.env'>
721                                                        <term>automake.env</term>
722                                                        <listitem>
723                                                                <para>Environmental variables to pass
724                                                                to automake</para>
725                                                                <para><userinput>CFLAGS="-I'${prefix}/include'"
726                                                                </userinput></para>
727
728                                                        </listitem>
729                                                </varlistentry>
730                                               
731                                                <varlistentry id='automake.args'>
732                                                        <term>automake.args</term>
733                                                        <listitem>
734                                                                <para>Arguments to pass to automake. </para>
735                                                                <para><userinput>automake.args  --foreign
736                                                                </userinput></para>
737
738                                                        </listitem>
739                                                </varlistentry>
740                                               
741                                                <varlistentry id='automake.dir'>
742                                                        <term>automake.dir</term>
743                                                        <listitem>
744                                                                <para>Directory in which to run ${automake.cmd}.
745                                                                Defaults to ${worksrcpath}</para>
746                                                                <para><userinput>automake.dir</userinput></para>
747
748                                                        </listitem>
749                                                </varlistentry>
750                                               
751                                                <varlistentry id='use_autoconf'>
752                                                        <term>use_autoconf</term>
753                                                        <listitem>
754                                                                <para>If set to yes, run autoconf. </para>
755                                                                <para><userinput>use_autoconf   yes
756                                                                </userinput></para>
757
758                                                        </listitem>
759                                                </varlistentry>
760                                               
761                                                <varlistentry id='autoconf.env'>
762                                                        <term>autoconf.env</term>
763                                                        <listitem>
764                                                                <para>Environmental variables to pass to
765                                                                autoconf</para>
766                                                                <para><userinput>autoconf.env   
767                                                                CFLAGS=-I'${prefix}/include/gtk12'</userinput>
768                                                                </para>
769
770                                                        </listitem>
771                                                </varlistentry>
772                                               
773                                                <varlistentry id='autoconf.args'>
774                                                        <term>autoconf.args</term>
775                                                        <listitem>
776                                                                <para>Arguments to pass to autoconf. </para>
777                                                                <para><userinput>autoconf.args  -l
778                                                                src/aclocaldir</userinput></para>
779
780                                                        </listitem>
781                                                </varlistentry>
782                                               
783                                                <varlistentry id='autoconf.dir'>
784                                                        <term>autoconf.dir</term>
785                                                        <listitem>
786                                                                <para>Directory in which to run
787                                                                ${autoconf.cmd}. </para>
788                                                                <para><userinput>autoconf.dir   
789                                                                src</userinput></para>
790
791                                                        </listitem>
792                                                </varlistentry>
793                                               
794                                        </variablelist>
795                                </sect2>
796                                <sect2>
797                                        <title>configure</title>
798                                        <variablelist>
799                                                <varlistentry id='configure.env'>
800                                                        <term>configure.env</term>
801                                                        <listitem>
802                                                                <para>Set environment variables for
803                                                                configure.</para>
804                                                                <para><userinput>configure.env
805                                                                CFLAGS="-I'${prefix}/include'"</userinput>
806                                                                </para>
807
808                                                        </listitem>
809                                                </varlistentry>
810                                               
811                                                <varlistentry id='configure.pre_args'>
812                                                        <term>configure.pre_args</term>
813                                                        <listitem>
814                                                                <para>Arguments added to configure command
815                                                                before ${configure.args}. Defaults to
816                                                                --prefix=${prefix}. </para>
817                                                                <para><userinput>configure.pre_args       
818                                                                --prefix="${prefix}/apache2"</userinput></para>
819
820                                                        </listitem>
821                                                </varlistentry>
822                                               
823                                                <varlistentry id='configure.args'>
824                                                        <term>configure.args</term>
825                                                        <listitem>
826                                                                <para>Arguments to pass to configure.</para>
827                                                                <para><userinput>configure.args     
828                                                                --etcdir="${prefix}/etc"</userinput></para>
829
830                                                        </listitem>
831                                                </varlistentry>
832                                        </variablelist>
833                                </sect2>
834                               
835        </sect1>
836        <sect1>
837                <title>Build phase</title>
838                <para></para>
839               
840                <variablelist>
841                       
842                        <varlistentry id='build.cmd'>
843                                <term>build.cmd</term>
844                                <listitem>
845                                        <para>Make command to run relative to ${worksrcdir}.
846                                        Defaults to make.</para>
847                                        <para><userinput>build.cmd pbxbuild</userinput></para>
848
849                                </listitem>
850                        </varlistentry>
851                       
852                        <varlistentry id='build.type'>
853                                <term>build.type</term>
854                                <listitem>
855                                        <para>Defines which 'make' is required, either 'gnu'
856                                        or 'bsd' Sets build.cmd to either
857                                                'gnumake' or 'bsdmake' accordingly</para>
858                                               
859                                        <para><userinput>build.type     gnu</userinput></para>
860
861                                </listitem>
862                        </varlistentry>
863                       
864                        <varlistentry id='build.pre_args'>
865                                <term>build.pre_args</term>
866                                <listitem>
867                                        <para>Arguments to pass to ${build.cmd} before
868                                        ${build.args}. Read only. Set to
869                                        ${build.target.current}</para>
870
871                                </listitem>
872                        </varlistentry>
873                       
874                        <varlistentry id='build.args'>
875                                <term>build.args</term>
876                                <listitem>
877                                        <para>Arguments to pass to ${build.cmd}</para>
878                                        <para><userinput>build.args     
879                                        -DNOWARN</userinput></para>
880
881                                </listitem>
882                        </varlistentry>
883                       
884                        <varlistentry id='build.target'>
885                                <term>build.target</term>
886                                <listitem>
887                                        <para>Target to pass to make for building everything.
888                                        Defaults to all.</para>
889                                        <para><userinput>build.target.all all-src</userinput>
890                                        </para>
891
892                                </listitem>
893                        </varlistentry>
894
895                </variablelist>
896        </sect1>
897
898        <sect1>
899          <title>Destroot phase</title>
900               
901          <variablelist>
902
903            <varlistentry id='destroot.cmd'>
904              <term>destroot.cmd</term>
905              <listitem>
906                <para>Install command to run relative to ${worksrcdir}.
907                  Defaults to ${build.cmd}.</para>
908                <para><userinput>destroot.cmd pbxbuild</userinput></para>
909              </listitem>
910            </varlistentry>
911                       
912            <varlistentry id='destroot.type'>
913              <term>destroot.type</term>
914              <listitem>
915                <para>Defines which 'make' is required, either 'gnu' or
916                  'bsd' Sets install.cmd to either
917                  'gnumake' or 'bsdmake' accordingly</para>
918                <para><userinput>destroot.type     gnu</userinput></para>
919              </listitem>
920            </varlistentry>
921                       
922            <varlistentry id='destroot.pre_args'>
923              <term>destroot.pre_args</term>
924              <listitem>
925                <para>Arguments to pass to ${destroot.cmd} before
926                  ${destroot.args}. Read only. Set to  ${destroot.target}</para>
927              </listitem>
928            </varlistentry>
929                       
930            <varlistentry id='destroot.args'>
931              <term>destroot.args</term>
932              <listitem>
933                <para>Arguments to pass to ${destroot.cmd}</para>
934                <para><userinput>destroot.args     -DNOWARN</userinput></para>
935              </listitem>
936            </varlistentry>
937               
938            <varlistentry id='destroot.target'>
939              <term>destroot.target</term>
940              <listitem>
941                <para>Install target to pass to ${destroot.cmd}.</para>
942                <para><userinput>destroot.target install-src</userinput></para>
943              </listitem>
944            </varlistentry>
945
946            <varlistentry id='destroot.destdir'>
947              <term>destroot.destdir</term>
948              <listitem>
949                <para>Arguments passed to ${destroot.cmd} in order to
950                  install correctly into the destroot.</para>
951                <para>All ports must install via the 'destroot' so
952                  that the MacPorts infrastructure can register each
953                  file and directory a port installs. Most autoconf based
954                  build systems will behave correctly and respect DESTDIR,
955                  however some will not. Most of those that do not respect
956                  DESTDIR will install correctly if you use 'prefix', as
957                  in the example below. If your port doesn't respect either
958                  of these, you'll have to figure out what to do yourself.
959                  Some ports use another term, others require you to patch
960                  the Makefile (or other build related script). </para>
961                <para><userinput>destroot.destdir prefix=${destroot}${prefix}
962                    </userinput></para>
963              </listitem>
964            </varlistentry>
965          </variablelist>
966        </sect1>
967
968        <sect1>
969          <title>Test phase</title>
970
971          <variablelist>
972
973            <varlistentry id="test.run">
974              <term>test.run</term>
975
976              <listitem>
977                <para>Enable running test suites bundled with a
978                port</para>
979               
980                <para><userinput>test.run yes</userinput></para>
981              </listitem>
982            </varlistentry>
983
984            <varlistentry id="test.cmd">
985              <term>test.cmd</term>
986
987              <listitem>
988                <para>Test command to run relative to
989                ${worksrcdir}</para>
990
991                <para><userinput>test.cmd checks.sh</userinput></para>
992              </listitem>
993            </varlistentry>
994           
995            <varlistentry id="test.target">
996              <term>test.target</term>
997
998              <listitem>
999                <para>Test target to pass to ${test.cmd}</para>
1000
1001                <para><userinput>test.target
1002                checks</userinput></para>
1003              </listitem>
1004            </varlistentry>
1005             
1006            <varlistentry id="test.dir">
1007              <term>test.dir</term>
1008
1009              <listitem>
1010                <para>Directory in which to run ${test.cmd}</para>
1011
1012                <para><userinput>test.dir
1013                ${worksrcpath}/checks</userinput></para>
1014              </listitem>
1015            </varlistentry>
1016          </variablelist>
1017        </sect1>
1018
1019        <sect1>
1020          <title>Install phase</title>
1021
1022          <para>These keys have all been deprecated.  You should use the
1023            destroot keys in their place.</para>
1024                </sect1>
1025
1026        <sect1>
1027                <title>StartupItems</title>
1028                        <para>To create StartupItems for your port, use these directives. It is considered good style to use the startupitem commands instead of creating a rc.s-tyle script.</para>
1029                        <variablelist>
1030                                <varlistentry id='startupitem.create'>
1031                                        <term>startupitem.create</term>
1032                                        <listitem>
1033                                                <para>This triggers the creation of a StartupItem, defaults to <userinput>no</userinput>.</para>
1034                                        </listitem>
1035                                </varlistentry>
1036
1037                                <varlistentry id='startupitem.name'>
1038                                        <term>startupitem.name</term>
1039                                        <listitem>
1040                                                <para>sets the name for the StartupItem, defaults to <userinput>${portname}</userinput></para>
1041                                        </listitem>
1042                                </varlistentry>
1043
1044                                <varlistentry id='startupitem.init'>
1045                                        <term>startupitem.init</term>
1046                                        <listitem>
1047                                                <para>commands that will get executes on initialization of StartupItem, e. g. assign common variables. Default is empty.</para>
1048                                                <para>Common usage would be to define the location of the pidfile, like <userinput>PIDFILE=${prefix}/var/run/food.pid</userinput>.</para>
1049                                        </listitem>
1050                                </varlistentry>
1051
1052                                <varlistentry id='startupitem.start'>
1053                                        <term>startupitem.start</term>
1054                                        <listitem>
1055                                                <para>command to call to start the daemon etc.; defaults to <userinput>${prefix}/etc/rc.d/${portname}.sh start</userinput></para>
1056                                                <para>The common unix daemon would just have something like <userinput>${prefix}/sbin/food</userinput></para>
1057                                        </listitem>
1058                                </varlistentry>
1059
1060                                <varlistentry id='startupitem.stop'>
1061                                        <term>startupitem.stop</term>
1062                                        <listitem>
1063                                                <para>command to call to stop the daemon etc.; defaults to <userinput>${prefix}/etc/rc.d/${portname}.sh stop</userinput></para>
1064                                                <para>The common schema on this command is to call <userinput>kill</userinput> on the daemons pid. If you have a pid-file, you would use something like <userinput>kill \$(cat ${prefix}/var/run/food.pid)</userinput>.</para>
1065                                        </listitem>
1066                                </varlistentry>
1067
1068                                <varlistentry id='startupitem.restart'>
1069                                        <term>startupitem.restart</term>
1070                                        <listitem>
1071                                                <para>command to call to restart the daemon etc.; defaults to <userinput>StopService; StartService</userinput> (execute stop, start on self).</para>
1072                                        </listitem>
1073                                </varlistentry>
1074
1075                                <varlistentry id='startupitem.requires'>
1076                                        <term>startupitem.requires</term>
1077                                        <listitem>
1078                                                <para>The required services to run this daemon, defaults to <userinput>"Disk" "NFS"</userinput>.</para>
1079                                        </listitem>
1080                                </varlistentry>
1081                        </variablelist>
1082        </sect1>
1083
1084        <sect1>
1085        <title>Dependencies</title>
1086        <para></para>                   
1087        <sect2>
1088                        <title>Principles</title>
1089                        <para></para>
1090                </sect2>
1091                <sect2>
1092                        <title>Dependency tests</title>
1093                        <para></para>
1094                        <variablelist>
1095                                <varlistentry>
1096                                                <term> depends_fetch </term>
1097                                                <listitem>
1098                                                <para></para>
1099                                                </listitem>
1100                                </varlistentry>
1101                                <varlistentry>
1102                                                <term> depends_extract </term>
1103                                                <listitem>
1104                                                <para></para>
1105                                                </listitem>
1106                                </varlistentry>
1107                                <varlistentry>
1108                                                <term> depends_lib </term>
1109                                                <listitem>
1110                                                <para></para>
1111                                                </listitem>
1112                                </varlistentry>
1113                                <varlistentry>
1114                                                <term> depends_build </term>
1115                                                <listitem>
1116                                                <para></para>
1117                                                </listitem>
1118                                </varlistentry>
1119                                <varlistentry>
1120                                                <term> depends_run </term>
1121                                                <listitem>
1122                                                        <para></para>
1123                                                </listitem>
1124                                </varlistentry> 
1125            </variablelist>
1126        </sect2>
1127    </sect1>
1128
1129        <sect1>
1130          <title>TCL primitives</title>
1131          <para>MacPorts provides several useful TCL primitives for
1132            use within Portfiles.</para>
1133
1134          <sect2>
1135            <title>adduser</title>
1136
1137            <para>Add a user to the system.</para>
1138           
1139            <para>Usage: <userinput>adduser name</userinput></para>
1140           
1141            <para>Where <userinput>name</userinput> is the username
1142              to add.  You can also override the defaults for any of the
1143              following user settings:</para>
1144
1145            <para><userinput>adduser name password={\*} uid=[nextuid]
1146              gid=[nextgid] realname=${name} home=/dev/null
1147              shell=/dev/null</userinput></para>
1148          </sect2>
1149
1150          <sect2>
1151            <title>addgroup</title>
1152           
1153            <para>Add a group to the system.</para>
1154
1155            <para>Usage: <userinput>addgroup name</userinput></para>
1156
1157            <para>Where <userinput>name</userinput> is the name of the
1158            group to add.  You can also override the defaults for any of
1159            the following group settings:</para>
1160
1161            <para><userinput>addgroup name gid=[nextgid]
1162            users=""</userinput></para>
1163          </sect2>
1164
1165          <sect2>
1166            <title>file</title>
1167
1168            <para>Manipulate file names and attributes.</para>
1169
1170            <para>Usage: <userinput>file option name ?arg arg
1171            ...?</userinput></para>
1172
1173            <para>Please see the Tcl documentation at <ulink
1174                url="http://www.tcl.tk/man/tcl8.3/TclCmd/file.htm">The
1175                Tcl/Tk Developer's Site.</ulink> for more on the options
1176                and arguments for file.</para>
1177          </sect2>
1178
1179          <sect2>
1180            <title>reinplace</title>
1181            <para>Provides "sed in place" functionality.</para>
1182            <para>Usage: <userinput>reinplace   sed_patern
1183            file</userinput></para>
1184            <para>Where <userinput>sed_patern</userinput> is a sed
1185            patern, and <userinput>file</userinput> is the name of the
1186            file to run sed on.</para>
1187          </sect2>
1188          <sect2>
1189            <title>system</title>
1190            <para>Execute a system command.</para>
1191            <para>Usage: <userinput>system  "command"</userinput></para>
1192          </sect2>             
1193        </sect1>
1194       
1195        <sect1>
1196                <title>Other</title>
1197                <para></para>
1198                <sect2>
1199                        <title>Pre and post phase steps</title>
1200                        <variablelist>
1201                                <varlistentry>
1202                                        <term>Pre-*</term>
1203                                        <listitem>
1204                                                <para></para>
1205                                        </listitem>
1206                                </varlistentry>
1207                               
1208                                <varlistentry>
1209                                        <term>Post-*</term>
1210                                        <listitem>
1211                                                <para></para>
1212
1213                                        </listitem>
1214                                </varlistentry>
1215                        </variablelist>
1216                </sect2>
1217                <sect2>
1218                        <title>Overriding a phase</title>
1219                        <para></para>
1220
1221                </sect2>
1222                       
1223    </sect1>
1224 </chapter>
1225       
1226
1227               
1228               
Note: See TracBrowser for help on using the repository browser.