source: branches/gsoc11-statistics/base/doc/port.1 @ 78932

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

manual merge/rewrite of images-and-archives branch, integrated with archivefetch and registry2.0

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 20.4 KB
Line 
1.\" port.1
2.\"
3.\" Copyright (c) 2002 Apple Computer, Inc.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of Apple Computer, Inc. nor the names of its
15.\"    contributors may be used to endorse or promote products derived from
16.\"    this software without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd April 29, 2007
31.Dt PORT 1 "MacPorts"
32.Os
33.Sh NAME
34.Nm port
35.Nd operate on individual or multiple Mac
36.Ar ports
37.Sh SYNOPSIS
38.Nm
39.Op Fl bcdfknopqRstuvy
40.Op Fl D Ar portdir
41.Op Fl F Ar cmdfile
42.Op Ar action
43.Op Ar actionflags
44.Op Oo Ar portname | pseudo-portname | port-url Oc
45.Op Oo Ar @version Oc Oo +/-variant ... Oc ... Oo option=value ... Oc
46.Sh DESCRIPTION
47.Nm
48is designed to operate on individual or multiple Mac
49.Ar ports ,
50optionally within a single call, based on the requested
51.Ar action .
52If no
53.Ar portdir
54or
55.Ar portname
56is specified, the current working directory is assumed; if no
57.Ar action
58is specified the port command enters interactive mode, in which commands are read via stdin. Batch commands may be
59passed via a
60.Ar cmdfile .
61Port
62.Ar options
63are passed as key=value pairs and take precedence over individual
64.Ar portname
65options as specified in its Portfile and system-wide settings.
66.Pp
67Port
68.Ar variants
69can specified as
70.Ar +name ,
71which indicates the variant is desired, or
72.Ar -name ,
73indicating the contrary. In case of ambiguities, a port can be fully specified with the
74.Ar @version_revision+variants
75format.
76.Pp
77Installed ports can be activated or deactivated without being uninstalled. A port can be installed if all other
78version/variant(s) combinations installed at any given moment are deactivated.
79.Pp
80The
81.Nm
82command knows various
83.Ar pseudo-portnames
84that will expand to the specified set of ports from the available ports tree(s). These may be used in place of a
85.Ar portname .
86Common options are:
87.Pp
88.Bl -bullet -offset indent -compact
89.It
90.Ar all :
91all the ports in each ports tree listed in
92.Ar sources.conf
93.Pp
94.It
95.Ar current :
96the port in the current working directory.
97.Pp
98.It
99.Ar active :
100set of installed and active ports.
101.Pp
102.It
103.Ar inactive :
104set of installed but inactive ports.
105.Pp
106.It
107.Ar installed :
108set of all installed ports.
109.Pp
110.It
111.Ar uninstalled :
112ports in the ports tree(s) that aren't installed.
113.Pp
114.It
115.Ar outdated :
116installed ports that are out of date with respect to their current version/revision in the ports tree(s)
117.Pp
118.It
119.Ar obsolete :
120set of ports that are installed but no longer exist in any port tree
121.Pp
122.It
123.Ar requested :
124installed ports that were explicitly asked for.
125.Pp
126.It
127.Ar unrequested :
128installed ports that were installed only to satisfy dependencies.
129.Pp
130.It
131.Ar leaves :
132installed ports that are unrequested and have no dependents.
133.Pp
134.El
135Sets of ports can also be specified with
136.Ar pseudo-portname selectors ,
137which expand to the ports in which the value of the
138.Ar Portfile
139key corresponding to the selector's name (in either singular or plural form where applicable)
140matches the given regular expression. Usage is:
141.Ar selector:regex
142.Pp
143Available selectors are:
144.Pp
145.Bl -bullet -offset indent -compact
146.It
147.Ar name
148.It
149.Ar version
150.It
151.Ar revision
152.It
153.Ar epoch
154.It
155.Ar variant
156.It
157.Ar variants
158.It
159.Ar category
160.It
161.Ar categories
162.It
163.Ar maintainer
164.It
165.Ar maintainers
166.It
167.Ar platform
168.It
169.Ar platforms
170.It
171.Ar description
172.It
173.Ar long_description
174.It
175.Ar homepage
176.It
177.Ar portdir
178.El
179.Pp
180.Pp
181Other pseudo-portname selectors match ports which have a particular relationship to
182another port. These will match ports that are direct or recursive dependencies or dependents
183of the given portname:
184.Pp
185.Bl -bullet -offset indent -compact
186.It
187.Ar depof
188.It
189.Ar rdepof
190.It
191.Ar dependentof
192.It
193.Ar rdependentof
194.El
195.Pp
196.Ar portnames
197containing valid UNIX glob patterns will also expand to the set of matching ports. Any
198.Ar action
199passed to
200.Nm
201will be invoked on each of them. For example:
202.Pp
203.Dl port list variant:no_ssl
204.Dl port uninstall name:sql
205.Dl port echo depof:mysql5
206.\" COMMENT: glob pattern expansion in portnames:
207.\" write an example here that illustrats better glob pattern expansion in portnames, but that does not employ
208.\" logical operators (and, or, not, !) because I still haven't gotten to them yet.
209.Dl port echo apache*
210.Pp
211Logical operators "and", "or", "not", "!", "(" and ")" may be used to combine individual
212.Ar portnames ,
213port glob patterns and/or
214.Ar pseudo-portnames
215to construct complex port expressions that expand to the set of matching ports. For example:
216.Pp
217.Dl port upgrade installed and "apache*"
218.Dl port echo maintainer:jberry and uninstalled and \e(\ category:java and not commons*\ \e)
219.\" COMMENT: more complex exmaples here would be useful.
220.\" PENDING: port-url explanation. Proposed text:
221.\".Pp
222.\"A
223.\".Ar portname
224.\"may also be specified as a URL pointing to the location of the
225.\".Ar portdir
226.\" ...
227.Pp
228The
229.Nm
230command also recognizes several command line flags and
231.Ar targets :
232.Sh OPTIONS
233.Bl -tag -width -indent
234.It Fl v
235verbose mode (generate verbose messages)
236.It Fl d
237debug mode (generate debugging messages, implies
238.Fl v )
239.It Fl q
240quiet mode (suppress messages)
241.It Fl n
242don't upgrade dependencies (affects upgrade and install)
243.It Fl R
244also upgrade dependents (only affects upgrade) - note that this does not upgrade dependents' dependencies
245.It Fl u
246uninstall non-active ports when upgrading and uninstalling
247.It Fl f
248force mode (ignore state file)
249.It Fl o
250honor state files older than Portfile
251.It Fl s
252source-only mode (build and install from source, do not attempt to fetch binary archives)
253.It Fl b
254binary-only mode (build and install from binary archives, ignore source, abort if no archive available)
255.It Fl c
256autoclean mode (execute clean after install)
257.It Fl k
258keep mode (don't autoclean after install)
259.It Fl D
260specify
261.Ar portdir
262.It Fl F
263Read and process the
264.Ar file
265of commands specified by the argument. If the argument is '-', then read commands from stdin. If the option is given multiple times, then multiple files will be read.
266.It Fl p
267Despite any errors encountered, proceed to process multiple ports and commands.
268.It Fl y
269Perform a dry run. All of the steps to build the ports and their dependencies are computed, but not actually performed. With the verbose flag, every step is reported; otherwise there is just one message per port, which allows you to easily determine the recursive deps of a port (and the order in which they will be built).
270.It Fl t
271enable trace mode debug facilities on platforms that support it (Mac OS X). This feature is two-folded. It consists in automatically detecting and reporting undeclared dependencies based on what files the port reads or what programs the port executes. In verbose mode, it will also report unused dependencies for each stage of the port installation. It also consists in forbidding and reporting file creation and file writes outside allowed directories (temporary directories and ${workpath}).
272.El
273.Sh USER TARGETS
274Targets most commonly used by regular MacPorts users are:
275.Ss search
276Search for an available port. By default, the search string is treated as a case-insensitive glob,
277and is matched against the name and description fields. To have the search string treated as
278a regular expression, as a literal, or in a case-sensitive manner, use
279.Fl -regex,
280.Fl -exact,
281or
282.Fl -case-sensitive,
283respectively. To match against a different set of fields, use one or more
284.Fl -<field-name>
285options. To display each result on a single line, use
286.Fl -line.
287For example:
288.Pp
289.Dl "port search vim"
290.Dl "port search --regex --depends_build 'docbook.*[0-9]+'"
291.Pp
292.Ss info
293Displays meta-information available for
294.Ar portname .
295Specific meta-information may be requested through an option such as
296.Fl -maintainer
297or
298.Fl -category
299(recognized field names are those from the PortIndex, see "port help
300info" for a complete list). If no specific fields are specified, a
301useful default collection of fields will be displayed. If the global option
302.Fl q
303is in effect, the meta-info fields will not be labeled.
304If the option
305.Fl -line
306is provided, all such data will be consolidated into a single line per port,
307suitable for processing in a pipe of commands.
308If the option
309.Fl -pretty
310is provided, the information will be formatted in a somewhat more
311attractive fashion for human readers. This is the default when no
312options at all are specified to info.
313If the option
314.Fl -index
315is provided, the information will be pulled from the PortIndex rather than
316from the Portfile (in this case variant information, such as dependencies,
317will not affect the output).
318.Pp
319For example:
320.br
321.Dl "port info vim +ruby"
322.Dl "port info --category --name apache*"
323.Dl "port -q info --category --name --version category:java"
324.Dl "port info --line --category --name all"
325.Dl "port info --pretty --fullname --depends gtk2"
326.Dl "port info --index python24"
327.Ss notes
328Displays notes for
329.Ar portname
330(useful information concerning setup and use of the port).
331.Ss variants
332Lists the build variants available for
333.Ar portname .
334.Ss deps
335Lists the other ports that are required to build and run
336.Ar portname .
337This is simply an alias for "info --pretty --fullname --depends".
338.Ss rdeps
339Recursively lists the other ports that are required to build and run
340.Ar portname .
341To display the full dependency tree instead of only showing each port once, use
342.Fl -full .
343To take dependency information from the PortIndex instead of the Portfile
344(faster, but does not take variant selections into account), use
345.Fl -index .
346To exclude dependencies that are only needed at build time (i.e.
347depends_fetch, depends_extract, depends_build), use
348.Fl -no-build .
349.Ss dependents
350Lists the installed ports that depend on the port
351.Ar portname .
352.Ss rdependents
353Recursively lists the installed ports that depend on the port
354.Ar portname .
355To display the full tree of dependents instead of only showing each port once, use
356.Fl -full .
357.Ss install
358Install and activate
359.Ar portname .
360.Ss uninstall
361Deactivate and uninstall
362.Ar portname .
363To uninstall all installed but inactive ports, use
364.Fl u .
365To recursively uninstall all dependents of
366.Ar portname
367before uninstalling the port itself, use
368.Fl -follow-dependents .
369To uninstall
370.Ar portname
371and then recursively uninstall all its dependencies, use
372.Fl -follow-dependencies .
373This will not uninstall dependencies that are marked as requested or that have other dependents.
374.Pp
375For example:
376.Pp
377.Dl "port uninstall vim"
378.Dl "port -u uninstall"
379.Dl "port uninstall --follow-dependents python24"
380.Ss activate
381Activate the installed
382.Ar portname .
383.Ss deactivate
384Deactivate the installed
385.Ar portname .
386.Ss setrequested
387Mark
388.Ar portname
389as requested.
390.Ss unsetrequested
391Mark
392.Ar portname
393as unrequested.
394.Ss installed
395Show the installed versions and variants for
396.Ar portname .
397If no
398.Ar portname
399is given, all installed ports are shown.
400.Ss location
401Print the install location of a given port.
402.Ss contents
403Lists the files installed by
404.Ar portname .
405.Ss provides
406Determines which port owns a given file and can take either a relative or absolute path. For example:
407.Pp
408.Dl "port provides /opt/local/etc/irssi.conf"
409.Dl "port provides include/tiff.h"
410.Ss sync
411Performs a sync operation only on the ports tree of a MacPorts installation, pulling in the latest
412revision available of the
413.Ar Portfiles
414from the MacPorts rsync server. To update you would normally do:
415.Pp
416.Dl "sudo port -d sync"
417.Pp
418If any of the ports tree(s) uses a file: URL that points to a local subversion working copy,
419.Ic sync
420will perform an
421.Ic "svn update"
422on the working copy with the user set to the owner of the working copy.
423.Ss outdated
424List the installed ports that need upgrading.
425.Ss upgrade
426The upgrade target works on a port and its dependencies. If you
427want to change this behaviour, look at the switches for n (no
428dependencies) and R (dependents) below.
429.Pp   
430Upgrade the installed
431.Ar portname .
432For example:
433.Pp
434.Dl "port upgrade vim"
435.Pp
436To upgrade all installed ports:
437.Pp
438.Dl "port upgrade installed"
439.Pp
440To upgrade
441.Ar portname
442and the ports that depend on it:
443.Pp
444.Dl "port -R upgrade libiconv"
445.Pp
446To force an upgrade (rebuild) use:
447.Pp
448.Dl "port upgrade --force vim"
449.Pp
450To upgrade
451.Ar portname
452without following its dependencies, use
453.Fl n .
454For example:
455.Pp
456.Dl "port -n upgrade wireshark"
457.Pp 
458Note that in selecting the variants to use in the upgraded build of the
459port, any variants specified on the command line take highest precedence,
460then the variants active in the latest installed version of the port, and
461finally the global variants specified in variants.conf, if any.  Note that
462upgrade will not normally rebuild a port only to change the selected
463variants; you can either specify --enforce-variants, or deactivate the port and reinstall it
464with different variants.
465.Ss clean
466Clean the files used for building
467.Ar portname .
468To just remove the work files, use the
469.Fl -work
470.Ar actionflag .
471This is the default when no flag is given.
472To remove the distribution files (tarballs, etc), specify
473.Fl -dist .
474To remove the work files, distribution files and logs, pass
475.Fl -all .
476To remove log files for certain port, pass
477.Fl -logs .
478For example:
479.Pp
480.Dl "port clean --dist vim"
481.Dl "port clean --logs vim"
482.Pp
483.Ss log
484Parses and shows log files for
485.Ar portname .
486To filter log files by some criterions use
487.Fl -phase
488to specify phase you want to show and
489.Fl -verbosity
490to specify message category (msg, info, debug)
491For example:
492.Pp
493.Dl "port log --phase configure vim"
494.Dl "port log --phase fetch --verbosity debug vim"
495.Pp
496.Ss echo
497Writes to stdout the arguments passed to
498.Nm .
499This follows the expansion of
500.Ar pseudo-portnames ,
501portname glob patterns,
502.Ar pseudo-portname selectors
503and the evaluation of port expressions.
504.Nm echo
505may be used to determine the exact set of ports to which a given string of arguments will expand, without performing any further operations on them. For example:
506.Pp
507.Dl port echo category:net
508.Dl port echo maintainer:jmpp and name:netw
509.Dl port echo maintainer:jmpp and \e(\ net* or category:text\ \e)
510.Pp
511.Ss list
512If no argument is given, display a list of the latest version of all available ports.
513If portname(s) are given as arguments, display a list of the latest version of each port.
514.Ss mirror
515Create/update a local mirror of distfiles used for ports given on the command line.  The filemap database can be reset by using the
516.Fl -new
517option (though if no database is found, it will be created automatically).
518If the fetched file does not match the checksum given in the Portfile, it is
519deleted.  This can be used with
520.Ar pseudo-portnames ,
521eg,
522.Ar all ,
523to mirror everything.  Note that if you use
524.Ar all ,
525you'll most likely want to use
526.Fl p
527so
528.Nm
529doesn't quit on the first download failure.
530.Ss version
531Display the release number of the installed MacPorts infrastructure.
532.Ss platform
533Display the platform information for the current system.
534.Ss selfupdate
535Updates the MacPorts system, ports tree(s) and base tools if needed, from the MacPorts rsync server,
536installing the newest infrastructure available. To update you would typically do:
537.Pp
538.Dl "sudo port selfupdate"
539.Pp
540See
541.Ic sync
542for more information about updating ports tree(s).
543.Ss load
544Provides a shortcut to using launchctl to load a port's daemon (as installed
545in /Library/LaunchDaemons).  It runs:
546.Pp
547.Dl launchctl load -w /Library/LaunchDaemons/org.macports.${port}.plist
548.Ss unload
549A shortcut to launchctl, like load, but unloads the daemon.
550.Ss gohome
551Loads the home page for the given
552.Ar portname
553in the default web browser.
554.Ss usage
555Displays a condensed usage summary.
556.Ss help
557Displays a summary of all available actions and port command syntax on stdout.
558.Sh DEVELOPER TARGETS
559The targets that are often used by Port developers are intended to provide access to the different phases of a Port's build process:
560.Ss dir
561Displays the path to the directory containing
562.Ar portname .
563.Ss work
564Displays the path to the work directory for
565.Ar portname .
566.Ss cd
567Changes the current working directory to the one containing
568.Ar portname .
569Only useful in interactive mode.
570.Ss file
571Displays the path to the Portfile for
572.Ar portname .
573.Ss url
574Displays the URL for the path of the given
575.Ar portname ,
576which can be passed as port-url
577.Ss cat
578Concatenates and prints the contents of
579.Ar Portfile
580on stdout.
581.Ss edit
582Opens
583.Ar Portfile
584with your default editor specified in your shell's environment variable. Alias
585.Ar ed
586also invokes this command.
587.Pp
588You can also use the
589.Fl -editor
590flag on the command line to specify an alternative editor. For example:
591.Dl port edit --editor nano apache2
592.Pp
593.Ss ed
594An alias for
595.Ic edit .
596.Ss fetch
597Fetches the distribution files required to build
598.Ar portname .
599.Ss checksum
600Compute the checksums of the distribution files for
601.Ar portname ,
602and compare them to the checksums listed in
603.Ar Portfile .
604.Ss extract
605Extracts the distribution files for
606.Ar portname .
607.Ss patch
608Applies any required patches to
609.Ar portname's
610extracted distribution files.
611.Ss configure
612Runs any configure process for
613.Ar portname .
614.Ss build
615Build
616.Ar portname .
617.Ss destroot
618Installs
619.Ar portname
620to a temporary directory.
621.Ss test
622Tests
623.Ar portname .
624.Ss lint
625Verifies Portfile for
626.Ar portname .
627To nitpick about whitespace and patchfile names, use
628.Fl -nitpick .
629.Ss distcheck
630Check if the distfiles haven't changed and can be fetched.
631.Ss distfiles
632Display each distfile, its checksums, and the URLs used to fetch it.
633.Ss livecheck
634Check if the software hasn't been updated since the Portfile was last modified.
635.Sh PACKAGING TARGETS
636There are also targets for producing installable packages of ports:
637.Pp
638.Ss pkg
639Creates an OS X installer package of
640.Ar portname.
641.Ss mpkg
642Creates an OS X installer metapackage of
643.Ar portname
644and its dependencies.
645.Ss dmg
646Creates an internet-enabled disk image containing an OS X package of
647.Ar portname .
648.Ss mdmg
649Creates an internet-enabled disk image containing an OS X metapackage of
650.Ar portname
651and its dependencies.
652.Ss rpm
653Creates an RPM binary package of
654.Ar portname ,
655similar to a tgz "archive".
656.Ss srpm
657Creates a SRPM source package of
658.Ar portname ,
659similar to a xar "portpkg".
660.Ss dpkg
661Creates a DEB binary package of
662.Ar portname .
663.Sh EXAMPLES
664The following demonstrates invoking
665.Nm
666with the
667.Ar extract
668target on
669.Ar portdir
670\&"textproc/figlet" and extract.suffix set to ".tgz":
671.Pp
672.Dl "port extract -D textproc/figlet extract.suffix=.tgz"
673.Pp
674.Sh FILES
675.Bl -tag -width
676.It Va ${prefix}/etc/macports/macports.conf
677Global configuration file for the MacPorts system.
678.It Va ${prefix}/etc/macports/sources.conf
679Global listing of the ports trees used by MacPorts. This file also enables rsync synchronization.
680.It Va ${prefix}/etc/macports/variants.conf
681Global variants used when a port is installed.
682.It Va ~/.macports/macports.conf
683User configuration file for the MacPorts system. It overrides the global
684.Ar macports.conf
685file.
686.El
687.Sh DIAGNOSTICS
688.Ex -std
689.Sh SEE ALSO
690.Xr macports.conf 5 ,
691.Xr portfile 7 ,
692.Xr portgroup 7 ,
693.Xr portstyle 7 ,
694.Xr porthier 7
695.Sh AUTHORS
696.An "Landon Fuller" Aq landonf@macports.org
697.An "James Berry" Aq jberry@macports.org
698.An "Jordan K. Hubbard" Aq jkh@macports.org
699.An "Juan Manuel Palacios" Aq jmpp@macports.org
700.An "Kevin Van Vechten" Aq kevin@opendarwin.org
701.An "Ole Guldberg Jensen" Aq olegb@opendarwin.org
702.An "Robert Shaw" Aq rshaw@opendarwin.org
703.An "Chris Ridd" Aq cjr@opendarwin.org
704.An "Matt Anton" Aq matt@opendarwin.org
705.An "Joe Auty" Aq joe@opendarwin.org
Note: See TracBrowser for help on using the repository browser.