Changeset 28039 for trunk/doc


Ignore:
Timestamp:
Aug 19, 2007, 2:31:52 AM (11 years ago)
Author:
markd@…
Message:

More cross reference links.

Location:
trunk/doc/guide/new/xml
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/guide/new/xml/installing.xml

    r28037 r28039  
    66
    77  <para>This chapter show you how to install MacPorts and its prerequistes
    8   step-by-step. Note that sections 2 to 4 are Mac OS X specific. If you wish
    9   to install MacPorts on FreeBSD, first make sure you have gcc and X11
    10   installed, and then begin with section 5.</para>
     8  step-by-step. Note that sections 1 through 3 are Mac OS X specific. If you
     9  wish to install MacPorts on FreeBSD, first make sure you have gcc and X11
     10  installed, and then begin with section <link
     11  linkend="installing-macports.install.macports.source">Install MacPorts -
     12  Source</link>.</para>
    1113
    1214  <section id="installing-macports.install.xcode.tools">
     
    122124    <para>If you wish to install MacPorts to a path other than
    123125    <filename>/opt/local</filename> do not install the MacPorts binary —skip
    124     this section and proceed to the next to install MacPorts from the source
    125     code. The MacPorts binary installer will only install to
    126     <filename>/opt/local</filename>.</para>
     126    this section and <link
     127    linkend="installing-macports.install.macports.source">install MacPorts
     128    from the source code</link>. The MacPorts binary installer will only
     129    install to <filename>/opt/local</filename>.</para>
    127130
    128131    <orderedlist>
     
    143146
    144147    <note>
    145       <para>A MacPorts selfupdate operation (see below) will automatically
    146       update to the latest release if the binary .dmg image is behind the
    147       latest released tarball.</para>
     148      <para>A MacPorts <link
     149      linkend="installing-macports.selfupdate">selfupdate</link> operation
     150      will automatically update to the latest release if the binary .dmg image
     151      is behind the latest released tarball.</para>
    148152    </note>
    149153  </section>
     
    152156    <title>Install MacPorts - Source</title>
    153157
    154     <para>Installing from source on Mac OS X is only necessary If you wish to
    155     install to a path other than <filename>/opt/local</filename>, so If you
    156     installed MacPorts using the binary installer, skip this section. If you
    157     wish to install MacPorts on FreeBSD you must install from source.</para>
     158    <para>If you installed MacPorts using the binary installer, skip this
     159    section. Installing from source on Mac OS X is only necessary if you wish
     160    to install to a path other than <filename>/opt/local</filename>, or if you
     161    wish to install a non-release version of MacPorts base. You must also
     162    install MacPorts from source if you wish to install MacPorts on a platform
     163    other than Mac OS X.</para>
    158164
    159165    <orderedlist>
     
    175181
    176182    <note>
    177       <para>A MacPorts' selfupdate (see below) will automatically update to
    178       the latest release if the binary .dmg image is behind the latest
    179       released tarball.</para>
     183      <para>A MacPorts <link
     184      linkend="installing-macports.selfupdate">selfupdate</link> operation
     185      will automatically update to the latest release if the binary .dmg image
     186      is behind the latest released tarball.</para>
    180187    </note>
    181188  </section>
     
    238245  </section>
    239246
    240   <section>
     247  <section id="installing-macports.selfupdate">
    241248    <title>MacPorts Selfupdate</title>
    242249
  • trunk/doc/guide/new/xml/portfiledev.xml

    r28037 r28039  
    66
    77  <para>This chapter covers a brief introduction to Portfiles, how to create a
    8   local <filename>Portfile</filename> repository for development, and creating
    9   Portfiles.</para>
     8  local Portfile repository for development, and creating Portfiles.</para>
    109
    1110  <section id="portfile-development.portfile.introduction">
    1211    <title>Portfile Introduction</title>
    1312
    14     <para>A MacPorts <filename>Portfile</filename> is a TCL script that
    15     usually contains only the simple keyword/value combinations and Tcl
    16     extensions as described in the Portfile Reference section below, though it
    17     may also contain arbitrary TCL code. Every port has a corresponding
    18     <filename>Portfile</filename>, but Portfiles do not completely define a
    19     port's installation behavior since the MacPorts base has default port
     13    <para>A MacPorts Portfile is a TCL script that usually contains only the
     14    simple keyword/value combinations and Tcl extensions as described in the
     15    <link linkend="portfile-reference">Portfile Reference</link> chapter,
     16    though it may also contain arbitrary TCL code. Every port has a
     17    corresponding Portfile, but Portfiles do not completely define a port's
     18    installation behavior since the MacPorts base has default port
    2019    installation characteristics coded within it. Therefore Portfiles need
    2120    only specify required options and, when required, non-default
     
    2423    <para>A common way for Portfiles to augment or override MacPorts base
    2524    default installation phase characteristics is by using
    26     <filename>Portfile</filename> phase declaration(s). If you use
    27     <filename>Portfile</filename> phase declaration(s), you should know how to
    28     identify the "global" section of a <filename>Portfile</filename>. Any
    29     statements not contained within a phase declaration, no matter where they
    30     are located in a <filename>Portfile</filename>, are said to be in the
    31     global section of the <filename>Portfile</filename>, therefore the global
    32     section need not be contiguous. Likewise, to remove statements from the
    33     global section they must be placed within a phase declaration.</para>
    34 
    35     <para>The main phases you need to be aware of when making a
    36     <filename>Portfile</filename> are these:</para>
     25    <filename>Portfile</filename> phase declaration(s). If you use Portfile
     26    phase declaration(s), you should know how to identify the "global" section
     27    of a Portfile. Any statements not contained within a phase declaration, no
     28    matter where they are located in a Portfile are said to be in the global
     29    section of the Portfile, therefore the global section need not be
     30    contiguous. Likewise, to remove statements from the global section they
     31    must be placed within a phase declaration.</para>
     32
     33    <para>The main phases you need to be aware of when making a Portfile are
     34    these:</para>
    3735
    3836    <itemizedlist>
     
    6866    destroot respectively. For applications that do not conform to this
    6967    standard behavior, any installation phase may be augmented using pre-
    70     and/or post- phases, or even overridden or eliminated. See the section
    71     "Example Portfiles" below.</para>
     68    and/or post- phases, or even overridden or eliminated. See <link
     69    linkend="portfile-development.example.portfiles">Example Portfiles</link>
     70    below.</para>
    7271
    7372    <note>
    74       <para>For a detailed description of all port phases, see the section
    75       "Portfile Reference" below.</para>
     73      <para>For a detailed description of all port phases, see the <link
     74      linkend="portfile-reference">Portfile Reference</link> chapter.</para>
    7675    </note>
    7776  </section>
     
    8079    <title>Local Portfile Repositories</title>
    8180
    82     <para>To create and test <filename>Portfile</filename>s that are not yet
    83     committed to subversion, you may create a local
    84     <filename>Portfile</filename> repository as shown.</para>
     81    <para>To create and test Portfiles that are not yet committed to
     82    subversion, you may create a local Portfile repository as shown.</para>
    8583
    8684    <orderedlist>
     
    103101        <note>
    104102          <para>The file URL should always appear before the rsync URL so that
    105           local <filename>Portfile</filename>s can be tested that are
    106           duplicated in the MacPorts tree, because the <command>port</command>
    107           command will always operate on the first
    108           <filename>Portfile</filename> it encounters.</para>
     103          local Portfiles can be tested that are duplicated in the MacPorts
     104          tree, because the <command>port</command> command will always
     105          operate on the first Portfile it encounters.</para>
    109106        </note>
    110107      </listitem>
    111108
    112109      <listitem>
    113         <para>Place the <filename>Portfile</filename>s you create inside a
    114         directory whose name matches the port, which should in turn be placed
    115         inside a directory that reflect the port's primary category (the first
    116         category entry in the <filename>Portfile</filename>).</para>
     110        <para>Place the Portfiles you create inside a directory whose name
     111        matches the port, which should in turn be placed inside a directory
     112        that reflect the port's primary category (the first category entry in
     113        the Portfile).</para>
    117114
    118115        <programlisting><prompt>%%</prompt> <userinput>cd /Users/julesverne</userinput>
     
    123120
    124121      <listitem>
    125         <para>After a <filename>Portfile</filename> is created (see below),
    126         use the MacPorts <command>portindex</command> command in the local
    127         repository's directory to install it into the
     122        <para>After a Portfile is created (see below), use the MacPorts
     123        <command>portindex</command> command in the local repository's
     124        directory to install it into the
    128125        <filename>Portindex</filename>.</para>
    129126
     
    142139    <para>Once the local port is added to the <filename>Portindex</filename>,
    143140    it becomes available for searching or installation as with any other
    144     <filename>Portfile</filename> in the MacPorts tree as shown.</para>
     141    Portfile in the MacPorts tree as shown.</para>
    145142
    146143    <programlisting><prompt>%%</prompt> <userinput>port search bestever</userinput></programlisting>
     
    152149    <title>Creating a Portfile</title>
    153150
    154     <para>Here we list the individual <filename>Portfile</filename> components
    155     for an application that conforms to the the standard <command>
    156     configure</command>, <command>make</command>, and <command>make
    157     install</command> steps of most open source application installs.</para>
     151    <para>Here we list the individual Portfile components for an application
     152    that conforms to the the standard <command> configure</command>,
     153    <command>make</command>, and <command>make install</command> steps of most
     154    open source application installs.</para>
    158155
    159156    <orderedlist>
     
    161158        <para>Subversion ID tag line</para>
    162159
    163         <para>The first line of a new <filename>Portfile</filename> must be
    164         set as shown. When a port is committed to subversion, ID tags are
    165         expanded to include the last person to commit and the commit
    166         time.</para>
     160        <para>The first line of a new Portfile must be set as shown. When a
     161        port is committed to subversion, ID tags are expanded to include the
     162        last person to commit and the commit time.</para>
    167163
    168164        <programlisting># $Id$</programlisting>
     
    194190        <para>A port may belong to more than one category, but the first
    195191        (primary) category should match the directory name in the ports tree
    196         where the <filename>Portfile</filename> is to reside.</para>
     192        where the Portfile is to reside.</para>
    197193
    198194        <programlisting>categories        net</programlisting>
     
    207203        from spambots, see the more full explanation of the maintainer keyword
    208204        in the <link linkend="portfile-reference.keywords.global">Global
    209         Keywords</link> section of the Portfile Reference.</para>
     205        Keywords</link> section of the <link
     206        linkend="portfile-reference">Portfile Reference</link> chapter.</para>
    210207
    211208        <programlisting>maintainers       julesverne@somedomain.org</programlisting>
     
    251248        <para>Port checksums</para>
    252249
    253         <para>The checksums specified in a <filename>Portfile</filename> are
    254         checked with the fetched tarball for security.</para>
     250        <para>The checksums specified in a Portfile are checked with the
     251        fetched tarball for security.</para>
    255252
    256253        <programlisting>checksums         md5 dafa161bc9c61e57636a6085c87c1fe8</programlisting>
     
    366363    <para>Variants are a way for port authors to provide options that may be
    367364    invoked at install time. They are declared in the global section of a
    368     <filename>Portfile</filename> using the "variant" keyword and may provide
    369     a description.</para>
     365    Portfile using the "variant" keyword and may provide a description.</para>
    370366
    371367    <section id="portfile-development.port.variants.modify.options">
     
    374370      <para>The most common use for a variant is to add or remove
    375371      dependencies, configure arguments, and build arguments from the global
    376       <filename>Portfile</filename> section. Here is an example of a port
    377       providing four variants that add additional configure arguments to a
    378       port. See "Variants" in the Portfile Reference section for full
    379       information.</para>
     372      Portfile section. Here is an example of a port providing four variants
     373      that add additional configure arguments to a port.</para>
    380374
    381375      <programlisting>variant pop     { configure.args-append --enable-pop }
     
    440434      <note>
    441435        <para>The default_variant keyword may only be used in the global
    442         <filename>Portfile</filename> section.</para>
     436        Portfile section.</para>
    443437      </note>
    444438    </section>
     
    456450      <title>Creating Portfile Patches</title>
    457451
    458       <para>If you wish to contribute modifications or fixes to a
    459       <filename>Portfile</filename>, you should do so in the form of a
    460       patch.</para>
     452      <para>If you wish to contribute modifications or fixes to a Portfile,
     453      you should do so in the form of a patch.</para>
    461454
    462455      <orderedlist>
    463456        <listitem>
    464           <para>Make a copy of the <filename>Portfile</filename> you wish to
    465           modify; both files must be in the same directory, though it may be
    466           any directory.</para>
     457          <para>Make a copy of the Portfile you wish to modify; both files
     458          must be in the same directory, though it may be any
     459          directory.</para>
    467460
    468461          <programlisting><prompt>%%</prompt> <userinput>cp Portfile Portfile.org</userinput></programlisting>
     
    484477          <para>A patch file that is a "unified" diff file is the easiest to
    485478          interpret by humans and this type should always be used for ports.
    486           The <filename>Portfile</filename> patch below will change the
    487           version and checksums when applied.</para>
     479          The Portfile patch below will change the version and checksums when
     480          applied.</para>
    488481
    489482          <programlisting>--- Portfile.org        2007-07-25 18:52:12.000000000 -0700
     
    593586        <listitem>
    594587          <para>Change to the directory containing the file to be patched. In
    595           this example, we'll apply a <filename>Portfile</filename> patch to
    596           the postfix port.</para>
     588          this example, we'll apply a Portfile patch to the postfix
     589          port.</para>
    597590
    598591          <programlisting><prompt>%%</prompt> <userinput>cd /opt/local/var/macports/sources/rsync.macports.org/release/ports/mail/postfix</userinput></programlisting>
  • trunk/doc/guide/new/xml/portfileref.xml

    r28038 r28039  
    1616    <command>configure</command>, <command>make</command>, and <command>make
    1717    install</command> steps, but for applications that do not conform to this
    18     behavior, installation phases may be declared in a Portfile to override or
    19     eliminate the default behavior, or augment it using pre- and/or post-
    20     phases as shown in the section "Portfile Development".</para>
     18    behavior, installation phases may be declared in a Portfile to <link
     19    linkend="portfile-development.example.portfiles.pre.post">augment</link>
     20    or <link
     21    linkend="portfile-development.example.portfiles.override">override</link>
     22    the default behavior as described in the <link
     23    linkend="portfile-development">Portfile Development</link> chapter.</para>
    2124
    2225    <section id="portfile-reference.port.phases.fetch">
     
    124127
    125128      <para>Overview: Copy a port's destrooted files into
    126       <filename>${prefix}/var/macports/software</filename>. See "Port Images"
    127       in section "MacPorts Internals" for details.</para>
     129      <filename>${prefix}/var/macports/software</filename>. See <link
     130      linkend="macports-internals.port.images">Port Images</link> in the <link
     131      linkend="macports-internals">MacPorts Internals</link> chapter for
     132      details.</para>
    128133    </section>
    129134
     
    133138      <para>Overview: Set <ulink
    134139      url="http://en.wikipedia.org/wiki/Hard_link">hardlinks</ulink> pointing
    135       to ${prefix}/var/macports/software to point to ${prefix}.</para>
     140      to <filename>${prefix}/var/macports/software</filename> to point to
     141      ${prefix}.</para>
    136142    </section>
    137143  </section>
  • trunk/doc/guide/new/xml/using.xml

    r28037 r28039  
    55  <title>Using MacPorts</title>
    66
    7   <para>This chapter describes the MacPorts file hierarchy, using the
    8   <command>port</command> command, creating port binaries, and setting up an
    9   rsync replication server.</para>
     7  <para>This chapter describes using the <command>port</command> command, port
     8  variants, common tasks, port binaries, and setting up an rsync replication
     9  server.</para>
    1010
    1111  <section id="using-macports.port.command">
     
    123123      variations of a port are available before you install it. Variants are a
    124124      way for port authors to provide options that may be invoked at install
    125       time. See the Variants" section below to see how to invoke
    126       variants.</para>
     125      time. See <link
     126      linkend="using-macports.port.variants.invoking.variants">Invoking Port
     127      Variants</link> below to install ports that have variants.</para>
    127128
    128129      <programlisting><prompt>%%</prompt> <userinput>port variants nmap</userinput></programlisting>
     
    138139      <title>install</title>
    139140
    140       <para>The option <option>install</option> is used to install a
    141       port.</para>
     141      <para>The option <option>install</option> is used to install a port. See
     142      <link linkend="using-macports.port.variants.invoking.variants">Invoking
     143      Port Variants</link> below to install ports that have variants.</para>
    142144
    143145      <programlisting><prompt>%%</prompt> <userinput>sudo port install nmap</userinput></programlisting>
     
    149151        destroot.</para>
    150152      </note>
    151 
    152       <programlisting><prompt>%%</prompt> <userinput>sudo port install nmap +no_ssl</userinput></programlisting>
    153153    </section>
    154154
     
    264264      <note>
    265265        <para>The <option>upgrade</option> option by default does not
    266         uninstall an upgraded port —it deactivates it (see section Port
    267         Installation Phases below). If you wish to uninstall the old version
    268         use the -u option.</para>
     266        uninstall an upgraded port —it deactivates it. See section <link
     267        linkend="macports-internals.port.images">Port Images</link>, and also
     268        <link
     269        linkend="portfile-reference.port.phases.destroot">Destroot</link> and
     270        <link
     271        linkend="portfile-reference.port.phases.activate">Activate</link>
     272        phases in <link linkend="portfile-reference.port.phases">Port
     273        Phases</link>. If you wish to uninstall the old version use the -u
     274        option.</para>
    269275
    270276        <programlisting><prompt>%%</prompt> <userinput>port -u upgrade vile</userinput></programlisting>
     
    337343      <title>Negating Default Variants</title>
    338344
    339       <para>For an explanation of default variants, see the "Port Development"
    340       section. Default variants are optional, and not all ports using variants
    341       have them. For ports with default variants, you may install a port
    342       without them by negating default variants using "-" as shown.</para>
     345      <para>For an explanation of default variants see <link
     346      linkend="portfile-development.port.variants">Port Variants</link>.
     347      Default variants are optional, and not all ports using variants have
     348      them. For ports with default variants, you may install a port without
     349      them by negating default variants using "-" as shown.</para>
    343350
    344351      <programlisting><prompt>%%</prompt> <userinput>port install fetchmail -ssl</userinput></programlisting>
Note: See TracChangeset for help on using the changeset viewer.