source: branches/gsoc09-logging/base/doc/port.1 @ 140300

Last change on this file since 140300 was 60075, checked in by blb@…, 11 years ago

Merge from trunk

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 19.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 April 29, 2007
31.Dt PORT 1 "MacPorts"
32.Os
33.Sh NAME
34.Nm port
35.Nd operate on individual or multiple Mac
36.Ar ports
37.Sh SYNOPSIS
38.Nm
39.Op Fl bcdfknopqRstuvy
40.Op Fl D Ar portdir
41.Op Fl F Ar cmdfile
42.Op Ar action
43.Op Ar actionflags
44.Op Oo Ar portname | pseudo-portname | port-url Oc
45.Op Oo Ar @version Oc Oo +/-variant ... Oc ... Oo option=value ... Oc
46.Sh DESCRIPTION
47.Nm
48is designed to operate on individual or multiple Mac
49.Ar ports ,
50optionally within a single call, based on the requested
51.Ar action .
52If no
53.Ar portdir
54or
55.Ar portname
56is specified, the current working directory is assumed; if no
57.Ar action
58is specified the port command enters interactive mode, in which commands are read via stdin. Batch commands may be
59passed via a
60.Ar cmdfile .
61Port
62.Ar options
63are passed as key=value pairs and take precedence over individual
64.Ar portname
65options as specified in its Portfile and system-wide settings.
66.Pp
67Port
68.Ar variants
69can specified as
70.Ar +name ,
71which indicates the variant is desired, or
72.Ar -name ,
73indicating the contrary. In case of ambiguities, a port can be fully specified with the
74.Ar @version_revision+variants
75format.
76.Pp
77Installed ports can be activated or deactivated without being uninstalled. A port can be installed if all other
78version/variant(s) combinations installed at any given moment are deactivated.
79.Pp
80The
81.Nm
82command knows various
83.Ar pseudo-portnames
84that will expand to the specified set of ports from the available ports tree(s). These may be used in place of a
85.Ar portname .
86Common options are:
87.Pp
88.Bl -bullet -offset indent -compact
89.It
90.Ar all :
91all the ports in each ports tree listed in
92.Ar sources.conf
93.Pp
94.It
95.Ar current :
96the port in the current working directory.
97.Pp
98.It
99.Ar active :
100set of installed and active ports.
101.Pp
102.It
103.Ar inactive :
104set of installed but inactive ports.
105.Pp
106.It
107.Ar installed :
108set of all installed ports.
109.Pp
110.It
111.Ar uninstalled :
112ports in the ports tree(s) that aren't installed.
113.Pp
114.It
115.Ar outdated :
116installed ports that are out of date with respect to their current version/revision in the ports tree(s)
117.Pp
118.It
119.Ar obsolete :
120set of ports that are installed but no longer exist in any port tree
121.Pp
122.El
123Other options, also known as
124.Ar pseudo-portname selectors ,
125matching the most common keys used in a
126.Ar Portfile
127are also accepted, in both singular and plural form where applicable. These are:
128.Pp
129.Bl -bullet -offset indent -compact
130.It
131.Ar name
132.It
133.Ar version
134.It
135.Ar revision
136.It
137.Ar epoch
138.It
139.Ar variant
140.It
141.Ar variants
142.It
143.Ar category
144.It
145.Ar categories
146.It
147.Ar maintainer
148.It
149.Ar maintainers
150.It
151.Ar platform
152.It
153.Ar platforms
154.It
155.Ar description
156.It
157.Ar long_description
158.It
159.Ar homepage
160.It
161.Ar portdir
162.El
163.Pp
164Search strings that will expand to a set of matching ports can be constructed based on the
165.Ar \(rqpseudo-portname selector\(lq:regex
166combination used.
167.Ar portnames
168containing valid UNIX glob patterns will also expand to the set of matching ports. Any
169.Ar action
170passed to
171.Nm
172will be invoked on each of them. For example:
173.Pp
174.Dl port list variant:no_ssl
175.Dl port uninstall name:sql
176.\" COMMENT: glob pattern expansion in portnames:
177.\" write an example here that illustrats better glob pattern expansion in portnames, but that does not employ
178.\" logical operators (and, or, not, !) because I still haven't gotten to them yet.
179.Dl port echo apache*
180.Pp
181Logical operators "and", "or", "not", "!", "(" and ")" may be used to combine individual
182.Ar portnames ,
183port glob patterns and/or
184.Ar pseudo-portnames
185to construct complex port expressions that expand to the set of matching ports. For example:
186.Pp
187.Dl port upgrade installed and "apache*"
188.Dl port echo maintainer:jberry and uninstalled and \e(\ category:java and not commons*\ \e)
189.\" COMMENT: more complex exmaples here would be useful.
190.\" PENDING: port-url explanation. Proposed text:
191.\".Pp
192.\"A
193.\".Ar portname
194.\"may also be specified as a URL pointing to the location of the
195.\".Ar portdir
196.\" ...
197.Pp
198The
199.Nm
200command also recognizes several command line flags and
201.Ar targets :
202.Sh OPTIONS
203.Bl -tag -width -indent
204.It Fl v
205verbose mode (generate verbose messages)
206.It Fl d
207debug mode (generate debugging messages, implies
208.Fl v )
209.It Fl q
210quiet mode (suppress messages)
211.It Fl n
212don't upgrade dependencies (affects upgrade and install)
213.It Fl R
214also upgrade dependents (only for upgrading)
215.It Fl u
216uninstall non-active ports when upgrading and uninstalling
217.It Fl f
218force mode (ignore state file)
219.It Fl o
220honor state files older than Portfile
221.It Fl s
222source-only mode (build and install from source, ignore all binary archives, do not create/recreate binary archives) (only applies when archive mode is enabled)
223.It Fl b
224binary-only mode (build and install from binary archives, ignore source, abort if no archive present; do not create/recreate binary archives from source) (only applies when archive mode is enabled)
225.It Fl c
226autoclean mode (execute clean after install)
227.It Fl k
228keep mode (don't autoclean after install)
229.It Fl D
230specify
231.Ar portdir
232.It Fl F
233Read and process the
234.Ar file
235of 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.
236.It Fl p
237Despite any errors encountered, proceed to process multiple ports and commands.
238.It Fl y
239Perform a dry run. All of the steps to build the ports and their dependencies are computed, but not actually performed. With the verbose flag, every step is reported; otherwise there is just one message per port, which allows you to easily determine the recursive deps of a port (and the order in which they will be built).
240.It Fl t
241enable trace mode debug facilities on platforms that support it (Mac OS 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 ${workpath}).
242.El
243.Sh USER TARGETS
244Targets most commonly used by regular MacPorts users are:
245.Ss search
246Search for an available port whose name matches a regular expression. For example:
247.Pp
248.Dl "port search vim"
249.Pp
250.Ss info
251Displays meta-information available for
252.Ar portname .
253Specific meta-information may be requested through an option such as
254.Fl -maintainer
255or
256.Fl -category
257(recognized field names are those from the PortIndex, see "port help
258info" for a complete list). If no specific fields are specified, a
259useful default collection of fields will be displayed. If the global option
260.Fl q
261is in effect, the meta-info fields will not be labeled.
262If the option
263.Fl -line
264is provided, all such data will be consolidated into a single line per port,
265suitable for processing in a pipe of commands.
266If the option
267.Fl -pretty
268is provided, the information will be formatted in a somewhat more
269attractive fashion for human readers. This is the default when no
270options at all are specified to info.
271If the option
272.Fl -index
273is provided, the information will be pulled from the PortIndex rather than
274from the Portfile (in this case variant information, such as dependencies,
275will not affect the output).
276.Pp
277For example:
278.br
279.Dl "port info vim +ruby"
280.Dl "port info --category --name apache*"
281.Dl "port -q info --category --name --version category:java"
282.Dl "port info --line --category --name all"
283.Dl "port info --pretty --fullname --depends gtk2"
284.Dl "port info --index python24"
285.Ss variants
286Lists the build variants available for
287.Ar portname .
288.Ss deps
289Lists the other ports that are required to build and run
290.Ar portname .
291This is simply an alias for "info --pretty --fullname --depends".
292.Ss dependents
293Lists the installed ports that depend on the port
294.Ar portname .
295.Ss install
296Install and activate
297.Ar portname .
298.Ss uninstall
299Deactivate and uninstall
300.Ar portname .
301To uninstall all installed but inactive ports, use
302.Fl u .
303To recursively uninstall all dependents of this port, use
304.Fl -follow-dependents .
305.Pp
306For example:
307.Pp
308.Dl "port uninstall vim"
309.Dl "port -u uninstall"
310.Dl "port uninstall --follow-dependents python24"
311.Ss activate
312Activate the installed
313.Ar portname .
314.Ss deactivate
315Deactivate the installed
316.Ar portname .
317.Ss installed
318List all installed ports.
319.Ss location
320Print the install location of a given port.
321.Ss contents
322Lists the files installed by
323.Ar portname .
324.Ss provides
325Determines which port owns a given file and can take either a relative or absolute path. For example:
326.Pp
327.Dl "port provides /opt/local/etc/irssi.conf"
328.Dl "port provides include/tiff.h"
329.Ss sync
330Performs a sync operation only on the ports tree of a MacPorts installation, pulling in the latest
331revision available of the
332.Ar Portfiles
333from the MacPorts rsync server. To update you would normally do:
334.Pp
335.Dl "sudo port -d sync"
336.Pp
337If any of the ports tree(s) uses a file: URL that points to a local subversion working copy,
338.Ic sync
339will perform an
340.Ic "svn update"
341on the working copy with the user set to the owner of the working copy.
342.Ss outdated
343List the installed ports that need upgrading.
344.Ss upgrade
345The upgrade target works on a port and its dependencies. If you
346want to change this behaviour, look at the switches for n (no
347dependencies) and R (dependents) below.
348.Pp   
349Upgrade the installed
350.Ar portname .
351For example:
352.Pp
353.Dl "port upgrade vim"
354.Pp
355To upgrade all installed ports:
356.Pp
357.Dl "port upgrade installed"
358.Pp
359To upgrade
360.Ar portname
361and the ports that depend on it:
362.Pp
363.Dl "port -R upgrade libiconv"
364.Pp
365To force an upgrade (rebuild) use:
366.Pp
367.Dl "port upgrade --force vim"
368.Pp
369To upgrade
370.Ar portname
371without following its dependencies, use
372.Fl n .
373For example:
374.Pp
375.Dl "port -n upgrade wireshark"
376.Pp 
377Note that in selecting the variants to use in the upgraded build of the
378port, any variants specified on the command line take highest precedence,
379then the variants active in the latest installed version of the port, and
380finally the global variants specified in variants.conf, if any.  Note that
381upgrade will not normally rebuild a port only to change the selected
382variants; you can either specify --enforce-variants, or deactivate the port and reinstall it
383with different variants.
384.Ss clean
385Clean the files used for building
386.Ar portname .
387To just remove the work files, use the
388.Fl -work
389.Ar actionflag .
390This is the default when no flag is given.
391To remove the distribution files (tarballs, etc), specify
392.Fl -dist .
393To remove the archive(s) for the current version of a port, pass
394.Fl -archive .
395To remove the work files, distribution files and archives, pass
396.Fl -all .
397To remove log files for certain port, pass
398.Fl -logs .
399For example:
400.Pp
401.Dl "port clean --dist vim"
402.Dl "port clean --archive vim"
403.Dl "port clean --logs vim"
404.Pp
405To remove only certain version(s) of a port's archives (
406.Ar version
407is any valid UNIX glob pattern), you can use:
408.Pp
409.Dl "port clean --archive vim 6.2.114"
410.Pp
411or:
412.Pp
413.Dl "port clean --archive vim '6.*'"
414.Ss log
415Parses and shows log files for
416.Ar portname .
417To filter log files by some criterions use
418.Fl -phase
419to specify phase you want to show and
420.Fl -verbosity
421to specify message category (msg, info, debug)
422For example:
423.Pp
424.Dl "port log --phase configure vim"
425.Dl "port log --phase fetch --verbosity debug vim"
426.Pp
427.Ss echo
428Writes to stdout the arguments passed to
429.Nm .
430This follows the expansion of
431.Ar pseudo-portnames ,
432portname glob patterns,
433.Ar pseudo-portname selectors
434and the evaluation of port expressions.
435.Nm echo
436may 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:
437.Pp
438.Dl port echo category:net
439.Dl port echo maintainer:jmpp and name:netw
440.Dl port echo maintainer:jmpp and \e(\ net* or category:text\ \e)
441.Pp
442.Ss list
443If no argument is given, display a list of the latest version of all available ports.
444If portname(s) are given as arguments, display a list of the latest version of each port.
445.Ss mirror
446Create/update a local mirror of distfiles used for ports given on the command line.  The filemap database can be reset by using the
447.Fl -new
448option (though if no database is found, it will be created automatically).
449If the fetched file does not match the checksum given in the Portfile, it is
450deleted.  This can be used with
451.Ar pseudo-portnames ,
452eg,
453.Ar all ,
454to mirror everything.  Note that if you use
455.Ar all ,
456you'll most likely want to use
457.Fl p
458so
459.Nm
460doesn't quit on the first download failure.
461.Ss version
462Display the release number of the installed MacPorts infrastructure.
463.Ss platform
464Display the platform information for the current system.
465.Ss selfupdate
466Updates the MacPorts system, ports tree(s) and base tools if needed, from the MacPorts rsync server,
467installing the newest infrastructure available. To update you would typically do:
468.Pp
469.Dl "sudo port -d selfupdate"
470.Pp
471See
472.Ic sync
473for more information about updating ports tree(s).
474.Ss load
475Provides a shortcut to using launchctl to load a port's daemon (as installed
476in /Library/LaunchDaemons).  It runs:
477.Pp
478.Dl launchctl load -w /Library/LaunchDaemons/org.macports.${port}.plist
479.Ss unload
480A shortcut to launchctl, like load, but unloads the daemon.
481.Ss gohome
482Loads the home page for the given
483.Ar portname
484in the default web browser.
485.Ss usage
486Displays a condensed usage summary.
487.Ss help
488Displays a summary of all available actions and port command syntax on stdout.
489.Sh DEVELOPER TARGETS
490The targets that are often used by Port developers are intended to provide access to the different phases of a Port's build process:
491.Ss dir
492Displays the path to the directory containing
493.Ar portname .
494.Ss work
495Displays the path to the work directory for
496.Ar portname .
497.Ss cd
498Changes the current working directory to the one containing
499.Ar portname .
500Only useful in interactive mode.
501.Ss file
502Displays the path to the Portfile for
503.Ar portname .
504.Ss url
505Displays the URL for the path of the given
506.Ar portname ,
507which can be passed as port-url
508.Ss cat
509Concatenates and prints the contents of
510.Ar Portfile
511on stdout.
512.Ss edit
513Opens
514.Ar Portfile
515with your default editor specified in your shell's environment variable. Alias
516.Ar ed
517also invokes this command.
518.Pp
519You can also use the
520.Fl -editor
521flag on the command line to specify an alternative editor. For example:
522.Dl port edit --editor nano apache2
523.Pp
524.Ss ed
525An alias for
526.Ic edit .
527.Ss unarchive
528Unpack the port from a pre-built binary archive. When archive mode is enabled, this command is called automatically, prior to
529.Ar fetch ,
530to check for an existing binary archive to unpack. If found, it is unpacked and all stages up to
531.Ar install
532are then skipped.
533.Ss fetch
534Fetches the distribution files required to build
535.Ar portname .
536.Ss checksum
537Compute the checksums of the distribution files for
538.Ar portname ,
539and compare them to the checksums listed in
540.Ar Portfile .
541.Ss extract
542Extracts the distribution files for
543.Ar portname .
544.Ss patch
545Applies any required patches to
546.Ar portname's
547extracted distribution files.
548.Ss configure
549Runs any configure process for
550.Ar portname .
551.Ss build
552Build
553.Ar portname .
554.Ss destroot
555Installs
556.Ar portname
557to a temporary directory.
558.Ss test
559Tests
560.Ar portname .
561.Ss lint
562Verifies Portfile for
563.Ar portname .
564To nitpick about whitespace and patchfile names, use
565.Fl -nitpick .
566.Ss archive
567Archive the port for a later
568.Ar unarchive .
569When archive mode is enabled, binary archives will be created automatically whenever an
570.Ar install
571is performed, or when the
572.Ar archive
573target is called explicitly.
574.Ss distcheck
575Check if the distfiles haven't changed and can be fetched.
576.Ss distfiles
577Display each distfile, its checksums, and the URLs used to fetch it.
578.Ss livecheck
579Check if the software hasn't been updated since the Portfile was last modified.
580.Sh PACKAGING TARGETS
581There are also targets for producing installable packages of ports:
582.Pp
583.Ss pkg
584Creates an OS X installer package of
585.Ar portname.
586.Ss mpkg
587Creates an OS X installer metapackage of
588.Ar portname
589and its dependencies.
590.Ss dmg
591Creates an internet-enabled disk image containing an OS X package of
592.Ar portname .
593.Ss mdmg
594Creates an internet-enabled disk image containing an OS X metapackage of
595.Ar portname
596and its dependencies.
597.Ss rpm
598Creates an RPM binary package of
599.Ar portname ,
600similar to a tgz "archive".
601.Ss srpm
602Creates a SRPM source package of
603.Ar portname ,
604similar to a xar "portpkg".
605.Ss dpkg
606Creates a DEB binary package of
607.Ar portname .
608.Sh EXAMPLES
609The following demonstrates invoking
610.Nm
611with the
612.Ar extract
613target on
614.Ar portdir
615\&"textproc/figlet" and extract.suffix set to ".tgz":
616.Pp
617.Dl "port extract -D textproc/figlet extract.suffix=.tgz"
618.Pp
619.Sh FILES
620.Bl -tag -width
621.It Va ${prefix}/etc/macports/macports.conf
622Global configuration file for the MacPorts system.
623.It Va ${prefix}/etc/macports/sources.conf
624Global listing of the ports trees used by MacPorts. This file also enables rsync synchronization.
625.It Va ${prefix}/etc/macports/variants.conf
626Global variants used when a port is installed.
627.It Va ~/.macports/macports.conf
628User configuration file for the MacPorts system. It overrides the global
629.Ar macports.conf
630file.
631.El
632.Sh DIAGNOSTICS
633.Ex -std
634.Sh SEE ALSO
635.Xr macports.conf 5 ,
636.Xr portfile 7 ,
637.Xr portgroup 7 ,
638.Xr portstyle 7 ,
639.Xr porthier 7
640.Sh AUTHORS
641.An "Landon Fuller" Aq landonf@macports.org
642.An "James Berry" Aq jberry@macports.org
643.An "Jordan K. Hubbard" Aq jkh@macports.org
644.An "Juan Manuel Palacios" Aq jmpp@macports.org
645.An "Kevin Van Vechten" Aq kevin@opendarwin.org
646.An "Ole Guldberg Jensen" Aq olegb@opendarwin.org
647.An "Robert Shaw" Aq rshaw@opendarwin.org
648.An "Chris Ridd" Aq cjr@opendarwin.org
649.An "Matt Anton" Aq matt@opendarwin.org
650.An "Joe Auty" Aq joe@opendarwin.org
Note: See TracBrowser for help on using the repository browser.