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