Changeset 122855 for trunk/doc-new


Ignore:
Timestamp:
Jul 31, 2014, 9:52:33 PM (4 years ago)
Author:
cal@…
Message:

guide: start autoformatting, add modeline, conform to standard macports formatting, increase textwidth

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

Legend:

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

    r120885 r122855  
    11<?xml version="1.0" encoding="UTF-8"?>
    2 <!-- vim:ts=2:sts=2:sw=2:et
     2<!-- -*- coding: utf-8; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4:tw=120
    33-->
    44<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    55"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    66<book>
    7   <title>
    8     <application>MacPorts</application> Guide
    9   </title>
    10   <bookinfo>
    11     <authorgroup>
    12       <author>
    13         <firstname>Mark</firstname>
    14         <surname>Duling</surname>
    15       </author>
    16       <author>
    17         <honorific>Dr</honorific>
    18         <firstname>Michael</firstname>
    19         <surname>Maibaum</surname>
    20         <othername role="mi">A</othername>
    21       </author>
    22       <author>
    23         <firstname>Will</firstname>
    24         <surname>Barton</surname>
    25       </author>
    26     </authorgroup>
     7    <title>
     8        <application>MacPorts</application> Guide
     9    </title>
     10    <bookinfo>
     11        <authorgroup>
     12            <author>
     13                <firstname>Mark</firstname>
     14                <surname>Duling</surname>
     15            </author>
     16            <author>
     17                <honorific>Dr</honorific>
     18                <firstname>Michael</firstname>
     19                <surname>Maibaum</surname>
     20                <othername role="mi">A</othername>
     21            </author>
     22            <author>
     23                <firstname>Will</firstname>
     24                <surname>Barton</surname>
     25            </author>
     26        </authorgroup>
    2727
    28     <copyright>
    29       <year>2007–2014</year>
    30       <holder>The MacPorts Project</holder>
    31     </copyright>
     28        <copyright>
     29            <year>2007–2014</year>
     30            <holder>The MacPorts Project</holder>
     31        </copyright>
    3232
    33     <copyright>
    34       <year>2002–2004</year>
    35       <holder>The OpenDarwin Project</holder>
    36     </copyright>
    37   </bookinfo>
     33        <copyright>
     34            <year>2002–2004</year>
     35            <holder>The OpenDarwin Project</holder>
     36        </copyright>
     37    </bookinfo>
    3838
    39   <xi:include href="intro.xml"
    40               xmlns:xi="http://www.w3.org/2001/XInclude" />
    41   <xi:include href="installing.xml"
    42               xmlns:xi="http://www.w3.org/2001/XInclude" />
    43   <xi:include href="using.xml"
    44               xmlns:xi="http://www.w3.org/2001/XInclude" />
    45   <xi:include href="portfiledev.xml"
    46               xmlns:xi="http://www.w3.org/2001/XInclude" />
    47   <xi:include href="portfileref.xml"
    48               xmlns:xi="http://www.w3.org/2001/XInclude" />
    49   <xi:include href="internals.xml"
    50               xmlns:xi="http://www.w3.org/2001/XInclude" />
    51   <xi:include href="project.xml"
    52               xmlns:xi="http://www.w3.org/2001/XInclude" />
    53   <xi:include href="glossary.xml"
    54               xmlns:xi="http://www.w3.org/2001/XInclude" />
     39    <xi:include href="intro.xml"
     40        xmlns:xi="http://www.w3.org/2001/XInclude" />
     41    <xi:include href="installing.xml"
     42        xmlns:xi="http://www.w3.org/2001/XInclude" />
     43    <xi:include href="using.xml"
     44        xmlns:xi="http://www.w3.org/2001/XInclude" />
     45    <xi:include href="portfiledev.xml"
     46        xmlns:xi="http://www.w3.org/2001/XInclude" />
     47    <xi:include href="portfileref.xml"
     48        xmlns:xi="http://www.w3.org/2001/XInclude" />
     49    <xi:include href="internals.xml"
     50        xmlns:xi="http://www.w3.org/2001/XInclude" />
     51    <xi:include href="project.xml"
     52        xmlns:xi="http://www.w3.org/2001/XInclude" />
     53    <xi:include href="glossary.xml"
     54        xmlns:xi="http://www.w3.org/2001/XInclude" />
    5555</book>
  • trunk/doc-new/guide/xml/installing.xml

    r122772 r122855  
    11<?xml version="1.0" encoding="UTF-8"?>
     2<!-- -*- coding: utf-8; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4:tw=120
     3-->
    24<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    35"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
     
    57]>
    68<chapter id="installing">
    7   <title>Installing MacPorts</title>
    8 
    9   <para>This chapter shows you how to install MacPorts and its prerequisites step-by-step. Note that the section about
    10   <link linkend="installing.xcode">installing Xcode</link> is OS X-specific. If you wish to install MacPorts on
    11   another platform, first make sure you have a working C compiler installed, skip ahead to <link
    12     linkend="installing.macports.source">installing MacPorts from source</link>, and continue to the end of the
    13   chapter.</para>
    14 
    15   <section id="installing.xcode">
    16     <title>Install Xcode</title>
    17 
    18     <para>
    19       <ulink url="https://developer.apple.com/xcode/">Xcode</ulink> is a package provided by Apple containing compilers,
    20       libraries and additional tools required to develop applications for OS X.
    21     </para>
    22 
    23     <note>
    24       <para>Always make sure to install the latest available version of Xcode for your OS X release; using outdated
    25         versions of Xcode may cause port install failures. Also note that Xcode is not updated via OS X's Software
    26         Update utility on OS versions prior to 10.6, and is updated via the Mac App Store starting with 10.7.</para>
    27     </note>
    28 
    29     <para>Follow the instructions for your version of OS X:</para>
    30 
    31     <section id="installing.xcode.mavericks">
    32       <title>Install Xcode on OS X 10.9 or later</title>
    33 
    34       <para>
    35         Download the latest version of Xcode <ulink url="https://developer.apple.com/downloads/index.action">from the
    36           Apple developer website</ulink> or get it <ulink url="http://itunes.apple.com/us/app/xcode/id497799835">using
    37           the Mac App Store</ulink>.
    38       </para>
    39       <para>
    40         Once you have Xcode installed, open a terminal, run <userinput>xcode-select --install</userinput>, and click the
    41         Install button to install the required command line developer tools. Don't worry if you see a message telling
    42         you the software cannot be installed because it is not currently available from the Software Update Server. This
    43         usually means you already have the latest version installed. You can also get the command line tools from <ulink
    44           url="https://developer.apple.com/downloads/index.action">the Apple developer website</ulink>.
    45       </para>
     9    <title>Installing MacPorts</title>
     10
     11    <para>This chapter shows you how to install MacPorts and its prerequisites step-by-step. Note that the section about
     12        <link linkend="installing.xcode">installing Xcode</link> is OS X-specific. If you wish to install MacPorts on
     13        another platform, first make sure you have a working C compiler installed, skip ahead to <link
     14            linkend="installing.macports.source">installing MacPorts from source</link>, and continue to the end of the
     15        chapter.</para>
     16
     17    <section id="installing.xcode">
     18        <title>Install Xcode</title>
     19
     20        <para><ulink url="https://developer.apple.com/xcode/">Xcode</ulink> is a package provided by Apple containing
     21            compilers, libraries and additional tools required to develop applications for OS X.</para>
     22
     23        <note>
     24            <para>Always make sure to install the latest available version of Xcode for your OS X release; using
     25                outdated versions of Xcode may cause port install failures. Also note that Xcode is not updated via OS
     26                X's Software Update utility on OS versions prior to 10.6, and is updated via the Mac App Store starting
     27                with 10.7.</para>
     28        </note>
     29
     30        <para>Follow the instructions for your version of OS X:</para>
     31
     32        <section id="installing.xcode.mavericks">
     33            <title>Install Xcode on OS X 10.9 or later</title>
     34
     35            <para>Download the latest version of Xcode <ulink
     36                    url="https://developer.apple.com/downloads/index.action">from the Apple developer website</ulink> or
     37                get it <ulink url="http://itunes.apple.com/us/app/xcode/id497799835">using the Mac App
     38                    Store</ulink>.</para>
     39
     40            <para>Once you have Xcode installed, open a terminal, run <userinput>xcode-select --install</userinput>, and
     41                click the Install button to install the required command line developer tools. Don't worry if you see
     42                a message telling you the software cannot be installed because it is not currently available from the
     43                Software Update Server. This usually means you already have the latest version installed. You can also
     44                get the command line tools from <ulink url="https://developer.apple.com/downloads/index.action">the
     45                    Apple developer website</ulink>.</para>
     46        </section>
     47
     48        <section id="installing.xcode.lion">
     49            <title>Install Xcode on OS X 10.7 Lion or OS X 10.8 Mountain Lion</title>
     50
     51            <para>Download the latest version of Xcode <ulink
     52                    url="https://developer.apple.com/downloads/index.action">from the Apple developer website</ulink> or
     53                get it <ulink url="http://itunes.apple.com/us/app/xcode/id497799835">using the Mac App
     54                    Store</ulink>.</para>
     55
     56            <section id="installing.xcode.lion.43">
     57                <title>Xcode 4.3 and later</title>
     58
     59                <para>Xcode 4.3 and later do not automatically install the command line tools, but MacPorts requires
     60                    them. To install them, open the Xcode application, go to the Preferences window, to the Downloads
     61                    section, and click the Install button next to Command Line Tools. Be sure to return to this window
     62                    after every Xcode upgrade to ensure that the command line tools are also upgraded.</para>
     63
     64                <para>If you wish to create Installer packages with <userinput>port pkg</userinput>, you will also need
     65                    to install PackageMaker, which is in the <quote>Auxiliary Tools for Xcode</quote> package as of
     66                    Xcode 4.3. The download page for this package can be opened via the Xcode -> Open Developer Tool ->
     67                    More Developer Tools... menu item. After downloading and mounting the disk image, drag the
     68                    PackageMaker application to your /Applications directory.</para>
     69            </section>
     70        </section>
     71
     72        <section id="installing.xcode.snowleopard">
     73            <title>Install Xcode on Mac OS X 10.6 Snow Leopard</title>
     74
     75            <para>If you are using Mac OS X 10.6, there are two branches of Xcode which could be considered to be the
     76                latest, 3.2.x and 4.x. Xcode 4 costs money, but Xcode 3 is still available free of charge. There are two
     77                options for downloading it:
     78
     79                <orderedlist>
     80                    <listitem>
     81                        <para>Xcode 3.2 - smaller download, but you will need to run Software Update after installing to
     82                            get the latest version. Note that Apple might at some point discontinue providing these
     83                            updates via their update servers.</para>
     84                    </listitem>
     85                    <listitem>
     86                        <para>Xcode 3.2.6 and iOS SDK 4.3 - includes the iOS SDK which is not needed for
     87                            MacPorts.</para>
     88                    </listitem>
     89                </orderedlist>
     90
     91                Both are available from the <ulink url="https://developer.apple.com/downloads/index.action">Apple
     92                    developer website</ulink>. You may also be able to install Xcode 3.2 from your Mac OS X 10.6 DVD and
     93                then run Software Update to get the latest version.</para>
     94
     95            <para>Ensure that those of the following options that are available in the installer for your version of
     96                Xcode are selected:
     97
     98                <itemizedlist>
     99                    <listitem>
     100                        <guibutton>UNIX Development</guibutton>
     101                    </listitem>
     102                    <listitem>
     103                        <guibutton>System Tools</guibutton>
     104                    </listitem>
     105                    <listitem>
     106                        <guibutton>X11 SDK</guibutton>
     107                    </listitem>
     108                    <listitem>
     109                        <guibutton>Command Line Support</guibutton>
     110                    </listitem>
     111                </itemizedlist>
     112            </para>
     113        </section>
     114
     115        <section id="installing.xcode.other">
     116            <title>Install Xcode on older releases of Mac OS X</title>
     117
     118            <para>If you have an earlier release of Mac OS X, you may download the latest version of Xcode for OS X 10.5
     119                (Xcode 3.0 and Xcode 3.1 Developer Tools) or 10.4 (Xcode 2.4.1 and Xcode 2.5 Developer Tools) from the
     120                <ulink url="https://developer.apple.com/downloads/index.action">Apple developer website</ulink>.</para>
     121
     122            <para>Ensure that those of the following options that are available in the installer for your version of
     123                Xcode are selected:
     124
     125                <itemizedlist>
     126                    <listitem>
     127                        <guibutton>UNIX Development</guibutton>
     128                    </listitem>
     129                    <listitem>
     130                        <guibutton>System Tools</guibutton>
     131                    </listitem>
     132                    <listitem>
     133                        <guibutton>X11 SDK</guibutton>
     134                    </listitem>
     135                    <listitem>
     136                        <guibutton>Command Line Support</guibutton>
     137                    </listitem>
     138                </itemizedlist>
     139            </para>
     140        </section>
    46141    </section>
    47142
    48     <section id="installing.xcode.lion">
    49       <title>Install Xcode on OS X 10.7 Lion or OS X 10.8 Mountain Lion</title>
    50 
    51       <para>
    52         Download the latest version of Xcode <ulink url="https://developer.apple.com/downloads/index.action">from the
    53           Apple developer website</ulink> or get it <ulink url="http://itunes.apple.com/us/app/xcode/id497799835">using
    54           the Mac App Store</ulink>.
    55       </para>
    56 
    57       <section id="installing.xcode.lion.43">
    58         <title>Xcode 4.3 and later</title>
    59         <para>
    60           Xcode 4.3 and later do not automatically install the command line tools, but MacPorts requires them. To
    61           install them, open the Xcode application, go to the Preferences window, to the Downloads section, and click
    62           the Install button next to Command Line Tools. Be sure to return to this window after every Xcode upgrade to
    63           ensure that the command line tools are also upgraded.
    64         </para>
    65         <para>
    66           If you wish to create Installer packages with <userinput>port pkg</userinput>, you will also need to install
    67           PackageMaker, which is in the <quote>Auxiliary Tools for Xcode</quote> package as of Xcode 4.3. The download
    68           page for this package can be opened via the Xcode -> Open Developer Tool -> More Developer Tools... menu item.
    69           After downloading and mounting the disk image, drag the PackageMaker application to your /Applications
    70           directory.
    71         </para>
    72       </section>
     143    <section id="installing.macports">
     144        <title>Install MacPorts</title>
     145
     146        <para>If you are using OS X, you should install MacPorts using the OS X package installer unless you do not wish
     147            to install it to <filename>/opt/local/</filename>, the default MacPorts location, or if you wish to install
     148            a pre-release version of MacPorts base. However, if you wish to <link
     149                linkend="installing.macports.source.multiple">install multiple copies of MacPorts</link> or install
     150            MacPorts on another OS platform, you must <link linkend="installing.macports.source">install MacPorts from
     151                the source code</link>.</para>
     152
     153        <note>
     154            <para>Though a distinction is made between pre-release and release versions of MacPorts base, the ports
     155                collection supports no such distinction or versioning. The <link
     156                    linkend="using.port.selfupdate">selfupdate</link> command installs the latest port revisions from
     157                Subversion (at a slight delay), and updates MacPorts base to the latest released version.</para>
     158        </note>
     159
     160        <section id="installing.macports.binary">
     161            <title>OS X Package Install</title>
     162
     163            <para>The OS X package installer automatically installs MacPorts, <link linkend="installing.shell">sets the
     164                    shell environment</link>, and runs a <link linkend="using.port.selfupdate">selfupdate</link>
     165                operation to update the ports tree and MacPorts base with the latest release.</para>
     166
     167            <orderedlist>
     168                <listitem>
     169                    <para>Download the latest
     170                        <filename>MacPorts-&macports-version;-<emphasis>...</emphasis>.pkg</filename> installer from the
     171                        <ulink url="https://distfiles.macports.org/MacPorts/">MacPorts download directory</ulink>. Here
     172                        are direct links for the latest versions of OS X:</para>
     173
     174                    <variablelist>
     175                        <varlistentry>
     176                            <term>
     177                                OS X 10.9 Mavericks:
     178                            </term>
     179                            <listitem>
     180                                <ulink url="https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;-10.9-Mavericks.pkg">MacPorts-&macports-version;-10.9-Mavericks.pkg</ulink>
     181                            </listitem>
     182                        </varlistentry>
     183                        <varlistentry>
     184                            <term>
     185                                OS X 10.8 Mountain Lion:
     186                            </term>
     187                            <listitem>
     188                                <ulink url="https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;-10.8-MountainLion.pkg">MacPorts-&macports-version;-10.8-MountainLion.pkg</ulink>
     189                            </listitem>
     190                        </varlistentry>
     191                        <varlistentry>
     192                            <term>
     193                                OS X 10.7 Lion:
     194                            </term>
     195                            <listitem>
     196                                <ulink url="https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;-10.7-Lion.pkg">MacPorts-&macports-version;-10.7-Lion.pkg</ulink>
     197                            </listitem>
     198                        </varlistentry>
     199                    </variablelist>
     200                </listitem>
     201
     202                <listitem>
     203                    <para>Double-click the downloaded package installer to perform the default <quote>easy</quote>
     204                        install.</para>
     205                </listitem>
     206
     207                <listitem>
     208                    <para>After this step you are done already, MacPorts is now installed and your shell environment was
     209                        set up automatically by the installer. To confirm the installation is working as expected, now
     210                        try using the <command>port</command> command in a <emphasis>new</emphasis> terminal
     211                        window.</para>
     212
     213                    <programlisting><prompt>$</prompt><userinput>port version</userinput></programlisting>
     214                    <screen>Version: &macports-version;</screen>
     215
     216                    <para>In case of problems such as <quote>command not found</quote>, make sure that you opened a new
     217                        terminal window or consult <xref linkend="installing.shell"/>. Otherwise, please skip the
     218                        remainder of this chapter and continue with <xref linkend="using"/> in this guide.</para>
     219                </listitem>
     220            </orderedlist>
     221        </section>
     222
     223        <section id="installing.macports.source">
     224            <title>Source Install</title>
     225
     226            <para>If you installed MacPorts using the package installer, skip this section. To install MacPorts from the
     227                source code, follow the steps below.</para>
     228
     229            <orderedlist>
     230                <listitem>
     231                    <para>Download and extract the <ulink
     232                            url="https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;.tar.bz2"> MacPorts
     233                            &macports-version; tarball</ulink>. Either do so using your browser and the Finder, or use
     234                        the given commands in a terminal window.</para>
     235
     236                    <programlisting><prompt>$</prompt> <userinput>curl -O https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;.tar.bz2</userinput>
     237<!--                --><prompt>$</prompt> <userinput>tar xf MacPorts-&macports-version;.tar.bz2</userinput></programlisting>
     238                </listitem>
     239
     240                <listitem>
     241                    <para>Afterwards, perform the commands shown in the terminal window. If you wish to use a path other
     242                        than <filename>/opt/local</filename>, follow the instructions for <link
     243                            linkend="installing.macports.source.multiple">installing multiple copies of MacPorts</link>
     244                        instead.</para>
     245
     246                    <programlisting><prompt>$</prompt> <userinput>cd MacPorts-&macports-version;/</userinput>
     247<!--                --><prompt>$</prompt> <userinput>./configure</userinput>
     248<!--                --><prompt>$</prompt> <userinput>make</userinput>
     249<!--                --><prompt>$</prompt> <userinput>sudo make install</userinput></programlisting>
     250                </listitem>
     251
     252                <listitem>
     253                    <para>Please continue with <xref linkend="installing.shell" /> to set up your shell
     254                        environment.</para>
     255                </listitem>
     256            </orderedlist>
     257        </section>
     258
     259        <section id="installing.macports.subversion">
     260            <title>Subversion Install</title>
     261
     262            <para>If you installed MacPorts using the package installer, skip this section.</para>
     263
     264            <para>There are times when some may want to run MacPorts from a version newer than the current stable
     265                release. Maybe there's a new feature that you'd like to use, or it fixes an issue you've encountered, or
     266                you just like to be on the cutting edge. These steps explain how to run completely from trunk, using
     267                only Subversion to keep MacPorts up to date.</para>
     268
     269            <orderedlist>
     270                <listitem>
     271                    <para>Check out MacPorts source</para>
     272
     273                    <para>Pick a location to store a working copy of the MacPorts code. For this example,
     274                        <filename>/opt/mports</filename> will be used, but you can put the source anywhere. This example
     275                        will create <filename>/opt/mports/trunk</filename> containing everything needed for
     276                        MacPorts.</para>
     277
     278                    <programlisting><prompt>$</prompt> <userinput>mkdir -p /opt/mports</userinput>
     279<!--                --><prompt>$</prompt> <userinput>cd /opt/mports</userinput>
     280<!--                --><prompt>$</prompt> <userinput>svn checkout https://svn.macports.org/repository/macports/trunk</userinput></programlisting>
     281
     282                    <note>
     283                        <para>You only really need the base subdirectory to run MacPorts, so you can avoid checking out
     284                            the rest if you don't want to use a Subversion-based ports tree (see Step 3 below). To just
     285                            get the base directory, append <filename>/base</filename> to the end of the svn checkout
     286                            command above. The resulting directory will then be
     287                            <filename>/opt/mports/base</filename>.</para>
     288                    </note>
     289                </listitem>
     290
     291                <listitem>
     292                    <para>Build and Install MacPorts</para>
     293
     294                    <para>MacPorts uses autoconf and makefiles for installation. These commands will build and install
     295                        MacPorts to <filename>/opt/local</filename>. You can add the <option>--prefix</option> option to
     296                        <filename>./configure</filename> to relocate MacPorts to another directory if needed.</para>
     297
     298                    <programlisting><prompt>$</prompt> <userinput>cd /opt/mports/trunk/base</userinput>
     299<!--                --><prompt>$</prompt> <userinput>./configure --enable-readline</userinput>
     300<!--                --><prompt>$</prompt> <userinput>make</userinput>
     301<!--                --><prompt>$</prompt> <userinput>sudo make install</userinput>
     302<!--                --><prompt>$</prompt> <userinput>make distclean</userinput></programlisting>
     303                </listitem>
     304
     305                <listitem>
     306                    <para>(Optional) Configure MacPorts to use port information from Subversion</para>
     307
     308                    <para>This step is useful if you want to do port development. Open
     309                        <filename>/opt/local/etc/macports/sources.conf</filename> in a text editor. The last line which
     310                        should look like this:</para>
     311
     312                    <programlisting>rsync://rsync.macports.org/release/tarballs/ports.tar [default]</programlisting>
     313
     314                    <para>Change it to point to the working copy you checked out:</para>
     315
     316                    <programlisting>file:///opt/mports/trunk/dports [default]</programlisting>
     317
     318                    <para>Now MacPorts will look for portfiles in the working copy and use Subversion instead of rsync
     319                        to update your ports tree.</para>
     320                </listitem>
     321
     322                <listitem>
     323                    <para>Environment</para>
     324
     325                    <para>You should setup your PATH and other environment options according to <xref
     326                        linkend="installing.shell" />.</para>
     327                </listitem>
     328            </orderedlist>
     329        </section>
     330
     331        <section id="installing.macports.source.multiple">
     332            <title>Install Multiple MacPorts Copies</title>
     333
     334            <para>Occasionally a MacPorts developer may wish to install more than one MacPorts instance on the same
     335                host. Only one copy of MacPorts may use the default prefix <filename>/opt/local</filename>, so for
     336                additional installations use the option <option>--prefix</option> as shown below. It's also recommended
     337                to change the applications dir using <option>--with-applications-dir</option> to avoid conflicts in
     338                <filename>/Applications/MacPorts</filename>.</para>
     339
     340            <note>
     341                <para>The first command temporarily removes the standard MacPorts binary paths because they must not be
     342                    present while installing a second instance.</para>
     343            </note>
     344
     345            <programlisting><prompt>$</prompt> <userinput>export PATH=/bin:/sbin:/usr/bin:/usr/sbin</userinput>
     346<!--                --><prompt>$</prompt> <userinput>MP_PREFIX=/opt/macports-test</userinput>
     347<!--                --><prompt>$</prompt> <userinput>./configure --prefix=$MP_PREFIX --with-applications-dir=$MP_PREFIX/Applications</userinput>
     348<!--                --><prompt>$</prompt> <userinput>make</userinput>
     349<!--                --><prompt>$</prompt> <userinput>sudo make install</userinput></programlisting>
     350
     351            <para>After installing the second instance you might need to add
     352                <programlisting>startupitem_install no</programlisting>
     353                to <filename>$MP_PREFIX/etc/macports/macports.conf</filename> to avoid conflicts in
     354                <filename>/Library/LaunchAgents</filename>.</para>
     355        </section>
    73356    </section>
    74357
    75     <section id="installing.xcode.snowleopard">
    76       <title>Install Xcode on Mac OS X 10.6 Snow Leopard</title>
    77 
    78       <para>
    79         If you are using Mac OS X 10.6, there are two branches of Xcode which could be considered to be the latest,
    80         3.2.x and 4.x. Xcode 4 costs money, but Xcode 3 is still available free of charge. There are two options for
    81         downloading it:
    82         <orderedlist>
    83           <listitem>
    84             <para>
    85               Xcode 3.2 - smaller download, but you will need to run Software Update after installing to get the latest
    86               version. Note that Apple might at some point discontinue providing these updates via their update servers.
    87             </para>
    88           </listitem>
    89           <listitem>
    90             <para>
    91               Xcode 3.2.6 and iOS SDK 4.3 - includes the iOS SDK which is not needed for MacPorts.
    92             </para>
    93           </listitem>
    94         </orderedlist>
    95         Both are available from the <ulink url="https://developer.apple.com/downloads/index.action">Apple developer
    96           website</ulink>. You may also be able to install Xcode 3.2 from your Mac OS X 10.6 DVD and then run Software
    97         Update to get the latest version.
    98       </para>
    99 
    100       <para>
    101         Ensure that those of the following options that are available in the installer for your version of Xcode are
    102         selected:
    103         <itemizedlist>
    104           <listitem>
    105             <guibutton>UNIX Development</guibutton>
    106           </listitem>
    107           <listitem>
    108             <guibutton>System Tools</guibutton>
    109           </listitem>
    110           <listitem>
    111             <guibutton>X11 SDK</guibutton>
    112           </listitem>
    113           <listitem>
    114             <guibutton>Command Line Support</guibutton>
    115           </listitem>
    116         </itemizedlist>
    117       </para>
     358    <section id="installing.macports.upgrade">
     359        <title>MacPorts Upgrade</title>
     360
     361        <para>MacPorts base upgrades are performed automatically (when a newer release is available) during a <link
     362                linkend="using.port.selfupdate">selfupdate</link> operation. To upgrade a copy of MacPorts that was
     363            installed from source to the newer release of the source code, simply repeat the <link
     364                linkend="installing.macports.source">source install</link> with the newer version of the MacPorts source
     365            code.</para>
    118366    </section>
    119367
    120     <section id="installing.xcode.other">
    121       <title>Install Xcode on older releases of Mac OS X</title>
    122 
    123       <para>
    124         If you have an earlier release of Mac OS X, you may download the latest version of Xcode for OS X 10.5 (Xcode
    125         3.0 and Xcode 3.1 Developer Tools) or 10.4 (Xcode 2.4.1 and Xcode 2.5 Developer Tools) from the <ulink
    126           url="https://developer.apple.com/downloads/index.action">Apple developer website</ulink>.
    127       </para>
    128 
    129       <para>
    130         Ensure that those of the following options that are available in the installer for your version of Xcode are
    131         selected:
    132         <itemizedlist>
    133           <listitem>
    134             <guibutton>UNIX Development</guibutton>
    135           </listitem>
    136           <listitem>
    137             <guibutton>System Tools</guibutton>
    138           </listitem>
    139           <listitem>
    140             <guibutton>X11 SDK</guibutton>
    141           </listitem>
    142           <listitem>
    143             <guibutton>Command Line Support</guibutton>
    144           </listitem>
    145         </itemizedlist>
    146       </para>
     368    <section id="installing.macports.uninstalling">
     369        <title>Uninstall</title>
     370
     371        <para>Uninstalling MacPorts can be a drastic step, and depending on the issue you are experiencing, you may not
     372            need to do so. If you are unsure, ask on the <ulink
     373                url="http://lists.macosforge.org/mailman/listinfo/macports-users">macports-users</ulink> mailing list
     374            first.</para>
     375
     376        <para>If you need to uninstall MacPorts, and your <command>port</command> command is functioning, first
     377        uninstall all the installed ports by running this command in the Terminal:</para>
     378
     379        <programlisting><prompt>$</prompt> <userinput>sudo port -fp uninstall installed</userinput></programlisting>
     380
     381        <para>All that will be left in your installation prefix now will be files that were not registered to any port.
     382            This includes configuration files, databases, any files which MacPorts renamed in order to allow a forced
     383            installation or upgrade, and the base MacPorts software itself. You may wish to save your configuration
     384            files (most are in <filename>$prefix/etc</filename>), databases, or any other unique data by moving it
     385            aside.</para>
     386
     387        <para>To remove all remaining traces of MacPorts, run the following command in the Terminal. If you have changed
     388            <varname>prefix</varname>, <varname>applications_dir</varname> or <varname>frameworks_dir</varname> from
     389            their default values, then replace <filename>/opt/local</filename> with your <varname>prefix</varname>,
     390            replace <filename>/Applications/MacPorts</filename> with your <varname>applications_dir</varname>, and/or
     391            add your <varname>frameworks_dir</varname> to the list, respectively.</para>
     392
     393        <programlisting><prompt>$</prompt> <userinput>sudo rm -rf \
     394        /opt/local \
     395        /Applications/DarwinPorts \
     396        /Applications/MacPorts \
     397        /Library/LaunchDaemons/org.macports.* \
     398        /Library/Receipts/DarwinPorts*.pkg \
     399        /Library/Receipts/MacPorts*.pkg \
     400        /Library/StartupItems/DarwinPortsStartup \
     401        /Library/Tcl/darwinports1.0 \
     402        /Library/Tcl/macports1.0 \
     403        ~/.macports</userinput></programlisting>
     404
     405        <para>If you use a shell other than bash (perhaps tcsh), you may need to adjust the above to fit your shell's
     406            syntax. Also note that depending on which version of MacPorts you have and which ports you have installed,
     407            not all of the above paths will exist on your system. This is OK.</para>
    147408    </section>
    148   </section>
    149 
    150   <section id="installing.macports">
    151     <title>Install MacPorts</title>
    152 
    153         <para>If you are using OS X, you should install MacPorts using the OS
    154         X package installer unless you do not wish to install it to
    155         <filename>/opt/local/</filename>, the default MacPorts location, or if you
    156         wish to install a pre-release version of MacPorts base. However, if you
    157         wish to <link linkend="installing.macports.source.multiple">install
    158                 multiple copies of MacPorts</link> or install MacPorts on another OS
    159         platform, you must <link linkend="installing.macports.source">install
    160                 MacPorts from the source code</link>.</para>
    161 
    162     <note>
    163       <para>Though a distinction is made between pre-release and release
    164       versions of MacPorts base, the ports collection supports no such
    165       distinction or versioning. The <link
    166       linkend="using.port.selfupdate">selfupdate</link> command installs the
    167       latest port revisions from Subversion (at a slight delay), and updates
    168       MacPorts base to the latest released version.</para>
    169     </note>
    170 
    171     <section id="installing.macports.binary">
    172       <title>OS X Package Install</title>
    173 
    174       <para>The OS X package installer automatically installs MacPorts,
    175       <link linkend="installing.shell">sets the shell environment</link>, and
    176       runs a <link linkend="using.port.selfupdate">selfupdate</link> operation
    177       to update the ports tree and MacPorts base with the latest
    178       release.</para>
    179 
    180       <orderedlist>
    181         <listitem>
    182             <para>Download the latest <filename>MacPorts-&macports-version;-<emphasis>...</emphasis>.pkg</filename>
    183           installer from the <ulink
    184           url="https://distfiles.macports.org/MacPorts/">MacPorts
    185           download directory</ulink>. Here are direct links for the latest versions of OS X:</para>
    186 
    187           <variablelist>
    188             <varlistentry>
    189             <term>
    190                 OS X 10.9 Mavericks:
    191             </term>
    192             <listitem>
    193                 <ulink url="https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;-10.9-Mavericks.pkg">MacPorts-&macports-version;-10.9-Mavericks.pkg</ulink>
    194             </listitem>
    195             </varlistentry>
    196             <varlistentry>
    197             <term>
    198                 OS X 10.8 Mountain Lion:
    199             </term>
    200             <listitem>
    201                 <ulink url="https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;-10.8-MountainLion.pkg">MacPorts-&macports-version;-10.8-MountainLion.pkg</ulink>
    202             </listitem>
    203             </varlistentry>
    204             <varlistentry>
    205             <term>
    206                 OS X 10.7 Lion:
    207             </term>
    208             <listitem>
    209                 <ulink url="https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;-10.7-Lion.pkg">MacPorts-&macports-version;-10.7-Lion.pkg</ulink>
    210             </listitem>
    211             </varlistentry>
    212           </variablelist>
    213         </listitem>
    214 
    215         <listitem>
    216           <para>Double-click the downloaded package installer to perform the default <quote>easy</quote> install.</para>
    217         </listitem>
    218 
    219         <listitem>
    220             <para>After this step you are done already, MacPorts is now
    221              installed and your shell environment was set up automatically
    222              by the installer. To confirm the installation is working as
    223              expected, now try using the <command>port</command> command in
    224              a <emphasis>new</emphasis> terminal window.</para>
    225 
    226             <programlisting><prompt>%%</prompt> <userinput>port version</userinput></programlisting>
    227             <screen>Version: &macports-version;</screen>
    228 
    229             <para>In case of problems such as <quote>command not found</quote>,
    230             make sure that you opened a new terminal window, consult <xref
    231                 linkend="installing.shell"/>. Otherwise, please skip the
    232             remainder of this chapter and continue with <xref linkend="using"/>
    233             in this guide.</para>
    234         </listitem>
    235       </orderedlist>
     409
     410    <section id="installing.shell">
     411        <title>MacPorts and the Shell</title>
     412
     413        <para>MacPorts requires that some environment variables be set in the shell. When MacPorts is installed using
     414            the OS X package installer, a <quote>postflight</quote> script is run after installation that automatically
     415            adds or modifies a shell configuration file in your home directory, ensuring that it defines variables
     416            according to the rules described in the following section. Those <link
     417                linkend="installing.macports.source">installing MacPorts from source code</link> must modify their
     418            environment manually using the rules as a guide.</para>
     419
     420        <para>Depending on your shell and which configuration files already exist, the installer may use
     421            <filename>.profile</filename>, <filename>.bash_login</filename>, <filename>.bash_profile</filename>,
     422            <filename>.tcshrc</filename>, or <filename>.cshrc</filename>.</para>
     423
     424        <section id="installing.shell.postflight">
     425            <title>The Postflight Script</title>
     426
     427            <para>The postflight script automatically sets the <varname>PATH</varname> variable, and optionally the
     428                <varname>MANPATH</varname> and <varname>DISPLAY</varname> variables according to the rules described
     429                below. If a current shell configuration file exists at installation time it is renamed to
     430                <quote>mpsaved_$timestamp</quote>. Those <link linkend="installing.macports.source">installing MacPorts
     431                    from source code</link> must modify their environment manually using the rules as a guide.</para>
     432
     433            <itemizedlist>
     434                <listitem>
     435                    <para>Required: <varname>PATH</varname> variable</para>
     436
     437                    <para>This variable is set by the postflight script to append the MacPorts executable paths to the
     438                        default path as shown. The MacPorts paths are appended at the front of <varname>PATH</varname>
     439                        so the MacPorts libraries will take precedence over vendor-supplied libraries for ported
     440                        software at runtime.</para>
     441
     442                    <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
     443
     444                    <note>
     445                        <para>The user environment's $PATH is not in effect while ports are being installed, because the
     446                            $PATH is scrubbed before ports are installed, and restored afterwards. To change the search
     447                            path for locating system executables (rsync, tar, etc.) during port installation, see the
     448                            <link linkend="internals.configuration-files.macports-conf">macports.conf</link> file
     449                            variable <varname>binpath</varname>. But changing this variable is for advanced users only,
     450                            and is not generally needed or recomended.</para>
     451                    </note>
     452                </listitem>
     453
     454                <listitem>
     455                    <para>Optional: <varname>MANPATH</varname> variable</para>
     456
     457                    <para>Condition: If prior to MacPorts installation a <varname>MANPATH</varname> variable exists in
     458                        a current <filename>.profile</filename> that contains neither the value
     459                        <filename>${prefix}/share/man,</filename> nor any empty values, the postflight script sets the
     460                        <varname>MANPATH</varname> variable as shown below. Otherwise, the <varname>MANPATH</varname>
     461                        variable is omitted.</para>
     462
     463                    <programlisting>export MANPATH=/opt/local/share/man:$MANPATH</programlisting>
     464
     465                    <para>Here are some examples of paths that contain empty values:</para>
     466
     467                    <simplelist>
     468                        <member>/usr/share/man:</member>
     469                        <member>:/usr/share/man</member>
     470                        <member>/usr/share/man::/usr/X11R6/man</member>
     471                    </simplelist>
     472                </listitem>
     473
     474                <listitem>
     475                    <para>Optional: <varname>DISPLAY</varname> variable</para>
     476
     477                    <para>Condition: If installing on a Mac OS X version earlier than 10.5 (Leopard), and if a shell
     478                        configuration file exists at time of MacPorts installation without a <varname>DISPLAY</varname>
     479                        variable, the postflight script sets a <varname>DISPLAY</varname> variable as shown below. The
     480                        <varname>DISPLAY</varname> variable is always omitted on Mac OS X 10.5 or higher.</para>
     481
     482                    <programlisting>export DISPLAY=:0.0</programlisting>
     483                </listitem>
     484            </itemizedlist>
     485        </section>
     486
     487        <section id="installing.shell.verifyprofile">
     488            <title>Verify the configuration file</title>
     489
     490            <para>To verify that the file containing the MacPorts variables is in effect, type <command>env</command> in
     491                the terminal to verify the current environment settings after the file has been created. Example output
     492                for the <command>env</command> command is shown below.</para>
     493
     494            <note>
     495                <para>Changes to shell configuration files do not take effect until a new terminal session is
     496                    opened.</para>
     497            </note>
     498
     499            <screen>MANPATH=
     500<!--        -->TERM_PROGRAM=Apple_Terminal
     501<!--        -->TERM=xterm-color
     502<!--        -->SHELL=/bin/bash
     503<!--        -->TERM_PROGRAM_VERSION=237
     504<!--        -->USER=joebob
     505<!--        -->__CF_USER_TEXT_ENCODING=0x1FC:0:0
     506<!--        -->PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
     507<!--        -->PWD=/Users/joebob
     508<!--        -->EDITOR=/usr/bin/pico
     509<!--        -->SHLVL=1
     510<!--        -->HOME=/Users/joebob
     511<!--        -->LOGNAME=joebob
     512<!--        -->DISPLAY=:0.0
     513<!--        -->SECURITYSESSIONID=b0cea0
     514<!--        -->_=/usr/bin/env</screen>
     515        </section>
     516
     517        <section id="installing.shell.editorvar">
     518            <title>Optional Editor Variables</title>
     519
     520            <para>You can set an environment variable in order to use your favorite text editor with edit option of port
     521                command.</para> <para>MacPorts will check <varname>MP_EDITOR</varname>, <varname>VISUAL</varname> and
     522                <varname>EDITOR</varname> in this order, allowing you to either use a default editor shared with other
     523                programs (<varname>VISUAL</varname> and <varname>EDITOR</varname>) or a Macports' specific one
     524                (<varname>MP_EDITOR</varname>).</para>
     525
     526            <para>For example, to use the nano editor, add this line to your bash config:</para>
     527
     528            <programlisting>export EDITOR=/usr/bin/nano</programlisting>
     529
     530            <para>To use the user-friendly GUI editor <ulink
     531                    url="http://www.barebones.com/products/textwrangler/">TextWrangler</ulink> (installation required),
     532                add this line:</para>
     533
     534            <programlisting>export EDITOR=/usr/bin/edit</programlisting>
     535
     536            <para>To keep a command-line text editor as default while using a graphic editor with portfiles, add
     537                this:</para>
     538
     539            <programlisting>export EDITOR=/usr/bin/vi
     540<!--        -->export MP_EDITOR=/usr/bin/edit</programlisting>
     541        </section>
    236542    </section>
    237 
    238     <section id="installing.macports.source">
    239       <title>Source Install</title>
    240 
    241       <para>If you installed MacPorts using the package installer, skip this
    242       section. To install MacPorts from the source code, follow the steps
    243       below.</para>
    244 
    245       <orderedlist>
    246         <listitem>
    247           <para>Download and extract the <ulink url="https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;.tar.bz2">
    248           MacPorts &macports-version; tarball</ulink>. Either do so using your browser and the Finder, or use the given commands
    249           in a terminal window.</para>
    250 
    251           <programlisting><prompt>%%</prompt> <userinput>curl -O https://distfiles.macports.org/MacPorts/MacPorts-&macports-version;.tar.bz2</userinput>
    252 <prompt>%%</prompt> <userinput>tar xf MacPorts-&macports-version;.tar.bz2</userinput></programlisting>
    253         </listitem>
    254 
    255         <listitem>
    256           <para>Afterwards, perform the commands shown in the terminal window. If you wish
    257           to use a path other than <filename>/opt/local</filename>, follow
    258           the instructions for <link linkend="installing.macports.source.multiple">installing
    259           multiple copies of MacPorts</link> instead.</para>
    260 
    261           <programlisting><prompt>%%</prompt> <userinput>cd MacPorts-&macports-version;/</userinput>
    262 <prompt>%%</prompt> <userinput>./configure</userinput>
    263 <prompt>%%</prompt> <userinput>make</userinput>
    264 <prompt>%%</prompt> <userinput>sudo make install</userinput></programlisting>
    265         </listitem>
    266 
    267         <listitem>
    268           <para>Please continue with <xref linkend="installing.shell" /> to set up your shell environment.</para>
    269         </listitem>
    270       </orderedlist>
    271     </section>
    272 
    273     <section id="installing.macports.subversion">
    274       <title>Subversion Install</title>
    275 
    276       <para>If you installed MacPorts using the package installer, skip this
    277       section.</para>
    278 
    279       <para>There are times when some may want to run MacPorts from a version
    280       newer than the current stable release. Maybe there's a new feature that
    281       you'd like to use, or it fixes an issue you've encountered, or you just
    282       like to be on the cutting edge. These steps explain how to run
    283       completely from trunk, using only Subversion to keep MacPorts up to
    284       date.</para>
    285 
    286       <orderedlist>
    287         <listitem>
    288           <para>Check out MacPorts source</para>
    289 
    290           <para>Pick a location to store a working copy of the MacPorts code.
    291           For this example, <filename>/opt/mports</filename> will be used, but
    292           you can put the source anywhere. This example will create
    293           <filename>/opt/mports/trunk</filename> containing everything needed
    294           for MacPorts.</para>
    295 
    296           <programlisting><prompt>%%</prompt> <userinput>mkdir -p /opt/mports</userinput>
    297 <prompt>%%</prompt> <userinput>cd /opt/mports</userinput>
    298 <prompt>%%</prompt> <userinput>svn checkout https://svn.macports.org/repository/macports/trunk</userinput></programlisting>
    299 
    300           <note>
    301               <para>
    302              You only really need the base subdirectory to run MacPorts, so you can avoid checking out the rest if you don't want to use a Subversion-based ports tree (see Step 3 below). To just get the base directory, append
    303 
    304             <filename>/base</filename>
    305 
    306              to the end of the svn checkout command above. The resulting directory will then be
    307 
    308             <filename>/opt/mports/base</filename>
    309 
    310             </para>
    311           </note>
    312         </listitem>
    313 
    314         <listitem>
    315           <para>Build and Install MacPorts</para>
    316 
    317           <para>MacPorts uses autoconf and makefiles for installation. These
    318           commands will build and install MacPorts to
    319           <filename>/opt/local</filename>. You can add the
    320           <option>--prefix</option> option to <filename>./configure</filename>
    321           to relocate MacPorts to another directory if needed.</para>
    322 
    323           <programlisting><prompt>%%</prompt> <userinput>cd /opt/mports/trunk/base</userinput>
    324 <prompt>%%</prompt> <userinput>./configure --enable-readline</userinput>
    325 <prompt>%%</prompt> <userinput>make</userinput>
    326 <prompt>%%</prompt> <userinput>sudo make install</userinput>
    327 <prompt>%%</prompt> <userinput>make distclean</userinput></programlisting>
    328         </listitem>
    329 
    330         <listitem>
    331           <para>(Optional) Configure MacPorts to use port information from
    332           Subversion</para>
    333 
    334           <para>This step is useful if you want to do port development. Open
    335           <filename>/opt/local/etc/macports/sources.conf</filename> in a text
    336           editor. The last line which should look like this:</para>
    337 
    338           <programlisting>rsync://rsync.macports.org/release/tarballs/ports.tar [default]</programlisting>
    339 
    340           <para>Change it to point to the working copy you checked out:</para>
    341 
    342           <programlisting>file:///opt/mports/trunk/dports [default]</programlisting>
    343 
    344           <para>Now MacPorts will look for portfiles in the working
    345           copy.</para>
    346         </listitem>
    347 
    348         <listitem>
    349           <para>Environment</para>
    350 
    351           <para>You should setup your PATH and other environment options
    352           according to <xref linkend="installing.shell" />.</para>
    353         </listitem>
    354       </orderedlist>
    355     </section>
    356 
    357     <section id="installing.macports.source.multiple">
    358       <title>Install Multiple MacPorts Copies</title>
    359 
    360       <para>Occasionally a MacPorts developer may wish to install more than
    361       one MacPorts instance on the same host. Only one copy of MacPorts may
    362       use the default prefix <filename>/opt/local</filename>, so
    363       for additional installations use the option
    364       <option>--prefix</option> as shown below. It's also recommended
    365       to change the applications dir using
    366       <option>--with-applications-dir</option> to avoid conflicts in
    367       <filename>/Applications/MacPorts</filename>.</para>
    368 
    369       <note>
    370         <para>The first command temporarily removes the standard MacPorts
    371         binary paths because they must not be present while installing a
    372         second instance.</para>
    373       </note>
    374 
    375       <programlisting><prompt>%%</prompt> <userinput>export PATH=/bin:/sbin:/usr/bin:/usr/sbin</userinput>
    376 <prompt>%%</prompt> <userinput>MP_PREFIX=/opt/macports-test</userinput>
    377 <prompt>%%</prompt> <userinput>./configure --prefix=$MP_PREFIX --with-applications-dir=$MP_PREFIX/Applications</userinput>
    378 <prompt>%%</prompt> <userinput>make</userinput>
    379 <prompt>%%</prompt> <userinput>sudo make install</userinput>
    380 </programlisting>
    381 
    382       <para>After installing the second instance you might need to add
    383       <programlisting>startupitem_install no</programlisting> to
    384       <filename>$MP_PREFIX/etc/macports/macports.conf</filename> to avoid
    385       conflicts in <filename>/Library/LaunchAgents</filename>.
    386       </para>
    387     </section>
    388   </section>
    389 
    390   <section id="installing.macports.upgrade">
    391     <title>MacPorts Upgrade</title>
    392 
    393     <para>MacPorts base upgrades are performed automatically (when a newer
    394     release is available) during a <link
    395     linkend="using.port.selfupdate">selfupdate</link> operation. To upgrade a
    396     copy of MacPorts that was installed from source to the newer release of
    397     the source code, simply repeat the <link
    398     linkend="installing.macports.source">source install</link> with the newer
    399     version of the MacPorts source code.</para>
    400   </section>
    401 
    402   <section id="installing.macports.uninstalling">
    403     <title>Uninstall</title>
    404 
    405     <para>Uninstalling MacPorts can be a drastic step, and depending on the
    406     issue you are experiencing, you may not need to do so. If you are unsure,
    407     ask on the
    408     <ulink url="http://lists.macosforge.org/mailman/listinfo/macports-users">macports-users</ulink>
    409     mailing list first.</para>
    410    
    411     <para>If you need to uninstall MacPorts, and your <command>port</command> command is
    412     functioning, first uninstall all the installed ports by running this
    413     command in the Terminal:</para>
    414     <programlisting><prompt>%%</prompt> <userinput>sudo port -fp uninstall installed</userinput></programlisting>
    415 
    416     <para>All that will be left in your installation prefix now will be files
    417     that were not registered to any port. This includes configuration
    418     files, databases, any files which MacPorts
    419     renamed in order to allow a forced installation or upgrade, and the base
    420     MacPorts software itself. You may wish to save your configuration files
    421     (most are in <filename>${prefix}/etc</filename>), databases, or any other
    422     unique data by moving it aside.</para>
    423 
    424     <para>To remove all remaining traces of MacPorts, run the following
    425     command in the Terminal. If you have changed <varname>prefix</varname>,
    426     <varname>applications_dir</varname> or <varname>frameworks_dir</varname>
    427     from their default values, then replace <filename>/opt/local</filename>
    428     with your <varname>prefix</varname>, replace <filename>/Applications/MacPorts</filename>
    429     with your <varname>applications_dir</varname>, and/or add your
    430     <varname>frameworks_dir</varname> to the list, respectively.</para>
    431     <programlisting><prompt>%%</prompt> <userinput>sudo rm -rf \
    432     /opt/local \
    433     /Applications/DarwinPorts \
    434     /Applications/MacPorts \
    435     /Library/LaunchDaemons/org.macports.* \
    436     /Library/Receipts/DarwinPorts*.pkg \
    437     /Library/Receipts/MacPorts*.pkg \
    438     /Library/StartupItems/DarwinPortsStartup \
    439     /Library/Tcl/darwinports1.0 \
    440     /Library/Tcl/macports1.0 \
    441     ~/.macports</userinput></programlisting>
    442  
    443   <para>If you use a shell other than bash (perhaps tcsh), you may need to
    444   adjust the above to fit your shell's syntax. Also note that depending on which
    445   version of MacPorts you have and which ports you have installed, not all of
    446   the above paths will exist on your system. This is OK.</para>
    447   </section>
    448 
    449   <section id="installing.shell">
    450     <title>MacPorts and the Shell</title>
    451 
    452     <para>MacPorts requires that some environment variables be set in the
    453     shell. When MacPorts is installed using the OS X package installer, a
    454     <quote>postflight</quote> script is run after installation that
    455     automatically adds or modifies a shell configuration file in your home directory,
    456     ensuring that it defines variables
    457     according to the rules described in the following section. Those <link
    458     linkend="installing.macports.source">installing MacPorts from source
    459     code</link> must modify their environment manually using the rules as a
    460     guide.</para>
    461 
    462     <para>Depending on your shell and which configuration files already exist, the
    463     installer may use <filename>.profile</filename>, <filename>.bash_login</filename>,
    464     <filename>.bash_profile</filename>, <filename>.tcshrc</filename>, or
    465     <filename>.cshrc</filename>.</para>
    466 
    467     <section id="installing.shell.postflight">
    468       <title>The Postflight Script</title>
    469 
    470       <para>The postflight script automatically sets
    471       the <varname>PATH</varname>
    472       variable, and optionally the <varname>MANPATH</varname> and
    473       <varname>DISPLAY</varname> variables according to the rules described
    474       below. If a current shell configuration file exists at
    475       installation time it is renamed to <quote>mpsaved_$timestamp</quote>.
    476       Those <link linkend="installing.macports.source">installing MacPorts
    477       from source code</link> must modify their environment manually using the
    478       rules as a guide.</para>
    479 
    480       <itemizedlist>
    481         <listitem>
    482           <para>Required: <varname>PATH</varname> variable</para>
    483 
    484           <para>This variable is set by the postflight script to append the
    485           MacPorts executable paths to the default path as shown. The MacPorts
    486           paths are appended at the front of <varname>PATH</varname> so the
    487           MacPorts libraries will take precedence over vendor-supplied
    488           libraries for ported software at runtime.</para>
    489 
    490           <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
    491 
    492           <note>
    493             <para>The user environment's $PATH is not in effect while ports
    494             are being installed, because the $PATH is scrubbed before ports
    495             are installed, and restored afterwards. To change the search path
    496             for locating system executables (rsync, tar, etc.) during port
    497             installation, see the <link
    498             linkend="internals.configuration-files.macports-conf">macports.conf</link>
    499             file variable <varname>binpath</varname>. But changing this
    500             variable is for advanced users only, and is not generally needed
    501             or recomended.</para>
    502           </note>
    503         </listitem>
    504 
    505         <listitem>
    506           <para>Optional: <varname>MANPATH</varname> variable</para>
    507 
    508           <para>Condition: If prior to MacPorts installation a
    509           <varname>MANPATH</varname> variable exists in a current
    510           <filename>.profile</filename> that contains neither the value
    511           <filename>${prefix}/share/man,</filename> nor any empty values, the
    512           postflight script sets the <varname>MANPATH</varname> variable as
    513           shown below. Otherwise, the <varname>MANPATH</varname> variable is
    514           omitted.</para>
    515 
    516           <programlisting>export MANPATH=/opt/local/share/man:$MANPATH</programlisting>
    517 
    518           <para>Here are some examples of paths that contain empty
    519           values:</para>
    520 
    521           <simplelist>
    522             <member>/usr/share/man:</member>
    523 
    524             <member>:/usr/share/man</member>
    525 
    526             <member>/usr/share/man::/usr/X11R6/man</member>
    527           </simplelist>
    528         </listitem>
    529 
    530         <listitem>
    531           <para>Optional: <varname>DISPLAY</varname> variable</para>
    532 
    533           <para>Condition: If installing on a Mac OS X version earlier than
    534           10.5 (Leopard), and if a shell configuration file exists
    535           at time of MacPorts installation without a
    536           <varname>DISPLAY</varname> variable, the postflight script sets a
    537           <varname>DISPLAY</varname> variable as shown below. The
    538           <varname>DISPLAY</varname> variable is always omitted on Mac OS X
    539           10.5 or higher.</para>
    540 
    541           <programlisting>export DISPLAY=:0.0</programlisting>
    542         </listitem>
    543       </itemizedlist>
    544     </section>
    545 
    546     <section id="installing.shell.verifyprofile">
    547       <title>Verify the configuration file</title>
    548 
    549       <para>To verify that the file containing the
    550       MacPorts variables is in effect, type <command>env</command> in the
    551       terminal to verify the current environment settings after the
    552       file has been created. Example output for the
    553       <command>env</command> command is shown below.</para>
    554 
    555       <note>
    556         <para>Changes to shell configuration files do not take effect
    557         until a new terminal session is opened.</para>
    558       </note>
    559 
    560       <screen>MANPATH=
    561 TERM_PROGRAM=Apple_Terminal
    562 TERM=xterm-color
    563 SHELL=/bin/bash
    564 TERM_PROGRAM_VERSION=237
    565 USER=joebob
    566 __CF_USER_TEXT_ENCODING=0x1FC:0:0
    567 PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
    568 PWD=/Users/joebob
    569 EDITOR=/usr/bin/pico
    570 SHLVL=1
    571 HOME=/Users/joebob
    572 LOGNAME=joebob
    573 DISPLAY=:0.0
    574 SECURITYSESSIONID=b0cea0
    575 _=/usr/bin/env</screen>
    576     </section>
    577 
    578     <section id="installing.shell.editorvar">
    579       <title>Optional Editor Variables</title>
    580 
    581       <para>You can set an environment variable in order to use your favorite
    582       text editor with edit option of port command.</para>
    583       <para>MacPorts will check <varname>MP_EDITOR</varname>,
    584       <varname>VISUAL</varname> and <varname>EDITOR</varname> in this order,
    585       allowing you to either use a default editor shared with other programs
    586       (<varname>VISUAL</varname> and <varname>EDITOR</varname>) or a Macports'
    587       specific one (<varname>MP_EDITOR</varname>).</para>
    588 
    589       <para>For example, to use the nano editor, add this line to your
    590       bash config:</para>
    591 
    592       <programlisting>export EDITOR=/usr/bin/nano</programlisting>
    593 
    594       <para>To use the user-friendly GUI editor <ulink
    595       url="http://www.barebones.com/products/textwrangler/">TextWrangler</ulink>
    596       (installation required), add this line:</para>
    597 
    598       <programlisting>export EDITOR=/usr/bin/edit</programlisting>
    599      
    600       <para>To keep a command-line text editor as default while using a graphic editor with
    601       portfiles, add this: </para>
    602 
    603       <programlisting>export EDITOR=/usr/bin/vi
    604 export MP_EDITOR=/usr/bin/edit</programlisting>
    605     </section>
    606   </section>
    607543</chapter>
  • trunk/doc-new/guide/xml/intro.xml

    r120888 r122855  
    11<?xml version="1.0" encoding="UTF-8"?>
     2<!-- -*- coding: utf-8; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4:tw=120
     3-->
    24<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    35"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    46<chapter id="introduction">
    5   <title>Introduction</title>
     7    <title>Introduction</title>
    68
    7   <para>MacPorts is an easy to use system for compiling, installing, and
    8   managing open source software. MacPorts may be conceptually divided into two
    9   main parts: the infrastructure, known as MacPorts base, and the set of
    10   available ports. A MacPorts port is a set of specifications contained in
    11   a <link linkend="development.introduction">Portfile</link> that defines an
    12   application, its characteristics, and any files or special instructions
    13   required to install it. This allows you to use a single command to tell
    14   MacPorts to automatically download, compile, and install applications and
    15   libraries. But using MacPorts to manage your open source software provides
    16   several other significant advantages. For example, MacPorts:</para>
     9    <para>MacPorts is an easy to use system for compiling, installing, and managing open source software. MacPorts may
     10        be conceptually divided into two main parts: the infrastructure, known as MacPorts base, and the set of
     11        available ports. A MacPorts port is a set of specifications contained in a <link
     12            linkend="development.introduction">Portfile</link> that defines an application, its characteristics, and any
     13        files or special instructions required to install it. This allows you to use a single command to tell MacPorts
     14        to automatically download, compile, and install applications and libraries. But using MacPorts to manage your
     15        open source software provides several other significant advantages. For example, MacPorts:</para>
    1716
    18   <itemizedlist>
    19     <listitem>
    20       <para>Installs automatically any required support software, known as
    21       <link linkend="reference.dependencies">dependencies</link>, for a given
    22       port.</para>
    23     </listitem>
     17    <itemizedlist>
     18        <listitem>
     19            <para>Installs automatically any required support software, known as <link
     20                    linkend="reference.dependencies">dependencies</link>, for a given port.</para>
     21        </listitem>
    2422
    25     <listitem>
    26       <para>Provides for uninstalls and upgrades for installed ports.</para>
    27     </listitem>
     23        <listitem>
     24            <para>Provides for uninstalls and upgrades for installed ports.</para>
     25        </listitem>
    2826
    29     <listitem>
    30       <para>Confines ported software to a private <quote>sandbox</quote> that
    31       keeps it from intermingling with your operating system and its
    32       vendor-supplied software to prevent them from becoming corrupted.</para>
    33     </listitem>
     27        <listitem>
     28            <para>Confines ported software to a private <quote>sandbox</quote> that keeps it from intermingling with
     29                your operating system and its vendor-supplied software to prevent them from becoming corrupted.</para>
     30        </listitem>
    3431
    35     <listitem>
    36       <para>Allows you to create pre-compiled binary installers of ported
    37       applications to quickly install software on remote computers without
    38       compiling from source code.</para>
    39     </listitem>
    40   </itemizedlist>
     32        <listitem>
     33            <para>Allows you to create pre-compiled binary installers of ported applications to quickly install software
     34                on remote computers without compiling from source code.</para>
     35        </listitem>
     36    </itemizedlist>
    4137
    42   <para>MacPorts is developed on OS X, though it is designed to be portable so
    43   it can work on other Unix-like systems, especially those descended from the
    44   Berkeley Software Distribution (BSD). In practice, installing ports only works
    45   on OS X. MacPorts base can be compiled on Linux (and possibly other
    46   POSIX-compatible systems) where it is mainly used to set up mirrors and
    47   generate portindices.</para>
     38    <para>MacPorts is developed on OS X, though it is designed to be portable so it can work on other Unix-like systems,
     39        especially those descended from the Berkeley Software Distribution (BSD). In practice, installing ports only
     40        works on OS X. MacPorts base can be compiled on Linux (and possibly other POSIX-compatible systems) where it is
     41        mainly used to set up mirrors and generate support files for installations on OS X.</para>
    4842
    49   <para>The following notational conventions are used in the MacPorts Guide to
    50   distinguish between terminal input/output, file text, and other special text
    51   types.</para>
     43    <para>The following notational conventions are used in the MacPorts Guide to distinguish between terminal
     44        input/output, file text, and other special text types.</para>
    5245
    53   <itemizedlist>
    54     <listitem>
    55       <para>Terminal I/O and file text.</para>
     46    <itemizedlist>
     47        <listitem>
     48            <para>Terminal I/O and file text.</para>
    5649
    57       <programlisting><prompt>%% </prompt><userinput>Commands to be typed into a terminal window.</userinput></programlisting>
     50            <programlisting><prompt>$ </prompt><userinput>Commands to be typed into a terminal window.</userinput></programlisting>
     51            <screen>Command output to a terminal window.</screen>
     52            <programlisting>File text.</programlisting>
     53        </listitem>
    5854
    59       <screen>Command output to a terminal window.</screen>
     55        <listitem>
     56            <para>Other special text types.</para>
    6057
    61       <programlisting>File text.</programlisting>
    62     </listitem>
    63 
    64     <listitem>
    65       <para>Other special text types.</para>
    66 
    67       <itemizedlist>
    68         <listitem>
    69           <para>A hyperlink: <ulink
    70               url="http://en.wikipedia.org/wiki/Spontaneous_combustion">spontaneous
    71               combustion</ulink>.</para>
     58            <itemizedlist>
     59                <listitem>
     60                    <para>A hyperlink: <ulink url="http://en.wikipedia.org/wiki/Spontaneous_combustion">spontaneous
     61                            combustion</ulink>.</para>
     62                </listitem>
     63                <listitem>
     64                    <para>A file: <filename>/var/log/system.log</filename>.</para>
     65                </listitem>
     66                <listitem>
     67                    <para>A command: <command>ifconfig</command>.</para>
     68                </listitem>
     69                <listitem>
     70                    <para>An option: port <option>install</option></para>
     71                </listitem>
     72            </itemizedlist>
    7273        </listitem>
    73         <listitem>
    74           <para>A file: <filename>/var/log/system.log</filename>.</para>
    75         </listitem>
    76         <listitem>
    77           <para>A command: <command>ifconfig</command>.</para>
    78         </listitem>
    79         <listitem>
    80           <para>An option: port <option>install</option></para>
    81         </listitem>
    82       </itemizedlist>
    83     </listitem>
    84   </itemizedlist>
     74    </itemizedlist>
    8575</chapter>
Note: See TracChangeset for help on using the changeset viewer.