xref: /freebsd/share/man/man7/ports.7 (revision ae83180158c4c937f170e31eff311b18c0286a93)
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.\"
26.\" $FreeBSD$
27.\"
28.Dd January 25, 1998
29.Dt PORTS 7
30.Os
31.Sh NAME
32.Nm ports
33.Nd contributed applications
34.Sh DESCRIPTION
35The
36.Fx
37Ports Collection
38offers a simple way for users and
39administrators to install applications.
40Each
41.Em port
42contains any patches necessary to make the original
43application source code compile and run on
44.Bx .
45Compiling an
46application is as simple as typing
47.Nm make Cm build
48in the port directory!
49The
50.Pa Makefile
51automatically fetches the
52application source code, either from a local disk or via FTP, unpacks it
53on your system, applies the patches, and compiles it.
54If all goes well,
55simply type
56.Nm make Cm install
57to install the application.
58.Pp
59It is possible to download and use ports from the
60.Fx
61repository
62that are newer than the installed system; however it is important to
63install the appropriate
64.Dq "Upgrade Kit"
65from
66.Pa http://www.FreeBSD.org/ports/
67first!
68The
69.Xr portcheckout 1
70script (also a port, of course!) will help to download new ports.
71.Pp
72For more information about using ports, see
73.Dq "Packages and Ports"
74in
75.%B "The FreeBSD Handbook" ,
76.Pa ( file:/usr/share/doc/handbook/ports.html
77or
78.Pa http://www.FreeBSD.org/doc/handbook/ports.html ) .
79For information about creating new ports, see
80.%B "The Porter's Handbook"
81.Pa ( file:/usr/share/doc/porters-handbook/index.html
82or
83.Pa http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/porters-handbook/ ) .
84.Sh TARGETS
85Some of the targets work recursively through subdirectories.
86This lets you, for example, install all of the
87.Dq Li biology
88ports.
89The targets that do this are
90.Cm build , checksum , clean , configure ,
91.Cm depends , extract , fetch , install ,
92and
93.Cm package .
94.Pp
95The following targets will be run automatically by each proceeding
96target in order.
97That is,
98.Cm build
99will be run
100(if necessary)
101by
102.Cm install ,
103and so on all the way to
104.Cm fetch .
105Usually, you will only use the
106.Cm install
107target.
108.Bl -tag -width ".Cm configure"
109.It Cm fetch
110Fetch all of the files needed to build this port from the sites
111listed in
112.Va MASTER_SITES
113and
114.Va PATCH_SITES .
115See
116.Va FETCH_CMD
117and
118.Va MASTER_SITE_OVERRIDE .
119.It Cm checksum
120Verify that the fetched distfile's checksum matches the one the port was
121tested against.
122Defining
123.Va NO_CHECKSUM
124will skip this step.
125.It Cm depends
126Install
127(or compile if only compilation is necessary)
128any dependencies of the current port.
129When called by the
130.Cm extract
131or
132.Cm fetch
133targets, this is run in piecemeal as
134.Cm fetch-depends , build-depends ,
135etc.
136Defining
137.Va NO_DEPENDS
138will skip this step.
139.It Cm extract
140Expand the distfile into a work directory.
141.It Cm patch
142Apply any patches that are necessary for the port.
143.It Cm configure
144Configure the port.
145Some ports will ask you questions during this stage.
146See
147.Va INTERACTIVE
148and
149.Va BATCH .
150.It Cm build
151Build the port.
152This is the same as calling the
153.Cm all
154target.
155.It Cm install
156Install the port and register it with the package system.
157This is all you really need to do.
158.El
159.Pp
160The following targets are not run during the normal install process.
161.Bl -tag -width ".Cm fetch-list"
162.It Cm fetch-list
163Show list of files needed to be fetched in order to build the port.
164.It Cm pretty-print-run-depends-list , pretty-print-build-depends-list
165Print a list of all the compile and run dependencies, and dependencies
166of those dependencies.
167.It Cm clean
168Remove the expanded source code.
169This recurses to dependencies unless
170.Va NOCLEANDEPENDS
171is defined.
172.It Cm distclean
173Remove the port's distfiles and perform the
174.Cm clean
175target.
176The
177.Cm clean
178portion recurses to dependencies unless
179.Va NOCLEANDEPENDS
180is defined, but the
181.Cm distclean
182portion never recurses
183(this is perhaps a bug).
184.It Cm reinstall
185Use this to restore a port after using
186.Xr pkg_delete 1
187when you should have used
188.Cm deinstall .
189.It Cm deinstall
190Remove an installed port from the system, similar to
191.Xr pkg_delete 1 .
192.It Cm package
193Make a binary package for the port.
194The port will be installed if it has not already been.
195The package is a
196.Pa .tgz
197file that you can use to
198install the port on other machines with
199.Xr pkg_add 1 .
200If the directory specified by
201.Va PACKAGES
202does not exist, the package will be put into the current directory.
203See
204.Va PKGREPOSITORY
205and
206.Va PKGFILE .
207.It Cm readmes
208Create a port's
209.Pa README.html .
210This can be used from
211.Pa /usr/ports
212to create a browsable web of all ports on your system!
213.It Cm search
214Search the
215.Pa INDEX
216file for the pattern specified by either the
217.Va key
218(searches the port name, comment, and dependencies) or
219.Va name
220(searches the port name only)
221.Xr make 1
222variable.
223For example, one would type:
224.Pp
225.Dl "cd /usr/ports && make search name=query"
226.Pp
227to find all ports whose
228name matches
229.Dq Li query .
230Results include the matching ports' path, comment, maintainer,
231build dependencies, and run dependencies.
232.It Cm index
233Create
234.Pa /usr/ports/INDEX ,
235which is used by the
236.Cm pretty-print-*
237and
238.Cm search
239targets.
240While the master
241.Pa INDEX
242file in the CVS repository is periodically
243updated, running the
244.Cm index
245target will ensure your
246.Pa INDEX
247file is up to date with your ports tree.
248.El
249.Sh ENVIRONMENT
250You can change all of these.
251.Bl -tag -width ".Va MASTER_SITES"
252.It Va PORTSDIR
253Location of the ports tree.
254This is
255.Pa /usr/ports
256on
257.Fx
258and
259.Ox ,
260and
261.Pa /usr/pkgsrc
262on
263.Nx .
264.It Va WRKDIRPREFIX
265Where to create any temporary files.
266Useful if
267.Va PORTSDIR
268is read-only (perhaps mounted from a CD-ROM).
269.It Va DISTDIR
270Where to find/put distfiles, normally
271.Pa distfiles/
272in
273.Va PORTSDIR .
274.It Va PACKAGES
275Used only for the
276.Cm package
277target; the base directory for the packages tree, normally
278.Pa packages/
279in
280.Va PORTSDIR .
281If this directory exists, the package tree will be (partially) constructed.
282This directory does not have to exist; if it does not, packages will be
283placed into the current directory, or you can define one of
284.Bl -tag -width ".Va PKGREPOSITORY"
285.It Va PKGREPOSITORY
286Directory to put the package in.
287.It Va PKGFILE
288The full path to the package.
289.El
290.It Va PREFIX
291Where to install things in general
292(usually
293.Pa /usr/local
294or
295.Pa /usr/X11R6 ) .
296.It Va MASTER_SITES
297Primary sites for distribution files if not found locally.
298.It Va PATCH_SITES
299Primary locations for distribution patch files if not found
300locally.
301.It Va MASTER_SITE_FREEBSD
302If set, go to the master
303.Fx
304site for all files.
305.It Va MASTER_SITE_OVERRIDE
306Try going to this site for all files and patches, first.
307.It Va NOCLEANDEPENDS
308If defined, do not let
309.Cm clean
310recurse to dependencies.
311.It Va FETCH_CMD
312Command to use to fetch files.
313Normally
314.Xr fetch 1 .
315.It Va FORCE_PKG_REGISTER
316If set, overwrite any existing package registration on the system.
317.It Va MOTIFLIB
318Location of
319.Pa libXm. Ns Brq Pa a , Ns Pa so .
320.It Va INTERACTIVE
321If defined, only operate on a port if it requires interaction.
322.It Va BATCH
323If defined, only operate on a port if it can be installed 100% automatically.
324.El
325.Sh FILES
326.Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact
327.It Pa /usr/ports
328The default ports directory
329.No ( Fx
330and
331.Ox ) .
332.It Pa /usr/pkgsrc
333The default ports directory
334.Pq Nx .
335.It Pa /usr/ports/Mk/bsd.port.mk
336The big Kahuna.
337.El
338.Sh SEE ALSO
339.Xr make 1 ,
340.Xr pkg_add 1 ,
341.Xr pkg_create 1 ,
342.Xr pkg_delete 1 ,
343.Xr pkg_info 1 ,
344.Xr pkg_version 1
345.Pp
346The following are part of the ports collection:
347.Pp
348.Xr pib 1 ,
349.Xr portcheckout 1 ,
350.Xr portlint 1
351.Rs
352.%B "The FreeBSD Handbook"
353.Re
354.Pp
355.Pa http://www.FreeBSD.org/ports
356(searchable index of all ports)
357.Sh AUTHORS
358.An -nosplit
359This man page was originated by
360.An David O'Brien .
361The ports collection is maintained by
362.An Satoshi Asami
363and the Awesome Ports Team.
364.Sh HISTORY
365The Ports Collection
366appeared in
367.Fx 1.0 .
368It has since spread to
369.Nx
370and
371.Ox .
372.Sh BUGS
373Ports documentation is split over four places \(em
374.Pa /usr/ports/Mk/bsd.port.mk ,
375.%B "The Porter's Handbook" ,
376the
377.Dq "Packages and Ports"
378chapter of
379.%B "The FreeBSD Handbook" ,
380and
381.Xr ports 7 .
382.Pp
383This man page is too long.
384