source: trunk/doc-new/guide/xml/portfiledev.xml @ 37464

Last change on this file since 37464 was 37464, checked in by markd@…, 11 years ago

Minor refinements to port style section.

File size: 28.6 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<chapter id="development">
5  <title>Portfile Development</title>
6
7  <para>This chapter covers a brief introduction to Portfiles, how to create a
8  local Portfile repository for development, and creating Portfiles.</para>
9
10  <section id="development.introduction">
11    <title>Portfile Introduction</title>
12
13    <para>A MacPorts Portfile is a <ulink
14    url="http://en.wikipedia.org/wiki/Tcl">TCL</ulink> script that usually
15    contains only the simple keyword/value combinations and Tcl extensions as
16    described in the <link linkend="reference">Portfile Reference</link>
17    chapter, though it may also contain arbitrary TCL code. Every port has a
18    corresponding Portfile, but Portfiles do not completely define a port's
19    installation behavior since MacPorts base has default port installation
20    characteristics coded within it. Therefore Portfiles need only specify
21    required options, though some ports may require non-default
22    options.</para>
23
24    <para>A common way for Portfiles to augment or override MacPorts base
25    default installation phase characteristics is by using
26    <filename>Portfile</filename> phase declaration(s). If you use Portfile
27    phase declaration(s), you should know how to identify the "global" section
28    of a Portfile. Any statements not contained within a phase declaration, no
29    matter where they are located in a Portfile, are said to be in the global
30    section of the Portfile; therefore the global section need not be
31    contiguous. Likewise, to remove statements from the global section they
32    must be placed within a phase declaration.</para>
33
34    <para>The main phases you need to be aware of when making a Portfile are
35    these:</para>
36
37    <itemizedlist>
38      <listitem>
39        <para>Fetch</para>
40      </listitem>
41
42      <listitem>
43        <para>Extract</para>
44      </listitem>
45
46      <listitem>
47        <para>Patch</para>
48      </listitem>
49
50      <listitem>
51        <para>Configure</para>
52      </listitem>
53
54      <listitem>
55        <para>Build</para>
56      </listitem>
57
58      <listitem>
59        <para>Destroot</para>
60      </listitem>
61    </itemizedlist>
62
63    <para>The default installation phase behavior performed by the MacPorts
64    base works fine for applications that use the standard
65    <command>configure</command>, <command>make</command>, and <command>make
66    install</command> steps, which conform to phases configure, build, and
67    destroot respectively. For applications that do not conform to this
68    standard behavior, any installation phase may be augmented using <link
69    linkend="development.examples.augment">pre- and/or post- phases</link>, or
70    even <link linkend="development.examples.override">overridden</link> or
71    <link linkend="development.examples.eliminate">eliminated</link>. See
72    <link linkend="development.examples">Example Portfiles</link>
73    below.</para>
74
75    <note>
76      <para>For a detailed description of all port phases, see the <link
77      linkend="reference.phases">Portfile Reference</link> chapter.</para>
78    </note>
79  </section>
80
81  <section id="development.creating-portfile">
82    <title>Creating a Portfile</title>
83
84    <para>Here we list the individual Portfile components for an application
85    that conforms to the standard <command>configure</command>,
86    <command>make</command>, and <command>make install</command> steps of most
87    open source application installs.</para>
88
89    <orderedlist>
90      <listitem>
91        <para>Subversion ID tag line</para>
92
93        <para>The first line of a new Portfile must be set as shown. When a
94        port is committed to subversion, ID tags are expanded to include the
95        last person to commit and the commit time.</para>
96
97        <programlisting># $Id$</programlisting>
98      </listitem>
99
100      <listitem>
101        <para>PortSystem line</para>
102
103        <para>This statement is required for all ports.</para>
104
105        <programlisting>PortSystem          1.0</programlisting>
106      </listitem>
107
108      <listitem>
109        <para>Port name</para>
110
111        <programlisting>name                rrdtool</programlisting>
112      </listitem>
113
114      <listitem>
115        <para>Port version</para>
116
117        <programlisting>version             1.2.23</programlisting>
118      </listitem>
119
120      <listitem>
121        <para>Port categories</para>
122
123        <para>A port may belong to more than one category, but the first
124        (primary) category should match the directory name in the ports tree
125        where the Portfile is to reside.</para>
126
127        <programlisting>categories          net</programlisting>
128      </listitem>
129
130      <listitem>
131        <para>Port maintainers</para>
132
133        <para>A port's maintainer is a person or persons who take
134        responsibility for keeping the port up-to-date, and the maintainer
135        keyword lists maintainer email addresses(s). To hide these addresses
136        from spambots, see the more full explanation of the <link
137        linkend="reference.keywords.maintainers">maintainer keyword</link> in
138        the <link linkend="reference.keywords">Global Keywords</link> section
139        of the <link linkend="reference">Portfile Reference</link>
140        chapter.</para>
141
142        <programlisting>maintainers         julesverne@example.org</programlisting>
143
144        <note>
145          <para>The address <email>nomaintainer@macports.org</email>, or in
146          hidden form <email>nomaintainer</email>, designates a port that may
147          be modified by any committer.</para>
148        </note>
149      </listitem>
150
151      <listitem>
152        <para>Port description</para>
153
154        <programlisting>description         Round Robin Database</programlisting>
155      </listitem>
156
157      <listitem>
158        <para>Port long_description</para>
159
160        <programlisting>long_description    RRDtool is a system to store and display time-series \
161                    data</programlisting>
162      </listitem>
163
164      <listitem>
165        <para>A port's application homepage</para>
166
167        <programlisting>homepage            http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/</programlisting>
168      </listitem>
169
170      <listitem>
171        <para>Platform statement</para>
172
173        <programlisting>platforms           darwin</programlisting>
174      </listitem>
175
176      <listitem>
177        <para>A port's download URLs</para>
178
179        <programlisting>master_sites        http://oss.oetiker.ch/rrdtool/pub/ \
180                    ftp://ftp.pucpr.br/rrdtool/</programlisting>
181      </listitem>
182
183      <listitem>
184        <para>Port checksums</para>
185
186        <para>The checksums specified in a Portfile are checked with the
187        fetched tarball for security. For the best security, use md5, sha1,
188        and rmd160 checksum types.</para>
189
190        <programlisting>checksums           md5 dafa161bc9c61e57636a6085c87c1fe8 \
191                    sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
192                    rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23</programlisting>
193
194        <para>To find the correct checksums for a port's distribution file,
195        follow this example:</para>
196
197        <programlisting><prompt>%%</prompt> <userinput>md5 rrdtool-1.2.23.tar.gz</userinput>
198<prompt>%%</prompt> <userinput>openssl sha1 rrdtool-1.2.23.tar.gz</userinput>
199<prompt>%%</prompt> <userinput>openssl rmd160 rrdtool-1.2.23.tar.gz</userinput></programlisting>
200
201        <screen>MD5 ( ... rrdtool-1.2.23.tar.gz) = dafa161bc9c61e57636a6085c87c1fe8
202
203SHA1( ... rrdtool-1.2.23.tar.gz)= 5da610e1c8bc01b80abc21ab9e98e004363b429c
204
205RIPEMD160( ... rrdtool-1.2.23.tar.gz)= 0c1147242adf476f5e93f4d59b553ee3ea378b23</screen>
206      </listitem>
207
208      <listitem>
209        <para>Port dependencies</para>
210
211        <para>A port's dependencies are ports that must be installed before
212        another port is installed.</para>
213
214        <programlisting>depends_lib         port:perl5.8 \
215                    port:tcl \
216                    port:zlib</programlisting>
217      </listitem>
218
219      <listitem>
220        <para>Port configure arguments (optional)</para>
221
222        <programlisting>configure.args      --prefix=${prefix} \
223                    --enable-perl-site-install \
224                    --mandir=${prefix}/share/man</programlisting>
225      </listitem>
226    </orderedlist>
227  </section>
228
229  <section id="development.examples">
230    <title>Example Portfiles</title>
231
232    <para>In this section we begin by taking a look at a complete simple
233    Portfile; then we see how to <link
234    linkend="development.examples.augment">augment default phases</link> by
235    defining pre- and post- phases, how to <link
236    linkend="development.examples.override">override default phases</link>,
237    and finally how to <link
238    linkend="development.examples.eliminate">eliminate port
239    phases</link>.</para>
240
241    <section id="development.examples.basic">
242      <title>A Basic Portfile</title>
243
244      <programlisting># $Id$
245
246PortSystem          1.0
247
248name                rrdtool
249version             1.2.23
250categories          net
251maintainers         julesverne
252description         Round Robin Database
253long_description    RRDtool is a system to store and display time-series data
254homepage            http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/
255platforms           darwin
256master_sites        http://oss.oetiker.ch/rrdtool/pub/ \
257                    ftp://ftp.pucpr.br/rrdtool/
258
259checksums           md5 dafa161bc9c61e57636a6085c87c1fe8 \
260                    sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
261                    rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23
262
263depends_lib         port:perl5.8 \
264                    port:tcl \
265                    port:zlib
266
267configure.args      --enable-perl-site-install \
268                    --mandir=${prefix}/share/man</programlisting>
269    </section>
270
271    <section id="development.examples.augment">
272      <title>Augment Phases Using pre- / post-</title>
273
274      <para>To augment a port's installation phase, and not override it, you
275      may use pre- and post- installation phases as shown in this
276      example.</para>
277
278      <programlisting>post-destroot {
279    # Install example files not installed by the Makefile
280    file mkdir ${destroot}${prefix}/share/doc/${name}/examples
281    file copy ${worksrcpath}/examples/ \
282        ${destroot}${prefix}/share/doc/${name}/examples
283}</programlisting>
284    </section>
285
286    <section id="development.examples.override">
287      <title>Overriding Phases</title>
288
289      <para>To override the automatic MacPorts installation phase processing,
290      define your own installation phases as shown in this example.</para>
291
292      <programlisting>destroot {
293    xinstall -m 755 -d ${destroot}${prefix}/bin
294    xinstall -m 755 ${worksrcpath}/cdpr ${destroot}${prefix}/bin
295}</programlisting>
296    </section>
297
298    <section id="development.examples.eliminate">
299      <title>Eliminating Phases</title>
300
301      <para>To eliminate a default phase, simply define a phase with no
302      contents as shown.</para>
303
304      <programlisting>build {}</programlisting>
305
306      <note>
307        <para>Because many software packages do not use
308        <option>configure</option>, a keyword is provided to eliminate the
309        <option>configure</option> phase. See the chapter <link
310        linkend="reference">Portfile Reference</link> for full
311        information.</para>
312      </note>
313    </section>
314
315    <section id="development.examples.startupitem">
316      <title>Creating a StartupItem</title>
317
318      <para>Startupitems may be placed in the global section of a
319      Portfile.</para>
320
321      <programlisting>startupitem.create      yes
322startupitem.name        nmicmpd
323startupitem.executable  "${prefix}/bin/nmicmpd"</programlisting>
324
325      <para>Startupitems keywords may also be used within a variant definition
326      to make their installation conditional.</para>
327
328      <programlisting>variant server {
329    startupitem.create  yes
330    startupitem.start   "${prefix}/share/${name}/vm-pop3d.init start"
331    startupitem.stop    "${prefix}/share/${name}/vm-pop3d.init stop"
332}</programlisting>
333    </section>
334  </section>
335
336  <section id="development.variants">
337    <title>Port Variants</title>
338
339    <para>Variants are a way for port authors to provide options that may be
340    invoked at install time. They are declared in the global section of a
341    Portfile using the "variant" keyword, and should include <link
342    linkend="reference.variants.descriptions">carefully chosen variant
343    descriptions</link>.</para>
344
345    <section id="development.variants.options">
346      <title>Example Variants</title>
347
348      <para>The most common actions for user-selected variants is to add or
349      remove dependencies, configure arguments, and build arguments according
350      to various options a port author wishes to provide. Here is an example
351      of several variants that modify depends_lib and configure arguments for
352      a port.</para>
353
354      <programlisting>variant fastcgi description {Add fastcgi binary} {
355    configure.args-append \
356            --enable-fastcgi \
357            --enable-force-cgi-redirect \
358            --enable-memory-limit
359}
360
361variant gmp description {Add GNU MP functions} {
362    depends_lib-append port:gmp
363    configure.args-append --with-gmp=${prefix}
364
365}
366
367variant sqlite description {Build sqlite support} {
368    depends_lib-append \
369        port:sqlite3
370    configure.args-delete \
371        --without-sqlite \
372        --without-pdo-sqlite
373    configure.args-append \
374        --with-sqlite \
375        --with-pdo-sqlite=${prefix} \
376        --enable-sqlite-utf8
377}</programlisting>
378
379      <note>
380        <para>Variant names may contain only the characters A-Z, a-z, and the
381        underscore character <quote>_</quote>. Therefore, take care to never
382        use hyphens in variant names.</para>
383      </note>
384
385      <para>In the example variant declaration below, the configure argument
386      <literal>--without-x</literal> is removed and a number of others are
387      appended.</para>
388
389      <programlisting>variant x11 description {Builds port as an X11 program with Lucid widgets} {
390    configure.args-delete   --without-x
391    configure.args-append   --with-x-toolkit=lucid \
392                            --without-carbon \
393                            --with-xpm \
394                            --with-jpeg \
395                            --with-tiff \
396                            --with-gif \
397                            --with-png
398    depends_lib-append      lib:libX11:XFree86 \
399                            lib:libXpm:XFree86 \
400                            port:jpeg \
401                            port:tiff \
402                            port:libungif \
403                            port:libpng
404}</programlisting>
405    </section>
406
407    <section id="development.variants.phase">
408      <title>Variant Actions in a Phase</title>
409
410      <para>If a variant requires options in addition to those provided by
411      keywords using -append and/or -delete, in other words, any actions that
412      would normally take place within a port installation phase, do not try
413      to do this within the variant declaration. Rather, modify the behavior
414      of any affected phases when the variant is invoked using the
415      variant_isset keyword.</para>
416
417      <programlisting>post-destroot {
418    xinstall -m 755 -d ${destroot}${prefix}/etc/
419    xinstall ${worksrcpath}/examples/foo.conf \
420        ${destroot}${prefix}/etc/
421
422    if {[variant_isset carbon]} {
423        delete ${destroot}${prefix}/bin/emacs
424        delete ${destroot}${prefix}/bin/emacs-${version}
425    }
426}</programlisting>
427    </section>
428
429    <section id="development.variants.default">
430      <title>Default Variants</title>
431
432      <para>Variants are used to specify actions that lie outside the core
433      functions of an application or port, but there may be some cases where
434      you wish to specify these non-core functions by default. For this
435      purpose you may use the keyword default_variants.</para>
436
437      <programlisting>default_variants    +foo +bar</programlisting>
438
439      <!-- TODO: add warning not to use default_variant at the moment -->
440
441      <note>
442        <para>The default_variant keyword may only be used in the global
443        Portfile section.</para>
444      </note>
445    </section>
446  </section>
447
448  <section id="development.patches">
449    <title>Patch Files</title>
450
451    <para>Patch files are files created with the Unix command
452    <command>diff</command> that are applied using the command
453    <command>patch</command> to modify text files to fix bugs or extend
454    functionality.</para>
455
456    <section id="development.patches.portfile">
457      <title>Creating Portfile Patches</title>
458
459      <para>If you wish to contribute modifications or fixes to a Portfile,
460      you should do so in the form of a patch. Follow the steps below to
461      create Portfile patch files</para>
462
463      <orderedlist>
464        <listitem>
465          <para>Make a copy of the Portfile you wish to modify; both files
466          must be in the same directory, though it may be any
467          directory.</para>
468
469          <programlisting><prompt>%%</prompt> <userinput>cp Portfile Portfile.orig</userinput></programlisting>
470        </listitem>
471
472        <listitem>
473          <para>Edit the file to make it as you want it to be after it is
474          fetched.</para>
475        </listitem>
476
477        <listitem>
478          <para>Now use the Unix command <command>diff -u </command>to create
479          a "unified" diff patch file. Put the name of the port in the
480          patchfile, for example, Portfile-rrdtool.diff.</para>
481
482          <programlisting><prompt>%%</prompt> <userinput>diff -u Portfile.orig Portfile &gt; Portfile-rrdtool.diff</userinput></programlisting>
483        </listitem>
484
485        <listitem>
486          <para>A patch file that is a "unified" diff file is the easiest to
487          interpret by humans and this type should always be used for ports.
488          The Portfile patch below will change the version and checksums when
489          applied.</para>
490
491          <programlisting>--- Portfile.orig        2007-07-25 18:52:12.000000000 -0700
492+++ Portfile    2007-07-25 18:53:35.000000000 -0700
493@@ -2,7 +2,7 @@
494 PortSystem          1.0
495 name                foo
496 
497-version             1.4.0
498+version             1.3.0
499 categories          net
500 maintainers         nomaintainer@macports.org
501 description         A network monitoring daemon.
502@@ -13,9 +13,9 @@
503 
504 homepage            http://rsug.itd.umich.edu/software/${name}
505 
506 master_sites        ${homepage}/files/
507-checksums           md5 f0953b21cdb5eb327e40d4b215110b71
508+checksums           md5 01532e67a596bfff6a54aa36face26ae
509 extract.suffix      .tgz
510 platforms           darwin
511</programlisting>
512        </listitem>
513      </orderedlist>
514
515      <para>Now you may attach the patch file to a MacPorts Trac ticket for
516      the port author to evaluate.</para>
517    </section>
518
519    <section id="development.patches.source">
520      <title>Creating Source Code Patches</title>
521
522      <para>Necessary or useful patches to application source code should
523      generally be sent to the application developer rather than the port
524      author so the modifications may be included in the next version of the
525      application.</para>
526
527      <para>You should create one patch file for each file to be patched,
528      though it is permissible to use existing patches you find that patch
529      multiple files. Patchfile filenames should uniquely distinguish the file
530      and generally be of the form
531      <filename>patch-</filename><replaceable>&lt;directory&gt;</replaceable>-<replaceable>&lt;filename&gt;.diff</replaceable>,
532      as shown in this example:
533      <filename>patch-src-Makefile.in.diff</filename>. Patch files should
534      apply with "patch -p0'' from the working source directory of the
535      port.</para>
536
537      <orderedlist>
538        <listitem>
539          <para>Locate the file you wish to patch in its original location
540          within the unpacked source directory and make a duplicate of
541          it.</para>
542
543          <programlisting><prompt>%%</prompt> <userinput>cd foo-1.34/src</userinput>
544<prompt>%%</prompt> <userinput>cp Makefile.in Makefile.in.orig</userinput></programlisting>
545        </listitem>
546
547        <listitem>
548          <para>Edit the file to make it as you want it to be after it is
549          fetched.</para>
550        </listitem>
551
552        <listitem>
553          <para>Now use the Unix command <command>diff -u</command> to create
554          a "unified" diff patch file.</para>
555
556          <programlisting><prompt>%%</prompt> <userinput>cd foo-1.34</userinput>
557<prompt>%%</prompt> <userinput>diff -u Makefile.in.orig Makefile.in &gt; patch-Makefile.in.diff</userinput></programlisting>
558
559          <note>
560            <para>You must execute the <command>diff</command> command in the
561            top-level of the unpacked source code. Otherwise the
562            <command>patch</command> command will look for the file to be
563            patched in the wrong path and fail.</para>
564          </note>
565        </listitem>
566
567        <listitem>
568          <para>A patch file that is a "unified" diff file is the easiest to
569          interpret by humans and this type should always be used for ports.
570          See the example below where a patch adds <varname>DESTDIR</varname>
571          support to a <filename>Makefile.in</filename> file.</para>
572
573          <programlisting>--- Makefile.in.orig   2007-06-01 16:30:47.000000000 -0700
574+++ Makefile.in       2007-06-20 10:10:59.000000000 -0700
575@@ -131,23 +131,23 @@
576        $(INSTALL_DATA)/gdata $(INSTALL_DATA)/perl
577
578 install-lib:
579-       -mkdir -p $(INSTALL_LIB)
580+       -mkdir -p $(DESTDIR)$(INSTALL_LIB)
581        $(PERL) tools/install_lib -s src -l $(INSTALL_LIB) $(LIBS)
582-       cp $(TEXT) $(INSTALL_LIB)/
583+       cp $(TEXT) $(DESTDIR)$(INSTALL_LIB)/</programlisting>
584        </listitem>
585
586        <listitem>
587          <para>Place the patch <filename>patch-Makefile.in.diff</filename> in
588          the directory <filename>${portpath}/files</filename> and use it in a
589          port using the <code>patchfiles</code> keyword.
590          <varname>${portpath}</varname> may be in a local Portfile repository
591          for development purposes, or the patch may be committed to the
592          global MacPorts repository for distribution.</para>
593
594          <programlisting>patchfiles          patch-Makefile.in</programlisting>
595        </listitem>
596      </orderedlist>
597    </section>
598
599    <section id="development.patches.applying">
600      <title>Manually Applying Patches</title>
601
602      <para>Though MacPorts applies patch files automatically, you may want to
603      know how to apply patch files manually if you want to test patch files
604      you have created or you wish to apply uncommitted Portfile
605      patches.</para>
606
607      <orderedlist>
608        <listitem>
609          <para>Change to the directory containing the file to be patched. In
610          this example, we'll apply a Portfile patch to the postfix
611          port.</para>
612
613          <programlisting><prompt>%%</prompt> <userinput>cd ${prefix}/var/macports/sources/rsync.macports.org/release/ports/mail/postfix</userinput></programlisting>
614        </listitem>
615
616        <listitem>
617          <para>Now apply the patch that is on the current user's desktop. The
618          patchfile knows the filename of the file to be patched.</para>
619
620          <programlisting><prompt>%%</prompt> <userinput>patch -p0 &lt; ~/Desktop/Portfile-postfix.diff</userinput></programlisting>
621
622          <screen>patching file Portfile</screen>
623        </listitem>
624      </orderedlist>
625    </section>
626  </section>
627
628  <section id="development.local-repositories">
629    <title>Local Portfile Repositories</title>
630
631    <para>To create and test Portfiles that are not yet committed to
632    subversion, you may create a local Portfile repository as shown. Replace
633    the hypothetical user <filename>julesverne</filename> with your username
634    in the example below.</para>
635
636    <orderedlist>
637      <listitem>
638        <para>Open the <filename>sources.conf</filename> file in a text
639        editor.</para>
640
641        <programlisting><prompt>%%</prompt> <userinput>cd ${prefix}/etc/macports/</userinput>
642<prompt>%%</prompt> <userinput>pico sources.conf</userinput></programlisting>
643      </listitem>
644
645      <listitem>
646        <para>Insert a URL pointing to your local repository location before
647        the rsync URL as shown.</para>
648
649        <programlisting>file:///Users/julesverne/ports
650rsync://rsync.macports.org/release/ports
651</programlisting>
652
653        <note>
654          <para>The file URL should always appear before the rsync URL so that
655          local Portfiles can be tested that are duplicated in the MacPorts
656          tree, because the <command>port</command> command will always
657          operate on the first Portfile it encounters.</para>
658        </note>
659      </listitem>
660
661      <listitem>
662        <para>Place the Portfiles you create inside a directory whose name
663        matches the port, which should in turn be placed inside a directory
664        that reflect the port's primary category (the first category entry in
665        the Portfile).</para>
666
667        <programlisting><prompt>%%</prompt> <userinput>cd /Users/julesverne</userinput>
668<prompt>%%</prompt> <userinput>mkdir -p ports/games/bestevergame</userinput>
669<prompt>%%</prompt> <userinput>cd ports/games/bestevergame</userinput>
670<prompt>%%</prompt> <userinput>touch Portfile</userinput></programlisting>
671      </listitem>
672
673      <listitem>
674        <para>After a Portfile is created (see below), use the MacPorts
675        <command>portindex</command> command in the local repository's
676        directory to install it into the
677        <filename>Portindex</filename>.</para>
678
679        <programlisting>%% <userinput>cd /Users/julesverne/ports</userinput>
680%% <userinput>portindex</userinput></programlisting>
681
682        <screen>Creating software index in /Users/julesverne/ports
683Adding port games/bestevergame
684
685Total number of ports parsed:   1
686Ports successfully parsed:      1
687Ports failed:                   0</screen>
688      </listitem>
689    </orderedlist>
690
691    <para>Once the local port is added to the <filename>Portindex</filename>,
692    it becomes available for searching or installation as with any other
693    Portfile in the MacPorts tree as shown.</para>
694
695    <programlisting><prompt>%%</prompt> <userinput>port search bestever</userinput></programlisting>
696
697    <screen>bestevergame   games/bestevergame 1.1   The Best Ever Game</screen>
698  </section>
699
700  <section id="development.practices">
701    <title>Portfile Best Practices</title>
702
703    <para>This section contains practical guidelines for creating Portfiles
704    that install smoothly and provide consistency between ports. The following
705    sections are on the TODO list.</para>
706
707    <section id="development.practices.portstyle">
708      <title>Port Style</title>
709
710      <para>Portfiles may be thought of as a table of keys and values in two
711      columns separated by spaces (not tabs), so you should set your editor to
712      use soft tabs, which are tabs emulated by spaces. By default, the top
713      line of all Portfiles should use a modeline that defines soft tabs for
714      the vim and emacs editors as shown.</para>
715
716      <programlisting># -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4</programlisting>
717
718      <para>The left column should consist of single words, and will be
719      separated from the more complex right side by spaces in multiples of
720      four. Variable assignments and variant declarations are exceptions, and
721      may be considered a single word on the left side, with a single space
722      between words.</para>
723
724      <programlisting>set libver "8.5"
725
726
727variant mysql5 { ... }</programlisting>
728
729      <para>Frequently multiple items are necessary in the second column. For
730      example, to set multiple source download locations, multiple
731      "master_sites" must be defined. Unless the second column items are few
732      and short you should place each additional item on a new line and
733      separate lines with a backslash. Indent the lines after the first line
734      to make it clear the items are second column values and also to
735      emphasize the unity of the block.</para>
736
737      <programlisting>destroot.keepdirs    ${destroot}${prefix}/var/run \
738                     ${destroot}${prefix}/var/log \
739                     ${destroot}${prefix}/var/cache/mrtg</programlisting>
740    </section>
741
742    <section id="development.practices.dont-overwrite">
743      <title>Don't Overwrite Config Files</title>
744
745      <para>TODO:</para>
746    </section>
747
748    <section id="development.practices.install-docs">
749      <title>Install Docs and Examples</title>
750
751      <para>TODO:</para>
752    </section>
753
754    <section id="development.practices.provide-messages">
755      <title>Provide User Messages</title>
756
757      <para>TODO:</para>
758    </section>
759
760    <section id="development.practices.use-variables">
761      <title>Use Variables</title>
762
763      <para>TODO: Set variables so changing paths may be done in one place;
764      use them anytime it makes updates simpler: distname
765      ${name}-src-${version}</para>
766    </section>
767  </section>
768</chapter>
Note: See TracBrowser for help on using the repository browser.