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.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 $
  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.