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