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

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

Try two: it's a <link> element, not <ulink>.

File size: 13.1 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 these
185      steps.</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 these commands in a terminal window, substituting a
196          real path for NEW_PREFIX if you wish to use a path other than
197          <filename>/opt/local/</filename>.</para>
198
199          <programlisting><prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
200<prompt>%%</prompt> <userinput>./configure</userinput> --prefix=NEW_PREFIX  (setting prefix is optional)
201<prompt>%%</prompt> <userinput>make</userinput>
202<prompt>%%</prompt> <userinput>sudo make install</userinput></programlisting>
203        </listitem>
204      </orderedlist>
205
206      <section id="installing.source.multiple">
207        <title>Install Multiple MacPorts Copies</title>
208
209        <para>Occasionally a MacPorts developer may wish to install more than
210        one copy of MacPorts on the same host, possibly to test two different
211        versions of MacPorts. But only one copy of MacPorts may use the
212        default MacPorts Tcl library path <filename>/Library/Tcl/</filename>,
213        so for a second installation use the
214        <literal>--with-tclpackage</literal> switch set to any newly created
215        (empty) directory, say /Library/Tcl/macports-new. Also, the standard
216        MacPorts binary path must not be present during the installation of
217        the second instance. To install a second instance of MacPorts, follow
218        these steps.</para>
219
220        <programlisting><prompt>%%</prompt> <userinput>export PATH=/bin:/sbin:/usr/bin:/usr/sbin</userinput>
221<prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
222<prompt>%%</prompt> <userinput>./configure --prefix=NEW_PREFIX --with-tcl-package=NEW_TCLPACKAGE</userinput>
223<prompt>%%</prompt> <userinput>make</userinput>
224<prompt>%%</prompt> <userinput>sudo make install</userinput>
225</programlisting>
226      </section>
227    </section>
228
229    <section id="installing.uninstalling">
230      <title>Uninstall</title>
231
232      <para>To uninstall MacPorts from the default location
233      <filename>/opt/local/</filename>, perform these commands from a terminal
234      window.</para>
235
236      <programlisting><prompt>%%</prompt> <userinput>sudo rm -rf /opt/local/</userinput>
237<prompt>%%</prompt> <userinput>sudo rm -rf /Applications/MacPorts/</userinput>
238<prompt>%%</prompt> <userinput>sudo rm -rf /Library/Tcl/macports1.0/</userinput>
239<prompt>%%</prompt> <userinput>sudo rm -rf /Library/LaunchDaemons/org.macports.*</userinput></programlisting>
240    </section>
241  </section>
242
243  <section id="installing.shell">
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>
305
306    <para>Changes to <filename>~/.profile</filename> do not take effect until
307    a new terminal session is opened. Type <command>env</command> in the
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
313TERM=xterm-color
314SHELL=/bin/bash
315TERM_PROGRAM_VERSION=237
316USER=joebob
317__CF_USER_TEXT_ENCODING=0x1FC:0:0
318PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
319PWD=/Users/joebob
320EDITOR=/usr/bin/pico
321SHLVL=1
322HOME=/Users/joebob
323LOGNAME=joebob
324DISPLAY=:0.0
325SECURITYSESSIONID=b0cea0
326_=/usr/bin/env</screen>
327
328    <note>
329      <para>If you have either a <filename>.bash_login</filename> or a
330      <filename>.bash_profile</filename> file in your home directory, they may
331      take precedence over <filename>.profile</filename>. You may either
332      remove the previously used file, or add the contents of
333      <filename>.profile</filename> to it.</para>
334    </note>
335  </section>
336</chapter>
Note: See TracBrowser for help on using the repository browser.