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

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

doc-newguide/xml/installing.xml: remove note made redundant by changeset:31985.

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