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

Last change on this file since 16424 was 16424, checked in by jberry, 15 years ago

Fix a couple of typos in port.1

  • Property svn:eol-style set to native
File size: 13.1 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 absolute 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
284The upgrade target works on a port and its dependencies. If you
285want to change this behaviour, look at the switches for n (no
286dependencies) and R (dependents) below.
287.Pp   
288Upgrade the installed
289.Ar portname .
290For example:
291.Pp
292.Dl "port upgrade vim"
293.Pp
294To upgrade all installed ports:
295.Pp
296.Dl "port upgrade installed"
297.Pp
298To upgrade
299.Ar portname
300and the ports that depend on it:
301.Pp
302.Dl "port -R upgrade libiconv"
303.Pp
304To force an upgrade (rebuild) use:
305.Pp
306.Dl "port -f upgrade vim"
307.Pp
308To upgrade
309.Ar portname
310wihtout following its dependencies, use
311.Fl n .
312For example:
313.Pp
314.Dl "port -n upgrade ethereal"
315.Ss clean
316Clean the files used for building
317.Ar portname .
318To just remove the work files, use the
319.Fl -work
320.Ar actionflag .
321To remove the distribution files (tarballs, etc), specify
322.Fl -dist .
323To remove the archive(s) for the current version of a port, pass
324.Fl -archive .
325To remove the work files, distribution files and archives, pass
326.Fl -all .
327For example:
328.Pp
329.Dl "port clean --dist vim"
330.Dl "port clean --archive vim"
331.Pp
332To remove only certain version(s) of a port's archives (
333.Ar version
334is any valid UNIX glob pattern), you can use:
335.Pp
336.Dl "port clean --archive vim 6.2.114"
337.Pp
338or:
339.Pp
340.Dl "port clean --archive vim '6.*'"
341.Ss echo
342Writes to stdout the arguments passed to
343.Nm .
344This follows the expansion of
345.Ar pseudo-portnames ,
346portname glob patterns,
347.Ar pseudo-portname selectors
348and the evaluation of port expressions.
349.Nm echo
350may 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:
351.Pp
352.Dl port echo category:net
353.Dl port echo maintainer:jmpp and name:netw
354.Dl port echo maintainer:jmpp and \e(\ net* or category:text\ \e)
355.Pp
356.Ss list
357List all available ports.
358.Ss version
359Display the release number of the installed DarwinPorts infrastructure.
360.Ss selfupdate
361Updates the DarwinPorts system, dports tree(s) and base tools if needed, from the DarwinPorts rsync server,
362installing the newest infrastructure available. To update you would typically do:
363.Pp
364.Dl "sudo port -d selfupdate"
365.Ss help
366Displays a summary of all available actions and port command syntax on stdout.
367.Sh DEVELOPER TARGETS
368The targets that are often used by Port developers are intended to provide access to the different phases of a Port's build process:
369.Ss dir
370Displays the path to the directory containing
371.Ar portname .
372.Ss file
373Displays the path to the Portfile for
374.Ar portname .
375.Ss cat
376Concatenates and prints the contents of
377.Ar Portfile
378on stdout.
379.Ss edit
380Opens
381.Ar Portfile
382with your default editor specified in your shell's environment variable. Alias
383.Ar ed
384also invokes this command.
385.Ss unarchive
386Unpack the port from a pre-built binary archive. When archive mode is enabled, this command is called automatically, prior to
387.Ar fetch ,
388to check for an existing binary archive to unpack. If found, it is unpacked and all stages up to
389.Ar install
390are then skipped.
391.Ss fetch
392Fetches the distribution files required to build
393.Ar portname .
394.Ss extract
395Extracts the distribution files for
396.Ar portname .
397.Ss patch
398Applies any required patches to
399.Ar portname's
400extracted distribution files.
401.Ss configure
402Runs any configure process for
403.Ar portname .
404.Ss build
405Build
406.Ar portname .
407.Ss destroot
408Installs
409.Ar portname
410to a temporary directory.
411.Ss test
412Tests
413.Ar portname .
414.Ss archive
415Archive the port for a later
416.Ar unarchive .
417When archive mode is enabled, binary archives will be created automatically whenever an
418.Ar install
419is performed, or when the
420.Ar archive
421target is called explicitly.
422.Ss livecheck
423Check if the distfiles haven't changed and can be fetched, and if the software hasn't been
424updated since the Portfile was last modified.
425.Sh PACKAGING TARGETS
426There are also targets for producing installable packages of ports:
427.Pp
428.Ss pkg
429Creates an OS X installer package of
430.Ar portname.
431.Ss mpkg
432Creates an OS X installer metapackage of
433.Ar portname
434and its dependencies.
435.Ss dmg
436Creates an internet-enabled disk image containing an OS X package of
437.Ar portname .
438.Ss rpmpackage
439Creates an RPM package of
440.Ar portname .
441.Sh EXAMPLES
442The following demonstrates invoking
443.Nm
444with the
445.Ar extract
446target on
447.Ar portdir
448\&"textproc/figlet" and extract.suffix set to ".tgz":
449.Pp
450.Dl "port extract -D textproc/figlet extract.suffix=.tgz"
451.Pp
452.Sh FILES
453.Bl -tag -width
454.It Va ${prefix}/etc/ports/ports.conf
455Global configuration file for the DarwinPorts system.
456.It Va ${prefix}/etc/ports/sources.conf
457Global listing of the dports/ trees used by DarwinPorts. This file also enables rsync synchronization.
458.It Va ${prefix}/etc/ports/variants.conf
459Global variants used when a port is installed.
460.It Va ~/.portsrc
461User configuration file for the DarwinPorts system. It overrides the global
462.Ar ports.conf
463file.
464.El
465.Sh DIAGNOSTICS
466.Ex -std
467.Sh SEE ALSO
468.Xr ports.conf 5 ,
469.Xr portfile 7 ,
470.Xr portgroup 7 ,
471.Xr portstyle 7 ,
472.Xr porthier 7
473.Sh AUTHORS
474.An "Landon Fuller" Aq landonf@opendarwin.org
475.An "Kevin Van Vechten" Aq kevin@opendarwin.org
476.An "Jordan K. Hubbard" Aq jkh@opendarwin.org
477.An "Ole Guldberg Jensen" Aq olegb@opendarwin.org
478.An "Robert Shaw" Aq rshaw@opendarwin.org
479.An "Chris Ridd" Aq cjr@opendarwin.org
480.An "Juan Manuel Palacios" Aq jmpp@opendarwin.org
481.An "Matt Anton" Aq matt@opendarwin.org
482.An "James Berry" Aq jberry@opendarwin.org
483.An "Joe Auty" Aq joe@opendarwin.org
Note: See TracBrowser for help on using the repository browser.