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

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

Refinements and corrections.

File size: 13.3 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 sections 1 through 3 are Mac OS X specific. If you
9  wish to install MacPorts on another platform, first make sure you have X11
10  and gcc installed, and then perform a <ulink
11  url="installing.source">MacPorts install from source code</ulink>.</para>
12
13  <section id="installing.x11">
14    <title>Install X11</title>
15
16    <para>It is recommended that you install the X Window System (X11) even if
17    you don't plan to run X11 applications immediately. Apple's X11 is
18    preferred over the MacPorts X11 port, and ports with an X11 dependency
19    will be satisfied by Apple's X11. If Apple's X11 wasn't installed at the
20    same time Mac OS X was installed, follow these steps.</para>
21
22    <orderedlist>
23      <listitem>
24        <para>Insert the "Mac OS X Install Disk" and run the package named
25        "Optional Installs".</para>
26      </listitem>
27
28      <listitem>
29        <para>At the software selection window expand the Applications
30        category and click the check box beside X11 (and nothing else).</para>
31      </listitem>
32
33      <listitem>
34        <para>Click <guibutton>Install</guibutton> to install X11.</para>
35      </listitem>
36
37      <listitem>
38        <para>Drag the <filename>/Applications/Utilities/X11</filename> icon
39        to your dock —you must open X11 before launching an X11
40        application.</para>
41      </listitem>
42    </orderedlist>
43
44    <para>If you're using Mac OS X 10.3 then you can download the X11
45    installer from the Apple <ulink
46    url="http://apple.com/support/downloads/x11formacosx.html">download
47    page</ulink>.</para>
48
49    <note>
50      <para>X11 and the X11SDK (from Xcode Tools) are both required for X11
51      apps. To verify the presence of both, check for files
52      <filename>com.apple.pkg.X11User.bom</filename> &amp;
53      <filename>com.apple.pkg.X11SDKLeo.bom</filename> in
54      <filename>/Library/Receipts/boms/</filename>. On Mac OS X 10.4, look for
55      files <filename>X11User.pkg</filename> &amp;
56      <filename>X11SDK.pkg</filename> in
57      <filename>/Library/Receipts/</filename>.</para>
58    </note>
59
60    <section id="installing.x11.settings">
61      <title>Optional X11 Settings</title>
62
63      <para>To launch X11 applications directly from an X11 window (instead of
64      a terminal window), you need to have the MacPorts paths imported into
65      X11 sessions when they are opened. This is a two step process.</para>
66
67      <para>First, tell X11 about the <filename>~/.profile</filename> file
68      that will be created after you install MacPorts. Do this by editing the
69      file <filename>/etc/X11/xinit/xinitrc</filename> and adding this line
70      near the top.</para>
71
72      <programlisting>source ~/.profile</programlisting>
73
74      <para>Now finish the process by making subsequent X11 sessions opened
75      using the menu bar respect your <filename>.profile</filename>
76      file.</para>
77
78      <orderedlist>
79        <listitem>
80          <para>Open X11 and select "Customize Menu ..." from the Applications
81          menu.</para>
82        </listitem>
83
84        <listitem>
85          <para>Double-click the menu item "Terminal" and change: "xterm" to
86          "xterm -ls"</para>
87        </listitem>
88
89        <listitem>
90          <para>Click "Done" to save the change.</para>
91        </listitem>
92      </orderedlist>
93    </section>
94  </section>
95
96  <section id="installing.xcode">
97    <title>Install Xcode Tools</title>
98
99    <para>To install Xcode Tools and the X11 SDK, follow these steps.</para>
100
101    <orderedlist>
102      <listitem>
103        <para>Download and install the latest version of <ulink
104        url="http://developer.apple.com/tools/xcode/">Xcode Tools</ulink> from
105        Apple's developer site—do not install it from a Mac OS X install disk
106        unless you've already checked for a more recent version on Apple's
107        site; older versions of Xcode Tools often cause port install
108        failures.</para>
109      </listitem>
110
111      <listitem>
112        <para>Run the Xcode Tools package installer.</para>
113      </listitem>
114
115      <listitem>
116        <para>Click the button <guibutton>Customize</guibutton>, expand the
117        Applications category and click the check box beside <guibutton>X11
118        SDK</guibutton> to add it to the default items.</para>
119      </listitem>
120
121      <listitem>
122        <para>Click <guibutton>Install</guibutton> to install Xcode Tools and
123        the X11 SDK.</para>
124      </listitem>
125    </orderedlist>
126
127    <note>
128      <para>Xcode Tools are not updated via Mac OS X's Software Update
129      utility.</para>
130    </note>
131  </section>
132
133  <section id="installing.macports">
134    <title>Install MacPorts</title>
135
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
138    <filename>/opt/local/</filename>, the default MacPorts location, or if you
139    wish to install a pre-release version of MacPorts base. However, if you
140    wish to <link linkend="installing.source.multiple">install multiple copies
141    of MacPorts</link> or install MacPorts on another OS platform, you must
142    <link linkend="installing.source">install MacPorts from the source
143    code</link>.</para>
144
145    <note>
146      <para>Though a distinction is made between pre-release and release
147      versions of MacPorts base, the ports collection supports no versioning;
148      a <link linkend="installing.selfupdate">selfupdate</link> installs the
149      latest commits from subversion (at a slight delay).</para>
150    </note>
151
152    <section id="installing.binary">
153      <title>Mac OS X Package Install</title>
154
155      <para>The Mac OS X package installer automatically installs MacPorts,
156      <link linkend="installing.shell">sets the shell environment</link>, 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>
160
161      <orderedlist>
162        <listitem>
163          <para>Download the latest <filename>MacPorts-1.x.x.dmg</filename>
164          disk image from the <ulink
165          url="http://svn.macports.org/repository/macports/downloads/">MacPorts
166          download directory</ulink>.</para>
167        </listitem>
168
169        <listitem>
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>
176        </listitem>
177      </orderedlist>
178    </section>
179
180    <section id="installing.source">
181      <title>Source Install</title>
182
183      <para>If you installed MacPorts using the package installer, skip this
184      section. To install MacPorts from the source code, follow the steps
185      below.</para>
186
187      <orderedlist>
188        <listitem>
189          <para>Download and unzip the latest MacPorts tarball from the <ulink
190          url="http://svn.macports.org/repository/macports/downloads/">MacPorts
191          download directory</ulink>.</para>
192        </listitem>
193
194        <listitem>
195          <para>Perform the commands shown in a terminal window. If you wish
196          to use a path other than <filename>/opt/local</filename>, use the
197          option <option>--prefix</option> and substitute a path for
198          NEW_PREFIX.</para>
199
200          <programlisting><prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
201<prompt>%%</prompt> <userinput>./configure</userinput> --prefix=NEW_PREFIX  (setting prefix is optional)
202<prompt>%%</prompt> <userinput>make</userinput>
203<prompt>%%</prompt> <userinput>sudo make install</userinput></programlisting>
204        </listitem>
205      </orderedlist>
206
207      <section id="installing.source.multiple">
208        <title>Install Multiple MacPorts Copies</title>
209
210        <para>Occasionally a MacPorts developer may wish to install more than
211        one MacPorts instance on the same host. Only one copy of MacPorts may
212        use the default Tcl library path <filename>/Library/Tcl/</filename>,
213        so for additional installations use the option
214        <option>--with-tclpackage</option> as shown below and substitute
215        NEW_TCL_PACKAGE with any empty directory, for example
216        <filename>/Library/Tcl/macports-new/</filename>.</para>
217
218        <note>
219          <para>The first command temporarily removes the standard MacPorts
220          binary paths because they must not be present while installing a
221          second instance.</para>
222        </note>
223
224        <programlisting><prompt>%%</prompt> <userinput>export PATH=/bin:/sbin:/usr/bin:/usr/sbin</userinput>
225<prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
226<prompt>%%</prompt> <userinput>./configure --prefix=NEW_PREFIX --with-tcl-package=NEW_TCLPACKAGE</userinput>
227<prompt>%%</prompt> <userinput>make</userinput>
228<prompt>%%</prompt> <userinput>sudo make install</userinput>
229</programlisting>
230      </section>
231    </section>
232
233    <section id="installing.uninstalling">
234      <title>Uninstall</title>
235
236      <para>To uninstall MacPorts from the default location
237      <filename>/opt/local/</filename>, perform these commands from a terminal
238      window.</para>
239
240      <programlisting><prompt>%%</prompt> <userinput>sudo rm -rf /opt/local/</userinput>
241<prompt>%%</prompt> <userinput>sudo rm -rf /Applications/MacPorts/</userinput>
242<prompt>%%</prompt> <userinput>sudo rm -rf /Library/Tcl/macports1.0/</userinput>
243<prompt>%%</prompt> <userinput>sudo rm -rf /Library/LaunchDaemons/org.macports.*</userinput></programlisting>
244    </section>
245  </section>
246
247  <section id="installing.shell">
248    <title>MacPorts and the Shell</title>
249
250    <para>MacPorts requires changes to the shell environment. If MacPorts was
251    installed using the Mac OS X package installer, a
252    <quote>postflight</quote> script was run after installation that places a
253    <filename>.profile</filename> file in the home directory, which
254    automatically contains the environmental variables required for MacPorts.
255    If a current <filename>.profile</filename> file exists at installation
256    time it is renamed to "mpsaved_$timestamp".</para>
257
258    <note>
259      <para>If you have either a <filename>.bash_login</filename> or a
260      <filename>.bash_profile</filename> file in your home directory, they may
261      take precedence over <filename>.profile</filename>. You may either
262      remove the previously used file, or add the contents of
263      <filename>.profile</filename> to it.</para>
264    </note>
265
266    <para>The postflight script automatically copies a
267    <filename>.profile</filename> containing variables according to the rules
268    described below. Those <link linkend="installing.source">installing
269    MacPorts from source code</link> must modify their environment manually
270    using the rules below as a guide. </para>
271
272    <note>
273      <para>Be sure to notice in the rules below that the variables MANPATH
274      and DISPLAY are only set under certain conditions.</para>
275    </note>
276
277    <itemizedlist>
278      <listitem>
279        <para>A PATH variable is set as shown regardless of platform or
280        environment that appends the MacPorts file paths in front of the
281        default file paths so MacPorts libraries will take precedence over
282        vendor-supplied libraries.</para>
283
284        <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
285      </listitem>
286
287      <listitem>
288        <para>A MANPATH variable is set as shown only if a MANPATH variable
289        was already set in a previous <filename>.profile</filename> that does
290        not include the value <filename>${prefix}/share/man,</filename> nor
291        any empty values. Otherwise it is omitted.</para>
292
293        <programlisting>export MANPATH=/opt/local/share/man:$MANPATH</programlisting>
294
295        <para>Here are some examples of paths that contain empty
296        values:</para>
297
298        <simplelist>
299          <member>/usr/share/man:</member>
300
301          <member>:/usr/share/man</member>
302
303          <member>/usr/share/man::/usr/X11R6/man</member>
304        </simplelist>
305      </listitem>
306
307      <listitem>
308        <para>A DISPLAY variable for X11 application support is set as shown
309        only for Mac OS X versions 10.4 (Tiger) and earlier if a DISPLAY
310        variable is not already set in a <filename>.profile</filename> active
311        at installation time. A DISPLAY variable is never set for Mac OS X
312        10.5 (Leopard) or higher.</para>
313
314        <programlisting>export DISPLAY=:0.0</programlisting>
315      </listitem>
316    </itemizedlist>
317
318    <note>
319      <para>Changes to <filename>~/.profile</filename> do not take effect
320      until a new terminal session is opened. Type <command>env</command> in
321      the terminal to verify the current environment settings. Example output
322      for the <command>env</command> command is shown below.</para>
323    </note>
324
325    <screen>MANPATH=
326TERM_PROGRAM=Apple_Terminal
327TERM=xterm-color
328SHELL=/bin/bash
329TERM_PROGRAM_VERSION=237
330USER=joebob
331__CF_USER_TEXT_ENCODING=0x1FC:0:0
332PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
333PWD=/Users/joebob
334EDITOR=/usr/bin/pico
335SHLVL=1
336HOME=/Users/joebob
337LOGNAME=joebob
338DISPLAY=:0.0
339SECURITYSESSIONID=b0cea0
340_=/usr/bin/env</screen>
341  </section>
342</chapter>
Note: See TracBrowser for help on using the repository browser.