home | help 
PORTS(7)		 Miscellaneous Information Manual		PORTS(7)

NAME
     ports -- contributed applications

DESCRIPTION
     The  FreeBSD  Ports  Collection  offers a simple way to compile and install
     third party applications.	It is also used to build  packages,  to  be  in-
     stalled using pkg(8).  It can be installed and updated using portsnap(8).

     The  ports  tree,	typically located at /usr/ports, consists of subdirecto-
     ries, one for each category; those in turn contain individual ports.   Each
     port  is a directory with metadata and patches necessary to make the origi-
     nal application source code compile and run on FreeBSD.  Compiling  an  ap-
     plication	is  as simple as typing "make build" in the port directory.  The
     Makefile automatically fetches the application source code, either  from  a
     local  disk  or  the network, unpacks it, applies the patches, and compiles
     it.  It also recursively handles dependencies -- other pieces  of	software
     the port depends on in order to build and work.  Afterwards, "make install"
     installs the application.

     For  more	information  about  using  ports,  see	the  "Packages and Ports
     section" in The FreeBSD Handbook:

     https://www.FreeBSD.org/doc/en/books/handbook/ports.html

     For information about creating new ports, see The Porter's Handbook:

     https://www.FreeBSD.org/doc/en/books/porters-handbook/

TARGETS
     Some of the make(1) targets work recursively through subdirectories.   This
     lets you, for example, install all of the "biology" ports with one command.
     The  targets  that  do this are build, checksum, clean, configure, depends,
     extract, fetch, install, and package.

     The following targets will be run automatically by each  proceeding  target
     in  order.  That is, build will be run (if necessary) by install, and so on
     all the way to fetch.  Usually, you will only use the install target.

     config	Configure OPTIONS for this port using dialog4ports(1).

     fetch	Fetch all of the files needed to build this port from the  sites
		listed	 in   MASTER_SITES   and  PATCH_SITES.	 See  FETCH_CMD,
		MASTER_SITE_OVERRIDE and MASTER_SITE_BACKUP.

     checksum	Verify that the fetched distfile's checksum matches the one  the
		port  was  tested  against.  If the distfile's checksum does not
		match, it also fetches the distfiles which are missing or failed
		the checksum calculation.  Defining NO_CHECKSUM will  skip  this
		step.

     depends	Install (or compile if only compilation is necessary) any depen-
		dencies  of  the  current  port.   When called by the extract or
		fetch targets,	this  is  run  in  piecemeal  as  fetch-depends,
		build-depends, etc.  Defining NO_DEPENDS will skip this step.

     extract	Expand the distfile into a work directory.

     patch	Apply any patches that are necessary for the port.

     configure	Configure  the	port.	Some ports will ask you questions during
		this stage.  See INTERACTIVE and BATCH.

     build	Build the port.  This is the same as calling the all target.

     install	Install the port and register it with the package system.   This
		is all you really need to do.

     The following targets are not run during the normal install process.

     showconfig       Display OPTIONS config for this port.

     showconfig-recursive
		      Display OPTIONS config for this port and all its dependen-
		      cies.

     rmconfig	      Remove OPTIONS config for this port.

     rmconfig-recursive
		      Remove  OPTIONS config for this port and all its dependen-
		      cies.

     config-conditional
		      Skip the ports which have already had their  OPTIONS  con-
		      figured.

     config-recursive
		      Configure  OPTIONS  for this port and all its dependencies
		      using dialog4ports(1).

     fetch-list       Show list of files to be fetched in  order  to  build  the
		      port.

     fetch-recursive  Fetch the distfiles of the port and all its dependencies.

     fetch-recursive-list
		      Show   list   of	 files	 that	would  be  retrieved  by
		      fetch-recursive.

     run-depends-list, build-depends-list
		      Print a list of all the compile and run dependencies,  and
		      dependencies of those dependencies, by port directory.

     all-depends-list
		      Print a list of all dependencies for the port.

     pretty-print-run-depends-list, pretty-print-build-depends-list
		      Print  a list of all the compile and run dependencies, and
		      dependencies of those dependencies, by port name and  ver-
		      sion.

     missing	      Print  a	list of missing dependencies to be installed for
		      the port.

     clean	      Remove the expanded source code.	This recurses to  depen-
		      dencies unless NOCLEANDEPENDS is defined.

     distclean	      Remove  the port's distfiles and perform the clean target.
		      The  clean  portion  recurses   to   dependencies   unless
		      NOCLEANDEPENDS is defined, but the distclean portion never
		      recurses (this is perhaps a bug).

     reinstall	      Use  this to restore a port after using pkg-delete(8) when
		      you should have used deinstall.

     deinstall	      Remove an installed port from the system, similar to  pkg-
		      delete(8).

     deinstall-all    Remove  all  installed  ports with the same PKGORIGIN from
		      the system.

     package	      Make a binary package for the port.  The port will be  in-
		      stalled if it has not already been.  The package is a .tbz
		      file  that  you  can  use to install the port on other ma-
		      chines with pkg-add(8).  If  the	directory  specified  by
		      PACKAGES	does not exist, the package will be put into the
		      current directory.  See PKGREPOSITORY and PKGFILE.

     package-recursive
		      Like package, but makes a package for each depending  port
		      as well.

     package-name     Prints the name with version of the port.

     readmes	      Create  a  port's  README.html.	This  can  be  used from
		      /usr/ports to create a browsable web of all ports on  your
		      system!

     search	      Search the INDEX file for the pattern specified by the key
		      (searches  the port name, comment, and dependencies), name
		      (searches the port name only),  path  (searches  the  port
		      path),  info (searches the port info), maint (searches the
		      port maintainer), cat (searches the port category),  bdeps
		      (searches the port build-time dependency), rdeps (searches
		      the  port run-time dependency), www (searches the port web
		      site) make(1) variables, and their exclusion counterparts:
		      xname, xkey etc.	For example, one would type:

			    cd /usr/ports && make search name=query

		      to find all ports whose name matches "query".  Results in-
		      clude the matching ports' path, comment, maintainer, build
		      dependencies, and run dependencies.

			    cd /usr/ports && make search name=pear- \
				xbdeps=apache

		      To find all ports whose names contain "pear-" and which do
		      not have apache listed in build-time dependencies.

			    cd /usr/ports && make search name=pear- \
				xname='ht(tp|ml)'

		      To find all ports whose names  contain  "pear-",	but  not
		      "html" or "http".

			    make search key=apache display=name,path,info keylim=1

		      To find ports that contain "apache" in either of the name,
		      path, info fields, ignore the rest of the record.

		      By  default the search is not case-sensitive.  In order to
		      make it case-sensitive you can use the icase variable:

			    make search name=p5-R icase=0

     quicksearch      Reduced search output.  Only display name, path and info.

     describe	      Generate a one-line description of each port  for  use  in
		      the INDEX file.

     maintainer       Display the port maintainer's email address.

     index	      Create	/usr/ports/INDEX,   which   is	 used	by   the
		      pretty-print-* and search targets.  Running the index tar-
		      get will ensure your INDEX file is up to	date  with  your
		      ports tree.

     fetchindex       Fetch the INDEX file from the FreeBSD cluster.

