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