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

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

Merge to HEAD changes between tags release_1_2-bp and release_1_2_0 on
release_1_2 branch. This should incorporate all changes that were made
on the 1.2 branch between the time it branched from HEAD, and the time
1.2 was tagged.

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