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

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

doc-new: Fixed description of use of modeline, closes #15406.

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