2 .\" Copyright (c) 1997 David E. O'Brien
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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.
33 .Nd contributed applications
38 offers a simple way to compile and install third party applications.
39 It is also used to build packages, to be installed using
42 The ports tree, typically located at
44 consists of subdirectories, one for each category; those in turn contain
46 Each port is a directory with metadata and patches necessary to make
47 the original application source code compile and run on
49 Compiling an application is as simple as typing
51 in the port directory.
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.
61 installs the application.
65 Ports Collection is maintained in several branches, which differ mostly
66 by versions of software provided: the
68 branch contains all the latest changes, while the
70 branches only provide critical fixes.
73 branch can be installed or updated from the Subversion repository located at:
75 .Lk https://svn.FreeBSD.org/ports/head
79 branches can be found in Subversion in the
83 .Lk https://svn.FreeBSD.org/ports/branches/2019Q1
85 It is generally a good idea to use the
87 branch that matches the
89 repository being used.
94 is configured to install packages built from the
98 or RELEASE versions it is configured to install packages built from
104 repository can be verified by looking at the
110 For more information about using ports, see the
111 .Dq "Packages and Ports" section
114 .%B "The FreeBSD Handbook"
118 .Lk https://www.FreeBSD.org/doc/en/books/handbook/ports.html
120 For information about creating new ports, see
122 .%B "The Porter's Handbook"
126 .Lk https://www.FreeBSD.org/doc/en/books/porters-handbook/
130 targets work recursively through subdirectories.
131 This lets you, for example, install all of the
133 ports with one command.
134 The targets that do this are
135 .Cm build , checksum , clean , configure ,
136 .Cm depends , extract , fetch , install ,
140 The following targets will be run automatically by each proceeding
144 will be run (if necessary) by
146 and so on all the way to
148 Usually, you will only use the
151 .Bl -tag -width ".Cm configure"
158 Fetch all of the files needed to build this port from the sites
164 .Va FETCH_CMD , MASTER_SITE_OVERRIDE
166 .Va MASTER_SITE_BACKUP .
168 Verify that the fetched distfile's checksum matches the one the port was
170 If the distfile's checksum does not match, it also fetches the distfiles
171 which are missing or failed the checksum calculation.
177 (or compile if only compilation is necessary)
178 any dependencies of the current port.
183 targets, this is run in piecemeal as
184 .Cm fetch-depends , build-depends ,
190 Expand the distfile into a work directory.
192 Apply any patches that are necessary for the port.
195 Some ports will ask you questions during this stage.
202 This is the same as calling the
206 Install the port and register it with the package system.
207 This is all you really need to do.
210 The following targets are not run during the normal install process.
211 .Bl -tag -width ".Cm fetch-recursive"
215 config for this port.
216 .It Cm showconfig-recursive
219 config for this port and all its dependencies.
223 config for this port.
224 .It Cm rmconfig-recursive
227 config for this port and all its dependencies.
228 .It Cm config-conditional
229 Skip the ports which have already had their
232 .It Cm config-recursive
235 for this port and all its dependencies using
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.
253 Print a list of missing dependencies to be installed for the port.
255 Remove the expanded source code.
256 This recurses to dependencies unless
260 Remove the port's distfiles and perform the
265 portion recurses to dependencies unless
269 portion never recurses
270 (this is perhaps a bug).
272 Use this to restore a port after using
274 when you should have used
277 Remove an installed port from the system, similar to
280 Remove all installed ports with the same
284 Make a binary package for the port.
285 The port will be installed if it has not already been.
288 file that you can use to
289 install the port on other machines with
291 If the directory specified by
293 does not exist, the package will be put into the current directory.
298 .It Cm package-recursive
301 but makes a package for each depending port as well.
303 Prints the name with version of the port.
307 This can be used from
309 to create a browsable web of all ports on your system!
313 file for the pattern specified by the
315 (searches the port name, comment, and dependencies),
317 (searches the port name only),
319 (searches the port path),
321 (searches the port info),
323 (searches the port maintainer),
325 (searches the port category),
327 (searches the port build-time dependency),
329 (searches the port run-time dependency),
331 (searches the port web site)
333 variables, and their exclusion counterparts:
336 For example, one would type:
338 .Dl "cd /usr/ports && make search name=query"
340 to find all ports whose
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
350 To find all ports whose
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
360 To find all ports whose names contain
366 .Bd -literal -offset indent
367 make search key=apache display=name,path,info keylim=1
370 To find ports that contain
372 in either of the name, path, info
373 fields, ignore the rest of the record.
375 By default the search is not case-sensitive.
376 In order to make it case-sensitive you can use the
379 .Bd -literal -offset indent
380 make search name=p5-R icase=0
386 Only display name, path and info.
388 Generate a one-line description of each port for use in the
392 Display the port maintainer's email address.
395 .Pa /usr/ports/INDEX ,
403 target will ensure your
405 file is up to date with your ports tree.
414 You can change all of these.
415 .Bl -tag -width ".Va MASTER_SITES"
417 Location of the ports tree.
422 Where to create any temporary files.
425 is read-only (perhaps mounted from a CD-ROM).
427 Where to find/put distfiles, normally
432 Command used to elevate privilege to configure and install a port.
433 The unprivileged user must have write access to
438 .Ql /usr/bin/su root -c .
440 .Ql /usr/local/bin/sudo -E sh -c
445 target; the base directory for the packages tree, normally
449 If this directory exists, the package tree will be (partially) constructed.
450 This directory does not have to exist; if it does not, packages will be
451 placed into the current directory, or you can define one of
452 .Bl -tag -width ".Va PKGREPOSITORY"
454 Directory to put the package in.
456 The full path to the package.
459 Where existing things are installed and where to search for files when
460 resolving dependencies (usually
463 Where to install this port (usually set to the same as
466 Primary sites for distribution files if not found locally.
468 Primary locations for distribution patch files if not found
470 .It Va MASTER_SITE_FREEBSD
471 If set, go to the master
474 .It Va MASTER_SITE_OVERRIDE
475 Try going to these sites for all files and patches, first.
476 .It Va MASTER_SITE_BACKUP
477 Try going to these sites for all files and patches, last.
478 .It Va RANDOMIZE_MASTER_SITES
479 Try the download locations in a random order.
481 Sort the download locations according to user supplied pattern.
483 .Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net
484 .It Va MASTER_SITE_INDEX
493 .Pa https://www.FreeBSD.org/ports/ .
502 .It Va NOCLEANDEPENDS
503 If defined, do not let
505 recurse to dependencies.
507 Command to use to fetch files.
510 .It Va FORCE_PKG_REGISTER
511 If set, overwrite any existing package registration on the system.
513 If defined, only operate on a port if it requires interaction.
515 If defined, only operate on a port if it can be installed 100% automatically.
516 .It Va DISABLE_VULNERABILITIES
517 If defined, disable check for security vulnerabilities using
519 when installing new ports.
521 If defined, allow installation of ports marked as
523 The default behavior of the Ports framework is to abort when the
524 installation of a forbidden port is attempted.
525 Of course, these ports may not work as expected, but if you really know
526 what you are doing and are sure about installing a forbidden port, then
530 If defined, skip verifying the port's checksum.
532 If defined, attempt to build a port even if it is marked as
535 Directory where the results of configuring
542 have been configured will have a uniquely named sub-directory, containing a
547 The following list provides a name and short description for many of the
548 variables that are used when building ports.
549 More information on these and other related variables may be found in
554 .Bl -tag -width "WITH_CCACHE_BUILD"
557 If set, debugging symbols are installed for ports binaries.
558 .It Va WITH_DEBUG_PORTS
559 A list of origins for which to set
561 .It Va WITH_CCACHE_BUILD
563 If set, enables the use of
567 Which directory to use for the
572 .Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact
574 The default ports directory.
575 .It Pa /usr/ports/Mk/bsd.port.mk
580 .It Sy Example 1\&: No Building and Installing a Port
582 The following command builds and installs Emacs.
583 .Bd -literal -offset 2n
584 .Li # Ic cd /usr/ports/editors/emacs
585 .Li # Ic make install
587 .It Sy Example 2\&: No Installing Dependencies with Xr pkg 8
589 The following example shows how to build and install a port without having to
590 build its dependencies.
591 Instead, the dependencies are downloaded via
593 .Bd -literal -offset 2n
594 .Li # Ic make install-missing-packages
595 .Li # Ic make install
598 It is especially useful, when the dependencies are costly
599 in time and resources to build
600 .Pq like Pa lang/rust .
603 offers only packages built with the default set of
605 .It Sy Example 3\&: No Building a Non-Default Flavor of a Port
607 The following command builds a non-default flavor of a port.
610 is going to be built with Python 3.7 support.)
611 .Bd -literal -offset 2n
612 .Li # Ic cd /usr/ports/devel/py-pip
613 .Li # Ic env FLAVOR=py37 make build
615 .It Sy Example 4\&: No Setting Ports Options via Xr make.conf 5
617 The following lines present various ways of configuring ports options via
619 (as an alternative to, e.g., running
620 .Dq Li make config ) :
621 .Bd -literal -offset 2n
622 # Enable NLS for all ports unless configured otherwise
623 # using the options dialog.
625 # Disable DOCS for all ports overriding the options set
626 # via the options dialog.
627 OPTIONS_UNSET_FORCE= DOCS
628 # Disable DOCS and EXAMPLES for the shells/zsh port.
629 shells_zsh_UNSET= DOCS EXAMPLES
632 These and other options-related variables are documented in
633 .Pa /usr/ports/Mk/bsd.options.mk .
641 Additional developer documentation:
642 .Bl -dash -width "" -offset indent
646 .Pa /usr/ports/Mk/bsd.port.mk
649 Additional user documentation:
650 .Bl -dash -width "" -offset indent
654 .Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports"
660 It has since spread to
666 This manual page was originated by
669 Ports documentation is split over four places \(em
670 .Pa /usr/ports/Mk/bsd.port.mk ,
671 .%B "The Porter's Handbook" ,
673 .Dq "Packages and Ports"
675 .%B "The FreeBSD Handbook" ,