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

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

Improve wording a bit and correct a typo.

File size: 15.5 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 installer
45    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
137    Mac 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>To install MacPorts with the Mac OS X package installer, follow
156      these steps.</para>
157
158      <orderedlist>
159        <listitem>
160          <para>Download the latest MacPorts .dmg disk image from the <ulink
161          url="http://svn.macports.org/repository/macports/downloads/">MacPorts
162          download directory</ulink>.</para>
163        </listitem>
164
165        <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:
181              <orderedlist>
182                <listitem>
183                  <para>The "/opt/local/bin" &amp; "/opt/local/sbin" paths are
184                    added to the PATH variable if not already there, in order to
185                    find MacPorts-installed programs.</para>
186                </listitem>
187
188                <listitem>
189                  <para>The "/opt/local/share/man" path is added to the MANPATH
190                    variable if and only if:
191                    <itemizedlist>
192                      <listitem>
193                        <para>it already exists;</para>
194                      </listitem>
195                      <listitem>
196                        <para>its value is not empty;</para>
197                      </listitem>
198                      <listitem>
199                        <para>the MacPorts path is not already in it;</para>
200                      </listitem>
201                      <listitem>
202                        <para>its value does not contain empty components, such
203                          as "/usr/share/man:", ":/usr/share/man" or
204                          "/usr/share/man::/usr/X11R6/man".</para>
205                      </listitem>
206                    </itemizedlist>
207                    In all of these cases, helper tools such as 'manpath(1)' or
208                    'path_helper(8)' (Leopard only) setup the MANPATH directly in
209                    coordination with the 'man(1)' command, so we avoid
210                    interfering with that.
211                  </para>
212                </listitem>
213
214                <listitem>
215                  <para>The <envar>DISPLAY</envar> environment variable is set
216                    to ":0" if and only if:
217                    <itemizedlist>
218                      <listitem>
219                        <para>
220                          It's a Tiger or earlier platform, since on Leopard
221                          connections to the X11 server are handled in a much
222                          cleaner fashion by the 'launchd(8)' daemon directly;
223                        </para>
224                      </listitem>
225                      <listitem>
226                        <para>
227                          a <envar>DISPLAY</envar> environment variable doesn't
228                          already exist.
229                        </para>
230                      </listitem>
231                    </itemizedlist>
232                  </para>
233                </listitem>
234              </orderedlist>
235            </para>
236
237            <para>Once all that is done, the script runs the 'selfupdate'
238              action of the 'port(1)' command to synchronize the MacPorts
239              installation with the project's rsync server, updating the
240              ports tree to its latest revision and MacPorts itself to the
241              latest point release if available.</para>
242           </note>
243        </listitem>
244      </orderedlist>
245
246      <note>
247        <para>Use the MacPorts <link
248        linkend="installing.selfupdate">selfupdate</link> operation
249        immediately after installing MacPorts. If a newer MacPorts base point
250        revision has been released before a new package installer has been
251        made, it is automatically updated.</para>
252      </note>
253    </section>
254
255    <section id="installing.source">
256      <title>Source Install</title>
257
258      <para>If you installed MacPorts using the package installer, skip this
259      section. To install MacPorts from the source code, follow these
260      steps.</para>
261
262      <orderedlist>
263        <listitem>
264          <para>Download and unzip the latest MacPorts tarball from the <ulink
265          url="http://svn.macports.org/repository/macports/downloads/">MacPorts
266          download directory</ulink>.</para>
267        </listitem>
268
269        <listitem>
270          <para>Perform these commands in a terminal window, substituting a
271          real path for NEW_PREFIX if you wish to use a path other than
272          <filename>/opt/local/</filename>.</para>
273
274          <programlisting><prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
275<prompt>%%</prompt> <userinput>./configure</userinput> --prefix=NEW_PREFIX  (setting prefix is optional)
276<prompt>%%</prompt> <userinput>make</userinput>
277<prompt>%%</prompt> <userinput>sudo make install</userinput></programlisting>
278        </listitem>
279      </orderedlist>
280
281      <section id="installing.source.multiple">
282        <title>Install Multiple MacPorts Copies</title>
283
284        <para>Occasionally a MacPorts developer may wish to install more than
285        one copy of MacPorts on the same host, possibly to test two different
286        versions of MacPorts. But only one copy of MacPorts may use the
287        default MacPorts Tcl library path <filename>/Library/Tcl/</filename>,
288        so for a second installation use the
289        <literal>--with-tclpackage</literal> switch set to any newly created
290        (empty) directory, say /Library/Tcl/macports-new. Also, the standard
291        MacPorts binary path must not be present during the installation of
292        the second instance. To install a second instance of MacPorts, follow
293        these steps.</para>
294
295        <programlisting><prompt>%%</prompt> <userinput>export PATH=/bin:/sbin:/usr/bin:/usr/sbin</userinput>
296<prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
297<prompt>%%</prompt> <userinput>./configure --prefix=NEW_PREFIX --with-tcl-package=NEW_TCLPACKAGE</userinput>
298<prompt>%%</prompt> <userinput>make</userinput>
299<prompt>%%</prompt> <userinput>sudo make install</userinput>
300</programlisting>
301      </section>
302    </section>
303
304    <section id="installing.uninstalling">
305      <title>Uninstall</title>
306
307      <para>To uninstall MacPorts from the default location
308      <filename>/opt/local/</filename>, perform these commands from a terminal
309      window.</para>
310
311      <programlisting><prompt>%%</prompt> <userinput>sudo rm -rf /opt/local/</userinput>
312<prompt>%%</prompt> <userinput>sudo rm -rf /Applications/MacPorts/</userinput>
313<prompt>%%</prompt> <userinput>sudo rm -rf /Library/Tcl/macports1.0/</userinput>
314<prompt>%%</prompt> <userinput>sudo rm -rf /Library/LaunchDaemons/org.macports.*</userinput></programlisting>
315    </section>
316  </section>
317
318  <section id="installing.shell">
319    <title>Set the Bash Shell</title>
320
321    <para>The MacPorts installer (from Mac OS X package or source) places a
322    <filename>.profile</filename> file in your home directory (view files with
323    a dot using <command>ls -a</command>). The contents of the
324    <filename>~/.profile</filename> adds the MacPorts paths in front of the
325    standard Unix paths for the default Bash shell so that MacPorts libraries
326    will take precedence over vendor-supplied libraries if both are
327    present.</para>
328
329    <para>The path statement in the MacPorts-installed .profile is set as
330    shown.</para>
331
332    <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
333
334    <para>You must add this <varname>DISPLAY</varname> variable for
335    X11.</para>
336
337    <programlisting>export DISPLAY=:0.0</programlisting>
338
339    <para>Add the <varname>EDITOR</varname> variable to use your favorite text
340    editor. A complete <filename>~/.profile</filename> file with the added
341    variables is shown below.</para>
342
343    <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH
344export DISPLAY=:0.0
345export EDITOR=/usr/bin/pico
346</programlisting>
347
348    <para>Changes to <filename>~/.profile</filename> do not take effect until
349    a new terminal session is opened. Type <command>env</command> in the
350    terminal to verify the current environment settings. Example output of
351    <command>env</command> is below.</para>
352
353    <screen>TERM_PROGRAM=Apple_Terminal
354TERM=xterm-color
355SHELL=/bin/bash
356TERM_PROGRAM_VERSION=133
357USER=joebob
358__CF_USER_TEXT_ENCODING=0x1FC:0:0
359PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
360PWD=/Users/joebob
361EDITOR=/usr/bin/pico
362SHLVL=1
363HOME=/Users/joebob
364LOGNAME=joebob
365DISPLAY=:0.0
366SECURITYSESSIONID=b0cea0
367_=/usr/bin/env</screen>
368
369    <note>
370      <para>If you have either a <filename>.bash_login</filename> or a
371      <filename>.bash_profile</filename> file in your home directory, they may
372      take precedence over <filename>.profile</filename>. You may either
373      remove the previously used file, or add the contents of
374      <filename>.profile</filename> to it.</para>
375    </note>
376  </section>
377
378  <section id="installing.selfupdate">
379    <title>Selfupdate MacPorts</title>
380
381    <para>You must always execute a <quote>selfupdate</quote> after a new
382    MacPorts install, and you should also do it frequently thereafter. See
383    <link linkend="using.port.selfupdate">selfupdate</link> —one of several
384    <link linkend="using.port">port commands</link>.</para>
385  </section>
386</chapter>
Note: See TracBrowser for help on using the repository browser.