source: trunk/doc-new/guide/xml/installing.xml @ 38647

Last change on this file since 38647 was 38647, checked in by markd@…, 12 years ago

Refine the MacPorts and the Shell section.

File size: 17.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<chapter id="installing">
5  <title>Installing MacPorts</title>
6
7  <para>This chapter shows you how to install MacPorts and its prerequisites
8  step-by-step. Note that section 1 and section 2 (installing X11 and Xcode
9  Tools) are Mac OS X specific. If you wish to install MacPorts on another
10  platform, first make sure you have X11 and gcc installed, and then begin at
11  section 3.2 by performing <link
12  linkend="installing.macports.source">MacPorts install from source</link> and
13  proceed to the end of the chapter.</para>
14
15  <section id="installing.x11">
16    <title>Install X11</title>
17
18    <para>It is recommended that you install the X Window System (X11) even if
19    you don't plan to run X11 applications immediately. Apple's X11 is
20    preferred over either of the X11 ports, XFree86 and Xorg, therefore
21    Apple's X11 is normally used to satisfy ports that depend upon X11 (see
22    <link linkend="reference.dependencies.types">non-port
23    dependencies</link>). If Apple's X11 wasn't installed when Mac OS X was
24    installed, follow these steps.</para>
25
26    <orderedlist>
27      <listitem>
28        <para>Insert the <quote>Mac OS X Install Disk</quote> and run the
29        package named <quote>Optional Installs</quote>.</para>
30      </listitem>
31
32      <listitem>
33        <para>At the software selection window expand the
34        <guilabel>Applications</guilabel> category and click the check box
35        beside <guilabel>X11</guilabel> (and nothing else).</para>
36      </listitem>
37
38      <listitem>
39        <para>Click <guibutton>Install</guibutton> to install X11.</para>
40      </listitem>
41
42      <listitem>
43        <para>Drag the <filename>/Applications/Utilities/X11</filename> icon
44        to your dock —you must open X11 before launching an X11
45        application.</para>
46      </listitem>
47    </orderedlist>
48
49    <para>If you're using Mac OS X 10.3 then you can download the X11
50    installer from the Apple <ulink
51    url="http://apple.com/support/downloads/x11formacosx.html">download
52    page</ulink>.</para>
53
54    <note>
55      <para>X11 and the X11SDK (from Xcode Tools) are both required for X11
56      apps. To verify the presence of both, check for files
57      <filename>com.apple.pkg.X11User.bom</filename> &amp;
58      <filename>com.apple.pkg.X11SDKLeo.bom</filename> in
59      <filename>/Library/Receipts/boms/</filename>. On Mac OS X 10.4, look for
60      files <filename>X11User.pkg</filename> &amp;
61      <filename>X11SDK.pkg</filename> in
62      <filename>/Library/Receipts/</filename>.</para>
63    </note>
64
65    <section id="installing.x11.settings">
66      <title>Optional X11 Settings</title>
67
68      <para>To launch X11 applications directly from an X11 window (instead of
69      a terminal window), you need to have the MacPorts paths imported into
70      X11 sessions when they are opened. This is a two step process.</para>
71
72      <para>First, tell X11 about the <filename>~/.profile</filename> file
73      that will be created after you install MacPorts. Do this by editing the
74      file <filename>/etc/X11/xinit/xinitrc</filename> and adding this line
75      near the top.</para>
76
77      <programlisting>source ~/.profile</programlisting>
78
79      <para>Now finish the process by making subsequent X11 sessions opened
80      using the menu bar respect your <filename>.profile</filename>
81      file.</para>
82
83      <orderedlist>
84        <listitem>
85          <para>Open X11 and select <guimenuitem>Customize Menu
86          ...</guimenuitem> from the <guimenu>Applications</guimenu>
87          menu.</para>
88        </listitem>
89
90        <listitem>
91          <para>Double-click the menu item <guimenuitem>Terminal</guimenuitem>
92          and change: <quote>xterm</quote> to <quote>xterm -ls</quote></para>
93        </listitem>
94
95        <listitem>
96          <para>Click <guibutton>Done</guibutton> to save the change.</para>
97        </listitem>
98      </orderedlist>
99    </section>
100  </section>
101
102  <section id="installing.xcode">
103    <title>Install Xcode Tools</title>
104
105    <para>To install Xcode Tools and the X11 SDK, follow these steps.</para>
106
107    <orderedlist>
108      <listitem>
109        <para>Download and install the latest version of <ulink
110        url="http://developer.apple.com/tools/xcode/">Xcode Tools</ulink> from
111        Apple's developer site—do not install it from a Mac OS X install disk
112        unless you've checked for the latest version on Apple's site; older
113        versions of Xcode Tools often cause port install failures.</para>
114      </listitem>
115
116      <listitem>
117        <para>Run the Xcode Tools package installer.</para>
118      </listitem>
119
120      <listitem>
121        <para>Click the button <guibutton>Customize</guibutton>, expand the
122        Applications category and click the check box beside <guibutton>X11
123        SDK</guibutton> to add it to the default items.</para>
124      </listitem>
125
126      <listitem>
127        <para>Click <guibutton>Install</guibutton> to install Xcode Tools and
128        the X11 SDK.</para>
129      </listitem>
130    </orderedlist>
131
132    <note>
133      <para>Xcode Tools are not updated via Mac OS X's Software Update
134      utility.</para>
135    </note>
136  </section>
137
138  <section id="installing.macports">
139    <title>Install MacPorts</title>
140
141    <para>If you are using Mac OS X, you should install MacPorts using the Mac
142    OS X package installer unless you do not wish to install it to
143    <filename>/opt/local/</filename>, the default MacPorts location, or if you
144    wish to install a pre-release version of MacPorts base. However, if you
145    wish to <link linkend="installing.macports.source.multiple">install
146    multiple copies of MacPorts</link> or install MacPorts on another OS
147    platform, you must <link linkend="installing.macports.source">install
148    MacPorts from the source code</link>.</para>
149
150    <note>
151      <para>Though a distinction is made between pre-release and release
152      versions of MacPorts base, the ports collection supports no such
153      distinction or versioning. The <link
154      linkend="using.port.selfupdate">selfupdate</link> command installs the
155      latest port revisions from subversion (at a slight delay), and updates
156      MacPorts base to the latest released version.</para>
157    </note>
158
159    <section id="installing.macports.binary">
160      <title>Mac OS X Package Install</title>
161
162      <para>The Mac OS X package installer automatically installs MacPorts,
163      <link linkend="installing.shell">sets the shell environment</link>, and
164      runs a <link linkend="using.port.selfupdate">selfupdate</link> operation
165      to update the ports tree and MacPorts base with the latest
166      release.</para>
167
168      <orderedlist>
169        <listitem>
170          <para>Download the latest <filename>MacPorts-1.x.x.dmg</filename>
171          disk image from the <ulink
172          url="http://svn.macports.org/repository/macports/downloads/">MacPorts
173          download directory</ulink>.</para>
174        </listitem>
175
176        <listitem>
177          <para>Double-click the <filename>MacPorts-1.x.x.pkg</filename>
178          package installer on the disk image.</para>
179        </listitem>
180
181        <listitem>
182          <para>Perform the default <quote>easy</quote> install.</para>
183        </listitem>
184      </orderedlist>
185    </section>
186
187    <section id="installing.macports.source">
188      <title>Source Install</title>
189
190      <para>If you installed MacPorts using the package installer, skip this
191      section. To install MacPorts from the source code, follow the steps
192      below.</para>
193
194      <orderedlist>
195        <listitem>
196          <para>Download and unzip the latest MacPorts tarball from the <ulink
197          url="http://svn.macports.org/repository/macports/downloads/">MacPorts
198          download directory</ulink>.</para>
199        </listitem>
200
201        <listitem>
202          <para>Perform the commands shown in a terminal window. If you wish
203          to use a path other than <filename>/opt/local</filename>, use the
204          option <option>--prefix</option> and substitute a path for
205          NEW_PREFIX.</para>
206
207          <programlisting><prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
208<prompt>%%</prompt> <userinput>./configure</userinput> --prefix=NEW_PREFIX  (setting prefix is optional)
209<prompt>%%</prompt> <userinput>make</userinput>
210<prompt>%%</prompt> <userinput>sudo make install</userinput></programlisting>
211        </listitem>
212      </orderedlist>
213
214      <section id="installing.macports.source.multiple">
215        <title>Install Multiple MacPorts Copies</title>
216
217        <para>Occasionally a MacPorts developer may wish to install more than
218        one MacPorts instance on the same host. Only one copy of MacPorts may
219        use the default Tcl library path <filename>/Library/Tcl/</filename>,
220        so for additional installations use the option
221        <option>--with-tclpackage</option> as shown below and substitute
222        NEW_TCL_PACKAGE with any empty directory, for example
223        <filename>/Library/Tcl/macports-new/</filename>.</para>
224
225        <note>
226          <para>The first command temporarily removes the standard MacPorts
227          binary paths because they must not be present while installing a
228          second instance.</para>
229        </note>
230
231        <programlisting><prompt>%%</prompt> <userinput>export PATH=/bin:/sbin:/usr/bin:/usr/sbin</userinput>
232<prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
233<prompt>%%</prompt> <userinput>./configure --prefix=NEW_PREFIX --with-tclpackage=NEW_TCLPACKAGE</userinput>
234<prompt>%%</prompt> <userinput>make</userinput>
235<prompt>%%</prompt> <userinput>sudo make install</userinput>
236</programlisting>
237      </section>
238    </section>
239
240    <section id="installing.macports.upgrade">
241      <title>MacPorts Upgrade</title>
242
243      <para>MacPorts base upgrades are performed automatically (when a newer
244      release is available) during a <link
245      linkend="using.port.selfupdate">selfupdate</link> operation. To upgrade
246      a copy of MacPorts that was installed from source to the newer release
247      of the source code, simply repeat the <link
248      linkend="installing.macports.source">source install</link> with the
249      newer version of the MacPorts source code.</para>
250    </section>
251
252    <section id="installing.macports.uninstalling">
253      <title>Uninstall</title>
254
255      <para>To uninstall MacPorts from the default location
256      <filename>/opt/local/</filename>, perform this command from a terminal
257      window.</para>
258
259      <programlisting><prompt>%%</prompt> <userinput>sudo rm -rf \
260    /opt/local \
261    /etc/manpaths.d/macports \
262    /etc/paths.d/macports \
263    /Applications/DarwinPorts \
264    /Applications/MacPorts \
265    /Library/LaunchDaemons/org.macports.* \
266    /Library/Receipts/DarwinPorts*.pkg \
267    /Library/Receipts/MacPorts*.pkg \
268    /Library/StartupItems/DarwinPortsStartup \
269    /Library/Tcl/darwinports1.0 \
270    /Library/Tcl/macports1.0</userinput></programlisting>
271    </section>
272  </section>
273
274  <section id="installing.shell">
275    <title>MacPorts and the Shell</title>
276
277    <para>MacPorts requires that some environmental variables be set in the
278    shell. When MacPorts is installed using the Mac OS X package installer, a
279    <quote>postflight</quote> script is run after installation that
280    automatically copies a <filename>.profile</filename> containing variables
281    according to the rules described in the following section. Those <link
282    linkend="installing.macports.source">installing MacPorts from source
283    code</link> must modify their environment manually using the rules as a
284    guide.</para>
285
286    <note>
287      <para>If you have either a <filename>.bash_login</filename> or a
288      <filename>.bash_profile</filename> file in your home directory, they may
289      take precedence over <filename>.profile</filename>. You may either
290      remove the previously used file, or add the contents of
291      <filename>.profile</filename> to it.</para>
292    </note>
293
294    <section id="installing.shell.postflight">
295      <title>The Postflight Script</title>
296
297      <para>The postflight script automatically copies a
298      <filename>.profile</filename> containing the <varname>PATH</varname>
299      variable, and optionally the <varname>MANPATH</varname> and
300      <varname>DISPLAY</varname> variables according to the rules described
301      below. If a current <filename>.profile</filename> file exists at
302      installation time it is renamed to <quote>mpsaved_$timestamp</quote>.
303      Those <link linkend="installing.macports.source">installing MacPorts
304      from source code</link> must modify their environment manually using the
305      rules as a guide.</para>
306
307      <itemizedlist>
308        <listitem>
309          <para>Required: <varname>PATH</varname> variable</para>
310
311          <para>This variable is set by the postflight script to append the
312          MacPorts executable paths to the default path as shown. The MacPorts
313          paths are appended at the front of <varname>PATH</varname> so the
314          MacPorts libraries will take precedence over vendor-supplied
315          libraries for ported software at runtime.</para>
316
317          <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
318
319          <note>
320            <para>The user environment's $PATH is not in effect while ports
321            are being installed, because the $PATH is scrubbed before ports
322            are installed, and restored afterwards. To change the search path
323            for locating system executables (rsync, tar, etc.) during port
324            installation, see the <link
325            linkend="internals.configuration-files.macports-conf">macports.conf</link>
326            file variable <varname>binpath</varname>. But changing this
327            variable is for advanced users only, and is not generally needed
328            or recomended.</para>
329          </note>
330        </listitem>
331
332        <listitem>
333          <para>Optional: <varname>MANPATH</varname> variable</para>
334
335          <para>Condition: If prior to MacPorts installation a
336          <varname>MANPATH</varname> variable exists in a current
337          <filename>.profile</filename> that contains neither the value
338          <filename>${prefix}/share/man,</filename> nor any empty values, the
339          postflight script sets the <varname>MANPATH</varname> variable as
340          shown below. Otherwise, the <varname>MANPATH</varname> variable is
341          omitted.</para>
342
343          <programlisting>export MANPATH=/opt/local/share/man:$MANPATH</programlisting>
344
345          <para>Here are some examples of paths that contain empty
346          values:</para>
347
348          <simplelist>
349            <member>/usr/share/man:</member>
350
351            <member>:/usr/share/man</member>
352
353            <member>/usr/share/man::/usr/X11R6/man</member>
354          </simplelist>
355        </listitem>
356
357        <listitem>
358          <para>Optional: <varname>DISPLAY</varname> variable</para>
359
360          <para>Condition: If installing on a Mac OS X version earlier than
361          10.5 (Leopard), and if a<filename> .profile</filename> file exists
362          at time of MacPorts installation without a
363          <varname>DISPLAY</varname> variable, the postflight script sets a
364          <varname>DISPLAY</varname> variable as shown below. The
365          <varname>DISPLAY</varname> variable is always omitted on Mac OS X
366          10.5 or higher.</para>
367
368          <programlisting>export DISPLAY=:0.0</programlisting>
369        </listitem>
370      </itemizedlist>
371    </section>
372
373    <section id="installing.shell.verifyprofile">
374      <title>Verify the .profile</title>
375
376      <para>To verify that the <filename>.profile</filename> containing the
377      MacPorts variables is in effect, type <command>env</command> in the
378      terminal to verify the current environment settings after the
379      <filename>.profile</filename> has been created. Example output for the
380      <command>env</command> command is shown below.</para>
381
382      <note>
383        <para>Changes to <filename>~/.profile</filename> do not take effect
384        until a new terminal session is opened.</para>
385      </note>
386
387      <screen>MANPATH=
388TERM_PROGRAM=Apple_Terminal
389TERM=xterm-color
390SHELL=/bin/bash
391TERM_PROGRAM_VERSION=237
392USER=joebob
393__CF_USER_TEXT_ENCODING=0x1FC:0:0
394PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
395PWD=/Users/joebob
396EDITOR=/usr/bin/pico
397SHLVL=1
398HOME=/Users/joebob
399LOGNAME=joebob
400DISPLAY=:0.0
401SECURITYSESSIONID=b0cea0
402_=/usr/bin/env</screen>
403    </section>
404
405    <section id="installing.shell.editorvar">
406      <title>Optional EDITOR Variable</title>
407
408      <para>A useful environment variable to set in
409      <filename>.profile</filename> is the <varname>EDITOR</varname> variable.
410      Setting this variable allows you to use the edit option to the port
411      command to edit Portfiles quickly and easily. Set the
412      <varname>EDITOR</varname> variable to point to your favorite text
413      editor.</para>
414
415      <para>For example, to use the nano editor, add this line to your
416      <filename>~/.profile</filename>:</para>
417
418      <programlisting>export EDITOR=/usr/bin/nano</programlisting>
419
420      <para>To use the user-friendly GUI editor <ulink
421      url="http://www.barebones.com/products/textwrangler/">TextWrangler</ulink>
422      (installation required), add this line to your
423      <filename>~/.profile</filename>:</para>
424
425      <programlisting>export EDITOR=/usr/bin/edit</programlisting>
426    </section>
427  </section>
428</chapter>
Note: See TracBrowser for help on using the repository browser.