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

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

installing.xml: list the latest versions of Xcode

File size: 17.4 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 section 1 and section 2 (installing X11 and Xcode
9  Tools) are Mac OS X specific. If you wish to install MacPorts on another
10  platform, first make sure you have X11 and gcc installed, and then begin at
11  section 3.2 by performing <link
12  linkend="installing.macports.source">MacPorts install from source</link> and
13  proceed to the end of the chapter.</para>
14
15  <section id="installing.x11">
16    <title>Install X11</title>
17
18    <para>It is recommended that you install the X Window System (X11) even if
19    you don't plan to run X11 applications immediately. Apple's X11 is
20    preferred over either of the X11 ports, XFree86 and Xorg, therefore
21    Apple's X11 is normally used to satisfy ports that depend upon X11 (see
22    <link linkend="reference.dependencies.types">non-port
23    dependencies</link>). If Apple's X11 wasn't installed when Mac OS X was
24    installed, follow these steps.</para>
25
26    <orderedlist>
27      <listitem>
28        <para>Insert the <quote>Mac OS X Install Disk</quote> and run the
29        package named <quote>Optional Installs</quote>.</para>
30      </listitem>
31
32      <listitem>
33        <para>At the software selection window expand the
34        <guilabel>Applications</guilabel> category and click the check box
35        beside <guilabel>X11</guilabel> (and nothing else).</para>
36      </listitem>
37
38      <listitem>
39        <para>Click <guibutton>Install</guibutton> to install X11.</para>
40      </listitem>
41
42      <listitem>
43        <para>Drag the <filename>/Applications/Utilities/X11</filename> icon
44        to your dock —you must open X11 before launching an X11
45        application.</para>
46      </listitem>
47    </orderedlist>
48
49    <para>If you're using Mac OS X 10.3 then you can download the X11
50    installer from the Apple <ulink
51    url="http://apple.com/support/downloads/x11formacosx.html">download
52    page</ulink>.</para>
53
54    <note>
55      <para>X11 and the X11SDK (from Xcode Tools) are both required for X11
56      apps. To verify the presence of both, check for files
57      <filename>com.apple.pkg.X11User.bom</filename> &amp;
58      <filename>com.apple.pkg.X11SDKLeo.bom</filename> in
59      <filename>/Library/Receipts/boms/</filename>. On Mac OS X 10.4, look for
60      files <filename>X11User.pkg</filename> &amp;
61      <filename>X11SDK.pkg</filename> in
62      <filename>/Library/Receipts/</filename>.</para>
63    </note>
64
65    <section id="installing.x11.settings">
66      <title>Optional X11 Settings</title>
67
68      <para>To launch X11 applications directly from an X11 window (instead of
69      a terminal window), you need to have the MacPorts paths imported into
70      X11 sessions when they are opened. This is a two step process.</para>
71
72      <para>First, tell X11 about the <filename>~/.profile</filename> file
73      that will be created after you install MacPorts. Do this by editing the
74      file <filename>/etc/X11/xinit/xinitrc</filename> and adding this line
75      near the top.</para>
76
77      <programlisting>source ~/.profile</programlisting>
78
79      <para>Now finish the process by making subsequent X11 sessions opened
80      using the menu bar respect your <filename>.profile</filename>
81      file.</para>
82
83      <orderedlist>
84        <listitem>
85          <para>Open X11 and select <guimenuitem>Customize Menu
86          ...</guimenuitem> from the <guimenu>Applications</guimenu>
87          menu.</para>
88        </listitem>
89
90        <listitem>
91          <para>Double-click the menu item <guimenuitem>Terminal</guimenuitem>
92          and change: <quote>xterm</quote> to <quote>xterm -ls</quote></para>
93        </listitem>
94
95        <listitem>
96          <para>Click <guibutton>Done</guibutton> to save the change.</para>
97        </listitem>
98      </orderedlist>
99    </section>
100  </section>
101
102  <section id="installing.xcode">
103    <title>Install Xcode Tools</title>
104
105    <para>To install Xcode Tools and the X11 SDK, follow these steps.</para>
106
107    <orderedlist>
108      <listitem>
109        <para>Download and install the latest version of <ulink
110        url="http://developer.apple.com/tools/xcode/">Xcode Tools</ulink> from
111        Apple's developer site—do not install it from a Mac OS X install disk
112        unless you've checked for the latest version on Apple's site; older
113        versions of Xcode Tools often cause port install failures. The latest
114        versions at the time of this writing are Xcode 3.1 for Mac OS X 10.5
115        Leopard, Xcode 2.5 for Mac OS X 10.4 Tiger, and Xcode 1.5 for Mac OS X
116        10.3 Panther.</para>
117      </listitem>
118
119      <listitem>
120        <para>Run the Xcode Tools package installer.</para>
121      </listitem>
122
123      <listitem>
124        <para>Click the button <guibutton>Customize</guibutton>, expand the
125        Applications category and click the check box beside <guibutton>X11
126        SDK</guibutton> to add it to the default items.</para>
127      </listitem>
128
129      <listitem>
130        <para>Click <guibutton>Install</guibutton> to install Xcode Tools and
131        the X11 SDK.</para>
132      </listitem>
133    </orderedlist>
134
135    <note>
136      <para>Xcode Tools are not updated via Mac OS X's Software Update
137      utility.</para>
138    </note>
139  </section>
140
141  <section id="installing.macports">
142    <title>Install MacPorts</title>
143
144    <para>If you are using Mac OS X, you should install MacPorts using the Mac
145    OS X package installer unless you do not wish to install it to
146    <filename>/opt/local/</filename>, the default MacPorts location, or if you
147    wish to install a pre-release version of MacPorts base. However, if you
148    wish to <link linkend="installing.macports.source.multiple">install
149    multiple copies of MacPorts</link> or install MacPorts on another OS
150    platform, you must <link linkend="installing.macports.source">install
151    MacPorts from the source code</link>.</para>
152
153    <note>
154      <para>Though a distinction is made between pre-release and release
155      versions of MacPorts base, the ports collection supports no such
156      distinction or versioning. The <link
157      linkend="using.port.selfupdate">selfupdate</link> command installs the
158      latest port revisions from subversion (at a slight delay), and updates
159      MacPorts base to the latest released version.</para>
160    </note>
161
162    <section id="installing.macports.binary">
163      <title>Mac OS X Package Install</title>
164
165      <para>The Mac OS X package installer automatically installs MacPorts,
166      <link linkend="installing.shell">sets the shell environment</link>, and
167      runs a <link linkend="using.port.selfupdate">selfupdate</link> operation
168      to update the ports tree and MacPorts base with the latest
169      release.</para>
170
171      <orderedlist>
172        <listitem>
173          <para>Download the latest <filename>MacPorts-1.x.x.dmg</filename>
174          disk image from the <ulink
175          url="http://svn.macports.org/repository/macports/downloads/">MacPorts
176          download directory</ulink>.</para>
177        </listitem>
178
179        <listitem>
180          <para>Double-click the <filename>MacPorts-1.x.x.pkg</filename>
181          package installer on the disk image.</para>
182        </listitem>
183
184        <listitem>
185          <para>Perform the default <quote>easy</quote> install.</para>
186        </listitem>
187      </orderedlist>
188    </section>
189
190    <section id="installing.macports.source">
191      <title>Source Install</title>
192
193      <para>If you installed MacPorts using the package installer, skip this
194      section. To install MacPorts from the source code, follow the steps
195      below.</para>
196
197      <orderedlist>
198        <listitem>
199          <para>Download and unzip the latest MacPorts tarball from the <ulink
200          url="http://svn.macports.org/repository/macports/downloads/">MacPorts
201          download directory</ulink>.</para>
202        </listitem>
203
204        <listitem>
205          <para>Perform the commands shown in a terminal window. If you wish
206          to use a path other than <filename>/opt/local</filename>, use the
207          option <option>--prefix</option> and substitute a path for
208          NEW_PREFIX.</para>
209
210          <programlisting><prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
211<prompt>%%</prompt> <userinput>./configure</userinput> --prefix=NEW_PREFIX  (setting prefix is optional)
212<prompt>%%</prompt> <userinput>make</userinput>
213<prompt>%%</prompt> <userinput>sudo make install</userinput></programlisting>
214        </listitem>
215      </orderedlist>
216
217      <section id="installing.macports.source.multiple">
218        <title>Install Multiple MacPorts Copies</title>
219
220        <para>Occasionally a MacPorts developer may wish to install more than
221        one MacPorts instance on the same host. Only one copy of MacPorts may
222        use the default Tcl library path <filename>/Library/Tcl/</filename>,
223        so for additional installations use the option
224        <option>--with-tclpackage</option> as shown below and substitute
225        NEW_TCL_PACKAGE with any empty directory, for example
226        <filename>/Library/Tcl/macports-new/</filename>.</para>
227
228        <note>
229          <para>The first command temporarily removes the standard MacPorts
230          binary paths because they must not be present while installing a
231          second instance.</para>
232        </note>
233
234        <programlisting><prompt>%%</prompt> <userinput>export PATH=/bin:/sbin:/usr/bin:/usr/sbin</userinput>
235<prompt>%%</prompt> <userinput>cd ~/MacPorts-1.x.x/</userinput>
236<prompt>%%</prompt> <userinput>./configure --prefix=NEW_PREFIX --with-tclpackage=NEW_TCLPACKAGE</userinput>
237<prompt>%%</prompt> <userinput>make</userinput>
238<prompt>%%</prompt> <userinput>sudo make install</userinput>
239</programlisting>
240      </section>
241    </section>
242
243    <section id="installing.macports.upgrade">
244      <title>MacPorts Upgrade</title>
245
246      <para>MacPorts base upgrades are performed automatically (when a newer
247      release is available) during a <link
248      linkend="using.port.selfupdate">selfupdate</link> operation. To upgrade
249      a copy of MacPorts that was installed from source to the newer release
250      of the source code, simply repeat the <link
251      linkend="installing.macports.source">source install</link> with the
252      newer version of the MacPorts source code.</para>
253    </section>
254
255    <section id="installing.macports.uninstalling">
256      <title>Uninstall</title>
257
258      <para>To uninstall MacPorts from the default location
259      <filename>/opt/local/</filename>, perform this command from a terminal
260      window.</para>
261
262      <programlisting><prompt>%%</prompt> <userinput>sudo rm -rf \
263    /opt/local \
264    /etc/manpaths.d/macports \
265    /etc/paths.d/macports \
266    /Applications/DarwinPorts \
267    /Applications/MacPorts \
268    /Library/LaunchDaemons/org.macports.* \
269    /Library/Receipts/DarwinPorts*.pkg \
270    /Library/Receipts/MacPorts*.pkg \
271    /Library/StartupItems/DarwinPortsStartup \
272    /Library/Tcl/darwinports1.0 \
273    /Library/Tcl/macports1.0</userinput></programlisting>
274    </section>
275  </section>
276
277  <section id="installing.shell">
278    <title>MacPorts and the Shell</title>
279
280    <para>MacPorts requires that some environmental variables be set in the
281    shell. When MacPorts is installed using the Mac OS X package installer, a
282    <quote>postflight</quote> script is run after installation that
283    automatically copies a <filename>.profile</filename> containing variables
284    according to the rules described in the following section. Those <link
285    linkend="installing.macports.source">installing MacPorts from source
286    code</link> must modify their environment manually using the rules as a
287    guide.</para>
288
289    <note>
290      <para>If you have either a <filename>.bash_login</filename> or a
291      <filename>.bash_profile</filename> file in your home directory, they may
292      take precedence over <filename>.profile</filename>. You may either
293      remove the previously used file, or add the contents of
294      <filename>.profile</filename> to it.</para>
295    </note>
296
297    <section id="installing.shell.postflight">
298      <title>The Postflight Script</title>
299
300      <para>The postflight script automatically copies a
301      <filename>.profile</filename> containing the <varname>PATH</varname>
302      variable, and optionally the <varname>MANPATH</varname> and
303      <varname>DISPLAY</varname> variables according to the rules described
304      below. If a current <filename>.profile</filename> file exists at
305      installation time it is renamed to <quote>mpsaved_$timestamp</quote>.
306      Those <link linkend="installing.macports.source">installing MacPorts
307      from source code</link> must modify their environment manually using the
308      rules as a guide.</para>
309
310      <itemizedlist>
311        <listitem>
312          <para>Required: <varname>PATH</varname> variable</para>
313
314          <para>This variable is set by the postflight script to append the
315          MacPorts executable paths to the default path as shown. The MacPorts
316          paths are appended at the front of <varname>PATH</varname> so the
317          MacPorts libraries will take precedence over vendor-supplied
318          libraries for ported software at runtime.</para>
319
320          <programlisting>export PATH=/opt/local/bin:/opt/local/sbin:$PATH</programlisting>
321
322          <note>
323            <para>The user environment's $PATH is not in effect while ports
324            are being installed, because the $PATH is scrubbed before ports
325            are installed, and restored afterwards. To change the search path
326            for locating system executables (rsync, tar, etc.) during port
327            installation, see the <link
328            linkend="internals.configuration-files.macports-conf">macports.conf</link>
329            file variable <varname>binpath</varname>. But changing this
330            variable is for advanced users only, and is not generally needed
331            or recomended.</para>
332          </note>
333        </listitem>
334
335        <listitem>
336          <para>Optional: <varname>MANPATH</varname> variable</para>
337
338          <para>Condition: If prior to MacPorts installation a
339          <varname>MANPATH</varname> variable exists in a current
340          <filename>.profile</filename> that contains neither the value
341          <filename>${prefix}/share/man,</filename> nor any empty values, the
342          postflight script sets the <varname>MANPATH</varname> variable as
343          shown below. Otherwise, the <varname>MANPATH</varname> variable is
344          omitted.</para>
345
346          <programlisting>export MANPATH=/opt/local/share/man:$MANPATH</programlisting>
347
348          <para>Here are some examples of paths that contain empty
349          values:</para>
350
351          <simplelist>
352            <member>/usr/share/man:</member>
353
354            <member>:/usr/share/man</member>
355
356            <member>/usr/share/man::/usr/X11R6/man</member>
357          </simplelist>
358        </listitem>
359
360        <listitem>
361          <para>Optional: <varname>DISPLAY</varname> variable</para>
362
363          <para>Condition: If installing on a Mac OS X version earlier than
364          10.5 (Leopard), and if a<filename> .profile</filename> file exists
365          at time of MacPorts installation without a
366          <varname>DISPLAY</varname> variable, the postflight script sets a
367          <varname>DISPLAY</varname> variable as shown below. The
368          <varname>DISPLAY</varname> variable is always omitted on Mac OS X
369          10.5 or higher.</para>
370
371          <programlisting>export DISPLAY=:0.0</programlisting>
372        </listitem>
373      </itemizedlist>
374    </section>
375
376    <section id="installing.shell.verifyprofile">
377      <title>Verify the .profile</title>
378
379      <para>To verify that the <filename>.profile</filename> containing the
380      MacPorts variables is in effect, type <command>env</command> in the
381      terminal to verify the current environment settings after the
382      <filename>.profile</filename> has been created. Example output for the
383      <command>env</command> command is shown below.</para>
384
385      <note>
386        <para>Changes to <filename>~/.profile</filename> do not take effect
387        until a new terminal session is opened.</para>
388      </note>
389
390      <screen>MANPATH=
391TERM_PROGRAM=Apple_Terminal
392TERM=xterm-color
393SHELL=/bin/bash
394TERM_PROGRAM_VERSION=237
395USER=joebob
396__CF_USER_TEXT_ENCODING=0x1FC:0:0
397PATH=/opt/local/bin:/opt/local/sbin:/bin:/sbin:/usr/bin:/usr/sbin
398PWD=/Users/joebob
399EDITOR=/usr/bin/pico
400SHLVL=1
401HOME=/Users/joebob
402LOGNAME=joebob
403DISPLAY=:0.0
404SECURITYSESSIONID=b0cea0
405_=/usr/bin/env</screen>
406    </section>
407
408    <section id="installing.shell.editorvar">
409      <title>Optional EDITOR Variable</title>
410
411      <para>A useful environment variable to set in
412      <filename>.profile</filename> is the <varname>EDITOR</varname> variable.
413      Setting this variable allows you to use the edit option to the port
414      command to edit Portfiles quickly and easily. Set the
415      <varname>EDITOR</varname> variable to point to your favorite text
416      editor.</para>
417
418      <para>For example, to use the nano editor, add this line to your
419      <filename>~/.profile</filename>:</para>
420
421      <programlisting>export EDITOR=/usr/bin/nano</programlisting>
422
423      <para>To use the user-friendly GUI editor <ulink
424      url="http://www.barebones.com/products/textwrangler/">TextWrangler</ulink>
425      (installation required), add this line to your
426      <filename>~/.profile</filename>:</para>
427
428      <programlisting>export EDITOR=/usr/bin/edit</programlisting>
429    </section>
430  </section>
431</chapter>
Note: See TracBrowser for help on using the repository browser.