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

Last change on this file since 15691 was 15691, checked in by olegb, 15 years ago

Bug:
Submitted by:
Reviewed by:
Approved by:
Obtained from:

Add

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