Changeset 33295 for trunk/doc-new

Jan 23, 2008, 8:22:36 AM (12 years ago)

Enhance install section; rename Setting the Shell section to MacPorts and the
Shell and enhance it; remove the now unnecessary selfupdate section.
from install.

1 edited


  • trunk/doc-new/guide/xml/installing.xml

    r32026 r33295  
    4242    </orderedlist>
    44     <para>If you're using Mac OS X 10.3 then you can download the X11 installer
    45     from the Apple <ulink
     44    <para>If you're using Mac OS X 10.3 then you can download the X11
     45    installer from the Apple <ulink
    4646    url="">download
    4747    page</ulink>.</para>
    134134    <title>Install MacPorts</title>
    136     <para>If you are using Mac OS X, you should install MacPorts using the
    137     Mac OS X package installer unless you do not wish to install it to
     136    <para>If you are using Mac OS X, you should install MacPorts using the Mac
     137    OS X package installer unless you do not wish to install it to
    138138    <filename>/opt/local/</filename>, the default MacPorts location, or if you
    139139    wish to install a pre-release version of MacPorts base. However, if you
    153153      <title>Mac OS X Package Install</title>
    155       <para>To install MacPorts with the Mac OS X package installer, follow
    156       these steps.</para>
     155      <para>The Mac OS X package installer automatically installs MacPorts,
     156      <ulink url="">sets the shell environment</ulink>, and
     157      runs a <link linkend="using.port.selfupdate">selfupdate</link> operation
     158      to download the ports tree with the latest versions and upgrade MacPorts
     159      base to the latest point release.</para>
    158161      <orderedlist>
    159162        <listitem>
    160           <para>Download the latest MacPorts .dmg disk image from the <ulink
     163          <para>Download the latest <filename>MacPorts-1.x.x.dmg</filename>
     164          disk image from the <ulink
    161165          url="">MacPorts
    162166          download directory</ulink>.</para>
    165169        <listitem>
    166           <para>Double-click the .pkg package installer on the disk
    167           image.</para>
    168         </listitem>
    170         <listitem>
    171           <para>Perform the default “easy” install.  As of MacPorts 1.6,
    172             this will install MacPorts, set up a MacPorts-compatible shell
    173             environment and, if you have a network connection, update the
    174             MacPorts core and ports tree.</para>
    175           <note id="installing.binary.postflight.details">
    176             <title>For advanced users: details of the postflight script</title>
    177             <para>
    178               The "postflight" script bundled with our "pkg" installer is
    179               run by Apple's after MacPorts is installed, in order
    180               to setup a MacPorts-compatible shell environment by editing the appropriate
    181               shell configuration file (which is properly backed up if necessary
    182               with an "mpsaved_$timestamp" suffix before proceeding):
    183               <orderedlist>
    184                 <listitem>
    185                   <para>The "/opt/local/bin" &amp; "/opt/local/sbin" paths are
    186                     added to the PATH variable if not already there, in order to
    187                     find MacPorts-installed programs.</para>
    188                 </listitem>
    190                 <listitem>
    191                   <para>The "/opt/local/share/man" path is added to the MANPATH
    192                     variable if and only if:
    193                     <itemizedlist>
    194                       <listitem>
    195                         <para>it already exists;</para>
    196                       </listitem>
    197                       <listitem>
    198                         <para>its value is not empty;</para>
    199                       </listitem>
    200                       <listitem>
    201                         <para>the MacPorts path is not already in it;</para>
    202                       </listitem>
    203                       <listitem>
    204                         <para>its value does not contain empty components, such
    205                           as "/usr/share/man:", ":/usr/share/man" or
    206                           "/usr/share/man::/usr/X11R6/man".</para>
    207                       </listitem>
    208                     </itemizedlist>
    209                     In all of these cases, helper tools such as 'manpath(1)' or
    210                     'path_helper(8)' (Leopard only) setup the MANPATH directly in
    211                     coordination with the 'man(1)' command, so we avoid
    212                     interfering with that.
    213                   </para>
    214                 </listitem>
    216                 <listitem>
    217                   <para>The <envar>DISPLAY</envar> environment variable is set
    218                     to ":0" if and only if:
    219                     <itemizedlist>
    220                       <listitem>
    221                         <para>
    222                           It's a Tiger or earlier platform, since on Leopard
    223                           connections to the X11 server are handled in a much
    224                           cleaner fashion by the 'launchd(8)' daemon directly;
    225                         </para>
    226                       </listitem>
    227                       <listitem>
    228                         <para>
    229                           a <envar>DISPLAY</envar> environment variable doesn't
    230                           already exist.
    231                         </para>
    232                       </listitem>
    233                     </itemizedlist>
    234                   </para>
    235                 </listitem>
    236               </orderedlist>
    237             </para>
    239             <para>Once all that is done, the script runs the 'selfupdate'
    240               action of the 'port(1)' command to synchronize the MacPorts
    241               installation with the project's rsync server, updating the
    242               ports tree to its latest revision and MacPorts itself to the
    243               latest point release if available.</para>
    244            </note>
     170          <para>Double-click the <filename>MacPorts-1.x.x.pkg</filename>
     171          package installer on the disk image.</para>
     172        </listitem>
     174        <listitem>
     175          <para>Perform the default “easy” install.</para>
    245176        </listitem>
    246177      </orderedlist>
    248178    </section>
    313243  <section id="">
    314     <title>Set the Bash Shell</title>
    316     <para>The MacPorts installer (from Mac OS X package or source) places a
    317     <filename>.profile</filename> file in your home directory (view files with
    318     a dot using <command>ls -a</command>). The contents of the
    319     <filename>~/.profile</filename> adds the MacPorts paths in front of the
    320     standard Unix paths for the default Bash shell so that MacPorts libraries
    321     will take precedence over vendor-supplied libraries if both are
    322     present.</para>
    324     <para>The path statement in the MacPorts-installed .profile is set as
    325     shown.</para>
    327     <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
    329     <para>You must add this <varname>DISPLAY</varname> variable for
    330     X11.</para>
    332     <programlisting>export DISPLAY=:0.0</programlisting>
    334     <para>Add the <varname>EDITOR</varname> variable to use your favorite text
    335     editor. A complete <filename>~/.profile</filename> file with the added
    336     variables is shown below.</para>
    338     <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH
    339 export DISPLAY=:0.0
    340 export EDITOR=/usr/bin/pico
    341 </programlisting>
     244    <title>MacPorts and the Shell</title>
     246    <para>MacPorts requires changes to the shell environment. If MacPorts was
     247    installed using the Mac OS X package installer, a
     248    <quote>postflight</quote> script is run after the install that places a
     249    <filename>.profile</filename> file in your home directory populated with
     250    environmental variables set according to the detected Mac OS X version and
     251    environment.</para>
     253    <para>The <quote>postflight</quote> script sets environmental variables in
     254    the <filename>.profile</filename> file as shown.</para>
     256    <itemizedlist>
     257      <listitem>
     258        <para>A PATH variable is set to append the MacPorts file paths in
     259        front of the default file paths so MacPorts libraries will take
     260        precedence over vendor-supplied libraries.</para>
     262        <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
     263      </listitem>
     265      <listitem>
     266        <para>No MANPATH variable is set by <quote>postflight</quote> unless a
     267        MANPATH variable is already set in the current
     268        <filename>.profile</filename> file that does not include the value
     269        <filename>${prefix}/share/man,</filename> nor any empty values. In
     270        those cases, a MANPATH variable is added to
     271        <filename>.profile</filename> as shown.</para>
     273        <programlisting>export MANPATH=/opt/local/share/man:$MANPATH</programlisting>
     275        <note>
     276          <para>Here are examples of paths that contain empty values:</para>
     278          <itemizedlist>
     279            <listitem>
     280              <para><literal>/usr/share/man:</literal></para>
     281            </listitem>
     283            <listitem>
     284              <para><literal>:/usr/share/man</literal></para>
     285            </listitem>
     287            <listitem>
     288              <para><literal>/usr/share/man::/usr/X11R6/man</literal></para>
     289            </listitem>
     290          </itemizedlist>
     291        </note>
     292      </listitem>
     294      <listitem>
     295        <para>No DISPLAY variable is set by <quote>postflight</quote> for Mac
     296        OS X 10.5 (Leopard) since it is not required to run X11 applications.
     297        However, for Mac OS X versions 10.4 and earlier the DISPLAY variable
     298        is required, so unless an existing DISPLAY variable was already set in
     299        a current <filename>.profile</filename>, the <quote>postflight</quote>
     300        script sets it as shown.</para>
     302        <programlisting>export DISPLAY=:0.0</programlisting>
     303      </listitem>
     304    </itemizedlist>
    343306    <para>Changes to <filename>~/.profile</filename> do not take effect until
    344307    a new terminal session is opened. Type <command>env</command> in the
    345     terminal to verify the current environment settings. Example output of
    346     <command>env</command> is below.</para>
    348     <screen>TERM_PROGRAM=Apple_Terminal
     308    terminal to verify the current environment settings. Example output for
     309    the <command>env</command> command is shown below.</para>
     311    <screen>MANPATH=
    370334    </note>
    371335  </section>
    373   <section id="installing.selfupdate">
    374     <title>Selfupdate MacPorts</title>
    376     <para>You must always execute a <quote>selfupdate</quote> after a new
    377     MacPorts install, and you should also do it frequently thereafter. See
    378     <link linkend="using.port.selfupdate">selfupdate</link> —one of several
    379     <link linkend="using.port">port commands</link>.</para>
    380   </section>
Note: See TracChangeset for help on using the changeset viewer.