Changeset 1111 for trunk/doc


Ignore:
Timestamp:
Oct 21, 2002, 10:35:25 PM (17 years ago)
Author:
michaelm
Message:

updated style of example ports, fixed some formatting

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/guide/xml/quick.xml

    r1102 r1111  
    22<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    33                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
    4 
    54<chapter id="quickstart">
    65        <chapterinfo>
    76                <keywordset>
    8                         <keyword>portfile</keyword>
    9                         <keyword>introduction</keyword>
    10                         <keyword>maintainer</keyword>
     7                        <keyword>
     8                                portfile
     9                        </keyword>
     10                        <keyword>
     11                                introduction
     12                        </keyword>
     13                        <keyword>
     14                                maintainer
     15                        </keyword>
    1116                </keywordset>
    1217        </chapterinfo>
    13     <title>Quick Start</title>
    14     <sect1>
    15         <title>Introduction to a Portfile</title>
    16         <para> This document will provide a short guide to the basics of the darwinports Portfile. A
    17             Portfile is actually a TCL script run by the port system, despite this the Portfile
    18             Syntax is very straightforward. To begin with we are going to look at a simple example
    19             Portfile and then explain the syntax that is used. </para>
    20     </sect1>
    21     <sect1>
    22         <title>Basic Portfile</title>
    23         <para> This is the first example (A real Portfile doesn't have the line numbers, they are
    24             used for clarity in the explanation only). </para>
    25         <sect2>
    26             <title> Example Portfile 1</title>
    27             <example>
    28                 <title>Expat Portfile</title>
    29                 <programlisting><![CDATA[
     18        <title>Quick Start</title>
     19        <sect1>
     20                <title>Introduction to a Portfile</title>
     21                <para>
     22                        This document will provide a short guide to the basics of the darwinports Portfile. A Portfile is actually a TCL script run by the port system, despite this the Portfile Syntax is very straightforward. To begin with we are going to look at a simple example Portfile and then explain the syntax that is used.
     23                </para>
     24        </sect1>
     25        <sect1>
     26                <title>Basic Portfile</title>
     27                <para>
     28                        This is the first example, Expat.
     29                </para>
     30                <sect2>
     31                        <title> Example Portfile 1</title>
     32                        <example>
     33                                <title>Expat Portfile</title>
     34                                <programlisting><![CDATA[
    3035########################### expat Portfile ##################################
    31 01> PortSystem 1.0
    32 02> name expat
    33 03> version 1.95.5
    34 04>
    35 05> categories textproc 
    36 06> maintainers rooneg@electricjellyfish.net 
    37 07> description An XML 1.0 parser written in C 
    38 08>
    39 09> master_sites ftp://eu.dl.sourceforge.net/pub/sourceforge/expat/ 
    40 10> checksums md5 6500d7d8c6c2c985cc0be257c9840cb4 
    41 11>
    42 12>
    43 13>
    44 14> contents { bin/xmlwf 
    45 15> include/expat.h
    46 16> lib/libexpat.0.4.0.dylib 
    47 17> lib/libexpat.a 
    48 18> lib/libexpat.la 
    49 19> lib/libexpat.0.dylib 
    50 20> lib/libexpat.dylib 
    51 21> } 
    52 22>
     36PortSystem 1.0
     37name            expat
     38version        1.95.5
     39
     40categories      textproc 
     41maintainers    rooneg@electricjellyfish.net 
     42description    An XML 1.0 parser written in C 
     43
     44master_sites    ftp://eu.dl.sourceforge.net/pub/sourceforge/expat/ 
     45checksums      md5 6500d7d8c6c2c985cc0be257c9840cb4 
     46
     47
     48
     49contents        bin/xmlwf  \
     50                  include/expat.h \
     51                  lib/libexpat.0.4.0.dylib \ 
     52                  lib/libexpat.a  \
     53                  lib/libexpat.la  \
     54                  lib/libexpat.0.dylib  \
     55                  lib/libexpat.dylib 
     56
     57
    5358###########################################################################
    54 ]]></programlisting>
    55             </example>
    56             <para> The Portfile uses key value pairs to define how it is executed. Below is a list
    57                 of some of the simple terms </para>
    58             <variablelist>
    59                 <title> Portfile Keys 1</title>
    60                 <varlistentry>
    61                     <term> PortSystem </term>
    62                     <listitem>
    63                         <para> The version of darwinports that the port depends on. If a later
    64                             release introduces a function that isn't in version 1.0, you can specify
    65                             the version of darwinports that the Port requires. The PortSystem value
    66                             is 1.0 (at the moment there is no &quot;higher&quot; version of
    67                             darwinports. </para>
    68                     </listitem>
    69                 </varlistentry>
    70                 <varlistentry>
    71                     <term> categories </term>
    72                     <listitem>
    73                         <para> Each port must have at least one category and may have more than one.
    74                             The primary category should be listed first. (The primary category is
    75                             also the directory under which the port is stored). </para>
    76                     </listitem>
    77                 </varlistentry>
    78                 <varlistentry>
    79                     <term> maintainers </term>
    80                     <listitem>
    81                         <para> The email address of the maintainer (or maintainers) of the port. </para>
    82                     </listitem>
    83                 </varlistentry>
    84                 <varlistentry>
    85                     <term> name </term>
    86                     <term> version </term>
    87                     <listitem>
    88                         <para> name is the name of the port, usually also the name of the
    89                             distribution file (distfile). In the example port the name is expat. </para>
    90                     </listitem>
    91                 </varlistentry>
    92                 <varlistentry>
    93                     <term> version </term>
    94                     <listitem>
    95                         <para> version is the version of the distribution being ported. In the
    96                             example port the version is 1.95.5. </para>
    97                     </listitem>
    98                 </varlistentry>
    99                 <varlistentry>
    100                     <term> distfile </term>
    101                     <listitem>
    102                         <para> The name and version are combined with the extract_sufx (by
    103                             default .tar.gz) this is used by default as the &quot;distfile&quot;
    104                             name and used by darwinports to fetch the distribution file. If the name
    105                             of the file on the server is not the same as the
    106                             name-version.tar.gz you can override the default behavior by
    107                             defining the distfile name. </para>
    108                     </listitem>
    109                 </varlistentry>
    110                 <varlistentry>
    111                     <term> master_sites </term>
    112                     <listitem>
    113                         <para> A list of URLs from which to fetch the distfile. The URLs must be
    114                             separated by spaces and on one line (or with new lines escaped with
    115                             '\'). </para>
    116                     </listitem>
    117                 </varlistentry>
    118                 <varlistentry>
    119                     <term> checksums </term>
    120                     <listitem>
    121                         <para> The md5 checksum of the distfiles. If you have more than one file
    122                             being fetched you should specify the checksum for each in the form: </para>
    123                         <simplelist type="vert">
    124                             <member> foo md5 .... </member>
    125                             <member> bar md5 .... </member>
    126                         </simplelist>
    127                     </listitem>
    128                 </varlistentry>
    129                 <varlistentry>
    130                     <term> contents </term>
    131                     <listitem>
    132                         <para> A list of all the files installed by the port. The files should be on
    133                             a single line, newlines escaped with '\' or wrapped in '{}' as in the
    134                             example port. The contents list should not include the prefix into which
    135                             the port will be installed (for example /opt/local/) and must not
    136                             include directories that will contain things installed by other ports. </para>
    137                     </listitem>
    138                 </varlistentry>
    139                 <varlistentry>
    140                     <term> prefix </term>
    141                     <listitem>
    142                         <para> This variable is the filesystem location relative to which files are
    143                             installed by the ports system. The prefix is '/opt/local' by default but
    144                             Portfile authors should always refer to it by the variable name
    145                             ${prefix}. </para>
    146                     </listitem>
    147                 </varlistentry>
    148             </variablelist>
    149         </sect2>
    150         <sect2>
    151             <title> Example Portfile 2</title>
    152             <para> A second example Portfile will give you an idea of how to deal with slightly more
    153                 complicated ports. </para>
    154             <example>   
    155                 <title>Neon Portfile</title>
    156                 <programlisting><![CDATA[
     59]]>
     60                                </programlisting>
     61                        </example>
     62                        <para>
     63                                The Portfile uses key value pairs to define how it is executed. Below is a list of some of the simple terms. Line up each of the values with tabs in a &ldquo;table&rdquo; type of format.
     64                        </para>
     65                        <variablelist>
     66                                <title> Portfile Keys 1</title>
     67                                <varlistentry>
     68                                        <term>
     69                                                PortSystem
     70                                        </term>
     71                                        <listitem>
     72                                                <para>
     73                                                        The version of darwinports that the port depends on. If a later release introduces a function that isn't in version 1.0, you can specify the version of darwinports that the Port requires. The PortSystem value is 1.0 (at the moment there is no &quot;higher&quot; version of darwinports.
     74                                                </para>
     75                                        </listitem>
     76                                </varlistentry>
     77                                <varlistentry>
     78                                        <term>
     79                                                categories
     80                                        </term>
     81                                        <listitem>
     82                                                <para>
     83                                                        Each port must have at least one category and may have more than one. The primary category should be listed first. (The primary category is also the directory under which the port is stored).
     84                                                </para>
     85                                        </listitem>
     86                                </varlistentry>
     87                                <varlistentry>
     88                                        <term>
     89                                                maintainers
     90                                        </term>
     91                                        <listitem>
     92                                                <para>
     93                                                        The email address of the maintainer (or maintainers) of the port.
     94                                                </para>
     95                                        </listitem>
     96                                </varlistentry>
     97                                <varlistentry>
     98                                        <term>
     99                                                name
     100                                        </term>
     101                                        <term>
     102                                                version
     103                                        </term>
     104                                        <listitem>
     105                                                <para>
     106                                                        name is the name of the port, usually also the name of the distribution file (distfile). In the example port the name is expat.
     107                                                </para>
     108                                        </listitem>
     109                                </varlistentry>
     110                                <varlistentry>
     111                                        <term>
     112                                                version
     113                                        </term>
     114                                        <listitem>
     115                                                <para>
     116                                                        version is the version of the distribution being ported. In the example port the version is 1.95.5.
     117                                                </para>
     118                                        </listitem>
     119                                </varlistentry>
     120                                <varlistentry>
     121                                        <term>
     122                                                distfile
     123                                        </term>
     124                                        <listitem>
     125                                                <para>
     126                                                        The name and version are combined with the extract_sufx (by default .tar.gz) this is used by default as the &quot;distfile&quot; name and used by darwinports to fetch the distribution file. If the name of the file on the server is not the same as the name-version.tar.gz you can override the default behavior by defining the distfile name.
     127                                                </para>
     128                                        </listitem>
     129                                </varlistentry>
     130                                <varlistentry>
     131                                        <term>
     132                                                master_sites
     133                                        </term>
     134                                        <listitem>
     135                                                <para>
     136                                                        A list of URLs from which to fetch the distfile. The URLs must be separated by spaces and on one line (or with new lines escaped with '\').
     137                                                </para>
     138                                        </listitem>
     139                                </varlistentry>
     140                                <varlistentry>
     141                                        <term>
     142                                                checksums
     143                                        </term>
     144                                        <listitem>
     145                                                <para>
     146                                                        The md5 checksum of the distfiles. If you have more than one file being fetched you should specify the checksum for each in the form:
     147                                                </para>
     148                                                <simplelist type="vert">
     149                                                        <member>
     150                                                                foo md5 ....
     151                                                        </member>
     152                                                        <member>
     153                                                                bar md5 ....
     154                                                        </member>
     155                                                </simplelist>
     156                                        </listitem>
     157                                </varlistentry>
     158                                <varlistentry>
     159                                        <term>
     160                                                contents
     161                                        </term>
     162                                        <listitem>
     163                                                <para>
     164                                                        A list of all the files installed by the port. The files should be on a single line, newlines escaped with '\'. The contents list should not include the prefix into which the port will be installed (for example /opt/local/) and must not include directories that will contain things installed by other ports.
     165                                                </para>
     166                                        </listitem>
     167                                </varlistentry>
     168                                <varlistentry>
     169                                        <term>
     170                                                prefix
     171                                        </term>
     172                                        <listitem>
     173                                                <para>
     174                                                        This variable is the filesystem location relative to which files are installed by the ports system. The prefix is '/opt/local' by default but Portfile authors should always refer to it by the variable name ${prefix}.
     175                                                </para>
     176                                        </listitem>
     177                                </varlistentry>
     178                        </variablelist>
     179                        </sect2>
     180                        <sect2>
     181                                <title> Example Portfile 2</title>
     182                                <para>
     183                                        A second example Portfile will give you an idea of how to deal with slightly more complicated ports.
     184                                </para>
     185                                <example>
     186                                        <title>Neon Portfile</title>
     187                                        <programlisting><![CDATA[
    157188###########################neon Portfile####################################
    158 01> PortSystem 1.0
    159 02> name neon
    160 03> version 0.23.4
    161 04>
    162 05> categories www
    163 06> maintainers rooneg@electricjellyfish.net
    164 07> description An HTTP and WebDAV client library with a C interface
    165 08>
    166 09> master_sites http://www.webdav.org/neon/
    167 10> checksums md5 56b380a7352c68d425b1d3d3d610f994
    168 11>
    169 12> depends_lib lib:libexpat.0.4:expat
    170 13> configure.env LDFLAGS=-L$prefix/lib CPPFLAGS=-I$prefix/include
    171 14> configure.args --with-ssl \
    172 15> --with-force-ssl \
    173 16> --enable-xml \
    174 17> --enable-shared \
    175 18> --with-expat
    176 19>
    177 20>
    178 21> include contents
     189PortSystem 1.0
     190name            neon
     191version        0.23.4
     192
     193categories      www
     194maintainers    rooneg@electricjellyfish.net
     195description    An HTTP and WebDAV client library with a C interface
     196
     197master_sites    http://www.webdav.org/neon/
     198checksums      md5 56b380a7352c68d425b1d3d3d610f994
     199
     200depends_lib    lib:libexpat.0.4:expat
     201configure.env  LDFLAGS=-L$prefix/lib CPPFLAGS=-I$prefix/include
     202
     203configure.args  --with-ssl \
     204                  --with-force-ssl \
     205                  --enable-xml \
     206                  --enable-shared \
     207                  --with-expat 
     208
     209include        contents
    179210############################################################################
    180 ]]></programlisting>
    181             </example>
    182             <para> Many of the components of this port are the same as those in the first example.
    183                 This port is more complicated as it requires something else to be installed, needs
    184                 certain environmental variables to be set prior to configuring and the configure
    185                 script is being passed arguments. </para>
    186             <variablelist>
    187                 <title> Portfile Keys 2</title>
    188                 <varlistentry>
    189                     <term> depends_lib </term>
    190                     <listitem>
    191                         <para> This is probably the most common kind of dependency. The port depends
    192                             on libraries or binaries to be installed during configuration and to
    193                             run. depends_lib takes three terms, separated by colons. The first term
    194                             is 'bin' or 'lib'. This defines the search path the port system will
    195                             look for the dependency in. If bin is specified $PATH is searched for
    196                             the dependency, if lib is specified, the library path is searched
    197                             instead. The second term is a regular expression that is used to search
    198                             the path defined in the first term for the dependency. Usually the name
    199                             of the library is a good enough. The port system will append .dylib to
    200                             the regex so only dynamic libraries will be matched. The third term is
    201                             the name of the port that can provide the dependency. If the dependency
    202                             is not satisfied by something already installed on the system the port
    203                             listed here will installed before the port. </para>
    204                     </listitem>
    205                 </varlistentry>
    206                 <varlistentry>
    207                     <term> configure.env </term>
    208                     <listitem>
    209                         <para> You may have to set environment variables for the configure script to
    210                             set library paths, compiler settings or some other configuration
    211                             variable. </para>
    212                     </listitem>
    213                 </varlistentry>
    214                 <varlistentry>
    215                     <term> configure.args </term>
    216                     <listitem>
    217                         <para> If you need to specify additional configure arguments you should
    218                             place them on a single line. As with other settings, newlines may be
    219                             escaped to break up long lines. </para>
    220                         <para> By default the configure script is passed --prefix=${prefix} where
    221                             ${prefix} is replaced with the prefix darwinports is configured to
    222                             install into. </para>
    223                     </listitem>
    224                 </varlistentry>
    225                 <varlistentry>
    226                     <term> Include </term>
    227                     <listitem>
    228                         <para> In this Portfile there is not contents directive, the contents are
    229                             included from a separate file. This is the preferred method if the
    230                             contents list is more than a few items. </para>
    231                         <para> The contents file has precisely the same format as the contents
    232                             section of the first example Portfile. </para>
    233                     </listitem>
    234                 </varlistentry>
    235             </variablelist>
    236         </sect2>
    237     </sect1>
    238 
    239         <sect1>
    240         <title>Common Mistakes</title>
    241         <sect2>
    242             <title>Don't quote or wrap items in '{}'.</title>
    243             <para> Frequently people submit ports with the description or configure arguments
    244                 quoted, or wrapped in curly brackets. In general this is not correct. The exception
    245                 is contents lists, which have been specifically designed to handle the list being
    246                 wrapped in curly brackets because of the very large number of files some ports
    247                 install make escaping all the newlines extremely irritating. </para>
    248         </sect2>
    249     </sect1>
    250     <sect1>
    251         <title>How to test</title>
    252         <orderedlist>
    253             <listitem>
    254                 <para> Enable debugging and verbose messages from the darwinports engine. Edit
    255                     /etc/ports/ports.conf and set <userinput>debug yes </userinput>and
    256                         <userinput>verbose yes </userinput>. </para>
    257             </listitem>
    258             <listitem>
    259                 <para> Enable a local source repository and comment out the remote repository. Edit
    260                     /etc/ports/sources.conf and set <userinput>file:///usr/dports </userinput> (or
    261                     wherever your copy of the dport tree is). </para>
    262             </listitem>
    263             <listitem>
    264                 <para> From the local source repository root, create an index file. This will also
    265                     syntax check portfiles contained. </para>
    266                 <para>
    267                     <userinput>portindex</userinput>
    268                 </para>
    269             </listitem>
    270             <listitem>
    271                 <para> Sync the index </para>
    272                 <para>
    273                     <userinput>port sync</userinput>
    274                 </para>
    275             </listitem>
    276             <listitem>
    277                 <para> Install port </para>
    278                 <para>
    279                     <userinput>sudo port install foo</userinput>
    280                 </para>
    281             </listitem>
    282             <listitem>
    283                 <para> Uninstall the port </para>
    284                 <para>
    285                     <userinput>sudo port uninstall foo </userinput>
    286                 </para>
    287             </listitem>
    288             <listitem>
    289                 <para> Make sure the port builds, installs and uninstalls on a &quot;clean
    290                     machine&quot;. A clean machine should have a clean install of the OS, to avoid
    291                     missing dependencies. </para>
    292             </listitem>
    293             <listitem>
    294                 <para> Make sure the contents list is correct. Ensure all the files installed are
    295                     listed and directories are listed after their contents, so they are empty when
    296                     the port system attempts to remove them. </para>
    297             </listitem>
    298             <listitem>
    299                 <para> Clean the working source directory for a port. This will allow a clean
    300                     reinstall if an error was encountered earlier in the build process. </para>
    301                 <para>
    302                     <userinput>port clean foo</userinput>
    303                 </para>
    304             </listitem>
    305         </orderedlist>
    306     </sect1>
    307     <sect1>
    308         <title>Where to submit</title>
    309         <para> Email your submission to <email>darwinports@opendarwin.org</email> mailing <ulink url="http://www.opendarwin.org/mailman/listinfo/darwinports">list</ulink>. In general the Portfile should be inlined in the email,
    310             rather than as an attatchment. This allows people to view and give feedback on the
    311             Portfile more easily. If there is a large contents list and/or patchfiles these may be
    312             attatched to the email as a tarred and gzipped archive. </para>
    313     </sect1>
    314     <sect1>
    315         <title>Where can I ask for Advice?</title>
    316         <para> Either on the <email>darwinports@opendarwin.org</email> mailing list, or on the
    317             #opendarwin channel on irc.openprojects.net. Don't be afraid to ask questions! </para>
    318     </sect1>
    319 </chapter>
     211]]>                                     </programlisting>
     212                                </example>
     213                                <para>
     214                                        Many of the components of this port are the same as those in the first example. This port is more complicated as it requires something else to be installed, needs certain environmental variables to be set prior to configuring and the configure script is being passed arguments.
     215                                </para>
     216                                <variablelist>
     217                                        <title> Portfile Keys 2</title>
     218                                        <varlistentry>
     219                                                <term>
     220                                                        depends_lib
     221                                                </term>
     222                                                <listitem>
     223                                                        <para>
     224                                                                This is probably the most common kind of dependency. The port depends on libraries or binaries to be installed during configuration and to run. depends_lib takes three terms, separated by colons. The first term is 'bin' or 'lib'. This defines the search path the port system will look for the dependency in. If bin is specified $PATH is searched for the dependency, if lib is specified, the library path is searched instead. The second term is a regular expression that is used to search the path defined in the first term for the dependency. Usually the name of the library is a good enough. The port system will append .dylib to the regex so only dynamic libraries will be matched. The third term is the name of the port that can provide the dependency. If the dependency is not satisfied by something already installed on the system the port listed here will installed before the port.
     225                                                        </para>
     226                                                </listitem>
     227                                        </varlistentry>
     228                                        <varlistentry>
     229                                                <term>
     230                                                        configure.env
     231                                                </term>
     232                                                <listitem>
     233                                                        <para>
     234                                                                You may have to set environment variables for the configure script to set library paths, compiler settings or some other configuration variable.
     235                                                        </para>
     236                                                </listitem>
     237                                        </varlistentry>
     238                                        <varlistentry>
     239                                                <term>
     240                                                        configure.args
     241                                                </term>
     242                                                <listitem>
     243                                                        <para>
     244                                                                If you need to specify additional configure arguments you should place them on a single line. As with other settings, newlines may be escaped to break up long lines. Note the continuing lines are indented two spaces.
     245                                                        </para>
     246                                                        <para>
     247                                                                By default the configure script is passed --prefix=${prefix} where ${prefix} is replaced with the prefix darwinports is configured to install into.
     248                                                        </para>
     249                                                </listitem>
     250                                        </varlistentry>
     251                                        <varlistentry>
     252                                                <term>
     253                                                        Include
     254                                                </term>
     255                                                <listitem>
     256                                                        <para>
     257                                                                In this Portfile there is not contents directive, the contents are included from a separate file. This is the preferred method if the contents list is more than a few items.
     258                                                        </para>
     259                                                        <para>
     260                                                                The contents file has precisely the same format as the contents section of the first example Portfile.
     261                                                        </para>
     262                                                </listitem>
     263                                        </varlistentry>
     264                                </variablelist>
     265                                </sect2>
     266                                </sect1>
     267                                <sect1>
     268                                        <title>Common Mistakes</title>
     269                                        <sect2>
     270                                                <title>Don't quote or wrap items in '{}'.</title>
     271                                                <para>
     272                                                        Frequently people submit ports with the description or configure arguments quoted, or wrapped in curly brackets. In general this is not correct. The exception is contents lists, which have been specifically designed to handle the list being wrapped in curly brackets because of the very large number of files some ports install make escaping all the newlines extremely irritating.
     273                                                </para>
     274                                        </sect2>
     275                                </sect1>
     276                                <sect1>
     277                                        <title>How to test</title>
     278                                        <orderedlist>
     279                                                <listitem>
     280                                                        <para>
     281                                                                Enable debugging and verbose messages from the darwinports engine. Edit /etc/ports/ports.conf and set:<userinput>debug yes </userinput>and <userinput>verbose yes </userinput>.
     282                                                        </para>
     283                                                </listitem>
     284                                                <listitem>
     285                                                        <para>
     286                                                                Enable a local source repository and comment out the remote repository. Edit /etc/ports/sources.conf and set:<userinput>file:///usr/dports</userinput> (or wherever your copy of the dport tree is).
     287                                                        </para>
     288                                                </listitem>
     289                                                <listitem>
     290                                                        <para>
     291                                                                From the local source repository root, create an index file. This will also syntax check portfiles contained.
     292                                                        </para>
     293                                                        <para>
     294                                                                <userinput>
     295                                                                        portindex
     296                                                                </userinput>
     297                                                        </para>
     298                                                </listitem>
     299                                                <listitem>
     300                                                        <para>
     301                                                                Sync the index
     302                                                        </para>
     303                                                        <para>
     304                                                                <userinput>
     305                                                                        port sync
     306                                                                </userinput>
     307                                                        </para>
     308                                                </listitem>
     309                                                <listitem>
     310                                                        <para>
     311                                                                Install port
     312                                                        </para>
     313                                                        <para>
     314                                                                <userinput>
     315                                                                        sudo port install foo
     316                                                                </userinput>
     317                                                        </para>
     318                                                </listitem>
     319                                                <listitem>
     320                                                        <para>
     321                                                                Uninstall the port
     322                                                        </para>
     323                                                        <para>
     324                                                                <userinput>
     325                                                                        sudo port uninstall foo
     326                                                                </userinput>
     327                                                        </para>
     328                                                </listitem>
     329                                                <listitem>
     330                                                        <para>
     331                                                                Make sure the port builds, installs and uninstalls on a &quot;clean machine&quot;. A clean machine should have a clean install of the OS, to avoid missing dependencies.
     332                                                        </para>
     333                                                </listitem>
     334                                                <listitem>
     335                                                        <para>
     336                                                                Make sure the contents list is correct. Ensure all the files installed are listed and directories are listed after their contents, so they are empty when the port system attempts to remove them.
     337                                                        </para>
     338                                                </listitem>
     339                                                <listitem>
     340                                                        <para>
     341                                                                Clean the working source directory for a port. This will allow a clean reinstall if an error was encountered earlier in the build process.
     342                                                        </para>
     343                                                        <para>
     344                                                                <userinput>
     345                                                                        port clean foo
     346                                                                </userinput>
     347                                                        </para>
     348                                                </listitem>
     349                                        </orderedlist>
     350                                </sect1>
     351                                <sect1>
     352                                        <title>Where to submit</title>
     353                                        <para>
     354                                                Email your submission to <email>darwinports@opendarwin.org</email> mailing <ulink url="http://www.opendarwin.org/mailman/listinfo/darwinports">list</ulink>. In general the Portfile should be inlined in the email, rather than as an attatchment. This allows people to view and give feedback on the Portfile more easily. If there is a large contents list and/or patchfiles these may be attatched to the email as a tarred and gzipped archive.
     355                                        </para>
     356                                </sect1>
     357                                <sect1>
     358                                        <title>Where can I ask for Advice?</title>
     359                                        <para>Either on the <email>darwinports@opendarwin.org</email> mailing list, or on the #opendarwin channel on irc.openprojects.net. Don't be afraid to ask questions!
     360                                        </para>
     361                                </sect1>
     362                                </chapter>
Note: See TracChangeset for help on using the changeset viewer.