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