Changeset 31880 for trunk/doc-new


Ignore:
Timestamp:
Dec 10, 2007, 9:44:13 PM (12 years ago)
Author:
simon@…
Message:

doc-new: Moved "Port Phases Introduction" to portfile-phases.7.xml so it's included in the man page and I think this is a better place. Also fixed some links.

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

Legend:

Unmodified
Added
Removed
  • trunk/doc-new/guide/xml/portfile-phase.7.xml

    r31878 r31880  
    55<section id="reference.phases">
    66  <title>Port Phases</title>
     7
     8  <section id="reference.phases.introduction">
     9    <title>Introduction</title>
     10
     11    <para>A MacPorts port has ten distinct phases. The MacPorts base is set to
     12    perform default steps for applications that use the standard
     13    <command>configure</command>, <command>make</command>, and <command>make
     14    install</command> steps, but for applications that do not conform to this
     15    behavior, installation phases may be declared in a Portfile to <link
     16    linkend="development.examples.augment">augment</link> or <link
     17    linkend="development.examples.override">override</link> the default
     18    behavior as described in the <link linkend="development">Portfile
     19    Development</link> chapter.</para>
     20
     21    <section id="reference.phases.introduction.fetch">
     22      <title>Fetch</title>
     23
     24      <para>Overview: Fetch the <varname>${distfiles}</varname> from
     25      <varname>${master_sites}</varname> and place it in
     26      <filename>${prefix}/var/macports/distfiles</filename>.</para>
     27    </section>
     28
     29    <section id="reference.phases.introduction.checksum">
     30      <title>Checksum</title>
     31
     32      <para>Overview: Compare <varname>${checksums}</varname> specified in a
     33      <filename>Portfile</filename> to the checksums of the fetched
     34      ${distfiles}.</para>
     35    </section>
     36
     37    <section id="reference.phases.introduction.extract">
     38      <title>Extract</title>
     39
     40      <para>Overview: Unzip and untar the <varname>${distfiles}</varname> into
     41      the path ${prefix}/var/macports/build/..../work</para>
     42    </section>
     43
     44    <section id="reference.phases.introduction.patch">
     45      <title>Patch</title>
     46
     47      <para>Overview: Apply optional <ulink
     48      url="http://en.wikipedia.org/wiki/Patch_(Unix)">patch</ulink> files
     49      specified in <varname>${patchfiles}</varname> to modify a port's source
     50      code file(s).</para>
     51
     52      <para>Details: Patch files are made using the <ulink
     53      url="http://en.wikipedia.org/wiki/Diff">diff</ulink> command, and
     54      MacPorts patches should be created as <ulink
     55      url="http://en.wikipedia.org/wiki/Diff#Unified_format">unified
     56      diffs</ulink>.</para>
     57    </section>
     58
     59    <section id="reference.phases.introduction.configure">
     60      <title>Configure</title>
     61
     62      <para>Overview: Execute the command "configure" in
     63      <varname>${workpath}</varname>.</para>
     64    </section>
     65
     66    <section id="reference.phases.introduction.build">
     67      <title>Build</title>
     68
     69      <para>Overview: Execute the command "make" in
     70      <varname>${workpath}</varname>.</para>
     71    </section>
     72
     73    <section id="reference.phases.introduction.destroot">
     74      <title>Destroot</title>
     75
     76      <para>Overview: Execute the command <command>make install
     77      DESTDIR=${destroot}</command> in <varname>${workpath}</varname>.</para>
     78
     79      <para>Details: Understanding the destroot phase is critical to
     80      understanding MacPorts, because, unlike some port systems, MacPorts
     81      "stages" an installation into an intermediate location —not the final
     82      file destination. There are two main advantages to this method.</para>
     83
     84      <orderedlist>
     85        <listitem>
     86          <para>A port's files may be cleanly uninstalled because all files
     87          and locations are tracked.</para>
     88        </listitem>
     89
     90        <listitem>
     91          <para>Since a port's files are not installed into MacPorts directory
     92          structure until an activation phase, a port may be deactivated
     93          through MacPorts to allow activation of a different version of the
     94          same port, thus allowing two versions of a port to be present,
     95          though not both active, on a given host.</para>
     96        </listitem>
     97      </orderedlist>
     98
     99      <note>
     100        <para>The <varname>$(DESTDIR)</varname> variable must be supported in
     101        an application's Makefile for the MacPorts destroot phase to work
     102        properly. Urge developers to fully support
     103        <varname>$(DESTDIR)</varname> in their Makefiles.</para>
     104      </note>
     105
     106      <para>At the beginning of the destroot phase, all the directories in the
     107      file <filename>${prefix}/etc/macports/prefix.mtree</filename> are
     108      created. Any directories still empty upon completion of the destroot
     109      phase are removed unless a directory is listed using a destroot.keepdirs
     110      keyword.</para>
     111    </section>
     112
     113    <section id="reference.phases.introduction.archive">
     114      <title>Archive</title>
     115
     116      <para>Overview: Use tar to create a tarball of a port's destrooted files
     117      and copy it to
     118      <filename>${prefix}/var/macports/packages/</filename>.</para>
     119    </section>
     120
     121    <section id="reference.phases.introduction.install">
     122      <title>Install</title>
     123
     124      <para>Overview: Copy a port's destrooted files into
     125      <filename>${prefix}/var/macports/software</filename>. See <link
     126      linkend="internals.images">Port Images</link> in the <link
     127      linkend="internals">MacPorts Internals</link> chapter for
     128      details.</para>
     129    </section>
     130
     131    <section id="reference.phases.introduction.activate">
     132      <title>Activate</title>
     133
     134      <para>Overview: Set <ulink
     135      url="http://en.wikipedia.org/wiki/Hard_link">hardlinks</ulink> pointing
     136      to <filename>${prefix}/var/macports/software</filename> to point to
     137      ${prefix}.</para>
     138    </section>
     139  </section>
    7140
    8141  <section id="reference.phases.installation">
  • trunk/doc-new/guide/xml/portfiledev.xml

    r31849 r31880  
    7575    <note>
    7676      <para>For a detailed description of all port phases, see the <link
    77       linkend="reference">Portfile Reference</link> chapter.</para>
     77      linkend="reference.phases">Portfile Reference</link> chapter.</para>
    7878    </note>
    7979  </section>
  • trunk/doc-new/guide/xml/portfileref.xml

    r31879 r31880  
    3030                xmlns:xi="http://www.w3.org/2001/XInclude" />
    3131  </section>
    32 
    33   <section id="reference.phases-old">
    34     <title>Port Phases</title>
    35 
    36     <para>A MacPorts port has ten distinct phases. The MacPorts base is set to
    37     perform default steps for applications that use the standard
    38     <command>configure</command>, <command>make</command>, and <command>make
    39     install</command> steps, but for applications that do not conform to this
    40     behavior, installation phases may be declared in a Portfile to <link
    41     linkend="development.examples.augment">augment</link> or <link
    42     linkend="development.examples.override">override</link> the default
    43     behavior as described in the <link linkend="development">Portfile
    44     Development</link> chapter.</para>
    45 
    46     <section id="reference.phases.fetch">
    47       <title>Fetch</title>
    48 
    49       <para>Overview: Fetch the <varname>${distfiles}</varname> from
    50       <varname>${master_sites}</varname> and place it in
    51       <filename>${prefix}/var/macports/distfiles</filename>.</para>
    52     </section>
    53 
    54     <section id="reference.phases.checksum">
    55       <title>Checksum</title>
    56 
    57       <para>Overview: Compare <varname>${checksums}</varname> specified in a
    58       <filename>Portfile</filename> to the checksums of the fetched
    59       ${distfiles}.</para>
    60     </section>
    61 
    62     <section id="reference.phases.extract">
    63       <title>Extract</title>
    64 
    65       <para>Overview: Unzip and untar the <varname>${distfiles}</varname> into
    66       the path ${prefix}/var/macports/build/..../work</para>
    67     </section>
    68 
    69     <section id="reference.phases.patch">
    70       <title>Patch</title>
    71 
    72       <para>Overview: Apply optional <ulink
    73       url="http://en.wikipedia.org/wiki/Patch_(Unix)">patch</ulink> files
    74       specified in <varname>${patchfiles}</varname> to modify a port's source
    75       code file(s).</para>
    76 
    77       <para>Details: Patch files are made using the <ulink
    78       url="http://en.wikipedia.org/wiki/Diff">diff</ulink> command, and
    79       MacPorts patches should be created as <ulink
    80       url="http://en.wikipedia.org/wiki/Diff#Unified_format">unified
    81       diffs</ulink>.</para>
    82     </section>
    83 
    84     <section id="reference.phases.configure">
    85       <title>Configure</title>
    86 
    87       <para>Overview: Execute the command "configure" in
    88       <varname>${workpath}</varname>.</para>
    89     </section>
    90 
    91     <section id="reference.phases.build">
    92       <title>Build</title>
    93 
    94       <para>Overview: Execute the command "make" in
    95       <varname>${workpath}</varname>.</para>
    96     </section>
    97 
    98     <section id="reference.phases.destroot">
    99       <title>Destroot</title>
    100 
    101       <para>Overview: Execute the command <command>make install
    102       DESTDIR=${destroot}</command> in <varname>${workpath}</varname>.</para>
    103 
    104       <para>Details: Understanding the destroot phase is critical to
    105       understanding MacPorts, because, unlike some port systems, MacPorts
    106       "stages" an installation into an intermediate location —not the final
    107       file destination. There are two main advantages to this method.</para>
    108 
    109       <orderedlist>
    110         <listitem>
    111           <para>A port's files may be cleanly uninstalled because all files
    112           and locations are tracked.</para>
    113         </listitem>
    114 
    115         <listitem>
    116           <para>Since a port's files are not installed into MacPorts directory
    117           structure until an activation phase, a port may be deactivated
    118           through MacPorts to allow activation of a different version of the
    119           same port, thus allowing two versions of a port to be present,
    120           though not both active, on a given host.</para>
    121         </listitem>
    122       </orderedlist>
    123 
    124       <note>
    125         <para>The <varname>$(DESTDIR)</varname> variable must be supported in
    126         an application's Makefile for the MacPorts destroot phase to work
    127         properly. Urge developers to fully support
    128         <varname>$(DESTDIR)</varname> in their Makefiles.</para>
    129       </note>
    130 
    131       <para>At the beginning of the destroot phase, all the directories in the
    132       file <filename>${prefix}/etc/macports/prefix.mtree</filename> are
    133       created. Any directories still empty upon completion of the destroot
    134       phase are removed unless a directory is listed using a destroot.keepdirs
    135       keyword.</para>
    136     </section>
    137 
    138     <section id="reference.phases.archive">
    139       <title>Archive</title>
    140 
    141       <para>Overview: Use tar to create a tarball of a port's destrooted files
    142       and copy it to
    143       <filename>${prefix}/var/macports/packages/</filename>.</para>
    144     </section>
    145 
    146     <section id="reference.phases.install">
    147       <title>Install</title>
    148 
    149       <para>Overview: Copy a port's destrooted files into
    150       <filename>${prefix}/var/macports/software</filename>. See <link
    151       linkend="internals.images">Port Images</link> in the <link
    152       linkend="internals">MacPorts Internals</link> chapter for
    153       details.</para>
    154     </section>
    155 
    156     <section id="reference.phases.activate">
    157       <title>Activate</title>
    158 
    159       <para>Overview: Set <ulink
    160       url="http://en.wikipedia.org/wiki/Hard_link">hardlinks</ulink> pointing
    161       to <filename>${prefix}/var/macports/software</filename> to point to
    162       ${prefix}.</para>
    163     </section>
    164   </section>
    16532</chapter>
  • trunk/doc-new/guide/xml/using.xml

    r30390 r31880  
    159159        troubleshooting by passing <command>port</command> a prior
    160160        installation phase such as fetch, configure, build, or destroot. See
    161         section <link linkend="development.phases">Port Phases</link> for a
     161        section <link linkend="reference.phases">Port Phases</link> for a
    162162        complete list of phases.</para>
    163163      </note>
     
    279279        uninstall an upgraded port —it deactivates it. See section <link
    280280        linkend="internals.images">Port Images</link>, and also <link
    281         linkend="reference.phases.destroot">Destroot</link> and <link
    282         linkend="reference.phases.activate">Activate</link> phases in <link
    283         linkend="reference.phases">Port Phases</link>. If you wish to
    284         uninstall the old version, use the <option>-u</option> option.</para>
     281        linkend="reference.phases.introduction.destroot">Destroot</link> and
     282        <link linkend="reference.phases.introduction.activate">Activate</link>
     283        phases in <link linkend="reference.phases">Port Phases</link>. If you
     284        wish to uninstall the old version, use the <option>-u</option>
     285        option.</para>
    285286
    286287        <programlisting><prompt>%%</prompt> <userinput>port -u upgrade vile</userinput></programlisting>
Note: See TracChangeset for help on using the changeset viewer.