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 and corresponds to the
70 package set, while the
72 branches only provide critical fixes.
75 branch can be cloned and updated from the Git repository located at:
77 .Lk https://git.FreeBSD.org/ports.git
81 .Cm git clone https://git.FreeBSD.org/ports.git
85 branches can be found in Git as branches like
89 indicates the year and
95 .Cm git clone -b 2021Q2 https://git.FreeBSD.org/ports.git
97 It is generally a good idea to use the
99 branch that matches the
101 repository being used.
106 is configured to install packages built from the
110 or RELEASE versions it is configured to install packages built from
116 repository can be verified by looking at the
122 For more information about using ports, see the
123 .Dq "Packages and Ports" section
126 .%B "The FreeBSD Handbook"
130 .Lk https://docs.FreeBSD.org/en/books/handbook/ports/
132 For information about creating new ports, see
134 .%B "The Porter's Handbook"
138 .Lk https://docs.FreeBSD.org/en/books/porters-handbook/
142 targets work recursively through subdirectories.
143 This lets you, for example, install all of the
145 ports with one command.
146 The targets that do this are
147 .Cm build , checksum , clean , configure ,
148 .Cm depends , extract , fetch , install ,
152 The following targets will be run automatically by each proceeding
156 will be run (if necessary) by
158 and so on all the way to
160 Usually, you will only use the
163 .Bl -tag -width ".Cm configure"
170 Fetch all of the files needed to build this port from the sites
176 .Va FETCH_CMD , MASTER_SITE_OVERRIDE
178 .Va MASTER_SITE_BACKUP .
180 Verify that the fetched distfile's checksum matches the one the port was
182 If the distfile's checksum does not match, it also fetches the distfiles
183 which are missing or failed the checksum calculation.
189 (or compile if only compilation is necessary)
190 any dependencies of the current port.
195 targets, this is run in piecemeal as
196 .Cm fetch-depends , build-depends ,
202 Expand the distfile into a work directory.
204 Apply any patches that are necessary for the port.
207 Some ports will ask you questions during this stage.
214 This is the same as calling the
218 Install the port and register it with the package system.
219 This is all you really need to do.
220 .It Cm install-missing-packages
221 Install missing dependencies from packages instead of building them.
224 The following targets are not run during the normal install process.
225 .Bl -tag -width ".Cm fetch-recursive"
229 config for this port.
230 .It Cm showconfig-recursive
233 config for this port and all its dependencies.
237 config for this port.
238 .It Cm rmconfig-recursive
241 config for this port and all its dependencies.
242 .It Cm config-conditional
243 Skip the ports which have already had their
246 .It Cm config-recursive
249 for this port and all its dependencies using
252 Show list of files to be fetched in order to build the port.
253 .It Cm fetch-recursive
254 Fetch the distfiles of the port and all its dependencies.
255 .It Cm fetch-recursive-list
256 Show list of files that would be retrieved by
257 .Cm fetch-recursive .
258 .It Cm run-depends-list , build-depends-list
259 Print a list of all the compile and run dependencies, and dependencies
260 of those dependencies, by port directory.
261 .It Cm all-depends-list
262 Print a list of all dependencies for the port.
263 .It Cm pretty-print-run-depends-list , pretty-print-build-depends-list
264 Print a list of all the compile and run dependencies, and dependencies
265 of those dependencies, by port name and version.
267 Print a list of missing dependencies to be installed for the port.
269 Remove the expanded source code.
270 This recurses to dependencies unless
274 Remove the port's distfiles and perform the
279 portion recurses to dependencies unless
283 portion never recurses
284 (this is perhaps a bug).
286 Use this to restore a port after using
288 when you should have used
291 Remove an installed port from the system, similar to
294 Remove all installed ports with the same
298 Make a binary package for the port.
299 The port will be installed if it has not already been.
302 file that you can use to
303 install the port on other machines with
305 If the directory specified by
307 does not exist, the package will be put in
308 .Pa /usr/ports/category/port/work/pkg .
313 for more information.
314 .It Cm package-recursive
317 but makes a package for each depending port as well.
319 Prints the name with version of the port.
323 This can be used from
325 to create a browsable web of all ports on your system!
329 file for the pattern specified by the
331 (searches the port name, comment, and dependencies),
333 (searches the port name only),
335 (searches the port path),
337 (searches the port info),
339 (searches the port maintainer),
341 (searches the port category),
343 (searches the port build-time dependency),
345 (searches the port run-time dependency),
347 (searches the port web site)
349 variables, and their exclusion counterparts:
352 For example, one would type:
354 .Dl "cd /usr/ports && make search name=query"
356 to find all ports whose
359 Results include the matching ports' path, comment, maintainer,
360 build dependencies, and run dependencies.
361 .Bd -literal -offset indent
362 cd /usr/ports && make search name=pear- \e
366 To find all ports whose
369 and which do not have apache
370 listed in build-time dependencies.
371 .Bd -literal -offset indent
372 cd /usr/ports && make search name=pear- \e
376 To find all ports whose names contain
382 .Bd -literal -offset indent
383 make search key=apache display=name,path,info keylim=1
386 To find ports that contain
388 in either of the name, path, info
389 fields, ignore the rest of the record.
391 By default the search is not case-sensitive.
392 In order to make it case-sensitive you can use the
395 .Bd -literal -offset indent
396 make search name=p5-R icase=0
402 Only display name, path and info.
404 Generate a one-line description of each port for use in the
408 Display the port maintainer's email address.
411 .Pa /usr/ports/INDEX ,
419 target will ensure your
421 file is up to date with your ports tree.
430 You can change all of these.
431 .Bl -tag -width ".Va MASTER_SITES"
433 Location of the ports tree.
438 Where to create any temporary files.
441 is read-only (perhaps mounted from a CD-ROM).
443 Where to find/put distfiles, normally
448 Command used to elevate privilege to configure and install a port.
449 The unprivileged user must have write access to
454 .Ql /usr/bin/su root -c .
456 .Ql /usr/local/bin/sudo -E sh -c
461 target; the base directory for the packages tree, normally
465 If this directory exists, the package tree will be (partially) constructed.
466 This directory does not have to exist; if it does not, packages will be
467 placed into the current directory, or you can define one of
468 .Bl -tag -width ".Va PKGREPOSITORY"
470 Directory to put the package in.
472 The full path to the package.
475 Where existing things are installed and where to search for files when
476 resolving dependencies (usually
479 Where to install this port (usually set to the same as
482 Primary sites for distribution files if not found locally.
484 Primary locations for distribution patch files if not found
486 .It Va MASTER_SITE_FREEBSD
487 If set, go to the master
490 .It Va MASTER_SITE_OVERRIDE
491 Try going to these sites for all files and patches, first.
492 .It Va MASTER_SITE_BACKUP
493 Try going to these sites for all files and patches, last.
494 .It Va RANDOMIZE_MASTER_SITES
495 Try the download locations in a random order.
497 Sort the download locations according to user supplied pattern.
499 .Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net
500 .It Va MASTER_SITE_INDEX
509 .Pa https://www.FreeBSD.org/ports/ .
518 .It Va NOCLEANDEPENDS
519 If defined, do not let
521 recurse to dependencies.
523 Command to use to fetch files.
526 .It Va FORCE_PKG_REGISTER
527 If set, overwrite any existing package registration on the system.
529 If defined, only operate on a port if it requires interaction.
531 If defined, only operate on a port if it can be installed 100% automatically.
532 .It Va DISABLE_VULNERABILITIES
533 If defined, disable check for security vulnerabilities using
535 when installing new ports.
537 If defined, allow installation of ports marked as
539 The default behavior of the Ports framework is to abort when the
540 installation of a forbidden port is attempted.
541 Of course, these ports may not work as expected, but if you really know
542 what you are doing and are sure about installing a forbidden port, then
546 If defined, skip verifying the port's checksum.
548 If defined, attempt to build a port even if it is marked as
551 Directory where the results of configuring
558 have been configured will have a uniquely named sub-directory, containing a
563 The following list provides a name and short description for many of the
564 variables that are used when building ports.
565 More information on these and other related variables may be found in
570 .Bl -tag -width "WITH_CCACHE_BUILD"
573 If set, debugging symbols are installed for ports binaries.
574 .It Va WITH_DEBUG_PORTS
575 A list of origins for which to set
584 .It Va WITH_CCACHE_BUILD
586 If set, enables the use of
590 Which directory to use for the
595 .Bl -tag -width ".Pa /usr/ports/Mk/bsd.port.mk" -compact
597 The default ports directory.
598 .It Pa /usr/ports/Mk/bsd.port.mk
603 .It Sy Example 1\&: No Building and Installing a Port
605 The following command builds and installs Emacs.
606 .Bd -literal -offset 2n
607 .Li # Ic cd /usr/ports/editors/emacs
608 .Li # Ic make install
610 .It Sy Example 2\&: No Installing Dependencies with Xr pkg 8
612 The following example shows how to build and install a port without having to
613 build its dependencies.
614 Instead, the dependencies are downloaded via
616 .Bd -literal -offset 2n
617 .Li # Ic make install-missing-packages
618 .Li # Ic make install
621 It is especially useful, when the dependencies are costly
622 in time and resources to build
623 .Pq like Pa lang/rust .
626 offers only packages built with the default set of
628 .It Sy Example 3\&: No Building a Non-Default Flavor of a Port
630 The following command builds a non-default flavor of a port.
633 is going to be built with Python 3.7 support.)
634 .Bd -literal -offset 2n
635 .Li # Ic cd /usr/ports/devel/py-pip
636 .Li # Ic env FLAVOR=py37 make build
638 .It Sy Example 4\&: No Setting Ports Options via Xr make.conf 5
640 The following lines present various ways of configuring ports options via
642 (as an alternative to, e.g., running
643 .Dq Li make config ) :
644 .Bd -literal -offset 2n
645 # Enable NLS for all ports unless configured otherwise
646 # using the options dialog.
648 # Disable DOCS for all ports overriding the options set
649 # via the options dialog.
650 OPTIONS_UNSET_FORCE= DOCS
651 # Disable DOCS and EXAMPLES for the shells/zsh port.
652 shells_zsh_UNSET= DOCS EXAMPLES
655 These and other options-related variables are documented in
656 .Pa /usr/ports/Mk/bsd.options.mk .
657 .It Sy Example 5\&: No Setting Xr make 1 Variables for Specific Ports via Xr make.conf 5
659 The following example shows how to set arbitrary
661 variables only specific ports:
662 .Bd -literal -offset 2n
663 # Set DISABLE_MAKE_JOBS for the lang/rust port:
664 \&.if ${.CURDIR:M*/lang/rust}
665 DISABLE_MAKE_JOBS= yes
669 .It Sy Example 6\&: No Debugging Ports
670 By default ports are built and packaged without debugging support (e.g.,
671 debugging symbols are stripped from binaries, optimization flags are used for
672 compiling, verbose logging is disabled).
673 Whether ports are built with debugging symbols can be controlled by the
677 .Bd -literal -offset 2n
678 # Enable debugging for all ports.
680 # Enable debugging for selected ports.
681 WITH_DEBUG_PORTS= mail/dovecot security/krb5
684 It is also possible to use the debug variables on the command line:
685 .Bd -literal -offset 2n
686 .Li # Ic make -DWITH_DEBUG DEBUG_FLAGS="-g -O0" build
691 section to learn more about the debug variables.
693 To understand the details of what happens when the debug variables are set it
694 is best to consult the files located at
700 If debugging is enabled for a specific port, the ports framework will:
710 Try to prevent the binaries from being stripped (including checking the install
715 Whether a binary has been stripped can be checked with
718 Try to enable other debugging features like debug build type or verbose logging.
719 However, this is port-specific and the ports framework might not be aware of
720 each supported debugging feature a given piece of software has to offer).
729 Additional developer documentation:
730 .Bl -dash -width "" -offset indent
734 .Pa /usr/ports/Mk/bsd.port.mk
737 Additional user documentation:
738 .Bl -dash -width "" -offset indent
742 .Lk "https://www.FreeBSD.org/ports" "Searchable index of all ports"
748 It has since spread to
754 This manual page was originated by
757 Ports documentation is split over four places \(em
758 .Pa /usr/ports/Mk/bsd.port.mk ,
759 .%B "The Porter's Handbook" ,
761 .Dq "Packages and Ports"
763 .%B "The FreeBSD Handbook" ,