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$
  27 .\"
  28 .Dd August 16, 2018
  29 .Dt PORTS 7
  30 .Os
  31 .Sh NAME
  32 .Nm ports
  33 .Nd contributed applications
  34 .Sh DESCRIPTION
  35 The
  36 .Fx
  37 Ports Collection
  38 offers a simple way to compile and install third party applications.
  39 It is also used to build packages, to be installed using
  40 .Xr pkg 8 .
  41 It can be installed and updated using
  42 .Xr portsnap 8 .
  43 .Pp
  44 The ports tree, typically located at
  45 .Pa /usr/ports ,
  46 consists of subdirectories, one for each category; those in turn contain
  47 individual ports.
  48 Each port is a directory with metadata and patches necessary to make
  49 the original application source code compile and run on
  50 .Fx .
  51 Compiling an application is as simple as typing
  52 .Dq Li "make build"
  53 in the port directory.
  54 The
  55 .Pa Makefile
  56 automatically fetches the
  57 application source code, either from a local disk or the network, unpacks it,
  58 applies the patches, and compiles it.
  59 It also recursively handles dependencies \(em other pieces of software
  60 the port depends on in order to build and work.
  61 Afterwards,
  62 .Dq Li "make install"
  63 installs the application.
  64 .Pp
  65 For more information about using ports, see the
  66 .Dq "Packages and Ports" section
  67 in
  68 .Sm off
  69 .%B "The FreeBSD Handbook"
  70 .No \&:
  71 .Sm on
  72 .Pp
  73 .Lk https://www.FreeBSD.org/doc/en/books/handbook/ports.html
  74 .Pp
  75 For information about creating new ports, see
  76 .Sm off
  77 .%B "The Porter's Handbook"
  78 .No \&:
  79 .Sm on
  80 .Pp
  81 .Lk https://www.FreeBSD.org/doc/en/books/porters-handbook/
  82 .Sh TARGETS
  83 Some of the
  84 .Xr make 1
  85 targets work recursively through subdirectories.
  86 This lets you, for example, install all of the
  87 .Dq Li biology
  88 ports with one command.
  89 The targets that do this are
  90 .Cm build , checksum , clean , configure ,
  91 .Cm depends , extract , fetch , install ,
  92 and
  93 .Cm package .
  94 .Pp
  95 The following targets will be run automatically by each proceeding
  96 target in order.
  97 That is,
  98 .Cm build
  99 will be run (if necessary) by
 100 .Cm install ,
 101 and so on all the way to
 102 .Cm fetch .
 103 Usually, you will only use the
 104 .Cm install
 105 target.
 106 .Bl -tag -width ".Cm configure"
 107 .It Cm config
 108 Configure
 109 .Va OPTIONS
 110 for this port using
 111 .Xr dialog4ports 1 .
 112 .It Cm fetch
 113 Fetch all of the files needed to build this port from the sites
 114 listed in
 115 .Va MASTER_SITES
 116 and
 117 .Va PATCH_SITES .
 118 See
 119 .Va FETCH_CMD , MASTER_SITE_OVERRIDE
 120 and
 121 .Va MASTER_SITE_BACKUP .
 122 .It Cm checksum
 123 Verify that the fetched distfile's checksum matches the one the port was
 124 tested against.
 125 If the distfile's checksum does not match, it also fetches the distfiles
 126 which are missing or failed the checksum calculation.
 127 Defining
 128 .Va NO_CHECKSUM
 129 will skip this step.
 130 .It Cm depends
 131 Install
 132 (or compile if only compilation is necessary)
 133 any dependencies of the current port.
 134 When called by the
 135 .Cm extract
 136 or
 137 .Cm fetch
 138 targets, this is run in piecemeal as
 139 .Cm fetch-depends , build-depends ,
 140 etc.
 141 Defining
 142 .Va NO_DEPENDS
 143 will skip this step.
 144 .It Cm extract
 145 Expand the distfile into a work directory.
 146 .It Cm patch
 147 Apply any patches that are necessary for the port.
 148 .It Cm configure
 149 Configure the port.
 150 Some ports will ask you questions during this stage.
 151 See
 152 .Va INTERACTIVE
 153 and
 154 .Va BATCH .
 155 .It Cm build
 156 Build the port.
 157 This is the same as calling the
 158 .Cm all
 159 target.
 160 .It Cm install
 161 Install the port and register it with the package system.
 162 This is all you really need to do.
 163 .El
 164 .Pp
 165 The following targets are not run during the normal install process.
 166 .Bl -tag -width ".Cm fetch-recursive"
 167 .It Cm showconfig
 168 Display
 169 .Va OPTIONS
 170 config for this port.
 171 .It Cm showconfig-recursive
 172 Display
 173 .Va OPTIONS
 174 config for this port and all its dependencies.
 175 .It Cm rmconfig
 176 Remove
 177 .Va OPTIONS
 178 config for this port.
 179 .It Cm rmconfig-recursive
 180 Remove
 181 .Va OPTIONS
 182 config for this port and all its dependencies.
 183 .It Cm config-conditional
 184 Skip the ports which have already had their
 185 .Va OPTIONS
 186 configured.
 187 .It Cm config-recursive
 188 Configure
 189 .Va OPTIONS
 190 for this port and all its dependencies using
 191 .Xr dialog4ports 1 .
 192 .It Cm fetch-list
 193 Show list of files to be fetched in order to build the port.
 194 .It Cm fetch-recursive
 195 Fetch the distfiles of the port and all its dependencies.
 196 .It Cm fetch-recursive-list
 197 Show list of files that would be retrieved by
 198 .Cm fetch-recursive .
 199 .It Cm run-depends-list , build-depends-list
 200 Print a list of all the compile and run dependencies, and dependencies
 201 of those dependencies, by port directory.
 202 .It Cm all-depends-list
 203 Print a list of all dependencies for the port.
 204 .It Cm pretty-print-run-depends-list , pretty-print-build-depends-list
 205 Print a list of all the compile and run dependencies, and dependencies
 206 of those dependencies, by port name and version.
 207 .It Cm missing
 208 Print a list of missing dependencies to be installed for the port.
 209 .It Cm clean
 210 Remove the expanded source code.
 211 This recurses to dependencies unless
 212 .Va NOCLEANDEPENDS
 213 is defined.
 214 .It Cm distclean
 215 Remove the port's distfiles and perform the
 216 .Cm clean
 217 target.
 218 The
 219 .Cm clean
 220 portion recurses to dependencies unless
 221 .Va NOCLEANDEPENDS
 222 is defined, but the
 223 .Cm distclean
 224 portion never recurses
 225 (this is perhaps a bug).
 226 .It Cm reinstall
 227 Use this to restore a port after using
 228 .Xr pkg-delete 8
 229 when you should have used
 230 .Cm deinstall .
 231 .It Cm deinstall
 232 Remove an installed port from the system, similar to
 233 .Xr pkg-delete 8 .
 234 .It Cm deinstall-all
 235 Remove all installed ports with the same
 236 .Va PKGORIGIN
 237 from the system.
 238 .It Cm package
 239 Make a binary package for the port.
 240 The port will be installed if it has not already been.
 241 The package is a
 242 .Pa .tbz
 243 file that you can use to
 244 install the port on other machines with
 245 .Xr pkg-add 8 .
 246 If the directory specified by
 247 .Va PACKAGES
 248 does not exist, the package will be put into the current directory.
 249 See
 250 .Va PKGREPOSITORY
 251 and
 252 .Va PKGFILE .
 253 .It Cm package-recursive
 254 Like
 255 .Cm package ,
 256 but makes a package for each depending port as well.
 257 .It Cm package-name
 258 Prints the name with version of the port.
 259 .It Cm readmes
 260 Create a port's
 261 .Pa README.html .
 262 This can be used from
 263 .Pa /usr/ports
 264 to create a browsable web of all ports on your system!
 265 .It Cm search
 266 Search the
 267 .Pa INDEX
 268 file for the pattern specified by the
 269 .Va key
 270 (searches the port name, comment, and dependencies),
 271 .Va name
 272 (searches the port name only),
 273 .Va path
 274 (searches the port path),
 275 .Va info
 276 (searches the port info),
 277 .Va maint
 278 (searches the port maintainer),
 279 .Va cat
 280 (searches the port category),
 281 .Va bdeps
 282 (searches the port build-time dependency),
 283 .Va rdeps
 284 (searches the port run-time dependency),
 285 .Va www
 286 (searches the port web site)
 287 .Xr make 1
 288 variables, and their exclusion counterparts:
 289 .Va xname , xkey
 290 etc.
 291 For example, one would type:
 292 .Pp
 293 .Dl "cd /usr/ports && make search name=query"
 294 .Pp
 295 to find all ports whose
 296 name matches
 297 .Dq Li query .
 298 Results include the matching ports' path, comment, maintainer,
 299 build dependencies, and run dependencies.
 300 .Bd -literal -offset indent
 301 cd /usr/ports && make search name=pear- \e
 302     xbdeps=apache
 303 .Ed
 304 .Pp
 305 To find all ports whose
 306 names contain
 307 .Dq Li pear-
 308 and which do not have apache
 309 listed in build-time dependencies.
 310 .Bd -literal -offset indent
 311 cd /usr/ports && make search name=pear- \e
 312     xname='ht(tp|ml)'
 313 .Ed
 314 .Pp
 315 To find all ports whose names contain
 316 .Dq Li pear- ,
 317 but not
 318 .Dq Li html
 319 or
 320 .Dq Li http .
 321 .Bd -literal -offset indent
 322 make search key=apache display=name,path,info keylim=1
 323 .Ed
 324 .Pp
 325 To find ports that contain
 326 .Dq Li apache
 327 in either of the name, path, info
 328 fields, ignore the rest of the record.
 329 .Pp
 330 By default the search is not case-sensitive.
 331 In order to make it case-sensitive you can use the
 332 .Va icase
 333 variable:
 334 .Bd -literal -offset indent
 335 make search name=p5-R icase=0
 336 .Ed
 337 .It Cm quicksearch
 338 Reduced
 339 .Cm search
 340 output.
 341 Only display name, path and info.
 342 .It Cm describe
 343 Generate a one-line description of each port for use in the
 344 .Pa INDEX
 345 file.
 346 .It Cm maintainer
 347 Display the port maintainer's email address.
 348 .It Cm index
 349 Create
 350 .Pa /usr/ports/INDEX ,
 351 which is used by the
 352 .Cm pretty-print-*
 353 and
 354 .Cm search
 355 targets.
 356 Running the
 357 .Cm index
 358 target will ensure your
 359 .Pa INDEX
 360 file is up to date with your ports tree.
 361 .It Cm fetchindex
 362 Fetch the
 363 .Pa INDEX
 364 file from the
 365 .Fx
 366 cluster.
 367 .El
 368 .Sh ENVIRONMENT
 369 You can change all of these.
 370 .Bl -tag -width ".Va MASTER_SITES"
 371 .It Va PORTSDIR
 372 Location of the ports tree.
 373 This is
 374 .Pa /usr/ports
 375 on
 376 .Fx
 377 and
 378 .Ox ,
 379 and
 380 .Pa /usr/pkgsrc
 381 on
 382 .Nx .
 383 .It Va WRKDIRPREFIX
 384 Where to create any temporary files.
 385 Useful if
 386 .Va PORTSDIR
 387 is read-only (perhaps mounted from a CD-ROM).
 388 .It Va DISTDIR
 389 Where to find/put distfiles, normally
 390 .Pa distfiles/
 391 in
 392 .Va PORTSDIR .
 393 .It Va PACKAGES
 394 Used only for the
 395 .Cm package
 396 target; the base directory for the packages tree, normally
 397 .Pa packages/
 398 in
 399 .Va PORTSDIR .
 400 If this directory exists, the package tree will be (partially) constructed.
 401 This directory does not have to exist; if it does not, packages will be
 402 placed into the current directory, or you can define one of
 403 .Bl -tag -width ".Va PKGREPOSITORY"
 404 .It Va PKGREPOSITORY
 405 Directory to put the package in.
 406 .It Va PKGFILE
 407 The full path to the package.
 408 .El
 409 .It Va LOCALBASE
 410 Where existing things are installed and where to search for files when
 411 resolving dependencies (usually
 412 .Pa /usr/local ) .
 413 .It Va PREFIX
 414 Where to install this port (usually set to the same as
 415 .Va LOCALBASE ) .
 416 .It Va MASTER_SITES
 417 Primary sites for distribution files if not found locally.
 418 .It Va PATCH_SITES
 419 Primary locations for distribution patch files if not found
 420 locally.
 421 .It Va MASTER_SITE_FREEBSD
 422 If set, go to the master
 423 .Fx
 424 site for all files.
 425 .It Va MASTER_SITE_OVERRIDE
 426 Try going to these sites for all files and patches, first.
 427 .It Va MASTER_SITE_BACKUP
 428 Try going to these sites for all files and patches, last.
 429 .It Va RANDOMIZE_MASTER_SITES
 430 Try the download locations in a random order.
 431 .It Va MASTER_SORT
 432 Sort the download locations according to user supplied pattern.
 433 Example:
 434 .Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net
 435 .It Va MASTER_SITE_INDEX
 436 Where to get
 437 .Pa INDEX
 438 source built on
 439 .Fx
 440 cluster (for
 441 .Cm fetchindex
 442 target).
 443 Defaults to
 444 .Pa https://www.FreeBSD.org/ports/ .
 445 .It Va FETCHINDEX
 446 Command to get
 447 .Pa INDEX
 448 (for
 449 .Cm fetchindex
 450 target).
 451 Defaults to
 452 .Dq Li "fetch -am" .
 453 .It Va NOCLEANDEPENDS
 454 If defined, do not let
 455 .Cm clean
 456 recurse to dependencies.
 457 .It Va FETCH_CMD
 458 Command to use to fetch files.
 459 Normally
 460 .Xr fetch 1 .
 461 .It Va FORCE_PKG_REGISTER
 462 If set, overwrite any existing package registration on the system.
 463 .It Va MOTIFLIB
 464 Location of
 465 .Pa "libXm\&." Ns Brq Pa a , Ns Pa so .
 466 .It Va INTERACTIVE
 467 If defined, only operate on a port if it requires interaction.
 468 .It Va BATCH
 469 If defined, only operate on a port if it can be installed 100% automatically.
 470 .It Va DISABLE_VULNERABILITIES
 471 If defined, disable check for security vulnerabilities using
 472 .Xr pkg-audit 8
 473 when installing new ports.
 474 .It Va NO_IGNORE
 475 If defined, allow installation of ports marked as
 476 .Aq Va FORBIDDEN .
 477 The default behavior of the Ports framework is to abort when the
 478 installation of a forbidden port is attempted.
 479 Of course, these ports may not work as expected, but if you really know
 480 what you are doing and are sure about installing a forbidden port, then
 481 .Va NO_IGNORE
 482 lets you do it.
 483 .It Va NO_CHECKSUM
 484 If defined, skip verifying the port's checksum.
 485 .It Va TRYBROKEN
 486 If defined, attempt to build a port even if it is marked as
 487 .Aq Va BROKEN .
 488 .It Va PORT_DBDIR
 489 Directory where the results of configuring
 490 .Va OPTIONS
 491 are stored.
 492 Defaults to
 493 .Pa /var/db/ports .
 494 Each port where
 495 .Va OPTIONS
 496 have been configured will have a uniquely named sub-directory, containing a
 497 single file
 498 .Pa options .
 499 .El
 500 .Sh MAKE VARIABLES
 501 The following list provides a name and short description for many of the
 502 variables that are used when building ports.
 503 More information on these and other related variables may be found in
 504 .Pa ${PORTSDIR}/Mk/*
 505 and the
 506 .Fx
 507 Porter's Handbook.
 508 .Bl -tag -width ".Va WITH_GHOSTSCRIPT_VER"
 509 .It Va WITH_OPENSSL_PORT
 510 .Pq Vt bool
 511 If set, causes ports that make use of OpenSSL to use the OpenSSL from
 512 ports
 513 .Pq if available
 514 instead of the OpenSSL from the base system.
 515 .It Va WITH_DEBUG
 516 .Pq Vt bool
 517 If set, debugging symbols are installed for ports binaries.
 518 .It Va WITH_DEBUG_PORTS
 519 A list of origins for which to set
 520 .Va WITH_DEBUG_PORTS .
 521 .It Va WITH_SSP_PORTS
 522 .Pq Vt bool
 523 If set, enables
 524 .Fl fstack-protector
 525 for most ports.
 526 .It Va WITH_GHOSTSCRIPT_VER
 527 If set, the version of ghostscript to be used by ports.
 528 .It Va WITH_CCACHE_BUILD
 529 .Pq Vt bool
 530 If set, enables the use of
 531 .Xr ccache 1
 532 for building ports.
 533 .It Va CCACHE_DIR
 534 Which directory to use for the
 535 .Xr ccache 1
 536 data.
 537 .El
 538 .Sh FILES
 539 .Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact
 540 .It Pa /usr/ports
 541 The default ports directory.
 542 .It Pa /usr/ports/Mk/bsd.port.mk
 543 The big Kahuna.
 544 .El
 545 .Sh EXAMPLES
 546 Build and install Emacs:
 547 .Bd -literal -offset indent
 548 cd /usr/ports/editors/emacs
 549 make install
 550 .Ed
 551 .Sh SEE ALSO
 552 .Xr make 1 ,
 553 .Xr make.conf 5 ,
 554 .Xr pkg 7 ,
 555 .Xr portsnap 8
 556 .Pp
 557 Additional developer documentation:
 558 .Bl -dash -width "" -offset indent
 559 .It
 560 .Xr portlint 1
 561 .It
 562 .Pa /usr/ports/Mk/bsd.port.mk
 563 .El
 564 .Pp
 565 Additional user documentation:
 566 .Bl -dash -width "" -offset indent
 567 .It
 568 .Xr pkg 8
 569 .It
 570 .Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports"
 571 .El
 572 .Sh HISTORY
 573 The Ports Collection
 574 appeared in
 575 .Fx 1.0 .
 576 It has since spread to
 577 .Nx
 578 and
 579 .Ox .
 580 .Sh AUTHORS
 581 .An -nosplit
 582 This manual page was originated by
 583 .An David O'Brien .
 584 .Sh BUGS
 585 Ports documentation is split over four places \(em
 586 .Pa /usr/ports/Mk/bsd.port.mk ,
 587 .%B "The Porter's Handbook" ,
 588 the
 589 .Dq "Packages and Ports"
 590 chapter of
 591 .%B "The FreeBSD Handbook" ,
 592 and
 593 this manual page.