source: trunk/base/src/port/port.1 @ 19066

Last change on this file since 19066 was 19066, checked in by jberry, 14 years ago

Update some UI strings and docs to use the MacPorts name, rather than darwinports.

  • Property svn:eol-style set to native
File size: 14.7 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 December 13, 2005
31.Dt PORT 1 "Apple Computer, Inc."
32.Os
33.Sh NAME
34.Nm port
35.Nd operate on individual or multiple Darwin
36.Ar ports
37.Sh SYNOPSIS
38.Nm
39.Op Fl vdqfonRusbckixpt
40.Op Fl D Ar portdir
41.Op Fl F Ar cmdfile
42.Ar action
43.Op Ar actionflags
44.Op Oo Ar portname | pseudo-portname | port-url Oc Oo Ar @version Oc Oo +/-variant ... Oc ... Oo option=value ... Oc
45.Sh DESCRIPTION
46.Nm
47is designed to operate on individual or multiple Darwin
48.Ar ports ,
49optionally within a single call, based on the requested
50.Ar action .
51If no
52.Ar portdir
53or
54.Ar portname
55is specified, the current working directory is assumed; if no
56.Ar action
57is specified, the port command enters interactive mode in which commands are read via stdin. Batch files of commands may be specified via batch files   .
58Port
59.Ar options
60are passed as key=value pairs and take precedence over individual port options and system-wide settings.
61.Pp
62Port
63.Ar variants
64can specified as
65.Ar +name ,
66which indicates the variant is desired, or
67.Ar -name ,
68indicating the contrary. In case of ambiguities, a port can be fully specified with the
69.Ar @version_revision+variants
70format.
71.Pp
72Installed ports can be activated or deactivated without being uninstalled. A port can be installed if all other
73version/variant(s) combinations installed at any given moment are deactivated.
74.Pp
75The
76.Nm
77command knows various
78.Ar pseudo-portnames
79that will expand to the specified set of ports from the available dports tree(s). These may be used in place of a
80.Ar portname .
81Common options are:
82.Pp
83.Bl -bullet -offset indent -compact
84.It
85.Ar all :
86all the ports in each dports tree listed in
87.Ar sources.conf
88.Pp
89.It
90.Ar current :
91the port in the current working directory.
92.Pp
93.It
94.Ar active :
95set of installed and active ports.
96.Pp
97.It
98.Ar inactive :
99set of installed but inactive ports.
100.Pp
101.It
102.Ar installed :
103set of all installed ports.
104.Pp
105.It
106.Ar uninstalled :
107ports in the dports tree(s) that aren't installed.
108.Pp
109.It
110.Ar outdated :
111installed ports that are out of date with respect to their current version/revision in the dports tree(s)
112.Pp
113.El
114Other options, also known as
115.Ar pseudo-portname selectors ,
116matching the most common keys used in a
117.Ar Portfile
118are also accepted, in both singular and plural form where applicable. These are:
119.Pp
120.Bl -bullet -offset indent -compact
121.It
122.Ar name
123.It
124.Ar version
125.It
126.Ar revision
127.It
128.Ar epoch
129.It
130.Ar variant
131.It
132.Ar variants
133.It
134.Ar category
135.It
136.Ar categories
137.It
138.Ar maintainer
139.It
140.Ar maintainers
141.It
142.Ar platform
143.It
144.Ar platforms
145.It
146.Ar description
147.It
148.Ar long_description
149.It
150.Ar homepage
151.It
152.Ar portdir
153.El
154.Pp
155Search strings that will expand to a set of matching ports can be constructed based on the
156.Ar \(rqpseudo-portname selector\(lq:regex
157combination used.
158.Ar portnames
159containing valid UNIX glob patterns will also expand to the set of matching ports. Any
160.Ar action
161passed to
162.Nm
163will be invoked on each of them. For example:
164.Pp
165.Dl port list variant:no_ssl
166.Dl port uninstall name:sql
167.\" COMMENT: glob pattern expansion in portnames:
168.\" write an example here that illustrats better glob pattern expansion in portnames, but that does not employ
169.\" logical operators (and, or, not, !) because I still haven't gotten to them yet.
170.Dl port echo apache*
171.Pp
172Logical operators "and", "or", "not", "!", "(" and ")" may be used to combine individual
173.Ar portnames ,
174port glob patterns and/or
175.Ar pseudo-portnames
176to construct complex port expressions that expand to the set of matching ports. For example:
177.Pp
178.Dl port upgrade installed and "apache*"
179.Dl port echo maintainer:jberry and uninstalled and \e(\ category:java and not commons*\ \e)
180.\" COMMENT: more complex exmaples here would be useful.
181.\" PENDING: port-url explanation. Proposed text:
182.\".Pp
183.\"A
184.\".Ar portname
185.\"may also be specified as a URL pointing to the location of the
186.\".Ar portdir
187.\" ...
188.Pp
189The
190.Nm
191command also recognizes several command line flags and
192.Ar targets :
193.Sh OPTIONS
194.Bl -tag -width -indent
195.It Fl v
196verbose mode (generate verbose messages)
197.It Fl d
198debug mode (generate debugging messages, implies
199.Fl v )
200.It Fl q
201quiet mode (suppress messages)
202.It Fl n
203don't follow dependencies in upgrade (only for upgrading)
204.It Fl R
205also upgrade dependents (only for upgrading)
206.It Fl u
207uninstall non-active ports when upgrading and uninstalling
208.It Fl f
209force mode (ignore state file)
210.It Fl o
211honor state files older than Portfile
212.It Fl s
213source-only mode (only build and install from source, ignores all binary archives, does not create/recreate binary archives) (only applies when archive mode is enabled)
214.It Fl b
215binary-only mode (only build and install from binary archives, ignores source, fails when no archive present, and does not create/recreate binary archives from source) (only applies when archive mode is enabled)
216.It Fl c
217autoclean mode (execute clean after install)
218.It Fl k
219keep mode (don't autoclean after install)
220.It Fl D
221specify
222.Ar portdir
223.It Fl F
224Read and process the
225.Ar file
226of 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.
227.It Fl i
228Read commands from stdin. Short for -F -
229.It Fl x
230In batch and interactive mode, exit on the first error encountered. Otherwise, errors during batch execution are simply reported.
231.It Fl p
232Despite any errors encountered, proceed to process multiple ports and commands.
233.It Fl t
234enable trace mode debug facilities on platforms that support it (MacOS 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 ${worksrcpath}).
235
236.El
237.Sh USER TARGETS
238Targets most commonly used by regular MacPorts users are:
239.Ss search
240Search for an available port whose name matches a regular expression. For example:
241.Pp
242.Dl "port search vim"
243.Pp
244.Ss info
245Displays all the meta-information available for
246.Ar portname .
247Specific meta-information may be requested through an option such as
248.Fl --maintainer
249or
250.Fl --category
251(recognized field names are those from the portindex). If the global option
252.Fl -q
253is in effect, the meta-info fields will not be labeled; if the option
254.Fl --line
255is provided, all such data will be consolodated into a single line per port, suitable for processing in a pipe of commands.
256For example:
257.Pp
258.Dl "port info vim"
259.Dl "port info --category --name apache*"
260.Dl "port -q info --category --name --version category:java"
261.Dl "port info --line --category --name all"
262.Ss variants
263Lists the build variants available for
264.Ar portname .
265.Ss deps
266Lists the other ports that are required to build and run
267.Ar portname .
268.Ss dependents
269Lists the ports that depend on the port
270.Ar portname .
271.Ss install
272Install and activate
273.Ar portname .
274.Ss uninstall
275Deactivate and uninstall
276.Ar portname .
277To uninstall all installed but inactive ports, use
278.Fl u .
279For example:
280.Pp
281.Dl "port uninstall vim"
282.Dl "port -u uninstall"
283.Ss activate
284Activate the installed
285.Ar portname .
286.Ss deactivate
287Deactivate the installed
288.Ar portname .
289.Ss installed
290List all installed ports.
291.Ss location
292Print the install location of a given port.
293.Ss contents
294Lists the files installed by
295.Ar portname .
296.Ss provides
297Determines which port owns a given file and can take either a relative or absolute path. For example:
298.Pp
299.Dl "port provides /opt/local/etc/irssi.conf"
300.Dl "port provides include/tiff.h"
301.Ss sync
302Performs a sync operation only on the dports tree of a MacPorts installation, pulling in the latest
303revision available of the
304.Ar Portfiles
305from the MacPorts rsync server. To update you would normally do:
306.Pp
307.Dl "sudo port -d sync"
308.Ss outdated
309List the installed ports that need upgrading.
310.Ss upgrade
311The upgrade target works on a port and its dependencies. If you
312want to change this behaviour, look at the switches for n (no
313dependencies) and R (dependents) below.
314.Pp   
315Upgrade the installed
316.Ar portname .
317For example:
318.Pp
319.Dl "port upgrade vim"
320.Pp
321To upgrade all installed ports:
322.Pp
323.Dl "port upgrade installed"
324.Pp
325To upgrade
326.Ar portname
327and the ports that depend on it:
328.Pp
329.Dl "port -R upgrade libiconv"
330.Pp
331To force an upgrade (rebuild) use:
332.Pp
333.Dl "port -f upgrade vim"
334.Pp
335To upgrade
336.Ar portname
337without following its dependencies, use
338.Fl n .
339For example:
340.Pp
341.Dl "port -n upgrade ethereal"
342.Ss clean
343Clean the files used for building
344.Ar portname .
345To just remove the work files, use the
346.Fl -work
347.Ar actionflag .
348To remove the distribution files (tarballs, etc), specify
349.Fl -dist .
350To remove the archive(s) for the current version of a port, pass
351.Fl -archive .
352To remove the work files, distribution files and archives, pass
353.Fl -all .
354For example:
355.Pp
356.Dl "port clean --dist vim"
357.Dl "port clean --archive vim"
358.Pp
359To remove only certain version(s) of a port's archives (
360.Ar version
361is any valid UNIX glob pattern), you can use:
362.Pp
363.Dl "port clean --archive vim 6.2.114"
364.Pp
365or:
366.Pp
367.Dl "port clean --archive vim '6.*'"
368.Ss echo
369Writes to stdout the arguments passed to
370.Nm .
371This follows the expansion of
372.Ar pseudo-portnames ,
373portname glob patterns,
374.Ar pseudo-portname selectors
375and the evaluation of port expressions.
376.Nm echo
377may 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:
378.Pp
379.Dl port echo category:net
380.Dl port echo maintainer:jmpp and name:netw
381.Dl port echo maintainer:jmpp and \e(\ net* or category:text\ \e)
382.Pp
383.Ss list
384List all available ports.
385.Ss version
386Display the release number of the installed MacPorts infrastructure.
387.Ss selfupdate
388Updates the MacPorts system, dports tree(s) and base tools if needed, from the MacPorts rsync server,
389installing the newest infrastructure available. To update you would typically do:
390.Pp
391.Dl "sudo port -d selfupdate"
392.Ss help
393Displays a summary of all available actions and port command syntax on stdout.
394.Sh DEVELOPER TARGETS
395The targets that are often used by Port developers are intended to provide access to the different phases of a Port's build process:
396.Ss dir
397Displays the path to the directory containing
398.Ar portname .
399.Ss file
400Displays the path to the Portfile for
401.Ar portname .
402.Ss cat
403Concatenates and prints the contents of
404.Ar Portfile
405on stdout.
406.Ss edit
407Opens
408.Ar Portfile
409with your default editor specified in your shell's environment variable. Alias
410.Ar ed
411also invokes this command.
412.Ss unarchive
413Unpack the port from a pre-built binary archive. When archive mode is enabled, this command is called automatically, prior to
414.Ar fetch ,
415to check for an existing binary archive to unpack. If found, it is unpacked and all stages up to
416.Ar install
417are then skipped.
418.Ss fetch
419Fetches the distribution files required to build
420.Ar portname .
421.Ss extract
422Extracts the distribution files for
423.Ar portname .
424.Ss patch
425Applies any required patches to
426.Ar portname's
427extracted distribution files.
428.Ss configure
429Runs any configure process for
430.Ar portname .
431.Ss build
432Build
433.Ar portname .
434.Ss destroot
435Installs
436.Ar portname
437to a temporary directory.
438.Ss test
439Tests
440.Ar portname .
441.Ss archive
442Archive the port for a later
443.Ar unarchive .
444When archive mode is enabled, binary archives will be created automatically whenever an
445.Ar install
446is performed, or when the
447.Ar archive
448target is called explicitly.
449.Ss distcheck
450Check if the distfiles haven't changed and can be fetched.
451.Ss livecheck
452Check if the software hasn't been updated since the Portfile was last modified.
453.Sh PACKAGING TARGETS
454There are also targets for producing installable packages of ports:
455.Pp
456.Ss pkg
457Creates an OS X installer package of
458.Ar portname.
459.Ss mpkg
460Creates an OS X installer metapackage of
461.Ar portname
462and its dependencies.
463.Ss dmg
464Creates an internet-enabled disk image containing an OS X package of
465.Ar portname .
466.Ss rpmpackage
467Creates an RPM package of
468.Ar portname .
469.Sh EXAMPLES
470The following demonstrates invoking
471.Nm
472with the
473.Ar extract
474target on
475.Ar portdir
476\&"textproc/figlet" and extract.suffix set to ".tgz":
477.Pp
478.Dl "port extract -D textproc/figlet extract.suffix=.tgz"
479.Pp
480.Sh FILES
481.Bl -tag -width
482.It Va ${prefix}/etc/ports/ports.conf
483Global configuration file for the MacPorts system.
484.It Va ${prefix}/etc/ports/sources.conf
485Global listing of the dports/ trees used by MacPorts. This file also enables rsync synchronization.
486.It Va ${prefix}/etc/ports/variants.conf
487Global variants used when a port is installed.
488.It Va ~/.portsrc
489User configuration file for the MacPorts system. It overrides the global
490.Ar ports.conf
491file.
492.El
493.Sh DIAGNOSTICS
494.Ex -std
495.Sh SEE ALSO
496.Xr ports.conf 5 ,
497.Xr portfile 7 ,
498.Xr portgroup 7 ,
499.Xr portstyle 7 ,
500.Xr porthier 7
501.Sh AUTHORS
502.An "Landon Fuller" Aq landonf@opendarwin.org
503.An "Kevin Van Vechten" Aq kevin@opendarwin.org
504.An "Jordan K. Hubbard" Aq jkh@opendarwin.org
505.An "Ole Guldberg Jensen" Aq olegb@opendarwin.org
506.An "Robert Shaw" Aq rshaw@opendarwin.org
507.An "Chris Ridd" Aq cjr@opendarwin.org
508.An "Juan Manuel Palacios" Aq jmpp@opendarwin.org
509.An "Matt Anton" Aq matt@opendarwin.org
510.An "James Berry" Aq jberry@opendarwin.org
511.An "Joe Auty" Aq joe@opendarwin.org
Note: See TracBrowser for help on using the repository browser.