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

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

Bug:
Submitted by:
Reviewed by:
Approved by: jmpp@
Obtained from:
Removal of -a

  • removed from port.tcl
  • removed from port(1)
  • Property svn:eol-style set to native
File size: 12.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 vdqfonusbckt
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 u
204uninstall non-active ports when upgrading and uninstalling
205.It Fl f
206force mode (ignore state file)
207.It Fl o
208honor state files older than Portfile
209.It Fl s
210source-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)
211.It Fl b
212binary-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)
213.It Fl c
214autoclean mode (execute clean after install)
215.It Fl k
216keep mode (don't autoclean after install)
217.It Fl D
218specify
219.Ar portdir
220.It Fl t
221enable trace mode debug facilities on platforms that support it
222.El
223.Sh USER TARGETS
224Targets most commonly used by regular DarwinPorts users are:
225.Ss search
226Search for an available port whose name matches a regular expression. For example:
227.Pp
228.Dl "port search vim"
229.Pp
230.Ss info
231Displays all the meta-information available for
232.Ar portname .
233.Ss variants
234Lists the build variants available for
235.Ar portname .
236.Ss deps
237Lists the other ports that are required to build and run
238.Ar portname .
239.Ss install
240Install and activate
241.Ar portname .
242.Ss uninstall
243Deactivate and uninstall
244.Ar portname .
245To uninstall all installed but inactive ports, use
246.Fl u .
247For example:
248.Pp
249.Dl "port uninstall vim"
250.Dl "port -u uninstall"
251.Ss activate
252Activate the installed
253.Ar portname .
254.Ss deactivate
255Deactivate the installed
256.Ar portname .
257.Ss installed
258List all installed ports.
259.Ss location
260Print the install location of a given port.
261.Ss contents
262Lists the files installed by
263.Ar portname .
264.Ss provides
265Determines which port owns a given file and can take either a relative or absolut path. For example:
266.Pp
267.Dl "port provides /opt/local/etc/irssi.conf"
268.Dl "port provides include/tiff.h"
269.Ss sync
270Performs a sync operation only on the dports tree of a DarwinPorts installation, pulling in the latest
271revision available of the
272.Ar Portfiles
273from the DarwinPorts rsync server. To update you would normally do:
274.Pp
275.Dl "sudo port -d sync"
276.Ss outdated
277List the installed ports that need upgrading.
278.Ss upgrade
279Upgrade the installed
280.Ar portname .
281For example:
282.Pp
283.Dl "port upgrade vim"
284.Pp
285To upgrade all installed ports:
286.Pp
287.Dl "port upgrade installed"
288.Pp
289To upgrade
290.Ar portname
291wihtout following its dependencies, use
292.Fl n .
293For example:
294.Pp
295.Dl "port -n upgrade ethereal"
296.Ss clean
297Clean the files used for building
298.Ar portname .
299To just remove the work files, use the
300.Fl -work
301.Ar actionflag .
302To remove the distribution files (tarballs, etc), specify
303.Fl -dist .
304To remove the archive(s) for the current version of a port, pass
305.Fl -archive .
306To remove the work files, distribution files and archives, pass
307.Fl -all .
308For example:
309.Pp
310.Dl "port clean --dist vim"
311.Dl "port clean --archive vim"
312.Pp
313To remove only certain version(s) of a port's archives (
314.Ar version
315is any valid UNIX glob pattern), you can use:
316.Pp
317.Dl "port clean --archive vim 6.2.114"
318.Pp
319or:
320.Pp
321.Dl "port clean --archive vim '6.*'"
322.Ss echo
323Writes to stdout the arguments passed to
324.Nm .
325This follows the expansion of
326.Ar pseudo-portnames ,
327portname glob patterns,
328.Ar pseudo-portname selectors
329and the evaluation of port expressions.
330.Nm echo
331may 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:
332.Pp
333.Dl port echo category:net
334.Dl port echo maintainer:jmpp and name:netw
335.Dl port echo maintainer:jmpp and \e(\ net* or category:text\ \e)
336.Pp
337.Ss list
338List all available ports.
339.Ss version
340Display the release number of the installed DarwinPorts infrastructure.
341.Ss selfupdate
342Updates the DarwinPorts system, dports tree(s) and base tools if needed, from the DarwinPorts rsync server,
343installing the newest infrastructure available. To update you would typically do:
344.Pp
345.Dl "sudo port -d selfupdate"
346.Ss help
347Displays a summary of all available actions and port command syntax on stdout.
348.Sh DEVELOPER TARGETS
349The targets that are often used by Port developers are intended to provide access to the different phases of a Port's build process:
350.Ss dir
351Displays the path to the directory containing
352.Ar portname .
353.Ss path
354Displays the path for
355.Ar portname .
356.Ss cat
357Concatenates and prints the contents of
358.Ar Portfile
359on stdout.
360.Ss edit
361Opens
362.Ar Portfile
363with your default editor specified in your shell's environment variable. Alias
364.Ar ed
365also invokes this command.
366.Ss unarchive
367Unpack the port from a pre-built binary archive. When archive mode is enabled, this command is called automatically, prior to
368.Ar fetch ,
369to check for an existing binary archive to unpack. If found, it is unpacked and all stages up to
370.Ar install
371are then skipped.
372.Ss fetch
373Fetches the distribution files required to build
374.Ar portname .
375.Ss extract
376Extracts the distribution files for
377.Ar portname .
378.Ss patch
379Applies any required patches to
380.Ar portname's
381extracted distribution files.
382.Ss configure
383Runs any configure process for
384.Ar portname .
385.Ss build
386Build
387.Ar portname .
388.Ss destroot
389Installs
390.Ar portname
391to a temporary directory.
392.Ss test
393Tests
394.Ar portname .
395.Ss archive
396Archive the port for a later
397.Ar unarchive .
398When archive mode is enabled, binary archives will be created automatically whenever an
399.Ar install
400is performed, or when the
401.Ar archive
402target is called explicitly.
403.Ss livecheck
404Check if the distfiles haven't change and can be fetched, and if the software hasn't been
405updated since the Portfile was last modified.
406.Sh PACKAGING TARGETS
407There are also targets for producing installable packages of ports:
408.Pp
409.Ss pkg
410Creates an OS X installer package of
411.Ar portname.
412.Ss mpkg
413Creates an OS X installer metapackage of
414.Ar portname
415and its dependencies.
416.Ss dmg
417Creates an internet-enabled disk image containing an OS X package of
418.Ar portname .
419.Ss rpmpackage
420Creates an RPM package of
421.Ar portname .
422.Sh EXAMPLES
423The following demonstrates invoking
424.Nm
425with the
426.Ar extract
427target on
428.Ar portdir
429\&"textproc/figlet" and extract.suffix set to ".tgz":
430.Pp
431.Dl "port extract -D textproc/figlet extract.suffix=.tgz"
432.Pp
433.Sh FILES
434.Bl -tag -width
435.It Va ${prefix}/etc/ports/ports.conf
436Global configuration file for the DarwinPorts system.
437.It Va ${prefix}/etc/ports/sources.conf
438Global listing of the dports/ trees used by DarwinPorts. This file also enables rsync synchronization.
439.It Va ${prefix}/etc/ports/variants.conf
440Global variants used when a port is installed.
441.It Va ~/.portsrc
442User configuration file for the DarwinPorts system. It overrides the global
443.Ar ports.conf
444file.
445.El
446.Sh DIAGNOSTICS
447.Ex -std
448.Sh SEE ALSO
449.Xr ports.conf 5 ,
450.Xr portfile 7 ,
451.Xr portgroup 7 ,
452.Xr portstyle 7 ,
453.Xr porthier 7
454.Sh AUTHORS
455.An "Landon Fuller" Aq landonf@opendarwin.org
456.An "Kevin Van Vechten" Aq kevin@opendarwin.org
457.An "Jordan K. Hubbard" Aq jkh@opendarwin.org
458.An "Ole Guldberg Jensen" Aq olegb@opendarwin.org
459.An "Robert Shaw" Aq rshaw@opendarwin.org
460.An "Chris Ridd" Aq cjr@opendarwin.org
461.An "Juan Manuel Palacios" Aq jmpp@opendarwin.org
462.An "Matt Anton" Aq matt@opendarwin.org
463.An "James Berry" Aq jberry@opendarwin.org
464.An "Joe Auty" Aq joe@opendarwin.org
Note: See TracBrowser for help on using the repository browser.