Changeset 2627 for trunk/doc


Ignore:
Timestamp:
May 16, 2003, 10:43:24 AM (17 years ago)
Author:
michaelm
Message:

incorporating Eric Albert's suggestions

Location:
trunk/doc/guide/xml
Files:
9 edited

Legend:

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

    r2614 r2627  
    44
    55<chapter id='details'>
    6     <title>Portfile Details</title>
     6    <title>Portfile details</title>
    77    <para> This Chapter describes in detail how each part of a portfile is works and is used. </para>
    88    <sect1>
    9         <title>General Syntax</title>
     9        <title>General dyntax</title>
    1010        <para>A Portfile is a TCL script, so the syntax used must be valid TCL or the Portfile will not work. The basic syntax of the Portfile has been designed so most tasks are performed using key value(s) combinations. Many people don't realise it is TCL until they want to do something more advanced and realise all that power is there.</para>
    1111                <para>All key value pairs in a Portfile are single lines so line breaks must be escaped with a back solidus '\'. </para>
     
    2222                </sect2>
    2323                <sect2>
    24                         <title>Required Keys</title>
     24                        <title>Required keys</title>
    2525                        <para>There is a small set of required key/value pairs without which a Portfile cannot be correct.</para>
    2626                        <para>The required keys are
     
    4545        </sect1>
    4646        <sect1>
    47                 <title>Useful Preset Variables</title>
     47                <title>Useful preset variables</title>
    4848                <para></para>
    4949                <variablelist>
     
    5858                                <term>libpath</term>
    5959                                <listitem>
    60                                         <para>Path to the Darwinports TCL libraries. Read only.</para>
     60                                        <para>Path to the DarwinPorts TCL libraries. Read only.</para>
    6161                                </listitem>
    6262                        </varlistentry>
     
    116116
    117117        <sect1>
    118                 <title>Initialization Phase</title>
     118                <title>Initialization phase</title>
    119119                <para>The first part of a Portfile deals with initialisation. Most of the keys (or options) in the initialisation phase  are required for all Portfiles.
    120120                </para>
     
    123123                                <term>PortSystem</term>
    124124                                <listitem>
    125                                         <para>Determines which version of the portsystem the Portfile is compatible with. Darwinports supports versioning of the PortSystem so if new, backwards incompatible changes are introduced older Portfiles can continue to use the older version of the system. The PortSystem line wraps the loading of TCL libraries appropriate for that version of Darwinports. If you don't load the libraries, nothing else in the Portfile will work. Thus, the PortSystem should be the top line in the Portfile.</para>
    126                                         <para>Currently Darwinports only has version 1.0 so you should put: <userinput>PortSystem 1.0</userinput> in your Portfile.
     125                                        <para>Determines which version of the portsystem the Portfile is compatible with. DarwinPorts supports versioning of the PortSystem so if new, backwards incompatible changes are introduced older Portfiles can continue to use the older version of the system. The PortSystem line wraps the loading of TCL libraries appropriate for that version of DarwinPorts. If you don't load the libraries, nothing else in the Portfile will work. Thus, the PortSystem should be the top line in the Portfile.</para>
     126                                        <para>Currently DarwinPorts only has version 1.0 so you should put: <userinput>PortSystem 1.0</userinput> in your Portfile.
    127127                                        </para>
    128128                                </listitem>
     
    229229        </sect1>
    230230        <sect1>
    231                 <title>Fetch Phase</title>
     231                <title>Fetch phase</title>
    232232                <para></para>
    233233                <variablelist> 
     
    260260        </sect1>
    261261        <sect1>
    262                 <title>Integrity Checking Phase</title>
     262                <title>Integrity checking phase</title>
    263263                <para>Each file downloaded is integrity checked using a checksum. This is used to help prevent trojaned sources being downloaded. If you do not include the checksums line, the file will be downloaded and the checksum reported as a conenience to the Portfile author.</para>
    264264                <variablelist>
     
    280280        </sect1>
    281281        <sect1>
    282                 <title>Extract Phase</title>
     282                <title>Extract phase</title>
    283283                <para></para>
    284284                <variablelist>
     
    330330        </sect1>
    331331        <sect1>
    332                 <title>Patch Phase</title>
     332                <title>Patch phase</title>
    333333                <para></para>
    334334                        <variablelist>
     
    345345        </sect1>
    346346        <sect1>
    347                 <title>Configuration Phase</title>
     347                <title>Configuration phase</title>
    348348                <para></para>
    349349                       
    350350                        <sect2>
    351                                 <title> Automake and Autoconf</title>                                           
     351                                <title> Automake and autoconf</title>                                           
    352352                                        <variablelist>
    353353                                                <varlistentry id='use_automake'>
     
    459459        </sect1>
    460460        <sect1>
    461                 <title>Build Phase</title>
     461                <title>Build phase</title>
    462462                <para></para>
    463463               
     
    512512        </sect1>
    513513        <sect1>
    514                 <title>Install Phase</title>
     514                <title>Install phase</title>
    515515               
    516516                <variablelist>
     
    583583                </sect2>
    584584                <sect2>
    585                         <title>Dependency Tests</title>
     585                        <title>Dependency tests</title>
    586586                        <para></para>
    587587                        <variablelist>
     
    620620    </sect1>
    621621        <sect1>
    622                 <title>TCL Primitives</title>
     622                <title>TCL primitives</title>
    623623                        <para></para>
    624624                <sect2>
     
    639639                <para></para>
    640640                <sect2>
    641                         <title>Pre and Post Phase Steps</title>
     641                        <title>Pre and post phase steps</title>
    642642                        <variablelist>
    643643                                <varlistentry>
     
    658658                </sect2>
    659659                <sect2>
    660                         <title>Overriding a Phase</title>
     660                        <title>Overriding a phase</title>
    661661                        <para>
    662662                        </para>
  • trunk/doc/guide/xml/guide.xml

    r2614 r2627  
    33                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
    44<book xmlns:xi="http://www.w3.org/2001/XInclude">
    5 <title>Darwinports User Guide</title>
     5<bookinfo>
     6<title>DarwinPorts User Guide</title>
     7<author>
     8  <honorific>Dr</honorific>
     9  <firstname>Michael</firstname>
     10  <surname>Maibaum</surname>
     11  <othername role='mi'>A</othername>
     12  <email><link mailto='michaelm@opendarwin.org'>mike@opendarwin.org</link></email>
     13</author>
     14</bookinfo>
    615<preface>
    7         <title>About this Guide</title>
    8         <para>This guide shows you how to use the Darwinports system and develop new Darwinports.</para>
     16        <title>About this guide</title>
     17        <para>This guide shows you how to use the DarwinPorts system and develop new DarwinPorts.</para>
     18        <para>The Guide is still at an early draft stage, if you have any comments, corrections or (even bettter) contributions, please contact me by <email><link mailto='michaelm@opendarwin.org'>email</link></email>.
     19        </para>
    920</preface>
    1021
    11 <xi:include  href="quick.xml" />
     22<xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="user.xml" />
     23<xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="quick.xml" />
    1224<xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="details.xml" />
    1325<xi:include  xmlns:xi="http://www.w3.org/2001/XInclude"  href="submission.xml" />
  • trunk/doc/guide/xml/quick.xml

    r2614 r2627  
    1616                </keywordset>
    1717        </chapterinfo>
    18         <title>Quick Start</title>
     18        <title>Quick start</title>
    1919        <sect1>
    2020                <title>Introduction to a Portfile</title>
     
    2929                </para>
    3030                <sect2>
    31                         <title> Example Portfile 1</title>
     31                        <title> Example Portfile: expat</title>
    3232                        <example>
    3333                                <title>Expat Portfile</title>
    3434                                <programlisting><![CDATA[
    3535########################### libxslt Portfile ##################################
    36 # $Id: quick.xml,v 1.9 2003/05/14 16:05:51 michaelm Exp $
     36# $Id: quick.xml,v 1.10 2003/05/16 10:43:20 michaelm Exp $
    3737
    3838PortSystem      1.0
     
    6363                        </para>
    6464                        <variablelist>
    65                                 <title> Portfile Keys 1</title>
     65                                <title> Portfile keys 1</title>
    6666                                <varlistentry>
    6767                                        <term>
     
    157157                        </sect2>
    158158                        <sect2>
    159                                 <title> Example Portfile 2</title>
     159                                <title> Example Portfile: neon</title>
    160160                                <para>
    161161                                        A second example Portfile will give you an idea of how to deal with slightly more complicated ports.
     
    165165                                        <programlisting><![CDATA[
    166166###########################neon Portfile####################################
    167 # $Id: quick.xml,v 1.9 2003/05/14 16:05:51 michaelm Exp $
     167# $Id: quick.xml,v 1.10 2003/05/16 10:43:20 michaelm Exp $
    168168
    169169PortSystem 1.0
     
    194194                                </para>
    195195                                <variablelist>
    196                                         <title> Portfile Keys 2</title>
     196                                        <title> Portfile keys 2</title>
    197197                                        <varlistentry>
    198198                                                <term> configure.env </term>
     
    215215                                </sect1>
    216216                                <sect1>
    217                                         <title>Common Mistakes</title>
     217                                        <title>Common mistakes</title>
    218218                                        <sect2>
    219219                                                <title>Don't quote or wrap items in '{}'.</title>
     
    254254                                </sect1>
    255255                                <sect1>
    256                                         <title>Where can I ask for Advice?</title>
     256                                        <title>Where can I ask for advice?</title>
    257257                                        <para>Either on the <email>darwinports@opendarwin.org</email> mailing list, or on the #opendarwin channel on irc.freenode.net. Don't be afraid to ask questions! You should also look at the later sections of the <link linkend="details">guide</link>, the Portfile <ulink url="http:http://www.opendarwin.org/projects/darwinports/en/portfileHOWTO.php">HOWTO</ulink> and the portfile(7) and portstyle(7) manpages for more information. </para>
    258258                                </sect1>
    259259                                <sect1>
    260260                                        <title>How do I submit my Ports</title>
    261                                         <para>See the <link linkend="submission">Submission Chapter</link> for all the infromation on how to submit a port properly.
     261                                        <para>See the <link linkend="submission">submission chapter</link> for all the infromation on how to submit a port properly.
    262262                                        </para>
    263263                                </sect1>
  • trunk/doc/guide/xml/special.xml

    r1102 r2627  
    44
    55<chapter>
    6     <title>Special Considerations</title>
     6    <title>Special considerations</title>
    77    <sect1>
    8         <title>OS X Applications</title>
     8        <title>Mac OS X applications</title>
    99        <para></para>
    1010                <sect2>
     
    1414        </sect1>
    1515        <sect1>
    16                 <title>XFree86 Servers</title>
     16                <title>XFree86 servers</title>
    1717        <para></para>
    1818                <sect2>
     
    2222        </sect1>
    2323        <sect1>
    24                 <title>Perl Modules and Other Language Libraries and Plug-ins</title>
     24                <title>Perl modules and other language libraries and plug-ins</title>
    2525        <para></para>
    2626                <sect2>
  • trunk/doc/guide/xml/style.xml

    r2614 r2627  
    33                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
    44<chapter>
    5         <title>Style Guide</title>
     5        <title>Style guide</title>
    66        <sect1>
    77                <title>Overview</title>
     
    1919                <title>Specifics</title>
    2020                <sect2>
    21                         <title># $Id: style.xml,v 1.5 2003/05/14 16:05:52 michaelm Exp $</title>
     21                        <title>CVS ID tags</title>
    2222                        <para>On the first line of the Portfile you should put a cvs ID tag. This tag will be expanded by cvs when the Portfile is committed and allows people to see at a glance details like who was the last person to commit to a port and when the last commit was performed.
    2323                        </para>
    2424                </sect2>
    2525                <sect2>
    26                         <title>Portsystem</title>
     26                        <title>PortSystem</title>
    2727                        <para>
    2828                                At the top of the port file is the requirement statement. There is a single space between the "PortSystem" statement and the version number.
     
    4242                </sect2>
    4343                <sect2>
    44                         <title>Items Across Multipl Lines</title>
     44                        <title>Items across multiple lines</title>
    4545                        <para>
    4646                                When items require multiple lines, they can be separated from the previous and next items with a blank line. Indent the additional lines to the same column that the right side begins on in the first line. If a single statement needs to span multiple lines, use a 2 space indentation from the first line for all additional lines.
     
    4848                </sect2>
    4949                <sect2>
    50                         <title>Braces or Curly Brackets "{}"</title>
     50                        <title>Braces or curly brackets "{}"</title>
    5151                        <para>
    5252                                the braces may appear on the first and last lines rather than on their own lines. This is done because the right side of the port file is already indented, and to make port file read like a table. Use a single space after the brace. Indent additional lines to this same column.
     
    6060                </sect2>
    6161                <sect2>
    62                         <title>Patch Files</title>
     62                        <title>Patch files</title>
    6363                        <para>
    6464                                Patch files reside in the files/ directory in the port's base directory. There should be one patch file for every file that needs to be patched. It is perfectly reasonable to use provided patches that affect multiple files, but do not create new patches that do so. Their names should begin with "patch-". The rest of the name should come from the name of the file that they apply to. In many cases just the base name of the file being patched is enough. For files such as "Makefile" this may not be the case. In this case, use enough components of the file's path to uniquely distinguish the file. Separate the components with '-' characters. The patch should apply with "patch -p0" from the working source directory of the port.
  • trunk/doc/guide/xml/submission.xml

    r2614 r2627  
    1616                </keywordset>
    1717        </chapterinfo>
    18         <title>DarwinPorts Submissions</title>
     18        <title>DarwinPorts submissions</title>
    1919        <sect1>
    2020                <title>Submitting a Port</title>
    2121                <para>Using a standardised approach to submitting the Portfiles and associated patches scripts, etc allows us to keep track of port submissions, process them efficiently and get them submitted as quickly as possible to our dports CVS tree. The following sections will describe the standard port submission procedures. </para>
    2222                <sect2>
    23                         <title>Where to Submit</title>
    24                         <para> New ports should be submitted via the Darwinports <ulink url="http://www.opendarwin.org/bugzilla/">bugzilla tool</ulink>. Your submission will be automatically emailled to the members of the <ulink url="http://www.opendarwin.org/mailman/listinfo/darwinports-bugs/">darwinports-bugs</ulink> mailing list. If you are uncertain about any aspect of your port, you may also want to email it with your questions and the bug number to 
     23                        <title>Where to submit</title>
     24                        <para> New ports should be submitted via the DarwinPorts <ulink url="http://www.opendarwin.org/bugzilla/">bugzilla tool</ulink>. Your submission will be automatically emailled to the members of the <ulink url="http://www.opendarwin.org/mailman/listinfo/darwinports-bugs/">darwinports-bugs</ulink> mailing list. If you are uncertain about any aspect of your port, you may also want to email it with your questions and the bug number to 
    2525                        <ulink url="mailto:darwinports@opendarwin.org">DarwinPorts</ulink> mailing list.</para>
    2626                        <para>If you are submitting a modification to an existing port, please assign the port to the current maintainer in your bugzilla submission, so that the automatic email is directed to the maintainer, who will be best suited to deal with your submission.</para>
    2727                </sect2>
    2828                <sect2>
    29                         <title>Using Bugzilla to Submit a port</title>
     29                        <title>Using bugzilla to submit a Port</title>
    3030                        <para>The following section describes in some more detail how to use Bugzilla to submit your port.</para>
    3131                        <sect3>
    32                                 <title>Submission Parameters</title>
     32                                <title>Submission parameters</title>
    3333                               
    3434                                <variablelist>
     
    3838                                                </term>
    3939                                                <listitem>
    40                                                         <para>Make sure you select the Darwinports project.
     40                                                        <para>Make sure you select the DarwinPorts project.
    4141                                                        </para>
    4242                                                </listitem>
     
    152152                        </sect3>
    153153                        <sect3>
    154                                 <title>Final Comments on Port Submission</title>
     154                                <title>Final comments on Port submission</title>
    155155                                <para>The following general points should also be borne in mind when submitting to bugzilla:
    156156                                        <simplelist type="vert">
  • trunk/doc/guide/xml/testing.xml

    r1102 r2627  
    44
    55<chapter>
    6     <title>Testing and Troubleshooting</title>
     6    <title>Testing and troubleshooting</title>
    77    <sect1>
    88        <title>Testing a Port</title>
     
    2929        <para></para>
    3030                <sect2>
    31                         <title>Uninstall Failures</title>
     31                        <title>Uninstall failures</title>
    3232                        <para></para>
    3333                </sect2>
  • trunk/doc/guide/xml/user.xml

    r2625 r2627  
    2323       
    2424        <sect1>
    25                 <title>About this Chapter</title>
     25                <title>About this chapter</title>
    2626                 
    27                 <para>This document will provide a short guide to the basics of the DarwinPorts system. The first section will provide a short description of the goals of the project and a brief comparison with other systems. Subsequent sections will describe how to get, install and use DarwinPorts on your own machines.
     27                <para>This document provides a short guide to the basics of the DarwinPorts system. The first section provides a short description of the goals of the project and a brief comparison with other systems. Subsequent sections describe how to get, install, and use DarwinPorts on your own machines.
    2828                </para>
    2929               
     
    3434                <title>About DarwinPorts</title>
    3535               
    36                 <para>The aim of the DarwinPorts project is to develop a second generation system for the building, installation and management of third party software. DarwinPorts is mainly developed on Mac OS X, however by design it is quite portable and is intended to work on other unix-like systems, especially *BSD and hopefully linux based systems. 
    37                 </para>
    38                
    39                 <para>DarwinPorts is probably best described by comparison:  It's sort of like the <ulink url='http://www.freebsd.org/ports'>FreeBSD ports collection</ulink> or <ulink url='http://fink.sf.org/'>fink</ulink> in that it automates the process of building 3rd party software for Mac OS X (and other operating systems).  It also tracks all dependency information for a given piece of software. In other words, it knows what it needs to build and install and in what order for the piece of software you want to work properly. Darwinports knows how to make it build and install it to a specific location, meaning that software installed via DarwinPorts doesn't simply scatter itself all over the system or require user knowledge of what to install in what order.
    40                 </para>
    41                
    42                 <para>FreeBSD Ports is a large collection of software ported to run on FreeBSD, the ports collection is also used on the other 'Free' BSDs. FreeBSD Ports is based on a large tree of ports where each piece of software has a directory withing a category (like mail or graphics). That directory contains the information needed to build the piece of software. DarwinPorts also uses a directory structure like this, although unlike FreeBSD ports the intention is to not require a complete copy of the 'Ports Tree' on every users machine.  FreeBSD ports is essentially implemented as some very impressive but hairy BSD make(1)'s macros and can be  opaque and non-extensible from the perspective of someone looking to extend or re-factor parts of the system.  Given that Makefiles aren't the easiest thing to parse, or for non-developers to understand, it is also harder to "mine" the FreeBSD ports collection for data to use for other purposes, such as generating documentation indexes or arbitrary front-ends for creating or managing ports.
     36                <para>The aim of the DarwinPorts project is to develop a second-generation system for the building, installation and management of third party software. DarwinPorts is mainly developed on Mac OS X, however by design it is quite portable and is intended to work on other UNIX-like systems, especially *BSD and hopefully Linux-based systems. 
     37                </para>
     38               
     39                <para>DarwinPorts is probably best described by comparison:  It's sort of like the <ulink url='http://www.freebsd.org/ports'>FreeBSD ports collection</ulink> or <ulink url='http://fink.sf.org/'>Fink</ulink> in that it automates the process of building third party software for Mac OS X and other operating systems.  DarwinPorts also tracks all dependency information for a given piece of software. In other words, it knows what it needs to build and install and in what order for the piece of software you want to work properly. DarwinPorts knows how to make, build and install the software to a specific location, meaning that software installed via DarwinPorts doesn't simply scatter itself all over the system or require user knowledge of dependencies in what order.
     40                </para>
     41               
     42                <para>The FreeBSD Ports Collection is a large set of software packages ported to FreeBSD. The ports collection is also used on the other "free" BSDs. The FreeBSD Ports Collection is based on a large tree of ports where each software has a directory within a category (like mail or graphics). That directory contains the information needed to build the piece of software. DarwinPorts also uses a directory structure like this, although unlike FreeBSD ports the intention is to avoid requiring a complete copy of the 'Ports Tree' on every user's machine.  The FreeBSD Ports Collection is essentially implemented as some very impressive but hairy BSD make(1)'s macros and can be  opaque and non-extensible from the perspective of someone looking to extend or refactor parts of the system.  Given that makefiles aren't the easiest thing to parse or for non-developers to understand, it is also harder to "mine" the FreeBSD ports collection for data to use for other purposes such as generating documentation indexes or arbitrary front-ends for creating or managing ports.
    4343                </para>
    4444
     
    4646                </para>
    4747               
    48                 <para>Even discounting some of the limitations of FreeBSD ports described above, the "science" of creating automated build systems is rather more complex than it looks at first glance and there's always room for fresh approaches to the problem, which is what we set out to do with DarwinPorts. There are certainly other systems, some of which have already been mentioned, which have made their own attempts at solving this problem and there will likely be many more such systems in the future since trying to find a single solution which pleases everyone is rather like trying to find a single programming language which pleases everyone - it's more or less impossible.
    49                 </para>
    50                
    51                 <para>DarwinPorts has been written in Tcl with some components having been written in C. Tcl was chosen to allow DarwinPorts to be readily embeded in other applications (e.g. a Cocoa GUI) and to allow flexible, but easy to read Portfiles.
    52                 </para>
    53                
    54                 <para>Even though DarwinPorts is written in Tcl, a user also does not need to know Tcl in order to use the system or even to add new ports.  Port description files, though they are actually full Tcl programs in their own right, are designed to look like nothing more than a list of key/value pairs.
     48                <para>Even discounting some of the limitations of The FreeBSD Ports Collection described above, creating automated build systems is rather more complex than it looks at first glance and there's always room for fresh approaches to the problem.  Which is what we have set out to do with DarwinPorts. There are certainly other systems, some of which have already been mentioned, which have made their own attempts at solving this problem. There will likely be many more such systems in the future since trying to find a single solution which pleases everyone is rather like trying to find a single programming language which pleases everyone - it's more or less impossible.
     49                </para>
     50               
     51                <para>DarwinPorts is mostly written in Tcl, with some components written in C. Tcl was chosen to allow DarwinPorts to be readily embedded in other applications (e.g. a Cocoa GUI) and to allow flexible, but easy to read Portfiles.
     52                </para>
     53               
     54                <para>Even though DarwinPorts is written in Tcl, users do not need to know Tcl in order to use the system or even to add new ports.  Port description files, though they are actually full Tcl programs in their own right, are designed to look like a simple list of key/value pairs.
    5555                </para>
    5656        </sect1>
     
    5858       
    5959        <sect1 id='setup'>
    60                 <title>Installing Darwinports</title>
     60                <title>Installing DarwinPorts</title>
    6161               
    6262                <sect2 id='prerequisites'>
     
    7474                        <title>Obtaining DarwinPorts</title>   
    7575                       
    76                         <para>Currently the main way to get DarwinPorts is by using the Concurrent Versioning System (cvs). CVS is installed with the Developers Tools on Mac OS X. To download DarwinPorts using cvs you should use the following Terminal commands. At this time you must keep the darwinports directoy that is downloaded on your machine, even after installation as it also contains all the port description files (Portfiles). In the future these will be automatically downloaded as they are needed so you won't need to keep the directory. Choose a location for darwinports where you won't want/need to move it. For the rest of the document I will assume the user name is 'mike' and the darwinports infrastructure is going to be downloaded to a directory (folder) called darwinports in your home directory (i.e. /Users/mike/darwinports/) you should replace the username with your own username and edit the commands I give so they work correctly on your installation. <programlisting><![CDATA[
     76                        <para>Currently the main way to get DarwinPorts is by using the Concurrent Versioning System (cvs). CVS is installed with the Developers Tools on Mac OS X. To download DarwinPorts using cvs you should use the following Terminal commands. At this time you must keep the darwinports directoy that is downloaded on your machine, even after installation as it also contains all the port description files (Portfiles). In the future these will be automatically downloaded as they are needed so you won't need to keep the directory. Choose a location for DarwinPorts where you won't want/need to move it. For the rest of the document I will assume the user name is 'mike' and the DarwinPorts infrastructure is going to be downloaded to a directory (folder) called darwinports in your home directory (i.e. /Users/mike/darwinports/) you should replace the username with your own username and edit the commands I give so they work correctly on your installation. <programlisting><![CDATA[
    7777 
    7878% cd ~/
     
    123123               
    124124                <sect2 id='port'>
    125                         <title>port Command</title>
     125                        <title>The port command</title>
    126126                       
    127127                        <para>Using DarwinPorts is very straightforward, most of the time all you need to do is execute a single command to install a port. For example, if you want to install the text editor vile, you'd simply execute the command <userinput>sudo port install vile</userinput>. That will fetch, build and install vim and anything else vim needs to work. All of the examples below use the vim port as an example, you should use whatever port you actually want to install.
     
    137137                        </para>
    138138                       
    139                         <para>Once the port has been installed, you may want to delete all the intermediate files that Darwinports has created while building the port, to do this you should enter: <userinput>port clean vile</userinput>.
     139                        <para>Once the port has been installed, you may want to delete all the intermediate files that DarwinPorts has created while building the port, to do this you should enter: <userinput>port clean vile</userinput>.
    140140                        </para>
    141141                       
     
    146146               
    147147                <sect2 id='portindex'>
    148                         <title>portindex Command</title>
     148                        <title>The portindex command</title>
    149149                       
    150150                        <para>Most of the time you won't need to use this command as it is used to build the index of all the available ports, but sometimes the index you have is out of date or innacurate for some reason. When this occurs you will get an error message like 'port search failed: expected integer but got "PortIndex"'. You can fix problem by moving to the dports directory (/Users/mike/darwinports/dports in our examples) and executing: <userinput>portindex</userinput>. This will go through all the available ports in the dport directory and build an index file called PortIndex.
     
    156156                        <title>Updating DarwinPorts</title>
    157157                       
    158                         <para>New ports are always being added to the darwinports dports tree, you should regularly update your tree to get access to new ports, and (hopefully) improved versions of current ports. Currently the simplest way you can update the dports tree is to use cvs. You should change directory to the dports directory and then execute: <userinput>cvs -z3 update -dP</userinput>. You should see a set of lines printed out in the terminal as the update progresses. You may need to update your PortIndex as mentioned previously: <userinput>portindex</userinput>.
     158                        <para>New ports are always being added to the DarwinPorts dports tree, you should regularly update your tree to get access to new ports, and (hopefully) improved versions of current ports. Currently the simplest way you can update the dports tree is to use cvs. You should change directory to the dports directory and then execute: <userinput>cvs -z3 update -dP</userinput>. You should see a set of lines printed out in the terminal as the update progresses. You may need to update your PortIndex as mentioned previously: <userinput>portindex</userinput>.
    159159                        </para>
    160160                       
     
    172172               
    173173                <sect2 id='uninstall_dports'>
    174                         <title>Removing Ports</title>
     174                        <title>Removing ports</title>
    175175                       
    176176                        <para>Ports are removed using the port command described above, simply execute the command: <userinput>sudo port uninstall vile</userinput></para>
     
    179179               
    180180                <sect2 id='upgrade_dports'>
    181                         <title>Upgrading Ports</title>
     181                        <title>Upgrading ports</title>
    182182                       
    183183                        <para>At the moment there is not a 'port upgrade' command so to upgrade a port you must uninstall and then install it again. <programlisting><![CDATA[
     
    199199                </para>
    200200                <sect2>
    201                         <title>Common Errors and Problems</title>
     201                        <title>Common errors and problems</title>
    202202                                       
    203203                        <sect3 id='E_port_search'>
     
    211211               
    212212                <sect2 id='user_bugs'>
    213                         <title>Bug Reports</title>
     213                        <title>Bug reports</title>
    214214                        <para>If the you have updated your ports tree, searched the darwinports@opendarwin.org mailling list archives and read the common problems and the FAQ and you still can't find the answer to the problem, you should submit a bug report via bugzilla.
    215215                        </para>
     
    218218
    219219                        <sect3>
    220                                 <title>Submission Parameters</title>
     220                                <title>Submission parameters</title>
    221221                               
    222222                                <variablelist>
     
    226226                                                </term>
    227227                                                <listitem>
    228                                                         <para>Make sure you select the Darwinports project.
     228                                                        <para>Make sure you select the DarwinPorts project.
    229229                                                        </para>
    230230                                                </listitem>
     
    304304                <title>Ports Manager.app</title>
    305305               
    306                 <para>Ports Manager.app is a Cocoa GUI for the DarwinPorts project, it allows users to browse through available ports and their descriptions and to download, install and uninstall the software. Ports Manager.app is currently under development and is less reliable in use than the command line tools. There is a Port for the application so you can actually use Darwinports to install it for you! <userinput>sudo port install 'PortsManager'</userinput>. Ports Manager.app will be installed in your /Applications/Utilities folder. You must have the DarwinPorts Tcl libraries installed to use the Ports Manager.app. A <ulink url='http://www.opendarwin.org/~fkr/portsmanager.png'>screen shot is available</ulink> of Ports Manager.app in action.
     306                <para>Ports Manager.app is a Cocoa GUI for the DarwinPorts project, it allows users to browse through available ports and their descriptions and to download, install and uninstall the software. Ports Manager.app is currently under development and is less reliable in use than the command line tools. There is a Port for the application so you can actually use DarwinPorts to install it for you! <userinput>sudo port install 'PortsManager'</userinput>. Ports Manager.app will be installed in your /Applications/Utilities folder. You must have the DarwinPorts Tcl libraries installed to use the Ports Manager.app. A <ulink url='http://www.opendarwin.org/~fkr/portsmanager.png'>screen shot is available</ulink> of Ports Manager.app in action.
    307307                </para>
    308308               
  • trunk/doc/guide/xml/variants.xml

    r2614 r2627  
    55        <title>Variants</title>
    66        <sect1>
    7                 <title>What are Variants?</title>
     7                <title>What are variants?</title>
    88                <para>
    9                         Darwinports allows multiple versions of a port to be specified in a single Portfile. For example, vim can be built with and without x11 support. Rather than duplicate the whole port and have vim-x11 vim-nox ports Darwinports supports "variants".
     9                        DarwinPorts allows multiple versions of a port to be specified in a single Portfile. For example, vim can be built with and without x11 support. Rather than duplicate the whole port and have vim-x11 vim-nox ports DarwinPorts supports "variants".
    1010                </para>
    1111        </sect1>
     
    7272        </sect1>
    7373        <sect1>
    74                 <title>Advanced Variants</title>
     74                <title>Advanced variants</title>
    7575                <para>
    7676                        For the most part, variants are quite straightforward to use. Several more advanced features of variants are also available.
Note: See TracChangeset for help on using the changeset viewer.