Changeset 33295 for trunk/doc-new


Ignore:
Timestamp:
Jan 23, 2008, 8:22:36 AM (12 years ago)
Author:
markd@…
Message:

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

File:
1 edited

Legend:

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

    r32026 r33295  
    4242    </orderedlist>
    4343
    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="http://apple.com/support/downloads/x11formacosx.html">download
    4747    page</ulink>.</para>
     
    134134    <title>Install MacPorts</title>
    135135
    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>
    154154
    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="installing.shell">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>
    157160
    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="http://svn.macports.org/repository/macports/downloads/">MacPorts
    162166          download directory</ulink>.</para>
     
    164168
    165169        <listitem>
    166           <para>Double-click the .pkg package installer on the disk
    167           image.</para>
    168         </listitem>
    169 
    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 Installer.app 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>
    189 
    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>
    215 
    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>
    238 
    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>
     173
     174        <listitem>
     175          <para>Perform the default “easy” install.</para>
    245176        </listitem>
    246177      </orderedlist>
    247 
    248178    </section>
    249179
     
    312242
    313243  <section id="installing.shell">
    314     <title>Set the Bash Shell</title>
    315 
    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>
    323 
    324     <para>The path statement in the MacPorts-installed .profile is set as
    325     shown.</para>
    326 
    327     <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
    328 
    329     <para>You must add this <varname>DISPLAY</varname> variable for
    330     X11.</para>
    331 
    332     <programlisting>export DISPLAY=:0.0</programlisting>
    333 
    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>
    337 
    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>
     245
     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>
     252
     253    <para>The <quote>postflight</quote> script sets environmental variables in
     254    the <filename>.profile</filename> file as shown.</para>
     255
     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>
     261
     262        <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
     263      </listitem>
     264
     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>
     272
     273        <programlisting>export MANPATH=/opt/local/share/man:$MANPATH</programlisting>
     274
     275        <note>
     276          <para>Here are examples of paths that contain empty values:</para>
     277
     278          <itemizedlist>
     279            <listitem>
     280              <para><literal>/usr/share/man:</literal></para>
     281            </listitem>
     282
     283            <listitem>
     284              <para><literal>:/usr/share/man</literal></para>
     285            </listitem>
     286
     287            <listitem>
     288              <para><literal>/usr/share/man::/usr/X11R6/man</literal></para>
     289            </listitem>
     290          </itemizedlist>
     291        </note>
     292      </listitem>
     293
     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>
     301
     302        <programlisting>export DISPLAY=:0.0</programlisting>
     303      </listitem>
     304    </itemizedlist>
    342305
    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>
    347 
    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>
     310
     311    <screen>MANPATH=
     312TERM_PROGRAM=Apple_Terminal
    349313TERM=xterm-color
    350314SHELL=/bin/bash
    351 TERM_PROGRAM_VERSION=133
     315TERM_PROGRAM_VERSION=237
    352316USER=joebob
    353317__CF_USER_TEXT_ENCODING=0x1FC:0:0
     
    370334    </note>
    371335  </section>
    372 
    373   <section id="installing.selfupdate">
    374     <title>Selfupdate MacPorts</title>
    375 
    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>
    381336</chapter>
Note: See TracChangeset for help on using the changeset viewer.