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