ENVIRONMENT
     You can change all of these.

     PORTSDIR	   Location  of  the  ports tree.  This is /usr/ports on FreeBSD
		   and OpenBSD, and /usr/pkgsrc on NetBSD.

     WRKDIRPREFIX  Where to create any temporary files.  Useful if  PORTSDIR  is
		   read-only (perhaps mounted from a CD-ROM).

     DISTDIR	   Where to find/put distfiles, normally distfiles/ in PORTSDIR.

     SU_CMD	   Command  used to elevate privilege to configure and install a
		   port.  The  unprivileged  user  must  have  write  access  to
		   WRKDIRPREFIX  and  DISTDIR.	The default is `/usr/bin/su root
		   -c'

     PACKAGES	   Used only for the package target; the base directory for  the
		   packages  tree,  normally packages/ in PORTSDIR.  If this di-
		   rectory exists, the package tree  will  be  (partially)  con-
		   structed.   This directory does not have to exist; if it does
		   not, packages will be placed into the current  directory,  or
		   you can define one of

		   PKGREPOSITORY  Directory to put the package in.

		   PKGFILE	  The full path to the package.

     LOCALBASE	   Where  existing  things are installed and where to search for
		   files when resolving dependencies (usually /usr/local).

     PREFIX	   Where to install this  port	(usually  set  to  the	same  as
		   LOCALBASE).

     MASTER_SITES  Primary sites for distribution files if not found locally.

     PATCH_SITES   Primary  locations  for distribution patch files if not found
		   locally.

     MASTER_SITE_FREEBSD
		   If set, go to the master FreeBSD site for all files.

     MASTER_SITE_OVERRIDE
		   Try going to these sites for all files and patches, first.

     MASTER_SITE_BACKUP
		   Try going to these sites for all files and patches, last.

     RANDOMIZE_MASTER_SITES
		   Try the download locations in a random order.

     MASTER_SORT   Sort the download locations according to user  supplied  pat-
		   tern.  Example:
			 .dk	 .sunet.se     .se     dk.php.net     .no    .de
			 heanet.dl.sourceforge.net

     MASTER_SITE_INDEX
		   Where to get INDEX  source  built  on  FreeBSD  cluster  (for
		   fetchindex		target).	    Defaults	      to
		   https://www.FreeBSD.org/ports/.

     FETCHINDEX    Command to get INDEX (for fetchindex  target).   Defaults  to
		   "fetch -am".

     NOCLEANDEPENDS
		   If defined, do not let clean recurse to dependencies.

     FETCH_CMD	   Command to use to fetch files.  Normally fetch(1).

     FORCE_PKG_REGISTER
		   If  set,  overwrite	any existing package registration on the
		   system.

     MOTIFLIB	   Location of libXm.{a,so}.

     INTERACTIVE   If defined, only operate on a port if  it  requires	interac-
		   tion.

     BATCH	   If  defined,  only  operate	on a port if it can be installed
		   100% automatically.

     DISABLE_VULNERABILITIES
		   If defined, disable check for security vulnerabilities  using
		   pkg-audit(8) when installing new ports.

     NO_IGNORE	   If	defined,   allow   installation   of   ports  marked  as
		   <FORBIDDEN>.  The default behavior of the Ports framework  is
		   to  abort  when  the  installation of a forbidden port is at-
		   tempted.  Of course, these ports may not  work  as  expected,
		   but	if you really know what you are doing and are sure about
		   installing a forbidden port, then NO_IGNORE lets you do it.

     NO_CHECKSUM   If defined, skip verifying the port's checksum.

     TRYBROKEN	   If defined, attempt to build a port even if it is  marked  as
		   <BROKEN>.

     PORT_DBDIR    Directory  where  the  results  of  configuring  OPTIONS  are
		   stored.  Defaults to /var/db/ports.	Each port where  OPTIONS
		   have  been  configured  will have a uniquely named sub-direc-
		   tory, containing a single file options.

MAKE VARIABLES
     The following list provides a name and short description for  many  of  the
     variables that are used when building ports.  More information on these and
     other  related  variables	may be found in ${PORTSDIR}/Mk/* and the FreeBSD
     Porter's Handbook.

     WITH_OPENSSL_PORT	   (bool) If set, causes ports that make use of  OpenSSL
			   to  use the OpenSSL from ports (if available) instead
			   of the OpenSSL from the base system.

     WITH_DEBUG 	   (bool) If set, debugging symbols  are  installed  for
			   ports binaries.

     WITH_DEBUG_PORTS	   A list of origins for which to set WITH_DEBUG_PORTS.

     WITH_SSP_PORTS	   (bool)  If  set,  enables  -fstack-protector for most
			   ports.

     WITH_GHOSTSCRIPT_VER  If set, the version of  ghostscript	to  be	used  by
			   ports.

     WITH_CCACHE_BUILD	   (bool)  If  set,  enables  the  use	of ccache(1) for
			   building ports.

     CCACHE_DIR 	   Which directory to use for the ccache(1) data.

FILES
     /usr/ports 		The default ports directory.
     /usr/ports/Mk/bsd.port.mk	The big Kahuna.

EXAMPLES
     Build and install Emacs:

	   cd /usr/ports/editors/emacs
	   make install

SEE ALSO
     make(1), make.conf(5), pkg(7), portsnap(8)

     Additional developer documentation:

	   - portlint(1)

	   - /usr/ports/Mk/bsd.port.mk

     Additional user documentation:

	   - pkg(8)

	   - Searchable index of all ports

HISTORY
     The Ports Collection appeared in FreeBSD  1.0.   It  has  since  spread  to
     NetBSD and OpenBSD.

AUTHORS
     This manual page was originated by David O'Brien.

BUGS
     Ports documentation is split over four places -- /usr/ports/Mk/bsd.port.mk,
     The  Porter's  Handbook,  the  "Packages  and Ports" chapter of The FreeBSD
     Handbook, and this manual page.

FreeBSD 12.2			  July 17, 2020 			PORTS(7)
home | help