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