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

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

Refine wording in installation section.

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 install <ulink url="installing.source.multiple">multiple copies of
141    MacPorts</ulink> 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 your home directory and populates it
254    with environmental variables according to the detected Mac OS X version
255    and environment. See details below.</para>
256
257    <note>
258      <para>If a previous <filename>.profile</filename> is present it is
259      renamed to "mpsaved_$timestamp" before the new .profile</para>
260    </note>
261
262    <para>The <quote>postflight</quote> script sets environmental variables in
263    the <filename>.profile</filename> file as shown.</para>
264
265    <itemizedlist>
266      <listitem>
267        <para>A PATH variable is set to append the MacPorts file paths in
268        front of the default file paths so MacPorts libraries will take
269        precedence over vendor-supplied libraries.</para>
270
271        <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
272      </listitem>
273
274      <listitem>
275        <para>A MANPATH variable is set in <filename>.profile</filename> by
276        the <quote>postflight</quote> script as shown only if a MANPATH
277        variable was already set in a previous <filename>.profile</filename>
278        that does not include the value
279        <filename>${prefix}/share/man,</filename> nor any empty values.
280        Otherwise it is omitted.</para>
281
282        <programlisting>export MANPATH=/opt/local/share/man:$MANPATH</programlisting>
283
284        <note>
285          <para>Here are examples of paths that contain empty values:</para>
286
287          <itemizedlist>
288            <listitem>
289              <para><literal>/usr/share/man:</literal></para>
290            </listitem>
291
292            <listitem>
293              <para><literal>:/usr/share/man</literal></para>
294            </listitem>
295
296            <listitem>
297              <para><literal>/usr/share/man::/usr/X11R6/man</literal></para>
298            </listitem>
299          </itemizedlist>
300        </note>
301      </listitem>
302
303      <listitem>
304        <para>A DISPLAY variable is set in <filename>.profile</filename> by
305        the <quote>postflight</quote> script as shown only for X11 application
306        support in Mac OS X versions 10.4 (Tiger) and earlier (unless DISPLAY
307        is already set in a <filename>.profile</filename>). A DISPLAY variable
308        is not set for Mac OS X 10.5 (Leopard) or higher.</para>
309
310        <programlisting>export DISPLAY=:0.0</programlisting>
311      </listitem>
312    </itemizedlist>
313
314    <para>Changes to <filename>~/.profile</filename> do not take effect until
315    a new terminal session is opened. Type <command>env</command> in the
316    terminal to verify the current environment settings. Example output for
317    the <command>env</command> command is shown below.</para>
318
319    <screen>MANPATH=
320TERM_PROGRAM=Apple_Terminal
321TERM=xterm-color
322SHELL=/bin/bash
323TERM_PROGRAM_VERSION=237
324USER=joebob
325__CF_USER_TEXT_ENCODING=0x1FC:0:0
326PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
327PWD=/Users/joebob
328EDITOR=/usr/bin/pico
329SHLVL=1
330HOME=/Users/joebob
331LOGNAME=joebob
332DISPLAY=:0.0
333SECURITYSESSIONID=b0cea0
334_=/usr/bin/env</screen>
335
336    <note>
337      <para>If you have either a <filename>.bash_login</filename> or a
338      <filename>.bash_profile</filename> file in your home directory, they may
339      take precedence over <filename>.profile</filename>. You may either
340      remove the previously used file, or add the contents of
341      <filename>.profile</filename> to it.</para>
342    </note>
343  </section>
344</chapter>
Note: See TracBrowser for help on using the repository browser.