Adjust FreeBSD tag to reflect sychronization.
[dragonfly.git] / share / man / man7 / ports.7
CommitLineData
984263bc
MD
1.\"
2.\" Copyright (c) 1997 David E. O'Brien
3.\"
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.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25.\"
26e57457
SW
26.\" $FreeBSD: src/share/man/man7/ports.7,v 1.49 2005/01/21 08:36:40 ru Exp $
27.\" $DragonFly: src/share/man/man7/Attic/ports.7,v 1.5 2005/01/27 19:17:13 swildner Exp $
984263bc 28.\"
f887368d 29.Dd December 17, 2004
984263bc
MD
30.Dt PORTS 7
31.Os
32.Sh NAME
33.Nm ports
34.Nd contributed applications
35.Sh DESCRIPTION
36The
37.Fx
38Ports Collection
39offers a simple way for users and
40administrators to install applications.
41Each
42.Em port
43contains any patches necessary to make the original
44application source code compile and run on
45.Bx .
46Compiling an
47application is as simple as typing
48.Nm make Cm build
49in the port directory!
50The
51.Pa Makefile
52automatically fetches the
53application source code, either from a local disk or via FTP, unpacks it
54on your system, applies the patches, and compiles it.
55If all goes well,
56simply type
57.Nm make Cm install
58to install the application.
59.Pp
60It is possible to download and use ports from the
61.Fx
62repository
63that are newer than the installed system; however it is important to
64install the appropriate
65.Dq "Upgrade Kit"
66from
67.Pa http://www.FreeBSD.org/ports/
68first!
69The
70.Xr portcheckout 1
71script (also a port, of course!) will help to download new ports.
72.Pp
73For more information about using ports, see
74.Dq "Packages and Ports"
75in
76.%B "The FreeBSD Handbook" ,
f887368d 77.Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/handbook/ports.html
984263bc 78or
f887368d 79.Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/ports.html ) .
984263bc
MD
80For information about creating new ports, see
81.%B "The Porter's Handbook"
f887368d 82.Pa ( file:/usr/share/doc/en_US.ISO8859-1/books/porters-handbook/index.html
984263bc
MD
83or
84.Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/ ) .
85.Sh TARGETS
86Some of the targets work recursively through subdirectories.
87This lets you, for example, install all of the
88.Dq Li biology
89ports.
90The targets that do this are
91.Cm build , checksum , clean , configure ,
92.Cm depends , extract , fetch , install ,
93and
94.Cm package .
95.Pp
96The following targets will be run automatically by each proceeding
97target in order.
98That is,
99.Cm build
100will be run
101(if necessary)
102by
103.Cm install ,
104and so on all the way to
105.Cm fetch .
106Usually, you will only use the
107.Cm install
108target.
109.Bl -tag -width ".Cm configure"
f887368d
SW
110.It Cm config
111Configure
112.Va OPTIONS
113for this port using
114.Xr dialog 1 .
984263bc
MD
115.It Cm fetch
116Fetch all of the files needed to build this port from the sites
117listed in
118.Va MASTER_SITES
119and
120.Va PATCH_SITES .
121See
f887368d 122.Va FETCH_CMD , MASTER_SITE_OVERRIDE
984263bc 123and
f887368d 124.Va MASTER_SITE_BACKUP .
984263bc
MD
125.It Cm checksum
126Verify that the fetched distfile's checksum matches the one the port was
127tested against.
128Defining
129.Va NO_CHECKSUM
130will skip this step.
131.It Cm depends
132Install
133(or compile if only compilation is necessary)
134any dependencies of the current port.
135When called by the
136.Cm extract
137or
138.Cm fetch
139targets, this is run in piecemeal as
140.Cm fetch-depends , build-depends ,
141etc.
142Defining
143.Va NO_DEPENDS
144will skip this step.
145.It Cm extract
146Expand the distfile into a work directory.
147.It Cm patch
148Apply any patches that are necessary for the port.
149.It Cm configure
150Configure the port.
151Some ports will ask you questions during this stage.
152See
153.Va INTERACTIVE
154and
155.Va BATCH .
156.It Cm build
157Build the port.
158This is the same as calling the
159.Cm all
160target.
161.It Cm install
162Install the port and register it with the package system.
163This is all you really need to do.
164.El
165.Pp
166The following targets are not run during the normal install process.
f887368d
SW
167.Bl -tag -width ".Cm fetch-recursive"
168.It Cm showconfig
169Display
170.Va OPTIONS
171config for this port.
172.It Cm rmconfig
173Remove
174.Va OPTIONS
175config for this port.
984263bc 176.It Cm fetch-list
f887368d
SW
177Show list of files to be fetched in order to build the port.
178.It Cm fetch-recursive
179Fetch the distfiles of the port and all its dependencies.
180.It Cm fetch-recursive-list
181Show list of files that would be retrieved by
182.Cm fetch-recursive .
984263bc
MD
183.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list
184Print a list of all the compile and run dependencies, and dependencies
185of those dependencies.
186.It Cm clean
187Remove the expanded source code.
188This recurses to dependencies unless
189.Va NOCLEANDEPENDS
190is defined.
191.It Cm distclean
192Remove the port's distfiles and perform the
193.Cm clean
194target.
195The
196.Cm clean
197portion recurses to dependencies unless
198.Va NOCLEANDEPENDS
199is defined, but the
200.Cm distclean
201portion never recurses
202(this is perhaps a bug).
203.It Cm reinstall
204Use this to restore a port after using
205.Xr pkg_delete 1
206when you should have used
207.Cm deinstall .
208.It Cm deinstall
209Remove an installed port from the system, similar to
210.Xr pkg_delete 1 .
f887368d
SW
211.It Cm deinstall-all
212Remove all installed ports with the same
213.Va PKGORIGIN
214from the system.
984263bc
MD
215.It Cm package
216Make a binary package for the port.
217The port will be installed if it has not already been.
218The package is a
f887368d 219.Pa .tbz
984263bc
MD
220file that you can use to
221install the port on other machines with
222.Xr pkg_add 1 .
223If the directory specified by
224.Va PACKAGES
225does not exist, the package will be put into the current directory.
226See
227.Va PKGREPOSITORY
228and
229.Va PKGFILE .
f887368d
SW
230.It Cm package-recursive
231Like
232.Cm package ,
233but makes a package for each depending port as well.
984263bc
MD
234.It Cm readmes
235Create a port's
236.Pa README.html .
237This can be used from
238.Pa /usr/ports
239to create a browsable web of all ports on your system!
240.It Cm search
241Search the
242.Pa INDEX
f887368d 243file for the pattern specified by the
984263bc 244.Va key
f887368d 245(searches the port name, comment, and dependencies),
984263bc 246.Va name
f887368d
SW
247(searches the port name only),
248.Va path
249(searches the port path),
250.Va info
251(searches the port info),
252.Va maint
253(searches the port maintainer),
254.Va cat
255(searches the port category),
256.Va bdeps
257(searches the port build-time dependency),
258.Va rdeps
259(searches the port run-time dependency)
984263bc 260.Xr make 1
f887368d
SW
261variables, and their exclusion counterparts:
262.Va xname , xkey
263etc.
984263bc
MD
264For example, one would type:
265.Pp
266.Dl "cd /usr/ports && make search name=query"
267.Pp
268to find all ports whose
269name matches
270.Dq Li query .
271Results include the matching ports' path, comment, maintainer,
272build dependencies, and run dependencies.
f887368d
SW
273.Bd -literal -offset indent
274cd /usr/ports && make search name=pear- \e
275 xbdeps=apache
276.Ed
277.Pp
278To find all ports whose
279names contain
280.Dq Li pear-
281and which do not have apache
282listed in build-time dependencies.
283.Bd -literal -offset indent
284cd /usr/ports && make search name=pear- \e
285 xname='ht(tp|ml)'
286.Ed
287.Pp
288To find all ports whose names contain
289.Dq Li pear- ,
290but not
291.Dq Li html
292or
293.Dq Li http .
294.Bd -literal -offset indent
295make search key=apache display=name,path,info keylim=1
296.Ed
297.Pp
298To find ports that contain
299.Dq Li apache
300in either of the name, path, info
301fields, ignore the rest of the record.
302.It Cm describe
303Generate a one-line description of each port for use in the
304.Pa INDEX
305file.
984263bc
MD
306.It Cm index
307Create
308.Pa /usr/ports/INDEX ,
309which is used by the
310.Cm pretty-print-*
311and
312.Cm search
313targets.
f887368d 314Running the
984263bc
MD
315.Cm index
316target will ensure your
317.Pa INDEX
318file is up to date with your ports tree.
f887368d
SW
319.It Cm fetchindex
320Fetch the
321.Pa INDEX
322file from the
323.Fx
324cluster.
984263bc
MD
325.El
326.Sh ENVIRONMENT
327You can change all of these.
328.Bl -tag -width ".Va MASTER_SITES"
329.It Va PORTSDIR
330Location of the ports tree.
331This is
332.Pa /usr/ports
333on
f887368d 334.Dx ,
984263bc
MD
335.Fx
336and
337.Ox ,
338and
339.Pa /usr/pkgsrc
340on
341.Nx .
342.It Va WRKDIRPREFIX
343Where to create any temporary files.
344Useful if
345.Va PORTSDIR
346is read-only (perhaps mounted from a CD-ROM).
347.It Va DISTDIR
348Where to find/put distfiles, normally
349.Pa distfiles/
350in
351.Va PORTSDIR .
352.It Va PACKAGES
353Used only for the
354.Cm package
355target; the base directory for the packages tree, normally
356.Pa packages/
357in
358.Va PORTSDIR .
359If this directory exists, the package tree will be (partially) constructed.
360This directory does not have to exist; if it does not, packages will be
361placed into the current directory, or you can define one of
362.Bl -tag -width ".Va PKGREPOSITORY"
363.It Va PKGREPOSITORY
364Directory to put the package in.
365.It Va PKGFILE
366The full path to the package.
367.El
368.It Va PREFIX
369Where to install things in general
370(usually
371.Pa /usr/local
372or
373.Pa /usr/X11R6 ) .
374.It Va MASTER_SITES
375Primary sites for distribution files if not found locally.
376.It Va PATCH_SITES
377Primary locations for distribution patch files if not found
378locally.
379.It Va MASTER_SITE_FREEBSD
380If set, go to the master
381.Fx
382site for all files.
383.It Va MASTER_SITE_OVERRIDE
f887368d
SW
384Try going to these sites for all files and patches, first.
385.It Va MASTER_SITE_BACKUP
386Try going to these sites for all files and patches, last.
387.It Va MASTER_SITE_INDEX
388Where to get
389.Pa INDEX
390source built on
391.Fx
392cluster (for
393.Cm fetchindex
394target).
395Defaults to
396.Pa http://www.FreeBSD.org/ports/ .
397.It Va FETCHINDEX
398Command to get
399.Pa INDEX
400(for
401.Cm fetchindex
402target).
403Defaults to
404.Dq Nm fetch Fl am .
984263bc
MD
405.It Va NOCLEANDEPENDS
406If defined, do not let
407.Cm clean
408recurse to dependencies.
409.It Va FETCH_CMD
410Command to use to fetch files.
411Normally
412.Xr fetch 1 .
413.It Va FORCE_PKG_REGISTER
414If set, overwrite any existing package registration on the system.
415.It Va MOTIFLIB
416Location of
417.Pa libXm. Ns Brq Pa a , Ns Pa so .
418.It Va INTERACTIVE
419If defined, only operate on a port if it requires interaction.
420.It Va BATCH
421If defined, only operate on a port if it can be installed 100% automatically.
f887368d
SW
422.It Va OPTIONS
423If defined, list of what
424.Va WITH_*
425options this port accepts.
426.Em Note :
427to make
428.Va OPTIONS
429actually work, it is necessary to include
430.Pa bsd.port.pre.mk
431before starting to test the
432.Va WITH_*
433variables.
434.It Va DISABLE_VULNERABILITIES
435If defined, disable check for security vulnerabilities using
436.Xr portaudit 1
437when installing new ports.
984263bc
MD
438.El
439.Sh FILES
440.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact
441.It Pa /usr/ports
442The default ports directory
f887368d
SW
443.No ( Dx ,
444.Fx
984263bc
MD
445and
446.Ox ) .
447.It Pa /usr/pkgsrc
448The default ports directory
449.Pq Nx .
7ca4eab6 450.It Pa /usr/dfports
f887368d 451DragonFly override ports.
984263bc
MD
452.It Pa /usr/ports/Mk/bsd.port.mk
453The big Kahuna.
454.El
455.Sh SEE ALSO
456.Xr make 1 ,
457.Xr pkg_add 1 ,
458.Xr pkg_create 1 ,
459.Xr pkg_delete 1 ,
460.Xr pkg_info 1 ,
461.Xr pkg_version 1
462.Pp
463The following are part of the ports collection:
464.Pp
465.Xr pib 1 ,
466.Xr portcheckout 1 ,
467.Xr portlint 1
468.Rs
469.%B "The FreeBSD Handbook"
470.Re
471.Pp
472.Pa http://www.FreeBSD.org/ports
473(searchable index of all ports)
984263bc
MD
474.Sh HISTORY
475The Ports Collection
476appeared in
477.Fx 1.0 .
478It has since spread to
479.Nx
480and
481.Ox .
f887368d
SW
482.Sh AUTHORS
483.An -nosplit
484This manual page was originated by
485.An David O'Brien .
984263bc
MD
486.Sh BUGS
487Ports documentation is split over four places \(em
488.Pa /usr/ports/Mk/bsd.port.mk ,
489.%B "The Porter's Handbook" ,
490the
491.Dq "Packages and Ports"
492chapter of
493.%B "The FreeBSD Handbook" ,
494and
f887368d 495this manual page.