Changeset 1894 for trunk/doc


Ignore:
Timestamp:
Jan 27, 2003, 2:03:10 AM (16 years ago)
Author:
michaelm
Message:

updated quick.xml to reflect no more contents, long_description and homepage key additions

File:
1 edited

Legend:

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

    r1529 r1894  
    3333                                <title>Expat Portfile</title>
    3434                                <programlisting><![CDATA[
    35 ########################### expat Portfile ##################################
    36 PortSystem 1.0
    37 name            expat
    38 version         1.95.5
    39  
    40 categories      textproc 
    41 maintainers     rooneg@electricjellyfish.net 
    42 description     An XML 1.0 parser written in C 
    43  
    44 master_sites    ftp://eu.dl.sourceforge.net/pub/sourceforge/expat/ 
    45 checksums       md5 6500d7d8c6c2c985cc0be257c9840cb4 
    46  
    47  
    48  
    49 contents        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 
     35########################### libxslt Portfile ##################################
     36PortSystem      1.0
     37
     38name            libxslt
     39version         1.0.21
     40homepage        http://www.xmlsoft.org/
     41description     gnome xslt library and xsltproc
     42categories      textproc
     43platforms       darwin
     44maintainers     mike+libxslt@gene-hacker.net
     45master_sites    ftp://xmlsoft.org/ \
     46                  ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.0/
     47
     48checksums       md5 9cc0491e2584788748eb7069ea1d5277
     49depends_lib     lib:libxml2:libxml2
     50patchfiles      patch-aclocal.m4 patch-configure patch-ltmain.sh
     51
     52long_description Gnome library for applying XSL stylesheet transformations to \
     53xml files, comes with several useful binaries.
    5754
    5855###########################################################################
     
    8683                                </varlistentry>
    8784                                <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>
     85                                        <term> maintainers </term>
     86                                        <listitem>
     87                                                <para> The email address of the maintainer (or maintainers) of the port.  </para>
     88                                        </listitem>
     89                                </varlistentry>
     90                                <varlistentry>
     91                                        <term> name </term>
     92                                        <listitem>
     93                                                <para> name is the name of the port, usually also the name of the distribution file (distfile). In the example port the name is libxslt.  </para>
     94                                        </listitem>
     95                                </varlistentry>
     96                                <varlistentry>
     97                                        <term> version </term>
     98                                        <listitem>
     99                                                <para> version is the version of the distribution being ported. In the example port the version is 1.0.21.  </para>
     100                                        </listitem>
     101                                </varlistentry>
     102                                <varlistentry>
     103                                        <term> distfile </term>
     104                                        <listitem>
     105                                                <para> 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.  </para>
     106                                        </listitem>
     107                                </varlistentry>
     108                                <varlistentry>
     109                                        <term> master_sites </term>
     110                                        <listitem>
     111                                                <para> 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 '\').  </para>
     112                                        </listitem>
     113                                </varlistentry>
     114                                <varlistentry>
     115                                        <term> homepage </term>
     116                                        <listitem>
     117                                                <para> The URL for the software's homepage.</para>
     118                                        </listitem>
     119                                </varlistentry>
     120                                <varlistentry>
     121                                        <term> checksums </term>
     122                                        <listitem>
     123                                                <para> 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: </para>
     124                                                <simplelist type="vert">
     125                                                        <member> foo md5 ....  </member>
     126                                                        <member> bar md5 ....  </member>
    155127                                                </simplelist>
    156128                                        </listitem>
    157129                                </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>
     130                                        <varlistentry>
     131                                                <term> depends_lib </term>
     132                                                <listitem>
     133                                                        <para> 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.  </para>
     134                                                </listitem>
     135                                        </varlistentry>
     136                                <varlistentry>
     137                                        <term> patchfiles </term>
     138                                        <listitem>
     139                                                <para> A list of patches to be applied to the port (needed for the software to compile/run or install correctly). Patches are usually provided in a files directory in the same directory as the Portfile. </para>
     140                                        </listitem>
     141                                </varlistentry>
     142                                        <term> long_description </term>
     143                                        <listitem>
     144                                                <para> Longer description of the software and the porting/packaging changes needed, if any. Long lines should be split with escaped newlines.</para>
     145                                        </listitem>
     146                                </varlistentry>
     147                                <varlistentry>
     148                                <varlistentry>
     149                                        <term> prefix </term>
     150                                        <listitem>
     151                                                <para> 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}.  </para>
    176152                                        </listitem>
    177153                                </varlistentry>
     
    207183                  --with-expat 
    208184
    209 include         contents
    210185############################################################################
    211186]]>                                     </programlisting>
     
    217192                                        <title> Portfile Keys 2</title>
    218193                                        <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>
     194                                                <term> configure.env </term>
     195                                                <listitem>
     196                                                        <para> You may have to set environment variables for the configure script to set library paths, compiler settings or some other configuration variable.  </para>
    226197                                                </listitem>
    227198                                        </varlistentry>
    228199                                        <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=&dollar;&lcub;prefix&rcub; where ${prefix} is replaced with the prefix darwinports is configured to install into.
    248                                                         </para>
     200                                                <term> configure.args </term>
     201                                                <listitem>
     202                                                        <para> 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.  </para>
     203                                                        <para> By default the configure script is passed --prefix=&dollar;&lcub;prefix&rcub; where ${prefix} is replaced with the prefix darwinports is configured to install into.  </para>
    249204                                                        <tip>
    250                                                                 <para>
    251                                                                         In general you should quote variables like &lcub;prefix&rcub; in case the path has a space in it.
    252                                                                 </para>
     205                                                                <para> In general you should quote variables like &lcub;prefix&rcub; in case the path has a space in it.  </para>
    253206                                                        </tip>
    254                                                 </listitem>
    255                                         </varlistentry>
    256                                         <varlistentry>
    257                                                 <term>
    258                                                         Include
    259                                                 </term>
    260                                                 <listitem>
    261                                                         <para>
    262                                                                 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.
    263                                                         </para>
    264                                                         <para>
    265                                                                 The contents file has precisely the same format as the contents section of the first example Portfile.
    266                                                         </para>
    267207                                                </listitem>
    268208                                        </varlistentry>
     
    274214                                        <sect2>
    275215                                                <title>Don't quote or wrap items in '{}'.</title>
    276                                                 <para>
    277                                                         Frequently people submit ports with the description or configure arguments quoted, or wrapped in curly brackets. In general this is not correct.
    278                                                 </para>
    279                                         </sect2>
     216                                                <para> Frequently people submit ports with the description or configure arguments quoted, or wrapped in curly brackets. In general this is not correct.  </para> </sect2>
    280217                                </sect1>
    281218                                <sect1>
     
    283220                                        <orderedlist>
    284221                                                <listitem>
    285                                                         <para>
    286                                                                 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>.
    287                                                         </para>
    288                                                 </listitem>
    289                                                 <listitem>
    290                                                         <para>
    291                                                                 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).
    292                                                         </para>
    293                                                 </listitem>
    294                                                 <listitem>
    295                                                         <para>
    296                                                                 From the local source repository root, create an index file. This will also syntax check portfiles contained.
    297                                                         </para>
    298                                                         <para>
    299                                                                 <userinput>
    300                                                                         portindex
    301                                                                 </userinput>
    302                                                         </para>
    303                                                 </listitem>
    304                                                 <listitem>
    305                                                         <para>
    306                                                                 Sync the index
    307                                                         </para>
    308                                                         <para>
    309                                                                 <userinput>
    310                                                                         port sync
    311                                                                 </userinput>
    312                                                         </para>
    313                                                 </listitem>
    314                                                 <listitem>
    315                                                         <para>
    316                                                                 Install port
    317                                                         </para>
    318                                                         <para>
    319                                                                 <userinput>
    320                                                                         sudo port install foo
    321                                                                 </userinput>
    322                                                         </para>
    323                                                 </listitem>
    324                                                 <listitem>
    325                                                         <para>
    326                                                                 Uninstall the port
    327                                                         </para>
    328                                                         <para>
    329                                                                 <userinput>
    330                                                                         sudo port uninstall foo
    331                                                                 </userinput>
    332                                                         </para>
    333                                                 </listitem>
    334                                                 <listitem>
    335                                                         <para>
    336                                                                 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.
    337                                                         </para>
    338                                                 </listitem>
    339                                                 <listitem>
    340                                                         <para>
    341                                                                 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.
    342                                                         </para>
    343                                                 </listitem>
    344                                                 <listitem>
    345                                                         <para>
    346                                                                 Clean the working source directory for a port. This will allow a clean reinstall if an error was encountered earlier in the build process.
    347                                                         </para>
    348                                                         <para>
    349                                                                 <userinput>
    350                                                                         port clean foo
    351                                                                 </userinput>
    352                                                         </para>
     222                                                        <para> 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>.  </para>
     223                                                </listitem>
     224                                                <listitem>
     225                                                        <para> 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).  </para>
     226                                                </listitem>
     227                                                <listitem>
     228                                                        <para> From the local source repository root, create an index file. This will also syntax check portfiles contained.  </para>
     229                                                        <para> <userinput> portindex </userinput> </para>
     230                                                </listitem>
     231                                                <listitem>
     232                                                        <para> Sync the index </para>
     233                                                        <para> <userinput> port sync </userinput> </para>
     234                                                </listitem>
     235                                                <listitem>
     236                                                        <para> Install port </para>
     237                                                        <para> <userinput> sudo port install foo </userinput> </para>
     238                                                </listitem>
     239                                                <listitem>
     240                                                        <para> Uninstall the port </para>
     241                                                        <para> <userinput> sudo port uninstall foo </userinput> </para>
     242                                                </listitem>
     243                                                <listitem>
     244                                                        <para> 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.  </para>
     245                                                </listitem>
     246                                                <listitem>
     247                                                        <para> Ensure the Port installs into the destroot and does not install anything onto the system directly, most software that uses autoconf should behave correctly automatically as darwinports sets DESTDIR by default. If files are directly installed to the system they will not be registered and packaging will fail.     </para>
     248                                                </listitem>
     249                                                <listitem>
     250                                                        <para> Clean the working source directory for a port. This will allow a clean reinstall if an error was encountered earlier in the build process.  </para>
     251                                                        <para> <userinput> port clean foo </userinput> </para>
    353252                                                </listitem>
    354253                                        </orderedlist>
     
    356255                                <sect1>
    357256                                        <title>Where to submit</title>
    358                                         <para>
    359                                                 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.
    360                                         </para>
     257                                        <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, 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.  </para>
    361258                                </sect1>
    362259                                <sect1>
    363260                                        <title>Where can I ask for Advice?</title>
    364                                         <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!
    365                                         </para>
     261                                        <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!  </para>
    366262                                </sect1>
    367263                                </chapter>
Note: See TracChangeset for help on using the changeset viewer.