source: trunk/doc-new/guide/xml/using.xml @ 84102

Last change on this file since 84102 was 84102, checked in by jmr@…, 9 years ago

guide: add examples for mpkg and mdmg actions (#26930)

File size: 37.0 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="using">
5  <title>Using MacPorts</title>
6
7  <para>This chapter describes using the <command>port</command> command, port
8  variants, common tasks and port binaries<!--, and setting up an rsync
9  replication server-->.</para>
10
11  <section id="using.port">
12    <title>The port Command</title>
13
14    <para>The MacPorts <command>port</command> command is the main utility
15    used to interact with MacPorts. It is used to update
16    <filename>Portfile</filename>s and the MacPorts infrastructure, and
17    install and manage ports.</para>
18
19    <section id="using.port.help">
20      <title>help</title>
21
22      <para>The <option>help</option> action shows some brief information about
23      the specified action, or if no action is specified, shows basic usage
24      information for the <command>port</command> command in general.</para>
25
26      <programlisting><prompt>%%</prompt> <userinput>port help selfupdate</userinput></programlisting>
27      <screen>Usage: selfupdate --nosync
28
29Upgrade MacPorts itself and run the sync target</screen>
30    </section>
31
32    <section id="using.port.selfupdate">
33      <title>selfupdate</title>
34
35      <para>The <option>selfupdate</option> action should be used regularly to
36      <option>sync</option> the local ports tree with the global MacPorts
37      ports repository so you will have the latest port versions. It also
38      checks for new revisions of the MacPorts infrastructure, called MacPorts
39      base, and upgrades it when necessary.</para>
40
41      <note>
42        <para>Selfupdate runs only on Mac OS X. If you are running MacPorts on
43        another platform, you must use the <link
44        linkend="using.port.sync">sync</link> action to update the ports tree; to
45        update MacPorts base you must manually install a newer version from
46        source.</para>
47      </note>
48
49      <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
50
51      <para>Use the debug flag for verbose output.</para>
52
53      <programlisting><prompt>%%</prompt> <userinput>sudo port -d selfupdate</userinput></programlisting>
54
55      <screen>DEBUG: Rebuilding the MacPorts base system if needed.
56DEBUG: Synchronizing ports tree(s)
57Synchronizing from rsync://rsync.macports.org/release/ports/
58DEBUG: /usr/bin/rsync -rtzv --delete-after rsync://rsync.macports.org/release/ports/
59receiving file list ... done
60
61[ ... trimmed ... ]
62
63
64The MacPorts installation is not outdated and so was not updated
65DEBUG: Setting ownership to root
66selfupdate done!</screen>
67
68      <para>If selfupdate detects that a newer version of MacPorts base is
69      available, it automatically updates the installed copy of MacPorts base
70      to the latest released version. In that case, you will see the upgrade
71      Makefile execute, and when it finishes you will see this message:</para>
72
73      <screen>DEBUG: Updating using rsync
74receiving file list ... done
75
76Congratulations, you have successfully installed the MacPorts system.</screen>
77    </section>
78
79    <section id="using.port.sync">
80      <title>sync</title>
81
82      <para>The <option>sync</option> action performs a subset of
83      <option>selfupdate</option> actions. It synchronizes the ports tree, as
84      does <option>selfupdate</option>, but it does not check for upgrades to
85      MacPorts base. On Mac OS X, unless there is a special reason not to do
86      so, you should run <link
87      linkend="using.port.selfupdate">selfupdate</link>.</para>
88
89      <note>
90        <para>For platforms other than Mac OS X, <option>sync</option> is the
91        only way to get port updates because <option>selfupdate</option> is
92        supported only on Mac OS X.</para>
93      </note>
94    </section>
95
96    <section id="using.port.list">
97      <title>list</title>
98
99      <para>The <option>list</option> action lists the currently available version of
100      the specified ports, or if no ports are specified, displays a list of all available
101      ports. The list of available ports is very long, so use <link
102      linkend="using.port.search">search</link> if you know a port's name or
103      part of it.</para>
104
105      <programlisting><prompt>%%</prompt> <userinput>port list</userinput></programlisting>
106    </section>
107
108    <section id="using.port.search">
109      <title>search</title>
110
111      <para>The <option>search</option> action allows finding ports
112      by partial matches of the name or description. Other fields can be matched
113      against, and matched in different ways, by using options. Run <userinput>port help search</userinput>
114      for details.</para>
115
116      <programlisting><prompt>%%</prompt> <userinput>port search rrd</userinput></programlisting>
117
118      <screen>php5-rrdtool @1.0 (php, net, devel)
119    PHP 5 glue for rrdtool
120
121rrdtool @1.4.4 (net)
122    Round Robin Database
123
124Found 2 ports.</screen>
125    </section>
126
127    <section id="using.port.info">
128      <title>info</title>
129
130      <para>The <option>info</option> action is used to get information about
131      a port: description, maintainer, etc.</para>
132
133      <programlisting><prompt>%%</prompt> <userinput>port info flowd</userinput></programlisting>
134
135      <screen>flowd @0.9 (net)
136Variants:             universal
137
138Description:          flowd is a small, fast and secure NetFlow collector.
139Homepage:             http://www.mindrot.org/flowd.html
140
141Platforms:            darwin
142License:              unknown
143Maintainers:          nomaintainer@macports.org</screen>
144    </section>
145
146    <section id="using.port.deps">
147      <title>deps</title>
148
149      <para>The <option>deps</option> action shows you the dependencies of a
150      port; dependencies are explicitly declared in
151      <filename>Portfile</filename>s.</para>
152
153      <programlisting><prompt>%%</prompt> <userinput>port deps apache2</userinput></programlisting>
154
155      <screen>Full Name: apache2 @2.2.17_0+preforkmpm
156Library Dependencies: apr, apr-util, expat, openssl, pcre</screen>
157    </section>
158
159    <section id="using.port.variants">
160      <title>variants</title>
161
162      <para>The <option>variants</option> action allows you to check what
163      variations of a port are available before you install it. Variants are a
164      way for port authors to provide options that may be invoked at install
165      time. See <link linkend="using.variants.invoking">Invoking Port
166      Variants</link> below to install ports that have variants.</para>
167
168      <programlisting><prompt>%%</prompt> <userinput>port variants nmap</userinput></programlisting>
169
170      <screen>nmap has the variants:
171   no_pcre: build without pcre support
172   no_ssl: build without ssl support
173   universal: Build for multiple architectures
174   zenmap: build zenmap in addition to nmap</screen>
175    </section>
176
177    <section id="using.port.install">
178      <title>install</title>
179
180      <para>The action <option>install</option> is used to install a port. See
181      <link linkend="using.variants.invoking">Invoking Port Variants</link>
182      below to install ports that have variants.</para>
183
184      <programlisting><prompt>%%</prompt> <userinput>sudo port install nmap</userinput></programlisting>
185
186      <note>
187        <para>You may break up a port's installation into smaller steps for
188        troubleshooting by passing <command>port</command> a prior
189        installation phase such as fetch, configure, build, or destroot. See
190        section <link linkend="reference.phases">Port Phases</link> for a
191        complete list of phases.</para>
192      </note>
193    </section>
194
195    <section id="using.port.clean">
196      <title>clean</title>
197
198      <para>The action <option>clean</option> deletes all intermediate files
199      that MacPorts creates while building a port. A <userinput>port
200      clean</userinput> is also often necessary to remove corrupted tarballs
201      after a failed <userinput>fetch</userinput> phase.</para>
202
203      <programlisting><prompt>%%</prompt> <userinput>sudo port clean --all vile</userinput></programlisting>
204
205      <note>
206        <para>You may also clean files selectively by using options
207        <option>--dist</option>, <option>--archive</option>, or
208        <option>--work</option>.</para>
209      </note>
210    </section>
211
212    <section id="using.port.uninstall">
213      <title>uninstall</title>
214
215      <para>The <option>uninstall</option> action will uninstall an installed
216      port.</para>
217
218      <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall vile</userinput></programlisting>
219
220      <note>
221        <para>To also recursively uninstall the ports that the given port depends on,
222        use the <option>&#x2011;&#x2011;follow&#x2011;dependencies</option> flag. This will not uninstall
223        dependencies that are marked as requested or that have other dependents.</para>
224        <para>To recursively uninstall all ports that depend on the given port before uninstalling
225        the port itself, use the <option>&#x2011;&#x2011;follow&#x2011;dependents</option> flag.</para>
226        <para>If a port is a dependency of another installed port,
227        uninstall will not remove it unless you remove the dependent port(s)
228        first. To override this behavior, use the <option>-f</option> (force)
229        switch. This will obviously break the dependents. Don't force uninstall ports
230        unless you know what you are doing.</para>
231
232        <programlisting><prompt>%%</prompt> <userinput>sudo port -f uninstall vile</userinput></programlisting>
233      </note>
234    </section>
235
236    <section id="using.port.contents">
237      <title>contents</title>
238
239      <para>The <option>contents</option> action displays the files that have
240      been installed by a given port. Uninstalled ports cannot have their
241      contents listed.</para>
242
243      <programlisting><prompt>%%</prompt> <userinput>port contents xorg-renderproto</userinput></programlisting>
244
245      <screen>Port xorg-renderproto contains:
246  /opt/local/include/X11/extensions/render.h
247  /opt/local/include/X11/extensions/renderproto.h
248  /opt/local/lib/pkgconfig/renderproto.pc
249  /opt/local/share/doc/renderproto/renderproto.txt</screen>
250    </section>
251
252    <section id="using.port.installed">
253      <title>installed</title>
254
255      <para>The <option>installed</option> action displays the installed versions,
256      variants and activation status of the
257      specified ports, or if no ports are specified, all installed
258      ports. Use the <option>-v</option> option to also display the platform and
259      CPU architecture(s) for which the ports were built, and any variants which were
260      explicitly negated.</para>
261
262      <programlisting><prompt>%%</prompt> <userinput>port installed</userinput></programlisting>
263
264      <screen>The following ports are currently installed:
265  aalib @1.4rc5_2 (active)
266  apr @1.2.8_0 (active)
267  apr-util @1.2.8_2 (active)
268  atk @1.18.0_0 (active)
269
270[ ... trimmed ...]
271
272  wxWidgets @2.8.4_2 (active)
273  Xft2 @2.1.7_0 (active)
274  xrender @0.9.0_0 (active)
275  zlib @1.2.3_1 (active)</screen>
276
277    <programlisting><prompt>%%</prompt> <userinput>port -v installed atlas</userinput></programlisting>
278    <screen>The following ports are currently installed:
279  atlas @3.8.3_4+gcc44-gcc43 (active) platform='darwin 10' archs='x86_64'</screen>
280    </section>
281
282    <section id="using.port.outdated">
283      <title>outdated</title>
284
285      <para>The <option>outdated</option> action checks your installed ports
286      against the current ports tree to see if updated Portfiles have been
287      released since your ports were installed. Note that you will not see new
288      versions unless you have updated your ports tree using <option>selfupdate</option>
289      or <option>sync</option>.</para>
290
291      <programlisting><prompt>%%</prompt> <userinput>port outdated</userinput></programlisting>
292
293      <screen>apr                            1.2.8_0 &lt; 1.2.9_0
294autoconf                       2.61_0 &lt; 2.61_1
295gimp                           2.2.14_0 &lt; 2.2.16_0
296libtool                        1.5.22_0 &lt; 1.5.24_0
297pkgconfig                      0.21_0 &lt; 0.22_0</screen>
298    </section>
299
300    <section id="using.port.upgrade">
301      <title>upgrade</title>
302
303      <para>The <option>upgrade</option> action upgrades installed ports and
304      their dependencies when a <filename>Portfile</filename> in the
305      repository has been updated after a port was installed.</para>
306
307      <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade gnome</userinput></programlisting>
308
309      <para>If you wish not to upgrade a port's dependencies, use the
310      <option>-n</option> switch. Note that this will often cause problems.</para>
311
312      <programlisting><prompt>%%</prompt> <userinput>sudo port -n upgrade gnome</userinput></programlisting>
313
314      <para>If you'd like to upgrade all outdated ports, use this
315      command.</para>
316
317      <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade outdated</userinput></programlisting>
318
319      <note>
320        <para>The <option>upgrade</option> action by default does not
321        uninstall an upgraded port —it deactivates it. See section <link
322        linkend="internals.images">Port Images</link>, and also Destroot and
323        Activate phases in <link linkend="reference.phases">Port
324        Phases</link>. If you wish to uninstall the old version, use the
325        <option>-u</option> option.</para>
326
327        <programlisting><prompt>%%</prompt> <userinput>sudo port -u upgrade vile</userinput></programlisting>
328      </note>
329    </section>
330
331    <section id="using.port.dependents">
332      <title>dependents</title>
333
334      <para>The <option>dependents</option> action reports what ports depend
335      upon a given port, if any. MacPorts learns about dependents during port
336      installation, so uninstalled ports will always report that there are no
337      dependents.</para>
338
339      <programlisting><prompt>%%</prompt> <userinput>port dependents openssl</userinput></programlisting>
340
341      <screen>neon depends on openssl
342gnome-vfs depends on openssl
343libdap depends on openssl</screen>
344    </section>
345
346    <section id="using.port.livecheck">
347      <title>livecheck</title>
348
349      <para>The livecheck action checks to see if the application
350      corresponding to a given port has been updated at the developer's
351      download site. It's especially useful for port maintainers, but others
352      may also wish to see if a port has the latest available distribution
353      source. See section <link linkend="reference.livecheck">Livecheck</link>
354      for more information.</para>
355
356      <programlisting><prompt>%%</prompt> <userinput>port livecheck rrdtool</userinput></programlisting>
357
358      <screen>rrdtool seems to have been updated (port version: 1.2.23, new version: 1.3beta1)</screen>
359
360      <note>
361        <para>If livecheck finds no higher version at the port's download
362        site, it prints nothing. The option <option>-d</option> (debug) may be
363        used for detailed livecheck processing information.</para>
364      </note>
365
366      <para></para>
367    </section>
368
369    <section id="using.port.lint">
370      <title>lint</title>
371
372      <para>The lint action checks if the Portfile conforms to the MacPorts
373      standards specified in <link linkend="development">Portfile
374      Development</link>.</para>
375
376      <para>If a Portfile validates fine the following message is
377      shown.</para>
378
379      <programlisting><prompt>%%</prompt> <userinput>port lint chemtool</userinput></programlisting>
380
381      <screen>--->  Verifying Portfile for chemtool
382--->  0 errors and 0 warnings found.</screen>
383
384      <para>Otherwise the warnings and errors are listed.</para>
385
386      <programlisting><prompt>%%</prompt> <userinput>port lint KeyArcher</userinput></programlisting>
387
388      <screen>--->  Verifying Portfile for KeyArcher
389Warning: Line 2 should be a newline (after RCS tag)
390Warning: Line 5 has trailing whitespace before newline
391Error: Missing required variable: platforms
392--->  1 errors and 2 warnings found.
393</screen>
394    </section>
395  </section>
396
397  <section id="using.variants">
398    <title>Port Variants</title>
399
400    <para>Variants are a way for port authors to provide options for a port
401    that may be chosen during the port install. To display the available
402    variants, if any, use this command:</para>
403
404    <programlisting><prompt>%%</prompt> <userinput>port variants fetchmail</userinput></programlisting>
405
406    <screen>fetchmail has the variants:
407        universal
408        ssl: Support secure connections using OpenSSL
409        fetchmailconf: Install a graphical configurator
410        ntlm: Enable NTLM authentication</screen>
411
412    <note>
413      <para>In some ports, you may find variants for which descriptions have
414      not yet been written.</para>
415    </note>
416
417    <section id="using.variants.invoking">
418      <title>Invoking Variants</title>
419
420      <para>A variant can only be invoked when a port is installed. After you
421      have determined what variants a given port has, if any, you may install
422      a port using the variant as shown.</para>
423
424      <programlisting><prompt>%%</prompt> <userinput>sudo port install fetchmail +ssl</userinput></programlisting>
425
426      <para>Port variant execution may be verified using the
427      <command>port</command> command with the verbose switch.</para>
428
429      <programlisting><prompt>%%</prompt> <userinput>sudo port -v install fetchmail +ssl</userinput></programlisting>
430
431      <para>When a port is installed using a valid variant and specified
432      correctly, the verbose output will contain:</para>
433
434      <screen>DEBUG: Executing variant ssl provides ssl</screen>
435    </section>
436
437    <section id="using.variants.negating">
438      <title>Negating Default Variants</title>
439
440      <para>For an explanation of default variants see <link
441      linkend="development.variants">Port Variants</link>. Default variants
442      are optional, and not all ports using variants have them. For ports with
443      default variants, you may install a port without them by negating
444      default variants using "-" as shown.</para>
445
446      <programlisting><prompt>%%</prompt> <userinput>sudo port install fetchmail -ssl</userinput></programlisting>
447
448      <para>To verify that you have properly negated a default variant, you
449      may want to use verbose mode. But negated variants are simply not
450      reported in any way by the <command>port</command> command, as if they
451      did not exist. You will know you have successfully negated the default
452      variant in the example above if you do <emphasis>not</emphasis> see this
453      line in the verbose output.</para>
454
455      <screen>DEBUG: Executing variant ssl provides ssl</screen>
456    </section>
457  </section>
458
459  <section id="using.common-tasks">
460    <title>Common Tasks</title>
461
462    <para>This section lists common operations you may want to perform when managing a MacPorts
463    installation. Some commands are described in further details elsewhere in the guide.</para>
464
465    <para>Mind the 'sudo' for some of the subsequent examples, which is necessary if you have a
466    root-MacPorts-installation.</para>
467
468    <section id="using.common-tasks.updating">
469      <title>Updating your ports tree</title>
470
471      <para>is essential to stay up-to-date with MacPorts:</para>
472
473      <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
474
475      <screen>Password:
476--->  Updating the ports tree
477--->  Updating MacPorts base sources using rsync
478MacPorts base version 1.9.1 installed,
479MacPorts base version 1.9.1 downloaded.
480--->  MacPorts base is already the latest version
481
482The ports tree has been updated. To upgrade your installed ports, you should run
483  port upgrade outdated</screen>
484    </section>
485
486    <section id="using.common-tasks.showports">
487      <title>Show all ports which actually need updating</title>
488
489      <para>is often useful, in case you don't have time to wait for port upgrades
490          (Every port needs to be downloaded, configured, built and installed, which can be -
491          depending on your systems resources - a very time consuming procedure.):</para>
492
493      <programlisting><prompt>%%</prompt> <userinput>port outdated</userinput></programlisting>
494      <screen>The following installed ports are outdated:
495makedepend                     1.0.2_0 &lt; 1.0.3_0         
496Xft2                           2.1.14_0 &lt; 2.2.0_0       
497xorg-bigreqsproto              1.1.0_0 &lt; 1.1.1_0         
498xorg-compositeproto            0.4.1_0 &lt; 0.4.2_0         
499xorg-damageproto               1.2.0_0 &lt; 1.2.1_0         
500xorg-fixesproto                4.1.1_0 &lt; 4.1.2_0         
501xorg-libXdmcp                  1.0.3_0 &lt; 1.1.0_0         
502xorg-libXmu                    1.0.5_0 &lt; 1.1.0_0         
503xorg-libXScrnSaver             1.2.0_0 &lt; 1.2.1_0         
504xorg-randrproto                1.3.1_0 &lt; 1.3.2_0         
505xorg-scrnsaverproto            1.2.0_0 &lt; 1.2.1_0         
506xorg-xcmiscproto               1.2.0_0 &lt; 1.2.1_0         
507xpm                            3.5.8_0 &lt; 3.5.9_0         
508xorg-util-macros               1.10.1_0 &lt; 1.11.0_0</screen>
509    </section>
510
511    <section id="using.common-tasks.upgrading">
512      <title>Upgrading outdated ports</title>
513
514      <para>is usually done with the following command:</para>
515
516      <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade outdated</userinput></programlisting>
517
518      <para>In case you want to upgrade only a specific port (for whatever reason):</para>
519
520      <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade makedepend</userinput></programlisting>
521      <screen>Password:
522--->  Computing dependencies for makedepend
523--->  Fetching makedepend
524--->  Attempting to fetch makedepend-1.0.3.tar.bz2 from http://lil.fr.distfiles.macports.org/makedepend
525--->  Verifying checksum(s) for makedepend
526--->  Extracting makedepend
527--->  Configuring makedepend
528--->  Building makedepend
529--->  Staging makedepend into destroot
530--->  Computing dependencies for makedepend
531--->  Installing makedepend @1.0.3_0
532--->  Deactivating makedepend @1.0.2_0
533--->  Activating makedepend @1.0.3_0
534--->  Cleaning makedepend</screen>
535    </section>
536
537    <section id="using.common-tasks.removeinactive">
538      <title>Removing inactive version(s) of upgraded port(s)</title>
539     
540      <para>makes sense if you are sure that you won't change back to the older version(s)
541            (which could be necessary in case of newly introduced bugs in the upgraded port
542            version):</para>
543
544      <programlisting><prompt>%%</prompt> <userinput>port installed inactive</userinput></programlisting>
545      <screen>The following ports are currently installed:
546  makedepend @1.0.2_0</screen>
547 
548      <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall inactive</userinput></programlisting>
549      <screen>Password:
550--->  Uninstalling makedepend @1.0.2_0</screen>
551
552      <para>Of course one could also select only a specific inactive port,
553            but that requires to specify the exact version:</para>
554      <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall makedepend @1.0.2_0</userinput></programlisting>
555      <screen>Password:
556--->  Uninstalling makedepend @1.0.2_0</screen>
557    </section>
558
559    <section id="using.common-tasks.finddepending">
560      <title>Finding ports depending on a certain port</title>
561
562      <para>can sometimes be very helpful (example: find ports depending on 'xorg-util-macros'):</para>
563
564      <programlisting><prompt>%%</prompt> <userinput>port echo depends:xorg-util-macros</userinput></programlisting>
565
566      <screen>mkfontscale
567xorg-libAppleWM
568xorg-libX11
569xorg-libXaw
570xorg-libXevie
571xorg-libXp
572xorg-libXt
573xorg-server
574xorg-server-devel
575xscope
576xtrap</screen>
577    </section>
578
579    <section id="using.common-tasks.findleaves">
580      <title>Finding leaves (nondependent ports)</title>
581      <para>can be sometimes worthwhile, since often additional ports get installed when
582            a specific port is installed. One can imagine that if one keeps installing and
583            uninstalling ports for some time the MacPorts tree can be swamped with ports actually
584            not necessary anymore. Leaves can be found by issuing the command:</para>
585
586      <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
587      <screen>aalib                          @1.4rc5_4
588autoconf                       @2.68_0
589autoconf263                    @2.63_0
590automake                       @1.11.1_0
591cmake                          @2.8.2_4
592coreutils                      @8.5_0</screen>
593
594      <para>The following command delivers a similar result:</para>
595      <programlisting><prompt>%%</prompt> <userinput>port installed leaves</userinput></programlisting>
596      <screen>  aalib @1.4rc5_4 (active)
597  autoconf @2.68_0 (active)
598  autoconf263 @2.63_0 (active)
599  automake @1.11.1_0 (active)
600  cmake @2.8.2_4 (active)
601  coreutils @8.5_0 (active)</screen>
602
603      <para>These leaves may be wanted, but could also be unwanted ports. (See the following entry!)</para>
604          </section>
605
606    <section id="using.common-tasks.keeplean">
607      <title>Keep your MacPorts installation lean by defining leaves as requested ports</title>
608      <para>Well, before we come to the procedure of defining your requested ports,
609            let's have a look at a typical scenario where you want to understand what is
610            actually installed and what is on the other hand truly necessary for your system.
611            Say checking leaves of your MacPorts installation gives this output:</para>
612
613      <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
614      <screen>aalib                          @1.4rc5_4
615autoconf                       @2.68_0
616autoconf263                    @2.63_0
617automake                       @1.11.1_0
618cmake                          @2.8.2_4
619coreutils                      @8.5_0
620physfs                         @2.0.1_0</screen>
621
622      <para>Now it is up to the user to decide what's needed and what is not.
623            Let's say one certainly would want ports starting with autoconf up to coreutils,
624            since they are often used in port installation. Set those as requested ports using:</para>
625
626      <programlisting><prompt>%%</prompt> <userinput>sudo port setrequested autoconf autoconf263 automake cmake coreutils</userinput></programlisting>
627
628      <para>Say port aalib is not needed anymore, while physfs seems odd and since you don't
629            know what to make of it, you need to check out what it actually is and which ports needed
630            its installation at some time in the past.</para>
631
632      <programlisting><prompt>%%</prompt> <userinput>port info physfs</userinput></programlisting>
633      <screen>physfs @2.0.1 (devel)
634Variants:             debug, universal
635
636Description:          PhysicsFS is a library to provide abstract access to various
637                      archives. It is intended for use in video games, and the design
638                      was somewhat inspired by Quake 3's file subsystem.
639Homepage:             http://icculus.org/physfs/
640
641Build Dependencies:   cmake
642Library Dependencies: zlib
643Platforms:            darwin
644License:              unknown
645Maintainers:          nomaintainer@macports.org</screen>
646
647      <para>Well, hmm, you certainly didn't want to install Quake 3 in the past. So, let's
648            find out which ports actually depend on it, perhaps that might ring a bell:</para>
649
650      <programlisting><prompt>%%</prompt> <userinput>port echo depends:physfs</userinput></programlisting>
651      <screen>fbg                             
652libsdl_sound                   
653lincity-ng                     
654netpanzer</screen>
655
656      <para>No, you didn't install netpanzer either,
657            but - see there - fbg (The classic Falling Block Game!) was once on your agenda. But
658            unfortunately that port was broken
659            (see issue <ulink url="http://trac.macports.org/ticket/24641">#24641</ulink>) when
660            you were trying to install it... Before you ran into the issue, of course, fbg's
661            dependencies were resolved by MacPorts, which is why port physfs is still present on
662            your system. Uff, great, confusion resolved. :-)</para>
663
664      <para>When you've step-by-step figured out which ports you want to keep on your system and
665            have set them as requested, you'll have a list of unnecessary ports, which might be
666            eventually as short as this:</para>
667
668      <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
669      <screen>aalib                          @1.4rc5_4
670physfs                         @2.0.1_0 </screen>
671
672      <para>Get rid of them by issuing the command:</para>
673
674      <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall leaves</userinput></programlisting>
675      <screen>--->  Deactivating physfs @2.0.1_0
676--->  Cleaning physfs
677--->  Uninstalling physfs @2.0.1_0
678--->  Cleaning physfs
679--->  Deactivating aalib @1.4rc5_4
680--->  Uninstalling aalib @1.4rc5_4</screen>
681
682      <para>Find all installed ports you previously set as requested using:</para>
683
684      <programlisting><prompt>%%</prompt> <userinput>port installed requested</userinput></programlisting>
685
686      <para>Checking the list of leaves from time to time will help to keep your system
687            free of too much "garbage". However, keep in mind that some ports may be dependencies
688            only during the installation of a port (library dependencies, installation or
689            configuration tools, etc.). So, be careful when removing seemingly unnecessary leaves,
690            otherwise you'll see them being installed again and again.</para>
691      </section>
692  </section>
693
694  <section id="using.binaries">
695    <title>Port Binaries</title>
696
697    <para>MacPorts can pre-compile ports into binaries so applications need
698    not be compiled when installing on a target system. MacPorts may create
699    two types of binaries: archives and packages.</para>
700
701    <section id="using.binaries.archives">
702      <title>Binary Archives</title>
703
704      <para>Binary archives can only be used on a target system running
705      MacPorts. Binary archives allow MacPorts utilities to begin installation
706      after the destroot phase and install and activate a port on the target
707      system. Binary archives are created whenever a port is installed, and can also
708      be downloaded from a server.</para>
709
710      <programlisting><prompt>%%</prompt> <userinput>sudo port -d archive logrotate</userinput></programlisting>
711
712      <para>Debug output is shown below.</para>
713
714      <screen>---&gt;  Creating logrotate-3.7_0.i386.tbz2
715
716[ ... trimmed ... ]
717
718DEBUG:
719./
720./+COMMENT
721./+CONTENTS
722./+DESC
723./+PORTFILE
724./+STATE
725./opt/
726./opt/local/
727./opt/local/etc/
728./opt/local/etc/logrotate.conf
729./opt/local/man/
730./opt/local/man/man8/
731./opt/local/man/man8/logrotate.8
732./opt/local/sbin/
733./opt/local/sbin/logrotate
734---&gt;  Archive logrotate-3.7_0.i386.tbz2 packaged
735DEBUG: Executing archive_finish
736---&gt;  Archive for logrotate 3.7_0 packaged</screen>
737
738      <para>Binary archive files are placed in
739      <filename>${prefix}/var/macports/software/</filename>. The archive file
740      type is set in the <filename>macports.conf</filename> file. The default
741      format is .tbz2; other options are: tar, tbz, tbz2, tgz, tlz, txz, xar, zip, cpgz,
742      cpio.</para>
743    </section>
744
745    <section id="using.binaries.binary-packages">
746      <title>Binary Packages</title>
747
748      <para>Binary packages are standalone binary installers that are
749      precompiled; they do not require MacPorts on the target system. Binary
750      files created with MacPorts may be either .pkg (Mac OS X Installer
751      Packages), or RPM (RPM Package Manager) format. MacPorts may also
752      process a .pkg package into a Mac OS X .dmg disk image file. You may
753      create binary packages with the <command>port</command> command as shown
754      in these examples.</para>
755
756      <programlisting><prompt>%%</prompt> <userinput>sudo port pkg pstree</userinput></programlisting>
757
758      <para>You may create a Mac OS X .dmg disk image file as shown.</para>
759
760      <programlisting><prompt>%%</prompt> <userinput>sudo port dmg pstree</userinput></programlisting>
761
762      <para>You can also create a metapackage containing packages of a port and all its
763      dependencies:</para>
764
765      <programlisting><prompt>%%</prompt> <userinput>sudo port mpkg gimp2</userinput></programlisting>
766
767      <para>Just as with a single package, a metapackage can also be wrapped in a .dmg.</para>
768
769      <programlisting><prompt>%%</prompt> <userinput>sudo port mdmg gimp2</userinput></programlisting>
770
771      <para>You may compile a port into an RPM file as shown, in order to
772      install it onto a target that has RPM utilities or a full package
773      management system that can install RPMs.</para>
774
775      <programlisting><prompt>%%</prompt> <userinput>sudo port rpm pstree</userinput></programlisting>
776
777      <para>All packages are placed in a port's work directory.</para>
778    </section>
779
780    <section id="using.binaries.source-packages">
781      <title>Port Source Packages</title>
782
783      <para>Source packages are bundles consisting of a
784      <filename>Portfile</filename>, patches if needed, and any other files
785      required to install the port. Port source packages are mainly used by
786      developers of package management and port submission frameworks. Port
787      source packages may be in either .portpkg (XAR) or .nosrc.rpm (SRPM)
788      format.</para>
789    </section>
790  </section>
791
792  <!--
793  <section id="using.rsync-replication">
794    <title>Rsync Replication Servers</title>
795
796    <para>You may setup an rsync replication server on your local network to
797    minimize internet delay and bandwidth when performing MacPorts selfupdate
798    operations. An rsync replication server pulls the latest MacPorts base,
799    development, and port sources from the remote MacPorts Subversion server,
800    and then serves as the rsync source when rsync replication clients on the
801    local network perform selfupdates. </para>
802
803    <note>
804      <para>Only advanced users should attempt to setup an rsync replication
805      server. Before doing so, please contact <email>macports-mgr @
806      lists.macosforge.org</email>. If the scripts are run too often you may overload
807      the MacPorts rsync mirrors; it must not be run any more often than each
808      one-half hour and should be run at an offset to the clock half hour
809      periods.</para>
810    </note>
811
812    <section id="using.rsync-replication.server-setup">
813      <title>Rsync Server Setup</title>
814
815      <para>TODO: This section needs to be completed.</para>
816
817      <para>To setup a host as an rsync replication server, follow these
818      steps:</para>
819
820      <orderedlist>
821        <listitem>
822          <para>Change to the portmgr directory where
823          <filename>mprsyncup</filename> and <filename>rsync.repos</filename>
824          reside.</para>
825
826          <programlisting><prompt>%%</prompt> <userinput>cd ${prefix}/var/macports/sources/rsync.macports.org/release/ \
827        base/portmgr</userinput>
828</programlisting>
829        </listitem>
830
831        <listitem>
832          <para>Set variables in the <filename>mprsyncup</filename>
833          script.</para>
834
835          <programlisting>???</programlisting>
836        </listitem>
837
838        <listitem>
839          <para>Set variables in the <filename>rsync.repos</filename>
840          script.</para>
841
842          <programlisting>???</programlisting>
843        </listitem>
844
845        <listitem>
846          <para>Set the <filename>mprsyncup</filename> and
847          <filename>rsync.repos</filename> scripts in
848          <filename>crontab</filename>.</para>
849
850          <note>
851            <para>If you wish to setup and rsync replication server, please
852            contact <email>macports-mgr@lists.macosforge.org</email>. If the
853            scripts are run too often you may overload the MacPorts rsync mirrors;
854            It must not be run any more often than each one-half hour and should
855            be run at an offset to the clock half hour periods.</para>
856          </note>
857
858          <programlisting><prompt>%%</prompt> <userinput>sudo crontab -e</userinput></programlisting>
859
860          <programlisting>15 * * * * ${prefix}/var/macports/sources/rsync.macports.org/release/ \
861          base/portmgr/mprsyncup</programlisting>
862        </listitem>
863      </orderedlist>
864    </section>
865
866    <section id="using.rsync-replication.client-setup">
867      <title>Rsync Client Setup</title>
868
869      <para>To setup a host as an rsync replication client, follow these
870      steps:</para>
871
872      <orderedlist>
873        <listitem>
874          <para>Change to the MacPorts <filename>etc/</filename> directory to
875          access <filename>macports.conf</filename> and
876          <filename>sources.conf</filename>.</para>
877
878          <programlisting><prompt>%%</prompt> <userinput>cd ${prefix}/etc/macports</userinput></programlisting>
879        </listitem>
880
881        <listitem>
882          <para>In <filename>macports.conf</filename>, set variable
883          <varname>rsync_server</varname> to the rsync replication server; the
884          <varname>rsync_dir</varname> path variable can be left at the
885          default if you follow the defaults that the MacPorts mirrors
886          use.</para>
887
888          <programlisting>rsync_server            rsync.mycompany.com
889
890rsync_dir               release/base/</programlisting>
891        </listitem>
892
893        <listitem>
894          <para>In <filename>sources.conf</filename>, set the URL rsync:// to
895          the rsync replication server.</para>
896
897          <programlisting>rsync://rsync.mycompany.com/release/ports/</programlisting>
898        </listitem>
899      </orderedlist>
900    </section>
901  </section>
902-->
903</chapter>
Note: See TracBrowser for help on using the repository browser.