path: root/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$

-->

<!--

  Document up-to date with r441983 revision of the ports tree.

  This file documents the values of the USES make variable.  The
  format is easy to grasp from the already-added entries below (or use
  this scheme below as a skeleton):

  <sect1 xml:id="uses-FEATURE">
    <title><literal>FEATURE</literal></title>

    <para>Possible arguments: ARGUMENTS</para>

    <para>DESCRIPTION</para>
  </sect1>

-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink=
  "http://www.w3.org/1999/xlink" version="5.0" xml:id="uses">

  <title>Using <varname>USES</varname> Macros</title>

  <sect1 xml:id="uses-intro">
    <title>An Introduction to <varname>USES</varname></title>

    <para><varname>USES</varname> macros make it easy to declare
      requirements and settings for a port.  They can add
      dependencies, change building behavior, add metadata to
      packages, and so on, all by selecting simple, preset
      values.</para>

    <para>Each section in this chapter describes a possible value for
      <varname>USES</varname>, along with its possible arguments.
      Arguments are appeneded to the value after a colon
      (<literal>:</literal>).  Multiple arguments are separated by
      commas (<literal>,</literal>).</para>

    <example xml:id="uses-intro-ex1">
      <title>Using Multiple Values</title>

      <programlisting>USES=	bison perl</programlisting>
    </example>

    <example xml:id="uses-intro-ex2">
      <title>Adding an Argument</title>

      <programlisting>USES=	tar:xz</programlisting>
    </example>

    <example xml:id="uses-intro-ex3">
      <title>Adding Multiple Arguments</title>

      <programlisting>USES=	drupal:7,theme</programlisting>
    </example>

    <example xml:id="uses-intro-ex4">
      <title>Mixing it All Together</title>

      <programlisting>USES=	pgsql:9.3+ cpe python:2.7,build</programlisting>
    </example>
  </sect1>

  <sect1 xml:id="uses-7z">
    <title><literal>7z</literal></title>

    <para>Possible arguments: (none), <literal>p7zip</literal>,
      <literal>partial</literal></para>

    <para>Extract using &man.7z.1; instead of &man.bsdtar.1; and sets
      <literal>EXTRACT_SUFX=.7z</literal>.  The
      <literal>p7zip</literal> option forces a dependency on the
      <command>7z</command> from <package
	role="port">archivers/p7zip</package> if the one from the base
      system is not able to extract the files.
      <varname>EXTRACT_SUFX</varname> is not changed if the
      <literal>partial</literal> option is used, this can be used if
      the main distribution file does not have a
      <filename>.7z</filename> extension.</para>
  </sect1>

  <sect1 xml:id="uses-ada">
    <title><literal>ada</literal></title>

    <para>Possible arguments: (none),
      <literal>5</literal>,
      <literal>6</literal></para>

    <para>Depends on an <application>Ada</application>-capable
      compiler, and sets <varname>CC</varname> accordingly.  Defaults
      to use <application>gcc</application> 5 from ports.  Use the
      <literal>:<replaceable>X</replaceable></literal> version option
      to force building with a different version.</para>
  </sect1>

  <sect1 xml:id="uses-autoreconf">
    <title><literal>autoreconf</literal></title>

    <para>Possible arguments: (none), <literal>build</literal></para>

    <para>Runs <command>autoreconf</command>.  It encapsulates the
      <command>aclocal</command>, <command>autoconf</command>,
      <command>autoheader</command>, <command>automake</command>,
      <command>autopoint</command>, and <command>libtoolize</command>
      commands.  Each command applies to
      <filename>${AUTORECONF_WRKSRC}/configure.ac</filename> or its
      old name,
      <filename>${AUTORECONF_WRKSRC}/configure.in</filename>.  If
      <filename>configure.ac</filename> defines subdirectories with
      their own <filename>configure.ac</filename> using
      <literal>AC_CONFIG_SUBDIRS</literal>,
      <command>autoreconf</command> will recursively update those as
      well.  The <literal>:build</literal> argument only adds build
      time dependencies on those tools but does not run
      <command>autoreconf</command>.  A port can set
      <varname>AUTORECONF_WRKSRC</varname> if
      <varname>WRKSRC</varname> does not contain the path to
      <filename>configure.ac</filename>.</para>
  </sect1>

  <sect1 xml:id="uses-blaslapack">
    <title><literal>blaslapack</literal></title>

    <para>Possible arguments: (none), <literal>atlas</literal>,
      <literal>netlib</literal> (default),
      <literal>gotoblas</literal>, <literal>openblas</literal></para>

    <para>Adds dependencies on Blas / Lapack libraries.</para>
  </sect1>

  <sect1 xml:id="uses-bdb">
    <title><literal>bdb</literal></title>

    <para>Possible arguments: (none), <literal>48</literal>,
      <literal>5</literal> (default), <literal>6</literal></para>

    <para>Add dependency on the <application>Berkeley DB</application>
      library.  Default to <package
	role="port">databases/db5</package>.  It can also depend on
      <package role="port">databases/db48</package> when using the
      <literal>:48</literal> argument or <package
	role="port">databases/db6</package> with
      <literal>:6</literal>.  It is possible to declare a range of
      acceptable values, <literal>:48+</literal> finds the highest
      installed version, and falls back to 4.8 if nothing else is
      installed.  <varname>INVALID_BDB_VER</varname> can be used to
      specify versions which do not work with this port.  The
      framework exposes the following variables to the port:</para>

    <variablelist>
      <varlistentry>
	<term><varname>BDB_LIB_NAME</varname></term>

	<listitem>
	  <para>The name of the <application>Berkeley DB</application>
	    library.  For example, when using <package
	      role="port">databases/db5</package>, it contains
	    <literal>db-5.3</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>BDB_LIB_CXX_NAME</varname></term>

	<listitem>
	  <para>The name of the <application>Berkeley DB</application>
	    <application>C++</application> library.  For example, when
	    using <package role="port">databases/db5</package>, it
	    contains <literal>db_cxx-5.3</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>BDB_INCLUDE_DIR</varname></term>

	<listitem>
	  <para>The location of the <application>Berkeley
	      DB</application> include directory.  For example, when
	    using <package role="port">databases/db5</package>, it
	    will contain
	    <literal>${LOCALBASE}/include/db5</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>BDB_LIB_DIR</varname></term>

	<listitem>
	  <para>The location of the <application>Berkeley
	      DB</application> library directory.  For example, when
	    using <package role="port">databases/db5</package>, it
	    contains <literal>${LOCALBASE}/lib</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>BDB_VER</varname></term>

	<listitem>
	  <para>The detected <application>Berkeley DB</application>
	    version.  For example, if using
	    <literal>USES=bdb:48+</literal> and <application>Berkeley
	      DB</application> 5 is installed, it contains
	    <literal>5</literal>.</para>
	</listitem>
      </varlistentry>
    </variablelist>


    <important>
      <para><package role="port">databases/db48</package> is
	deprecated and unsupported.  It must not be used by any
	port.</para>
    </important>
  </sect1>

  <sect1 xml:id="uses-bison">
    <title><literal>bison</literal></title>

    <para>Possible arguments: (none), <literal>build</literal>,
      <literal>run</literal>, <literal>both</literal></para>

    <para>Uses <package role="port">devel/bison</package> By default,
      with no arguments or with the <literal>build</literal> argument,
      it implies <command>bison</command> is a build-time dependency,
      <literal>run</literal> implies a run-time dependency, and
      <literal>both</literal> implies both run-time and build-time
      dependencies.</para>
  </sect1>

  <sect1 xml:id="uses-cabal">
    <title><literal>cabal</literal></title>

    <important>
      <para>Ports should not be created for Haskell libraries, see
	<xref linkend="haskell-libs"/> for more information.</para>
    </important>

    <para>Possible arguments: (none), <literal>hpack</literal></para>

    <para>Sets default values and targets used to build
      <application>Haskell</application> software using Cabal.
      A build dependency on the Haskell compiler port (GHC)
      is added.  If <literal>hpack</literal> argument is given,
      a build dependency on <package role="port">devel/hs-hpack</package>
      is added and <command>hpack</command> is invoked at
      configuration step to generate .cabal file.</para>

    <para>The framework provides the following variables:</para>

    <variablelist>
      <varlistentry>
	<term><varname>USE_CABAL</varname></term>

	<listitem>
	  <para>If the software uses Haskell dependencies, list them in
	    this variable.  Each item should be present on Hackage and
	    be listed in form <literal>packagename-<replaceable>0.1.2</replaceable></literal>.
	    Dependencies can have revisions, which are specified after the
	    <literal>_</literal> symbol. Automatic generation of dependency
	    list is supported, see <xref linkend="using-cabal"/>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>CABAL_FLAGS</varname></term>

	<listitem>
	  <para>List of flags to be passed to <command>cabal-install</command>
	    during the configuring and building stage. The flags are
	    passed verbatim.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>EXECUTABLES</varname></term>

	<listitem>
	  <para>List of executable files installed by the port.
	    Default value: <varname>${PORTNAME}</varname>.
	    Items from this list are automatically added to pkg-plist.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>SKIP_CABAL_PLIST</varname></term>

	<listitem>
	  <para>If defined, do not add items from
	    <varname>${EXECUTABLES}</varname> to pkg-plist.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>opt_USE_CABAL</varname></term>

	<listitem>
	  <para>Adds items to <varname>${USE_CABAL}</varname>
	    depending on <literal>opt</literal> option.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>opt_EXECUTABLES</varname></term>

	<listitem>
	  <para>Adds items to <varname>${EXECUTABLES}</varname>
	    depending on <literal>opt</literal> option.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>opt_CABAL_FLAGS</varname></term>

	<listitem>
	  <para>If <option>opt</option> is enabled, append the value
	    to <varname>${CABAL_FLAGS}</varname>. Otherwise, append
	    <literal>-value</literal> to disable the flag.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>FOO_DATADIR_VARS</varname></term>

	<listitem>
	  <para>For an executable named <literal>FOO</literal>
	    list Haskell packages, whose data files
	    should be accessible by the executable.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 xml:id="uses-cargo">
    <title><literal>cargo</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Uses Cargo for configuring, building, and testing.
      It can be used to port Rust applications that use the Cargo
      build system. For more information see <xref
        linkend="using-cargo" />.</para>
  </sect1>

  <sect1 xml:id="uses-charsetfix">
    <title><literal>charsetfix</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Prevents the port from installing
      <filename>charset.alias</filename>.  This must be installed only
      by <package role="port">converters/libiconv</package>.
      <varname>CHARSETFIX_MAKEFILEIN</varname> can be set to a path
      relative to <varname>WRKSRC</varname> if
      <filename>charset.alias</filename> is not installed by
      <filename>${WRKSRC}/Makefile.in</filename>.</para>
  </sect1>

  <sect1 xml:id="uses-cmake">
    <title><literal>cmake</literal></title>

    <para>Possible arguments: (none), <literal>insource</literal>,
      <literal>noninja</literal>, <literal>run</literal></para>

    <para>Uses <application>CMake</application> for configuring and
      building.</para>

    <para>By default an out-of-source build is performed, leaving the
      sources in <varname>WRKSRC</varname> free from build artifacts.
      With the <literal>insource</literal> argument, an in-source
      build will be performed instead.  Setting it should be the
      exception when a regular out-of-source build does not
      work.</para>

    <para>By default <application>Ninja</application> is used for
      the build.  In some cases this does not work correctly.  With
      the <literal>noninja</literal> argument, the build will
      fallback to using regular <command>make</command> for builds.
      It should only be used if a
      <application>Ninja</application>-based build does not
      work.</para>

    <para>With the <literal>run</literal> argument, a run dependency
      is registered in addition to a build dependency.</para>

    <para>For more information see <xref linkend="using-cmake"/>.</para>
  </sect1>

  <sect1 xml:id="uses-compiler">
    <title><literal>compiler</literal></title>

    <para>Possible arguments: (none), <literal>env</literal>
      (default, implicit), <literal>c++17-lang</literal>,
      <literal>c++14-lang</literal>,
      <literal>c++11-lang</literal>, <literal>gcc-c++11-lib</literal>,
      <literal>c++11-lib</literal>, <literal>c++0x</literal>,
      <literal>c11</literal>, <literal>openmp</literal>,
      <literal>nestedfct</literal>, <literal>features</literal></para>

    <para>Determines which compiler to use based on any given wishes.
      Use <literal>c++17-lang</literal> if the port needs a
      C++17-capable compiler,
      <literal>c++14-lang</literal> if the port needs a
      C++14-capable compiler, <literal>c++11-lang</literal>
      if the port needs a C++11-capable compiler,
      <literal>gcc-c++11-lib</literal> if the
      port needs the <command>g++</command> compiler with a C++11
      library, or <literal>c++11-lib</literal> if the port needs
      a C++11-ready standard library.  If the port needs a compiler
      understanding C++0X, C11, OpenMP, or nested functions,
      the corresponding parameters should be used.</para>

    <para>Use
      <literal>features</literal> to request a list of features
      supported by the default compiler.  After including
      <filename>bsd.port.pre.mk</filename> the port can inspect the
      results using these variables:</para>

    <itemizedlist>
      <listitem>
	<para><varname>COMPILER_TYPE</varname>: the default compiler
	  on the system, either gcc or clang</para>
      </listitem>

      <listitem>
	<para><varname>ALT_COMPILER_TYPE</varname>: the alternative
	  compiler on the system, either gcc or clang.  Only set if
	  two compilers are present in the base system.</para>
      </listitem>

      <listitem>
	<para><varname>COMPILER_VERSION</varname>: the first two
	  digits of the version of the default compiler.</para>
      </listitem>

      <listitem>
	<para><varname>ALT_COMPILER_VERSION</varname>: the first two
	  digits of the version of the alternative compiler, if
	  present.</para>
      </listitem>

      <listitem>
	<para><varname>CHOSEN_COMPILER_TYPE</varname>: the chosen
	  compiler, either gcc or clang</para>
      </listitem>

      <listitem>
	<para><varname>COMPILER_FEATURES</varname>: the features
	  supported by the default compiler.  It currently lists the
	  C++ library.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="uses-cpe">
    <title><literal>cpe</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Include Common Platform Enumeration
      (<acronym>CPE</acronym>) information in package manifest as a
      <acronym>CPE</acronym> 2.3 formatted string.  See the <link
	xlink:href="http://scap.nist.gov/specifications/cpe/"><acronym>CPE</acronym>
	specification</link> for details.  To add
      <acronym>CPE</acronym> information to a port, follow these
      steps:</para>

    <procedure>
      <step>
	<para>Search for the official CPE entry for the software
	  product either by using the NVD's <link
	    xlink:href="http://web.nvd.nist.gov/view/cpe/search"><acronym>CPE</acronym>
	    search engine</link> or in the <link
	    xlink:href="http://static.nvd.nist.gov/feeds/xml/cpe/dictionary/official-cpe-dictionary_v2.3.xml">official
	    <acronym>CPE</acronym> dictionary</link> (warning, very
	  large <acronym>XML</acronym> file).  <emphasis>Do not ever
	    make up <acronym>CPE</acronym> data.</emphasis></para>
      </step>

      <step>
	<para>Add <literal>cpe</literal> to <varname>USES</varname>
	  and compare the result of <command>make -V CPE_STR</command>
	  to the <acronym>CPE</acronym> dictionary entry.  Continue one
	  step at a time until <command>make -V CPE_STR</command> is
	  correct.</para>
      </step>

      <step>
	<para>If the product name (second field, defaults to
	  <varname>PORTNAME</varname>) is incorrect, define
	  <varname>CPE_PRODUCT</varname>.</para>
      </step>

      <step>
	<para>If the vendor name (first field, defaults to
	  <varname>CPE_PRODUCT</varname>) is incorrect, define
	  <varname>CPE_VENDOR</varname>.</para>
      </step>

      <step>
	<para>If the version field (third field, defaults to
	  <varname>PORTVERSION</varname>) is incorrect, define
	  <varname>CPE_VERSION</varname>.</para>
      </step>

      <step>
	<para>If the update field (fourth field, defaults to empty) is
	  incorrect, define <varname>CPE_UPDATE</varname>.</para>
      </step>

      <step>
	<para>If it is still not correct, check
	  <filename>Mk/Uses/cpe.mk</filename> for additional details,
	  or contact the &a.ports-secteam;.</para>
      </step>

      <step>
	<para>Derive as much as possible of the <acronym>CPE</acronym>
	  name from existing variables such as
	  <varname>PORTNAME</varname> and
	  <varname>PORTVERSION</varname>.  Use variable modifiers to
	  extract the relevant portions from these variables rather
	  than hardcoding the name.</para>
      </step>

      <step>
	<para><emphasis>Always</emphasis> run <command>make -V
	    CPE_STR</command> and check the output before committing
	  anything that changes <varname>PORTNAME</varname> or
	  <varname>PORTVERSION</varname> or any other variable which
	  is used to derive <varname>CPE_STR</varname>.</para>
      </step>
    </procedure>
  </sect1>

  <sect1 xml:id="uses-cran">
    <title><literal>cran</literal></title>

    <para>Possible arguments: (none),
      <literal>auto-plist</literal>,
      <literal>compiles</literal></para>

    <para>Uses the Comprehensive R Archive Network.  Specify
      <varname>auto-plist</varname> to automatically generate
      <filename>pkg-plist</filename>.  Specify
      <literal>compiles</literal> if the port has code that need to be
      compiled.</para>
  </sect1>

  <sect1 xml:id="uses-desktop-file-utils">
    <title><literal>desktop-file-utils</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Uses <application>update-desktop-database</application> from
      <package role="port">devel/desktop-file-utils</package>.  An
      extra post-install step will be run without interfering with any
      post-install steps already in the port
      <filename>Makefile</filename>.  A line with <link
	linkend="plist-keywords-desktop-file-utils"><literal>@desktop-file-utils</literal></link>
      will be added to the plist.</para>
  </sect1>

  <sect1 xml:id="uses-desthack">
    <title><literal>desthack</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Changes the behavior of GNU configure to properly support
      <varname>DESTDIR</varname> in case the original software does
      not.</para>
  </sect1>

  <sect1 xml:id="uses-display">
    <title><literal>display</literal></title>

    <para>Possible arguments: (none),
      <replaceable>ARGS</replaceable></para>

    <para>Set up a virtual display environment.  If the environment
      variable <varname>DISPLAY</varname> is not set, then
      <application>Xvfb</application> is added as a build dependency,
      and <varname>CONFIGURE_ENV</varname> is extended with the port
      number of the currently running instance of
      <application>Xvfb</application>.  The
      <replaceable>ARGS</replaceable>
      parameter defaults to <literal>install</literal> and controls
      the phase around which to start and stop the virtual
      display.</para>
  </sect1>

  <sect1 xml:id="uses-dos2unix">
    <title><literal>dos2unix</literal></title>

    <para>Possible arguments: (none)</para>

    <para>The port has files with line endings in
      <acronym>DOS</acronym> format which need to be converted.
      Several variables can be set to control which files will be
      converted.  The default is to convert <emphasis>all</emphasis>
      files, including binaries.  See <xref
	linkend="slow-patch-automatic-replacements"/> for
      examples.</para>

    <itemizedlist>
      <listitem>
	<para><varname>DOS2UNIX_REGEX</varname>: match file names
	  based on a regular expression.</para>
      </listitem>

      <listitem>
	<para><varname>DOS2UNIX_FILES</varname>: match literal file
	  names.</para>
      </listitem>

      <listitem>
	<para><varname>DOS2UNIX_GLOB</varname>: match file names based
	  on a glob pattern.</para>
      </listitem>

      <listitem>
	<para><varname>DOS2UNIX_WRKSRC</varname>: the directory from
	  which to start the conversions.  Defaults to
	  <literal>${WRKSRC}</literal>.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="uses-drupal">
    <title><literal>drupal</literal></title>

    <para>Possible arguments:
      <literal>7</literal>, <literal>module</literal>,
      <literal>theme</literal></para>

    <para>Automate installation of a port that is a
      <application>Drupal</application> theme or module.  Use with the
      version of Drupal that the port is expecting.  For example,
      <literal>USES=drupal:7,module</literal> says that this port
      creates a Drupal 6 module.  A Drupal 7 theme can be specified
      with <literal>USES=drupal:7,theme</literal>.</para>
  </sect1>

  <sect1 xml:id="uses-fakeroot">
    <title><literal>fakeroot</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Changes some default behavior of build systems to allow
      installing as a user.  See <link
	xlink:href="https://wiki.debian.org/FakeRoot"/> for more
      information on <command>fakeroot</command>.</para>
  </sect1>

  <sect1 xml:id="uses-fam">
    <title><literal>fam</literal></title>

    <para>Possible arguments: (none), <literal>fam</literal>,
      <literal>gamin</literal></para>

    <para>Uses a File Alteration Monitor as a library dependency,
      either <package role="port">devel/fam</package> or <package
	role="port">devel/gamin</package>.  End users can set
      WITH_FAM_SYSTEM to specify their preference.</para>
  </sect1>

  <sect1 xml:id="uses-firebird">
    <title><literal>firebird</literal></title>

    <para>Possible arguments: (none), <literal>25</literal></para>

    <para>Add a dependency to the client library of the Firebird
      database.</para>
  </sect1>

  <sect1 xml:id="uses-fonts">
    <title><literal>fonts</literal></title>

    <para>Possible arguments: (none), <literal>fc</literal>,
      <literal>fcfontsdir</literal> (default),
      <literal>fontsdir</literal>, <literal>none</literal></para>

    <para>Adds a runtime dependency on tools needed to register fonts.
      Depending on the argument, add a <literal><link
	  linkend="plist-keywords-fc">@fc</link> ${FONTSDIR}</literal>
      line, <literal><link
	  linkend="plist-keywords-fcfontsdir">@fcfontsdir</link>
	${FONTSDIR}</literal> line, <literal><link
	  linkend="plist-keywords-fontsdir">@fontsdir</link>
	${FONTSDIR}</literal> line, or no line if the argument is
      <literal>none</literal>, to the plist.
      <varname>FONTSDIR</varname> defaults to
      <filename>${PREFIX}/share/fonts/${FONTNAME}</filename> and
      <varname>FONTNAME</varname> to <literal>${PORTNAME}</literal>.
      Add <literal>FONTSDIR</literal> to <varname>PLIST_SUB</varname>
      and <varname>SUB_LIST</varname></para>
  </sect1>

  <sect1 xml:id="uses-fortran">
    <title><literal>fortran</literal></title>

    <para>Possible arguments: <literal>gcc</literal> (default)</para>

    <para>Uses the GNU Fortran compiler.</para>
  </sect1>

  <sect1 xml:id="uses-fuse">
    <title><literal>fuse</literal></title>

    <para>Possible arguments: <literal>2</literal> (default),
      <literal>3</literal></para>

    <para>The port will depend on the FUSE library and handle the
      dependency on the kernel module depending on the version of
      &os;.</para>
  </sect1>

  <sect1 xml:id="uses-gem">
    <title><literal>gem</literal></title>

    <para>Possible arguments: (none),
      <literal>noautoplist</literal></para>

    <para>Handle building with <application>RubyGems</application>.
      If <literal>noautoplist</literal> is used, the packing list is
      not generated automatically.</para>
  </sect1>

  <sect1 xml:id="uses-gettext">
    <title><literal>gettext</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Deprecated.  Will include both <link
	linkend="uses-gettext-runtime"><literal>gettext-runtime</literal></link>
      and <link
	linkend="uses-gettext-tools"><literal>gettext-tools</literal></link>.</para>
  </sect1>

  <sect1 xml:id="uses-gettext-runtime">
    <title><literal>gettext-runtime</literal></title>

    <para>Possible arguments: (none), <literal>lib</literal>
      (default), <literal>build</literal>,
      <literal>run</literal></para>

    <para>Uses <package role="port">devel/gettext-runtime</package>.
      By default, with no arguments or with the <literal>lib</literal>
      argument, implies a library dependency on
      <filename>libintl.so</filename>.  <literal>build</literal> and
      <literal>run</literal> implies, respectively a build-time and a
      run-time dependency on <filename>gettext</filename>.</para>
  </sect1>

  <sect1 xml:id="uses-gettext-tools">
    <title><literal>gettext-tools</literal></title>

    <para>Possible arguments: (none), <literal>build</literal>
      (default), <literal>run</literal></para>

    <para>Uses <package role="port">devel/gettext-tools</package>.  By
      default, with no argument, or with the <literal>build</literal>
      argument, a build time dependency on <filename>msgfmt</filename>
      is registered.  With the <literal>run</literal> argument, a
      run-time dependency is registered.</para>
  </sect1>

  <sect1 xml:id="uses-ghostscript">
    <title><literal>ghostscript</literal></title>

    <para>Possible arguments: <replaceable>X</replaceable>,
      <literal>build</literal>, <literal>run</literal>,
      <literal>nox11</literal></para>

    <para>A specific version <replaceable>X</replaceable> can be used.
      Possible versions are <literal>7</literal>,
      <literal>8</literal>, <literal>9</literal>, and
      <literal>agpl</literal> (default).  <literal>nox11</literal>
      indicates
      that the <literal>-nox11</literal> version of the port is
      required.  <literal>build</literal> and <literal>run</literal>
      add build- and run-time dependencies on
      <application>Ghostscript</application>.  The default is both
      build- and run-time dependencies.</para>
  </sect1>

  <sect1 xml:id="uses-gl">
    <title><literal>gl</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Provides an easy way to depend on
      <application>GL</application> components.  The components
      should be listed in <varname>USE_GL</varname>.  The available
      components are:</para>

    <variablelist>
      <varlistentry>
	<term><literal>egl</literal></term>

	<listitem>
	  <para>add a library dependency on <filename>libEGL.so</filename>
	    from <package role="port">graphics/mesa-libs</package></para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>gbm</literal></term>

	<listitem>
	  <para>Add a library dependency on <filename>libgbm.so</filename>
	    from <package role="port">graphics/mesa-libs</package></para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>gl</literal></term>

	<listitem>
	  <para>Add a library dependency on <filename>libGL.so</filename>
	    from <package role="port">graphics/mesa-libs</package></para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>glesv2</literal></term>

	<listitem>
	  <para>Add a library dependency on <filename>libGLESv2.so</filename>
	    from <package role="port">graphics/mesa-libs</package></para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>glew</literal></term>

	<listitem>
	  <para>Add a library dependency on <filename>libGLEW.so</filename>
	    from <package role="port">graphics/glew</package></para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>glu</literal></term>

	<listitem>
	  <para>Add a library dependency on <filename>libGLU.so</filename>
	    from <package role="port">graphics/libGLU</package></para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>glut</literal></term>

	<listitem>
	  <para>Add a library dependency on <filename>libglut.so</filename>
	    from <package role="port">graphics/freeglut</package></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 xml:id="uses-gmake">
    <title><literal>gmake</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Uses <package role="port">devel/gmake</package> as a
      build-time dependency and sets up the environment to use
      <command>gmake</command> as the default <command>make</command>
      for the build.</para>
  </sect1>

  <sect1 xml:id="uses-gnome">
    <title><literal>gnome</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Provides an easy way to depend on
      <application>GNOME</application> components.  The components
      should be listed in <varname>USE_GNOME</varname>.  The available
      components are:</para>

    <!--
      From any port with USES=gnome, run:
      $ make -V '${_USE_GNOME_ALL:O:u:C,.*,<listitem> <para><literal>&</literal></para> </listitem> ,}'
      replace all spaces with new lines and reindent.
      -->
    <itemizedlist>
      <listitem>
	<para><literal>atk</literal></para>
      </listitem>

      <listitem>
	<para><literal>atkmm</literal></para>
      </listitem>

      <listitem>
	<para><literal>cairo</literal></para>
      </listitem>

      <listitem>
	<para><literal>cairomm</literal></para>
      </listitem>

      <listitem>
	<para><literal>dconf</literal></para>
      </listitem>

      <listitem>
	<para><literal>esound</literal></para>
      </listitem>

      <listitem>
	<para><literal>evolutiondataserver3</literal></para>
      </listitem>

      <listitem>
	<para><literal>gconf2</literal></para>
      </listitem>

      <listitem>
	<para><literal>gconfmm26</literal></para>
      </listitem>

      <listitem>
	<para><literal>gdkpixbuf</literal></para>
      </listitem>

      <listitem>
	<para><literal>gdkpixbuf2</literal></para>
      </listitem>

      <listitem>
	<para><literal>glib12</literal></para>
      </listitem>

      <listitem>
	<para><literal>glib20</literal></para>
      </listitem>

      <listitem>
	<para><literal>glibmm</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnomecontrolcenter3</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnomedesktop3</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnomedocutils</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnomemenus3</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnomemimedata</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnomeprefix</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnomesharp20</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnomevfs2</literal></para>
      </listitem>

      <listitem>
	<para><literal>gsound</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtk-update-icon-cache</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtk12</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtk20</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtk30</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtkhtml3</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtkhtml4</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtkmm20</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtkmm24</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtkmm30</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtksharp20</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtksourceview</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtksourceview2</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtksourceview3</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtksourceviewmm3</literal></para>
      </listitem>

      <listitem>
	<para><literal>gvfs</literal></para>
      </listitem>

      <listitem>
	<para><literal>intlhack</literal></para>
      </listitem>

      <listitem>
	<para><literal>intltool</literal></para>
      </listitem>

      <listitem>
	<para><literal>introspection</literal></para>
      </listitem>

      <listitem>
	<para><literal>libartlgpl2</literal></para>
      </listitem>

      <listitem>
	<para><literal>libbonobo</literal></para>
      </listitem>

      <listitem>
	<para><literal>libbonoboui</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgda5</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgda5-ui</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgdamm5</literal></para>
      </listitem>

      <listitem>
	<para><literal>libglade2</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgnome</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgnomecanvas</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgnomekbd</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgnomeprint</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgnomeprintui</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgnomeui</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgsf</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgtkhtml</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgtksourceviewmm</literal></para>
      </listitem>

      <listitem>
	<para><literal>libidl</literal></para>
      </listitem>

      <listitem>
	<para><literal>librsvg2</literal></para>
      </listitem>

      <listitem>
	<para><literal>libsigc++12</literal></para>
      </listitem>

      <listitem>
	<para><literal>libsigc++20</literal></para>
      </listitem>

      <listitem>
	<para><literal>libwnck</literal></para>
      </listitem>

      <listitem>
	<para><literal>libwnck3</literal></para>
      </listitem>

      <listitem>
	<para><literal>libxml++26</literal></para>
      </listitem>

      <listitem>
	<para><literal>libxml2</literal></para>
      </listitem>

      <listitem>
	<para><literal>libxslt</literal></para>
      </listitem>

      <listitem>
	<para><literal>metacity</literal></para>
      </listitem>

      <listitem>
	<para><literal>nautilus3</literal></para>
      </listitem>

      <listitem>
	<para><literal>orbit2</literal></para>
      </listitem>

      <listitem>
	<para><literal>pango</literal></para>
      </listitem>

      <listitem>
	<para><literal>pangomm</literal></para>
      </listitem>

      <listitem>
	<para><literal>pangox-compat</literal></para>
      </listitem>

      <listitem>
	<para><literal>py3gobject3</literal></para>
      </listitem>

      <listitem>
	<para><literal>pygnome2</literal></para>
      </listitem>

      <listitem>
	<para><literal>pygobject</literal></para>
      </listitem>

      <listitem>
	<para><literal>pygobject3</literal></para>
      </listitem>

      <listitem>
	<para><literal>pygtk2</literal></para>
      </listitem>

      <listitem>
	<para><literal>pygtksourceview</literal></para>
      </listitem>

      <listitem>
	<para><literal>referencehack</literal></para>
      </listitem>

      <listitem>
	<para><literal>vte</literal></para>
      </listitem>

      <listitem>
	<para><literal>vte3</literal></para>
      </listitem>
    </itemizedlist>

    <para>The default dependency is build- and run-time, it can be
      changed with <literal>:build</literal> or
      <literal>:run</literal>.  For example:</para>

    <programlisting>USES=		gnome
USE_GNOME=	gnomemenus3:build intlhack</programlisting>

    <para>See <xref linkend="using-gnome"/> for more
      information.</para>
  </sect1>

  <sect1 xml:id="uses-go">
    <title><literal>go</literal></title>

    <important>
      <para>Ports should not be created for Go libs, see
	<xref linkend="go-libs"/> for more information.</para>
    </important>

    <para>Possible arguments: (none), <literal>modules</literal>,
      <literal>no_targets</literal>, <literal>run</literal></para>

    <para>Sets default values and targets used to build
      <application>Go</application> software.  A build dependency
      on the Go compiler port selected via <varname>GO_PORT</varname>
      is added.  By default the build is performed in GOPATH mode.
      If Go software uses modules, the modules-aware mode can be
      switched on with <literal>modules</literal> argument.
      <literal>no_targets</literal> will setup build environment like
      <varname>GO_ENV</varname>, <varname>GO_BUILDFLAGS</varname> but
      skip creating <buildtarget>post-extract</buildtarget> and
      <buildtarget>do-{build,install,test}</buildtarget> targets.
      <literal>run</literal> will also add a run dependency on
      what is in <varname>GO_PORT</varname>.</para>

    <para>The build process is controlled by several variables:</para>

    <variablelist>
      <varlistentry>
	<term><varname>GO_PKGNAME</varname></term>

	<listitem>
	  <para>The name of the <application>Go</application> package
	    when building in GOPATH mode.  This is the directory that
	    will be created in <literal>${GOPATH}/src</literal>.  If
	    not set explicitly and <varname>GH_SUBDIR</varname> or
	    <varname>GL_SUBDIR</varname> is present,
	    <varname>GO_PKGNAME</varname> will be inferred from it.
	    It is not needed when building in modules-aware
	    mode.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>GO_TARGET</varname></term>

	<listitem>
	  <para>The packages to build.  The default
	    value is <varname>${GO_PKGNAME}</varname>.
	    <varname>GO_TARGET</varname> can also be a tuple in the
	    form <literal>package:path</literal> where path can be
	    either a simple filename or a full path starting with
	    <literal>${PREFIX}</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>GO_TESTTARGET</varname></term>

	<listitem>
	  <para>The packages to test.  The default
	    value is <literal>./...</literal> (the current package
	    and all subpackages).</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>CGO_CFLAGS</varname></term>

	<listitem>
	  <para>Additional <varname>CFLAGS</varname> values to be
	    passed to the <application>C</application> compiler by
	    <command>go</command>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>CGO_LDFLAGS</varname></term>

	<listitem>
	  <para>Additional <varname>LDFLAGS</varname> values to be
	    passed to the <application>C</application> compiler by
	    <command>go</command>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>GO_BUILDFLAGS</varname></term>

	<listitem>
	  <para>Additional build arguments to be passed to
	    <command>go build</command>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>GO_TESTFLAGS</varname></term>

	<listitem>
	  <para>Additional build arguments to be passed to
	    <command>go test</command>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>GO_PORT</varname></term>

	<listitem>
	  <para>The Go compiler port to use.  By default this is
	    <package role="port">lang/go</package> but can be set
	    to <package role="port">lang/go-devel</package> in
	    <literal>make.conf</literal> for testing with future Go
	    versions.</para>

	  <warning>
	    <para>This variable must not be set by individual
	      ports!</para>
	  </warning>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>See <xref linkend="using-go" /> for usage examples.</para>
  </sect1>

  <sect1 xml:id="uses-gperf">
    <title><literal>gperf</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Add a buildtime dependency on <package
	role="port">devel/gperf</package> if <command>gperf</command>
      is not present in the base system.</para>
  </sect1>

  <sect1 xml:id="uses-grantlee">
    <title><literal>grantlee</literal></title>

    <para>Possible arguments: <literal>5</literal>,
      <literal>selfbuild</literal></para>

    <para>Handle dependency on <application>Grantlee</application>.
      Specify <literal>5</literal> to depend on the
      <application>Qt5</application> based version, <package
	role="port">devel/grantlee5</package>.
      <literal>selfbuild</literal> is used internally by <package
	role="port">devel/grantlee5</package> to get their versions
      numbers.</para>
  </sect1>

  <sect1 xml:id="uses-groff">
    <title><literal>groff</literal></title>

    <para>Possible arguments: <literal>build</literal>,
      <literal>run</literal>, <literal>both</literal></para>

    <para>Registers a dependency on <package
	role="port">textproc/groff</package> if not present in the
      base system.</para>
  </sect1>

  <sect1 xml:id="uses-gssapi">
    <title><literal>gssapi</literal></title>

    <para>Possible arguments: (none), <literal>base</literal>
      (default), <literal>heimdal</literal>, <literal>mit</literal>,
      <literal>flags</literal>, <literal>bootstrap</literal></para>

    <para>Handle dependencies needed by consumers of the
      <acronym>GSS-API</acronym>.  Only libraries that provide the
      <application>Kerberos</application> mechanism are available.  By
      default, or set to <literal>base</literal>, the
      <acronym>GSS-API</acronym> library from the base system is used.
      Can also be set to <literal>heimdal</literal> to use <package
	role="port">security/heimdal</package>, or
      <literal>mit</literal> to use <package
	role="port">security/krb5</package>.</para>

    <para>When the local <application>Kerberos</application>
      installation is not in <varname>LOCALBASE</varname>, set
      <varname>HEIMDAL_HOME</varname> (for <literal>heimdal</literal>)
      or <varname>KRB5_HOME</varname> (for <literal>krb5</literal>) to
      the location of the <application>Kerberos</application>
      installation.</para>

    <para>These variables are exported for the ports to use:</para>

    <itemizedlist>
      <listitem>
	<para><varname>GSSAPIBASEDIR</varname></para>
      </listitem>

      <listitem>
	<para><varname>GSSAPICPPFLAGS</varname></para>
      </listitem>

      <listitem>
	<para><varname>GSSAPIINCDIR</varname></para>
      </listitem>

      <listitem>
	<para><varname>GSSAPILDFLAGS</varname></para>
      </listitem>

      <listitem>
	<para><varname>GSSAPILIBDIR</varname></para>
      </listitem>

      <listitem>
	<para><varname>GSSAPILIBS</varname></para>
      </listitem>

      <listitem>
	<para><varname>GSSAPI_CONFIGURE_ARGS</varname></para>
      </listitem>
    </itemizedlist>

    <para>The <literal>flags</literal> option can be given alongside
      <literal>base</literal>, <literal>heimdal</literal>, or
      <literal>mit</literal> to automatically add
      <varname>GSSAPICPPFLAGS</varname>,
      <varname>GSSAPILDFLAGS</varname>, and
      <varname>GSSAPILIBS</varname> to <varname>CFLAGS</varname>,
      <varname>LDFLAGS</varname>, and <varname>LDADD</varname>,
      respectively.  For example, use
      <literal>base,flags</literal>.</para>

    <para>The <literal>bootstrap</literal> option is a special prefix
      only for use by <package role="port">security/krb5</package> and
      <package role="port">security/heimdal</package>.  For example,
      use <literal>bootstrap,mit</literal>.</para>

    <example xml:id="uses-gssapi-ex1">
      <title>Typical Use</title>

      <programlisting>OPTIONS_SINGLE=	GSSAPI
OPTIONS_SINGLE_GSSAPI=	GSSAPI_BASE GSSAPI_HEIMDAL GSSAPI_MIT GSSAPI_NONE

GSSAPI_BASE_USES=	gssapi
GSSAPI_BASE_CONFIGURE_ON=	--with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS}
GSSAPI_HEIMDAL_USES=	gssapi:heimdal
GSSAPI_HEIMDAL_CONFIGURE_ON=	--with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS}
GSSAPI_MIT_USES=	gssapi:mit
GSSAPI_MIT_CONFIGURE_ON=	--with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS}
GSSAPI_NONE_CONFIGURE_ON=	--without-gssapi</programlisting>
    </example>
  </sect1>

  <sect1 xml:id="uses-horde">
    <title><literal>horde</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Add buildtime and runtime dependencies on <package
	role="port">devel/pear-channel-horde</package>.  Other
      <application>Horde</application> dependencies can be added
      with <varname>USE_HORDE_BUILD</varname> and
      <varname>USE_HORDE_RUN</varname>.  See <xref
	linkend="php-horde"/> for more information.</para>
  </sect1>

  <sect1 xml:id="uses-iconv">
    <title><literal>iconv</literal></title>

    <para>Possible arguments: (none), <literal>lib</literal>,
      <literal>build</literal>,
      <literal>patch</literal>, <literal>translit</literal>,
      <literal>wchar_t</literal></para>

    <para>Uses <command>iconv</command> functions, either from the
      port <package role="port">converters/libiconv</package> as a
      build-time and run-time dependency, or from the base system on
      10-CURRENT after a native <command>iconv</command> was committed
      in <revnumber>254273</revnumber>.  By default, with no arguments
      or with the <literal>lib</literal> argument, implies
      <command>iconv</command> with build-time and run-time
      dependencies.  <literal>build</literal> implies a build-time
      dependency, and <literal>patch</literal> implies a patch-time
      dependency.  If the port uses the <literal>WCHAR_T</literal> or
      <literal>//TRANSLIT</literal> iconv extensions, add the relevant
      arguments so that the correct iconv is used.  For more
      information see <xref linkend="using-iconv"/>.</para>
  </sect1>

  <sect1 xml:id="uses-imake">
    <title><literal>imake</literal></title>

    <para>Possible arguments: (none), <literal>env</literal>,
      <literal>notall</literal>, <literal>noman</literal></para>

    <para>Add <package role="port">devel/imake</package> as a
      build-time dependency and run <command>xmkmf -a</command> during
      the <buildtarget>configure</buildtarget> stage.  If the
      <literal>env</literal> argument is given, the
      <buildtarget>configure</buildtarget> target is not set.  If the
      <option>-a</option> flag is a problem for the port, add the
      <literal>notall</literal> argument.  If <command>xmkmf</command>
      does not generate a <buildtarget>install.man</buildtarget>
      target, add the <literal>noman</literal> argument.</para>
  </sect1>

  <sect1 xml:id="uses-kde">
    <title><literal>kde</literal></title>

    <para>Possible arguments: <literal>5</literal></para>

    <para>Add dependency on <application>KDE</application> components.
      See <xref linkend="using-kde"/> for more information.</para>
  </sect1>

  <sect1 xml:id="uses-kmod">
    <title><literal>kmod</literal></title>

    <para>Possible arguments: (none), <literal>debug</literal></para>

    <para>Fills in the boilerplate for kernel module ports,
      currently:</para>

    <itemizedlist>
      <listitem>
	<para>Add <literal>kld</literal> to
	  <varname>CATEGORIES</varname>.</para>
      </listitem>

      <listitem>
	<para>Set <varname>SSP_UNSAFE</varname>.</para>
      </listitem>

      <listitem>
	<para>Set <varname>IGNORE</varname> if the kernel sources are
	  not found in <varname>SRC_BASE</varname>.</para>
      </listitem>

      <listitem>
	<para>Define <varname>KMODDIR</varname> to
	  <filename>/boot/modules</filename> by default, add it to
	  <varname>PLIST_SUB</varname> and
	  <varname>MAKE_ENV</varname>, and create it upon
	  installation.  If <varname>KMODDIR</varname> is set to
	  <filename>/boot/kernel</filename>, it will be rewritten to
	  <filename>/boot/modules</filename>.  This prevents breaking
	  packages when upgrading the kernel due to
	  <filename>/boot/kernel</filename> being renamed to
	  <filename>/boot/kernel.old</filename> in the process.</para>
      </listitem>

      <listitem>
	<para>Handle cross-referencing kernel modules upon
	  installation and deinstallation, using <link
	    linkend="plist-keywords-kld"><literal>@kld</literal></link>.</para>
      </listitem>

      <listitem>
	<para>If the <literal>debug</literal> argument is given, the
	  port can install a debug version of the module into
	  <filename>KERN_DEBUGDIR</filename>/<filename>KMODDIR</filename>.
	  By default, <varname>KERN_DEBUGDIR</varname> is copied from
	  <varname>DEBUGDIR</varname> and set to
	  <filename>/usr/lib/debug</filename>.  The framework will
	  take care of creating and removing any required
	  directories.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="uses-lha">
    <title><literal>lha</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Set <varname>EXTRACT_SUFX</varname> to
      <literal>.lzh</literal></para>
  </sect1>

  <sect1 xml:id="uses-libarchive">
    <title><literal>libarchive</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Registers a dependency on <package
	role="port">archivers/libarchive</package>.  Any ports
      depending on <application>libarchive</application> must include
      <literal>USES=libarchive</literal>.</para>
  </sect1>

  <sect1 xml:id="uses-libedit">
    <title><literal>libedit</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Registers a dependency on <package
	role="port">devel/libedit</package>.  Any ports depending on
      <application>libedit</application> must include
      <literal>USES=libedit</literal>.</para>
  </sect1>

  <sect1 xml:id="uses-libtool">
    <title><literal>libtool</literal></title>

    <para>Possible arguments: (none), <literal>keepla</literal>,
      <literal>build</literal></para>

    <para>Patches <command>libtool</command> scripts.  This must be
      added to all ports that use <command>libtool</command>.  The
      <literal>keepla</literal> argument can be used to keep
      <filename>.la</filename> files.  Some ports do not ship with
      their own copy of libtool and need a build time dependency on
      <package role="port">devel/libtool</package>, use the
      <literal>:build</literal> argument to add such
      dependency.</para>
  </sect1>

  <sect1 xml:id="uses-linux">
    <title><literal>linux</literal></title>

    <para>Possible arguments: <literal>c6</literal>,
      <literal>c7</literal></para>

    <para>Ports <application>Linux</application> compatibility
      framework.  Specify <literal>c6</literal> to depend on
      <application>CentOS</application> 6 packags.  Specify
      <literal>c7</literal> to depend on
      <application>CentOS</application> 7 packages.  The available
      packages are:</para>

    <!--
    $ sed -ne 's/^linux_\(.*\)_DEP=.*/\1/p' Mk/Uses/linux.mk |sort -u|sed -e 's,.*,<listitem> <para><literal>&</literal></para> </listitem> ,'
    -->
    <itemizedlist>
      <listitem>
	<para><literal>allegro</literal></para>
      </listitem>

      <listitem>
	<para><literal>alsa-plugins-oss</literal></para>
      </listitem>

      <listitem>
	<para><literal>alsa-plugins-pulseaudio</literal></para>
      </listitem>

      <listitem>
	<para><literal>alsalib</literal></para>
      </listitem>

      <listitem>
	<para><literal>atk</literal></para>
      </listitem>

      <listitem>
	<para><literal>avahi-libs</literal></para>
      </listitem>

      <listitem>
	<para><literal>base</literal></para>
      </listitem>

      <listitem>
	<para><literal>cairo</literal></para>
      </listitem>

      <listitem>
	<para><literal>cups-libs</literal></para>
      </listitem>

      <listitem>
	<para><literal>curl</literal></para>
      </listitem>

      <listitem>
	<para><literal>cyrus-sasl2</literal></para>
      </listitem>

      <listitem>
	<para><literal>dbusglib</literal></para>
      </listitem>

      <listitem>
	<para><literal>dbuslibs</literal></para>
      </listitem>

      <listitem>
	<para><literal>devtools</literal></para>
      </listitem>

      <listitem>
	<para><literal>dri</literal></para>
      </listitem>

      <listitem>
	<para><literal>expat</literal></para>
      </listitem>

      <listitem>
	<para><literal>flac</literal></para>
      </listitem>

      <listitem>
	<para><literal>fontconfig</literal></para>
      </listitem>

      <listitem>
	<para><literal>gdkpixbuf2</literal></para>
      </listitem>

      <listitem>
	<para><literal>gnutls</literal></para>
      </listitem>

      <listitem>
	<para><literal>graphite2</literal></para>
      </listitem>

      <listitem>
	<para><literal>gtk2</literal></para>
      </listitem>

      <listitem>
	<para><literal>harfbuzz</literal></para>
      </listitem>

      <listitem>
	<para><literal>jasper</literal></para>
      </listitem>

      <listitem>
	<para><literal>jbigkit</literal></para>
      </listitem>

      <listitem>
	<para><literal>jpeg</literal></para>
      </listitem>

      <listitem>
	<para><literal>libasyncns</literal></para>
      </listitem>

      <listitem>
	<para><literal>libaudiofile</literal></para>
      </listitem>

      <listitem>
	<para><literal>libelf</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgcrypt</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgfortran</literal></para>
      </listitem>

      <listitem>
	<para><literal>libgpg-error</literal></para>
      </listitem>

      <listitem>
	<para><literal>libmng</literal></para>
      </listitem>

      <listitem>
	<para><literal>libogg</literal></para>
      </listitem>

      <listitem>
	<para><literal>libpciaccess</literal></para>
      </listitem>

      <listitem>
	<para><literal>libsndfile</literal></para>
      </listitem>

      <listitem>
	<para><literal>libsoup</literal></para>
      </listitem>

      <listitem>
	<para><literal>libssh2</literal></para>
      </listitem>

      <listitem>
	<para><literal>libtasn1</literal></para>
      </listitem>

      <listitem>
	<para><literal>libthai</literal></para>
      </listitem>

      <listitem>
	<para><literal>libtheora</literal></para>
      </listitem>

      <listitem>
	<para><literal>libv4l</literal></para>
      </listitem>

      <listitem>
	<para><literal>libvorbis</literal></para>
      </listitem>

      <listitem>
	<para><literal>libxml2</literal></para>
      </listitem>

      <listitem>
	<para><literal>mikmod</literal></para>
      </listitem>

      <listitem>
	<para><literal>naslibs</literal></para>
      </listitem>

      <listitem>
	<para><literal>ncurses-base</literal></para>
      </listitem>

      <listitem>
	<para><literal>nspr</literal></para>
      </listitem>

      <listitem>
	<para><literal>nss</literal></para>
      </listitem>

      <listitem>
	<para><literal>openal</literal></para>
      </listitem>

      <listitem>
	<para><literal>openal-soft</literal></para>
      </listitem>

      <listitem>
	<para><literal>openldap</literal></para>
      </listitem>

      <listitem>
	<para><literal>openmotif</literal></para>
      </listitem>

      <listitem>
	<para><literal>openssl</literal></para>
      </listitem>

      <listitem>
	<para><literal>pango</literal></para>
      </listitem>

      <listitem>
	<para><literal>pixman</literal></para>
      </listitem>

      <listitem>
	<para><literal>png</literal></para>
      </listitem>

      <listitem>
	<para><literal>pulseaudio-libs</literal></para>
      </listitem>

      <listitem>
	<para><literal>qt</literal></para>
      </listitem>

      <listitem>
	<para><literal>qt-x11</literal></para>
      </listitem>

      <listitem>
	<para><literal>qtwebkit</literal></para>
      </listitem>

      <listitem>
	<para><literal>scimlibs</literal></para>
      </listitem>

      <listitem>
	<para><literal>sdl12</literal></para>
      </listitem>

      <listitem>
	<para><literal>sdlimage</literal></para>
      </listitem>

      <listitem>
	<para><literal>sdlmixer</literal></para>
      </listitem>

      <listitem>
	<para><literal>sqlite3</literal></para>
      </listitem>

      <listitem>
	<para><literal>tcl85</literal></para>
      </listitem>

      <listitem>
	<para><literal>tcp_wrappers-libs</literal></para>
      </listitem>

      <listitem>
	<para><literal>tiff</literal></para>
      </listitem>

      <listitem>
	<para><literal>tk85</literal></para>
      </listitem>

      <listitem>
	<para><literal>ucl</literal></para>
      </listitem>

      <listitem>
	<para><literal>xorglibs</literal></para>
      </listitem>
    </itemizedlist>

  </sect1>

  <sect1 xml:id="uses-localbase">
    <title><literal>localbase</literal></title>

    <para>Possible arguments: (none),
      <literal>ldflags</literal></para>

    <para>Ensures that libraries from dependencies in
      <varname>LOCALBASE</varname> are used instead of the ones from
      the base system.  Specify <literal>ldflags</literal> to add
      <literal>-L${LOCALBASE}/lib</literal> to
      <varname>LDFLAGS</varname> instead of <varname>LIBS</varname>.
      Ports that depend on libraries that are also
      present in the base system should use this.  It is also used
      internally by a few other <varname>USES</varname>.</para>
  </sect1>

  <sect1 xml:id="uses-lua">
    <title><literal>lua</literal></title>

    <para>Possible arguments: (none),
      <literal><replaceable>XY</replaceable></literal>,
      <literal><replaceable>XY</replaceable>+</literal>,
      <literal>-<replaceable>XY</replaceable></literal>,
      <literal><replaceable>XY</replaceable>-<replaceable>ZA</replaceable></literal>,
      <literal>module</literal>, <literal>flavors</literal>,
      <literal>build</literal>, <literal>run</literal>,
      <literal>env</literal></para>

    <para>Adds a dependency on <application>Lua</application>.  By
      default this is a library dependency, unless overridden by the
      <literal>build</literal> and/or <literal>run</literal> option.
      The <literal>env</literal> option prevents the addition of any
      dependency, while still defining all the usual variables.</para>

    <para>The default version is set by the usual
      <literal>DEFAULT_VERSIONS</literal> mechanism, unless a version or
      range of versions is specified as an argument, for
      example, <literal>51</literal> or <literal>51-53</literal>.</para>

    <para>Applications using <application>Lua</application> are
      normally built for only a single <application>Lua</application>
      version.  However, library modules intended to be loaded by
      <application>Lua</application> code should use the
      <literal>module</literal> option to build with multiple
      flavors.</para>

    <para>For more information see <xref linkend="using-lua" />.</para>
  </sect1>

  <sect1 xml:id="uses-lxqt">
    <title><literal>lxqt</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Handle dependencies for the <application>LXQt Desktop
	Environment</application>.  Use <varname>USE_LXQT</varname> to
      select the components needed for the port.  See <xref
	linkend="using-lxqt"/> for more information.</para>
  </sect1>

  <sect1 xml:id="uses-makeinfo">
    <title><literal>makeinfo</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Add a build-time dependency on <command>makeinfo</command>
      if it is not present in the base system.</para>
  </sect1>

  <sect1 xml:id="uses-makeself">
    <title><literal>makeself</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Indicates that the distribution files are makeself archives
      and sets the appropriate dependencies.</para>
  </sect1>

  <sect1 xml:id="uses-mate">
    <title><literal>mate</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Provides an easy way to depend on
      <application>MATE</application> components.  The components
      should be listed in <varname>USE_MATE</varname>.  The available
      components are:</para>

    <itemizedlist>
      <listitem>
	<para><literal>autogen</literal></para>
      </listitem>

      <listitem>
	<para><literal>caja</literal></para>
      </listitem>

      <listitem>
	<para><literal>common</literal></para>
      </listitem>

      <listitem>
	<para><literal>controlcenter</literal></para>
      </listitem>

      <listitem>
	<para><literal>desktop</literal></para>
      </listitem>

      <listitem>
	<para><literal>dialogs</literal></para>
      </listitem>

      <listitem>
	<para><literal>docutils</literal></para>
      </listitem>

      <listitem>
	<para><literal>icontheme</literal></para>
      </listitem>

      <listitem>
	<para><literal>intlhack</literal></para>
      </listitem>

      <listitem>
	<para><literal>intltool</literal></para>
      </listitem>

      <listitem>
	<para><literal>libmatekbd</literal></para>
      </listitem>

      <listitem>
	<para><literal>libmateweather</literal></para>
      </listitem>

      <listitem>
	<para><literal>marco</literal></para>
      </listitem>

      <listitem>
	<para><literal>menus</literal></para>
      </listitem>

      <listitem>
	<para><literal>notificationdaemon</literal></para>
      </listitem>

      <listitem>
	<para><literal>panel</literal></para>
      </listitem>

      <listitem>
	<para><literal>pluma</literal></para>
      </listitem>

      <listitem>
	<para><literal>polkit</literal></para>
      </listitem>

      <listitem>
	<para><literal>session</literal></para>
      </listitem>

      <listitem>
	<para><literal>settingsdaemon</literal></para>
      </listitem>
    </itemizedlist>

    <para>The default dependency is build- and run-time, it can be
      changed with <literal>:build</literal> or
      <literal>:run</literal>.  For example:</para>

    <programlisting>USES=		mate
USE_MATE=	menus:build intlhack</programlisting>
  </sect1>

  <sect1 xml:id="uses-meson">
    <title><literal>meson</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Provide support for Meson based projects.  For more
      information see <xref linkend="using-meson" />.</para>
  </sect1>

  <sect1 xml:id="uses-metaport">
    <title><literal>metaport</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Sets the following variables to make it easier to create a
      metaport: <varname>MASTER_SITES</varname>,
      <varname>DISTFILES</varname>, <varname>EXTRACT_ONLY</varname>,
      <varname>NO_BUILD</varname>, <varname>NO_INSTALL</varname>,
      <varname>NO_MTREE</varname>, <varname>NO_ARCH</varname>.</para>
  </sect1>

  <sect1 xml:id="uses-mysql">
    <title><literal>mysql</literal></title>

    <para>Possible arguments: (none),
      <literal><replaceable>version</replaceable></literal>,
      <literal>client</literal> (default), <literal>server</literal>,
      <literal>embedded</literal></para>

    <para>Provide support for <application>MySQL</application>.  If no
      version is given, try to find the current installed version.
      Fall back to the default version, MySQL-5.6.  The possible
      versions are <literal>55</literal>, <literal>55m</literal>,
      <literal>55p</literal>, <literal>56</literal>,
      <literal>56p</literal>, <literal>56w</literal>,
      <literal>57</literal>, <literal>57p</literal>,
      <literal>80</literal>, <literal>100m</literal>,
      <literal>101m</literal>, and <literal>102m</literal>.  The
      <literal>m</literal> and <literal>p</literal> suffixes are for
      the <application>MariaDB</application> and
      <application>Percona</application> variants of
      <application>MySQL</application>.  <literal>server</literal> and
      <literal>embedded</literal> add a build- and run-time dependency
      on the <application>MySQL</application> server.  When using
      <literal>server</literal> or <literal>embedded</literal>, add
      <literal>client</literal> to also add a dependency on
      <filename>libmysqlclient.so</filename>.  A port can set
      <varname>IGNORE_WITH_MYSQL</varname> if some versions are not
      supported.</para>

    <para>The framework sets <varname>MYSQL_VER</varname> to the
      detected MySQL version.</para>
  </sect1>

  <sect1 xml:id="uses-mono">
    <title><literal>mono</literal></title>

    <para>Possible arguments: (none), <literal>nuget</literal></para>

    <para>Adds a dependency on the <application>Mono</application>
      (currently only C#) framework by setting the appropriate
      dependencies.</para>

    <para>Specify <literal>nuget</literal> when the port uses nuget
      packages.  <varname>NUGET_DEPENDS</varname> needs to be set with
      the names and versions of the nuget packages in the format
      <literal><replaceable>name</replaceable>=<replaceable>version</replaceable></literal>.
      An optional package origin can be added using
      <literal><replaceable>name</replaceable>=<replaceable>version</replaceable>:<replaceable>origin</replaceable></literal>.</para>

    <para>The helper target, <buildtarget>buildnuget</buildtarget>,
      will output the content of the <varname>NUGET_DEPENDS</varname>
      based on the provided
      <filename>packages.config</filename>.</para>
  </sect1>

  <sect1 xml:id="uses-motif">
    <title><literal>motif</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Uses <package role="port">x11-toolkits/open-motif</package>
      as a library dependency.  End users can set
      <varname>WANT_LESSTIF</varname> for the dependency to be on
      <package role="port">x11-toolkits/lesstif</package> instead of
      <package role="port">x11-toolkits/open-motif</package>.</para>
  </sect1>

  <sect1 xml:id="uses-ncurses">
    <title><literal>ncurses</literal></title>

    <para>Possible arguments: (none), <literal>base</literal>,
      <literal>port</literal></para>

    <para>Uses <application>ncurses</application>, and causes some
      useful variables to be set.</para>
  </sect1>

  <sect1 xml:id="uses-ninja">
    <title><literal>ninja</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Uses <application>ninja</application> to build the
      port.</para>
  </sect1>

  <sect1 xml:id="uses-objc">
    <title><literal>objc</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Add objective C dependencies (compiler, runtime library) if
      the base system does not support it.</para>
  </sect1>

  <sect1 xml:id="uses-openal">
    <title><literal>openal</literal></title>

    <para>Possible arguments: <literal>al</literal>,
      <literal>soft</literal> (default), <literal>si</literal>,
      <literal>alut</literal></para>

    <para>Uses <application>OpenAL</application>.  The backend can be
      specified, with the software implementation as the default.  The
      user can specify a preferred backend with
      <varname>WANT_OPENAL</varname>.  Valid values for this knob are
      <literal>soft</literal> (default) and
      <literal>si</literal>.</para>
  </sect1>

  <sect1 xml:id="uses-pathfix">
    <title><literal>pathfix</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Look for <filename>Makefile.in</filename> and
      <filename>configure</filename> in
      <varname>PATHFIX_WRKSRC</varname> (defaults to
      <varname>WRKSRC</varname>)
      and fix common paths to make sure they respect the &os;
      hierarchy.  For example, it fixes the installation directory
      of <command>pkgconfig</command>'s <filename>.pc</filename> files
      to <filename>${PREFIX}/libdata/pkgconfig</filename>.  If
      the port uses <literal>USES=autoreconf</literal>,
      <filename>Makefile.am</filename> will be added to
      <varname>PATHFIX_MAKEFILEIN</varname> automatically.</para>

    <para>If the port <link
	linkend="uses-cmake"><literal>USES=cmake</literal></link> it
      will look for <filename>CMakeLists.txt</filename> in
      <varname>PATHFIX_WRKSRC</varname>.  If needed, that default
      filename can be changed with
      <varname>PATHFIX_CMAKELISTSTXT</varname>.</para>
  </sect1>

  <sect1 xml:id="uses-pear">
    <title><literal>pear</literal></title>

    <para>Possible arguments: <literal>env</literal></para>

    <para>Adds a dependency on <package
	role="port">devel/pear</package>.  It will setup default
      behavior for software using the <application>PHP</application>
      Extension and Application Repository.  Using the
      <literal>env</literal> arguments only sets up the
      <application>PEAR</application> environment variables.  See
      <xref linkend="php-pear"/> for more information.</para>
  </sect1>

  <sect1 xml:id="uses-perl5">
    <title><literal>perl5</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Depends on <application>Perl</application>.  The
      configuration is done using <varname>USE_PERL5</varname>.</para>

    <para><varname>USE_PERL5</varname> can contain the phases in which
      to use <application>Perl</application>, can be
      <literal>extract</literal>, <literal>patch</literal>,
      <literal>build</literal>, <literal>run</literal>, or
      <literal>test</literal>.</para>

    <para><varname>USE_PERL5</varname> can also contain
      <literal>configure</literal>,
      <literal>modbuild</literal>, or <literal>modbuildtiny</literal>
      when <filename>Makefile.PL</filename>,
      <filename>Build.PL</filename>, or
      <application>Module::Build::Tiny</application>'s flavor of
      <filename>Build.PL</filename> is required.</para>

    <para><varname>USE_PERL5</varname> defaults to <literal>build
	run</literal>.  When using <literal>configure</literal>,
      <literal>modbuild</literal>, or <literal>modbuildtiny</literal>,
      <literal>build</literal> and <literal>run</literal> are
      implied.</para>

    <para>See <xref linkend="using-perl"/> for more
	information.</para>
  </sect1>

  <sect1 xml:id="uses-pgsql">
    <title><literal>pgsql</literal></title>

    <para>Possible arguments: (none),
      <literal><replaceable>X.Y</replaceable></literal>,
      <literal><replaceable>X.Y</replaceable>+</literal>,
      <literal><replaceable>X.Y</replaceable>-</literal>,
      <literal><replaceable>X.Y</replaceable>-<replaceable>Z.A</replaceable></literal></para>

    <para>Provide support for PostgreSQL.
      Port maintainer can set version required.
      Minimum and maximum versions or a range can be specified; for
      example, <literal>9.0-</literal>, <literal>8.4+</literal>,
      <literal>8.4-9.2.</literal></para>

    <para>By default, the added dependency will be the client, but if
      the port requires additional components, this can be done using
      <literal>WANT_PGSQL=<replaceable>component[:target]</replaceable></literal>;
      for example,
      <literal>WANT_PGSQL=server:configure pltcl plperl</literal>.
      The available components are:</para>

    <itemizedlist>
      <listitem>
	<para><literal>client</literal></para>
      </listitem>

      <listitem>
	<para><literal>contrib</literal></para>
      </listitem>

      <listitem>
	<para><literal>docs</literal></para>
      </listitem>

      <listitem>
	<para><literal>pgtcl</literal></para>
      </listitem>

      <listitem>
	<para><literal>plperl</literal></para>
      </listitem>

      <listitem>
	<para><literal>plpython</literal></para>
      </listitem>

      <listitem>
	<para><literal>pltcl</literal></para>
      </listitem>

      <listitem>
	<para><literal>server</literal></para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="uses-php">
    <title><literal>php</literal></title>

    <para>Possible arguments: (none), <literal>phpize</literal>,
      <literal>ext</literal>, <literal>zend</literal>,
      <literal>build</literal>, <literal>cli</literal>,
      <literal>cgi</literal>, <literal>mod</literal>,
      <literal>web</literal>, <literal>embed</literal>,
      <literal>pecl</literal>, <literal>flavors</literal>,
      <literal>noflavors</literal></para>

    <para>Provide support for <application>PHP</application>.  Add a
      runtime dependency on the default PHP version, <package
	role="port">lang/php56</package>.</para>

    <variablelist>
      <varlistentry>
	<term><literal>phpize</literal></term>
	<listitem>
	  <para>Use to build a <application>PHP</application>
	    extension.  Enables flavors.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>ext</literal></term>
	<listitem>
	  <para>Use to build, install and register a
	    <application>PHP</application> extension.  Enables
	    flavors.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>zend</literal></term>
	<listitem>
	  <para>Use to build, install and register a Zend
	    extension.  Enables flavors.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>build</literal></term>
	<listitem>
	  <para>Set <application>PHP</application> also as a
	    build-time dependency.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>cli</literal></term>
	<listitem>
	  <para>Needs the CLI version of
	    <application>PHP</application>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>cgi</literal></term>
	<listitem>
	  <para>Needs the CGI version of
	    <application>PHP</application>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>mod</literal></term>
	<listitem>
	  <para>Needs the <application>Apache</application> module for
	    <application>PHP</application>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>web</literal></term>
	<listitem>
	  <para>Needs the <application>Apache</application> module or
	    the <acronym>CGI</acronym> version of
	    <application>PHP</application>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>embed</literal></term>
	<listitem>
	  <para>Needs the embedded library version of
	    <application>PHP</application>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>pecl</literal></term>
	<listitem>
	  <para>Provide defaults for fetching
	    <application>PHP</application> extensions from the PECL
	    repository.  Enables flavors.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>flavors</literal></term>
	<listitem>
	  <para>Enable automatic <link
	      linkend="flavors-auto-php"><application>PHP</application>
	      flavors</link> generation.  Flavors will be generated
	    for all PHP versions, except the ones present in
	    <link linkend="uses-php-ignore"><varname>IGNORE_WITH_PHP</varname></link>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>noflavors</literal></term>
	<listitem>
	  <para>Disable automatic <application>PHP</application>
	    flavors generation.  <emphasis>Must only</emphasis> be
	    used with extensions provided by
	    <application>PHP</application> itself.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>Variables are used to specify which
      <application>PHP</application> modules are required, as well as
      which version of <application>PHP</application> are
      supported.</para>

    <variablelist>
      <varlistentry>
	<term><varname>USE_PHP</varname></term>
	<listitem>
	  <para>The list of required <application>PHP</application>
	    extensions at run-time.  Add <literal>:build</literal> to
	    the extension name to add a build-time dependency.
	    Example: <literal>pcre xml:build gettext</literal></para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="uses-php-ignore">
	<term><varname>IGNORE_WITH_PHP</varname></term>
	<listitem>
	  <para>The port does not work with
	    <application>PHP</application> of the given version.  For
	    possible values look at the content of
	    <varname>_ALL_PHP_VERSIONS</varname> in
	    <filename>Mk/Uses/php.mk</filename>.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>When building a <application>PHP</application> or
      <application>Zend</application> extension with
      <literal>:ext</literal> or <literal>:zend</literal>, these
      variables can be set:</para>

    <variablelist>
      <varlistentry>
	<term><varname>PHP_MODNAME</varname></term>
	<listitem>
	  <para>The name of the <application>PHP</application> or
	    <application>Zend</application> extension.  Default value
	    is <literal>${PORTNAME}</literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>PHP_HEADER_DIRS</varname></term>
	<listitem>
	  <para>A list of subdirectories from which to install header
	    files.  The framework will always install the header files
	    that are present in the same directory as the
	    extension.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>PHP_MOD_PRIO</varname></term>
	<listitem>
	  <para>The priority at which to load the extension.  It is a
	    number between <literal>00</literal> and
	    <literal>99</literal>.</para>

	  <para>For extensions that do not depend on any extension,
	    the priority is automatically set to
	    <literal>20</literal>, for extensions that depend on
	    another extension, the priority is automatically set to
	    <literal>30</literal>.  Some extensions may need to be
	    loaded before every other extension, for example <package
	      role="port">www/php56-opcache</package>.  Some may need
	    to be loaded after an extension with a priority of
	    <literal>30</literal>.  In that case, add
	    <literal>PHP_MOD_PRIO=<replaceable>XX</replaceable></literal>
	    in the port's Makefile.  For example:</para>

	  <programlisting>USES=		php:ext
USE_PHP=	wddx
PHP_MOD_PRIO=	40</programlisting>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>These variables are available to use in
      <varname>PKGNAMEPREFIX</varname> or
      <varname>PKGNAMESUFFIX</varname>:</para>

    <variablelist>
      <varlistentry>
	<term><varname>PHP_PKGNAMEPREFIX</varname></term>
	<listitem>
	  <para>Contains
	    <literal>php<replaceable>XY</replaceable>-</literal> where
	    <replaceable>XY</replaceable> is the current flavor's PHP
	    version.  Use with PHP extensions and modules.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>PHP_PKGNAMESUFFIX</varname></term>
	<listitem>
	  <para>Contains
	    <literal>-php<replaceable>XY</replaceable></literal> where
	    <replaceable>XY</replaceable> is the current flavor's PHP
	    version.  Use with PHP applications.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>PECL_PKGNAMEPREFIX</varname></term>
	<listitem>
	  <para>Contains
	    <literal>php<replaceable>XY</replaceable>-pecl-</literal>
	    where <replaceable>XY</replaceable> is the current
	    flavor's PHP version.  Use with
	    <application>PECL</application> modules.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <important>
      <para>With flavors, all PHP extensions, PECL extensions, PEAR
	modules <emphasis>must have</emphasis> a different package
	name, so they must all use one of these three variables  in
	their <varname>PKGNAMEPREFIX</varname> or
	<varname>PKGNAMESUFFIX</varname>.</para>
    </important>
  </sect1>

  <sect1 xml:id="uses-pkgconfig">
    <title><literal>pkgconfig</literal></title>

    <para>Possible arguments: (none), <literal>build</literal>
      (default), <literal>run</literal>,
      <literal>both</literal></para>

    <para>Uses <package role="port">devel/pkgconf</package>.  With no
      arguments or with the <literal>build</literal> argument, it
      implies <command>pkg-config</command> as a build-time
      dependency.  <literal>run</literal> implies a run-time
      dependency and <literal>both</literal> implies both run-time and
      build-time dependencies.</para>
  </sect1>

  <sect1 xml:id="uses-pure">
    <title><literal>pure</literal></title>

    <para>Possible arguments: (none), <literal>ffi</literal></para>

    <para>Uses <package role="port">lang/pure</package>.  Largely used
      for building related <application>pure</application> ports.
      With the <literal>ffi</literal> argument, it implies <package
	role="port">devel/pure-ffi</package> as a run-time
      dependency.</para>
  </sect1>

  <sect1 xml:id="uses-pyqt">
    <title><literal>pyqt</literal></title>

    <para>Possible arguments: (none), <literal>4</literal>,
      <literal>5</literal></para>

    <para>Uses <application>PyQt</application>.  If the port is part
      of PyQT itself, set <varname>PYQT_DIST</varname>.  Use
      <varname>USE_PYQT</varname> to select the components the port
      needs.  The available components are:</para>

    <itemizedlist>
      <listitem>
	<para><literal>core</literal></para>
      </listitem>

      <listitem>
	<para><literal>dbus</literal></para>
      </listitem>

      <listitem>
	<para><literal>dbussupport</literal></para>
      </listitem>

      <listitem>
	<para><literal>demo</literal></para>
      </listitem>

      <listitem>
	<para><literal>designer</literal></para>
      </listitem>

      <listitem>
	<para><literal>designerplugin</literal></para>
      </listitem>

      <listitem>
	<para><literal>doc</literal></para>
      </listitem>

      <listitem>
	<para><literal>gui</literal></para>
      </listitem>

      <listitem>
	<para><literal>multimedia</literal></para>
      </listitem>

      <listitem>
	<para><literal>network</literal></para>
      </listitem>

      <listitem>
	<para><literal>opengl</literal></para>
      </listitem>

      <listitem>
	<para><literal>qscintilla2</literal></para>
      </listitem>

      <listitem>
	<para><literal>sip</literal></para>
      </listitem>

      <listitem>
	<para><literal>sql</literal></para>
      </listitem>

      <listitem>
	<para><literal>svg</literal></para>
      </listitem>

      <listitem>
	<para><literal>test</literal></para>
      </listitem>

      <listitem>
	<para><literal>webkit</literal></para>
      </listitem>

      <listitem>
	<para><literal>xml</literal></para>
      </listitem>

      <listitem>
	<para><literal>xmlpatterns</literal></para>
      </listitem>
    </itemizedlist>

    <para>These components are only available with
      <application>PyQT4</application>:</para>

    <itemizedlist>
      <listitem>
	<para><literal>assistant</literal></para>
      </listitem>

      <listitem>
	<para><literal>declarative</literal></para>
      </listitem>

      <listitem>
	<para><literal>help</literal></para>
      </listitem>

      <listitem>
	<para><literal>phonon</literal></para>
      </listitem>

      <listitem>
	<para><literal>script</literal></para>
      </listitem>

      <listitem>
	<para><literal>scripttools</literal></para>
      </listitem>
    </itemizedlist>

    <para>These components are only available with
      <application>PyQT5</application>:</para>

    <itemizedlist>
      <listitem>
	<para><literal>multimediawidgets</literal></para>
      </listitem>

      <listitem>
	<para><literal>printsupport</literal></para>
      </listitem>

      <listitem>
	<para><literal>qml</literal></para>
      </listitem>

      <listitem>
	<para><literal>serialport</literal></para>
      </listitem>

      <listitem>
	<para><literal>webkitwidgets</literal></para>
      </listitem>

      <listitem>
	<para><literal>widgets</literal></para>
      </listitem>
    </itemizedlist>

    <para>The default dependency for each component is build- and
      run-time, to select only build or run, add
      <literal>_build</literal> or <literal>_run</literal> to the
      component name.  For example:</para>

    <programlisting>USES=		pyqt
USE_PYQT=	core doc_build designer_run</programlisting>
  </sect1>

  <sect1 xml:id="uses-python">
    <title><literal>python</literal></title>

    <para>Possible arguments: (none),
      <literal><replaceable>X.Y</replaceable></literal>,
      <literal><replaceable>X.Y+</replaceable></literal>,
      <literal><replaceable>-X.Y</replaceable></literal>,
      <literal><replaceable>X.Y-Z.A</replaceable></literal>,
      <literal>patch</literal>,
      <literal>build</literal>, <literal>run</literal>,
      <literal>test</literal></para>

    <para>Uses <application>Python</application>.  A supported version
      or version range can be specified.  If Python is only needed at
      build time, run time or for the tests, it can be set as a build,
      run or test dependency with <literal>build</literal>,
      <literal>run</literal>, or <literal>test</literal>.  If Python
      is also needed during the patch phase, use
      <literal>patch</literal>.  See
      <xref linkend="using-python"/> for more information.</para>

    <para><literal>PYTHON_NO_DEPENDS=yes</literal> can be used when
      the variables exported by the framework are needed but a
      dependency on <application>Python</application> is not.  It can
      happen when using with <link
	linkend="uses-shebangfix"><literal>USES=shebangfix</literal></link>,
      and the goal is only to fix the shebangs but not add a
      dependency on <application>Python</application>.</para>
  </sect1>

  <sect1 xml:id="uses-qmail">
    <title><literal>qmail</literal></title>

    <para>Possible arguments: (none), <literal>build</literal>,
      <literal>run</literal>, <literal>both</literal>,
      <literal>vars</literal></para>

    <para>Uses <package role="port">mail/qmail</package>.  With the
      <literal>build</literal> argument, it implies
      <command>qmail</command> as a build-time dependency.
      <literal>run</literal> implies a run-time dependency.  Using no
      argument or the <literal>both</literal> argument implies both
      run-time and build-time dependencies.  <literal>vars</literal>
      will only set QMAIL variables for the port to use.</para>
  </sect1>

  <sect1 xml:id="uses-qmake">
    <title><literal>qmake</literal></title>

    <para>Possible arguments: (none), <literal>norecursive</literal>,
      <literal>outsource</literal>, <literal>no_env</literal>,
      <literal>no_configure</literal></para>

    <para>Uses <application>QMake</application> for configuring.  For
      more information see <xref linkend="using-qmake"/>.</para>
  </sect1>

  <sect1 xml:id="uses-qt">
    <title><literal>qt</literal></title>

    <para>Possible arguments: <literal>5</literal>,
      <literal>no_env</literal></para>

    <para>Add dependency on <application>Qt</application> components.
      <literal>no_env</literal> is passed directly to
      <literal>USES= qmake</literal>.  See <xref linkend="using-qt"/>
      for more information.</para>
  </sect1>

  <sect1 xml:id="uses-qt-dist">
    <title><literal>qt-dist</literal></title>

    <para>Possible arguments: (none) or <literal>5</literal> and
      (none) or one of <literal>3d</literal>,
      <literal>activeqt</literal>, <literal>androidextras</literal>,
      <literal>base</literal>, <literal>canvas3d</literal>,
      <literal>charts</literal>, <literal>connectivity</literal>,
      <literal>datavis3d</literal>,  <literal>declarative</literal>,
      <literal>doc</literal>,  <literal>gamepad</literal>,
      <literal>graphicaleffects</literal>,
      <literal>imageformats</literal>, <literal>location</literal>,
      <literal>macextras</literal>, <literal>multimedia</literal>,
      <literal>networkauth</literal>, <literal>purchasing</literal>,
      <literal>quickcontrols2</literal>,
      <literal>quickcontrols</literal>,
      <literal>remoteobjects</literal>,  <literal>script</literal>,
      <literal>scxml</literal>,  <literal>sensors</literal>,
      <literal>serialbus</literal>,  <literal>serialport</literal>,
      <literal>speech</literal>,  <literal>svg</literal>,
      <literal>tools</literal>,  <literal>translations</literal>,
      <literal>virtualkeyboard</literal>, <literal>wayland</literal>,
      <literal>webchannel</literal>, <literal>webengine</literal>,
      <literal>websockets</literal>, <literal>webview</literal>,
      <literal>winextras</literal>, <literal>x11extras</literal>,
      <literal>xmlpatterns</literal></para>

    <para>Provides support for building <application>Qt
	5</application> components.  It takes care of setting up the
      appropriate configuration environment for the port to
      build.</para>

    <example xml:id="qt5-dist-example">
      <title>Building Qt 5 Components</title>

      <para>The port is <application>Qt 5</application>'s
	  <literal>networkauth</literal> component, which is part of
	the <literal>networkauth</literal> distribution file.</para>

      <programlisting>PORTNAME=	networkauth
DISTVERSION=	${QT5_VERSION}

USES=		qt-dist:5</programlisting>
    </example>

    <para>If <varname>PORTNAME</varname> does not match the
      component name, it can be passed as an argument to
      <literal>qt-dist</literal>.</para>

    <example xml:id="qt5-dist-example-explicit">
      <title>Building Qt 5 Components with Different Names</title>

      <para>The port is <application>Qt 5</application>'s
	<literal>gui</literal> component, which is part of the
	<literal>base</literal> distribution file.</para>

      <programlisting>PORTNAME=	gui
DISTVERSION=	${QT5_VERSION}

USES=		qt-dist:5,base</programlisting>
    </example>
  </sect1>

  <sect1 xml:id="uses-readline">
    <title><literal>readline</literal></title>

    <para>Possible arguments: (none), <literal>port</literal></para>

    <para>Uses <application>readline</application> as a library
      dependency, and sets <varname>CPPFLAGS</varname> and
      <varname>LDFLAGS</varname> as necessary.  If the
      <literal>port</literal> argument is used or if readline is not
      present in the base system, add a dependency on <package
	role="port">devel/readline</package></para>
  </sect1>

  <sect1 xml:id="uses-samba">
    <title><literal>samba</literal></title>

    <para>Possible arguments: <literal>build</literal>,
      <literal>env</literal>, <literal>lib</literal>,
      <literal>run</literal></para>

    <para>Handle dependency on <application>Samba</application>.
      <literal>env</literal> will not add any dependency and only set
      up the variables.  <literal>build</literal> and
      <literal>run</literal> will add build-time and run-time
      dependency on <filename>smbd</filename>.  <literal>lib</literal>
      will add a dependency on <filename>libsmbclient.so</filename>.
      The variables that are exported are:</para>

    <variablelist>
      <varlistentry>
	<term><varname>SAMBAPORT</varname></term>
	<listitem>
	  <para>The origin of the default
	    <application>Samba</application> port.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>SAMBAINCLUDES</varname></term>
	<listitem>
	  <para>The location of the <application>Samba</application>
	    header files.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>SAMBALIBS</varname></term>
	<listitem>
	  <para>The directory where the
	    <application>Samba</application> shared libraries are
	    available.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 xml:id="uses-scons">
    <title><literal>scons</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Provide support for the use of <package
	role="port">devel/scons</package>.  See <xref
	linkend="using-scons"/> for more information.</para>
  </sect1>

  <sect1 xml:id="uses-shared-mime-info">
    <title><literal>shared-mime-info</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Uses <application>update-mime-database</application> from
      <package role="port">misc/shared-mime-info</package>.  This uses
      will automatically add a post-install step in such a way that
      the port itself still can specify there own post-install step if
      needed.  It also add an <link
	linkend="plist-keywords-shared-mime-info"><literal>@shared-mime-info</literal></link>
      entry to the plist.</para>
  </sect1>

  <sect1 xml:id="uses-shebangfix">
    <title><literal>shebangfix</literal></title>

    <para>Possible arguments: (none)</para>

    <para>A lot of software uses incorrect locations for script
      interpreters, most notably <filename>/usr/bin/perl</filename>
      and <filename>/bin/bash</filename>.  The shebangfix macro fixes
      shebang lines in scripts listed in
      <varname>SHEBANG_REGEX</varname>,
      <varname>SHEBANG_GLOB</varname>, or
      <varname>SHEBANG_FILES</varname>.</para>

    <variablelist>
      <varlistentry>
	<term><varname>SHEBANG_REGEX</varname></term>

	<listitem>
	  <para>Contains <emphasis>one</emphasis> extended regular
	    expressions, and is used with the
	    <literal>-iregex</literal> argument of &man.find.1;.  See
	    <xref linkend="uses-shebangfix-ex-regex"/>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>SHEBANG_GLOB</varname></term>

	<listitem>
	  <para>Contains a list of patterns used with the
	    <literal>-name</literal> argument of &man.find.1;.  See
	    <xref linkend="uses-shebangfix-ex-glob"/>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>SHEBANG_FILES</varname></term>

	<listitem>
	  <para>Contains a list of files or &man.sh.1; globs.  The
	    shebangfix macro is run from <literal>${WRKSRC}</literal>,
	    so <varname>SHEBANG_FILES</varname> can contain paths that
	    are relative to <literal>${WRKSRC}</literal>.  It can also
	    deal with absolute paths if files outside of
	    <literal>${WRKSRC}</literal> require patching.  See <xref
	      linkend="uses-shebangfix-ex-files" />.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>Currently
      <application>Bash</application>,
      <application>Java</application>, <application>Ksh</application>,
      <application>Lua</application>,
      <application>Perl</application>, <application>PHP</application>,
      <application>Python</application>,
      <application>Ruby</application>, <application>Tcl</application>,
      and <application>Tk</application> are supported by
      default.</para>

    <para>There are three configuration variables:</para>

    <variablelist>
      <varlistentry>
	<term><varname>SHEBANG_LANG</varname></term>

	<listitem>
	  <para>The list of supported interpreters.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname><replaceable>interp</replaceable>_CMD</varname></term>

	<listitem>
	  <para>The path to the command interpreter on &os;.  The
	    default value is
	    <literal>${LOCALBASE}/bin/<replaceable>interp</replaceable></literal>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname><replaceable>interp</replaceable>_OLD_CMD</varname></term>
	<listitem>
	  <para>The list of wrong invocations of interpreters.  These
	    are typically obsolete paths, or paths used on other
	    operating systems that are incorrect on &os;.  They
	    will be replaced by the correct path in
	    <varname><replaceable>interp</replaceable>_CMD</varname>.</para>

	  <note>
	    <para>These will <emphasis>always</emphasis> be part of
	      <varname><replaceable>interp</replaceable>_OLD_CMD</varname>:
	      <literal>"/usr/bin/env
		<replaceable>interp</replaceable>"
		/bin/<replaceable>interp</replaceable>
		/usr/bin/<replaceable>interp</replaceable>
		/usr/local/bin/<replaceable>interp</replaceable></literal>.</para>
	  </note>

	  <tip>
	    <para><varname><replaceable>interp</replaceable>_OLD_CMD</varname>
	      contain multiple values.  Any entry with spaces must be
	      quoted.  See <xref
		linkend="uses-shebangfix-ex-ksh"/>.</para>
	  </tip>
	</listitem>
      </varlistentry>
    </variablelist>

    <important>
      <para>The fixing of shebangs is done during the
	<buildtarget>patch</buildtarget> phase.  If scripts are
	created with incorrect shebangs during the
	<buildtarget>build</buildtarget> phase, the build process (for
	example, the <filename>configure</filename> script, or the
	<filename>Makefiles</filename>) must be patched or given the
	right path (for example, with
	<varname>CONFIGURE_ENV</varname>,
	<varname>CONFIGURE_ARGS</varname>,
	<varname>MAKE_ENV</varname>, or <varname>MAKE_ARGS</varname>)
	to generate the right shebangs.</para>

      <para>Correct paths for supported interpreters
	are available in
	<literal><replaceable>interp</replaceable>_CMD</literal>.</para>
    </important>

    <tip>
      <para>When used with <link
	  linkend="uses-python"><literal>USES=python</literal></link>,
	and the aim is only to fix the shebangs but a dependency on
	<application>Python</application> itself is not wanted, use
	<literal>PYTHON_NO_DEPENDS=yes</literal>.</para>
    </tip>

    <example xml:id="uses-shebangfix-ex-lua">
      <title>Adding Another Interpreter to
	<literal>USES=shebangfix</literal></title>

      <para>To add another interpreter, set
	<varname>SHEBANG_LANG</varname>.  For example:</para>

      <programlisting>SHEBANG_LANG=	lua</programlisting>
    </example>

    <example xml:id="uses-shebangfix-ex-ksh">
      <title>Specifying all the Paths When Adding an Interpreter to
	<literal>USES=shebangfix</literal></title>

      <para>If it was not already defined, and there were no default
	values for
	<varname><replaceable>interp</replaceable>_OLD_CMD</varname>
	and <varname><replaceable>interp</replaceable>_CMD</varname>
	the <application>Ksh</application> entry could be defined
	as:</para>

      <programlisting>SHEBANG_LANG=	ksh
ksh_OLD_CMD=	"/usr/bin/env ksh" /bin/ksh /usr/bin/ksh
ksh_CMD=	${LOCALBASE}/bin/ksh</programlisting>
    </example>

    <example xml:id="uses-shebangfix-ex-strange">
      <title>Adding a Strange Location for an Interpreter</title>

      <para>Some software uses strange locations for an interpreter.
	For example, an application might expect
	<application>Python</application> to be located in
	<filename>/opt/bin/python2.7</filename>.  The strange path to
	be replaced can be declared in the port
	<filename>Makefile</filename>:</para>

      <programlisting>python_OLD_CMD=	/opt/bin/python2.7</programlisting>
    </example>

    <example xml:id="uses-shebangfix-ex-regex">
      <title><literal>USES=shebangfix</literal> with
	<varname>SHEBANG_REGEX</varname></title>

      <para>To fix all the files in
	<literal>${WRKSRC}/scripts</literal> ending in
	<filename>.pl</filename>, <filename>.sh</filename>, or
	<filename>.cgi</filename> do:</para>

      <programlisting>USES=	shebangfix
SHEBANG_REGEX=	./scripts/.*\.(sh|pl|cgi)</programlisting>

      <note>
	<para><varname>SHEBANG_REGEX</varname> is used by running
	  <command>find -E</command>, which uses modern regular
	  expressions also known as extended regular expressions.  See
	  &man.re.format.7; for more information.</para>
      </note>
    </example>

    <example xml:id="uses-shebangfix-ex-glob">
      <title><literal>USES=shebangfix</literal> with
	<varname>SHEBANG_GLOB</varname></title>

      <para>To fix all the files in <literal>${WRKSRC}</literal>
	ending in <filename>.pl</filename> or
	<filename>.sh</filename>, do:</para>

      <programlisting>USES=	shebangfix
SHEBANG_GLOB=	*.sh *.pl</programlisting>
    </example>

    <example xml:id="uses-shebangfix-ex-files">
      <title><literal>USES=shebangfix</literal> with
	<varname>SHEBANG_FILES</varname></title>

      <para>To fix the files <filename>script/foobar.pl</filename> and
	<filename>script/*.sh</filename> in
	<literal>${WRKSRC}</literal>, do:</para>

      <programlisting>USES=	shebangfix
SHEBANG_FILES=	scripts/foobar.pl scripts/*.sh</programlisting>
    </example>
  </sect1>

  <sect1 xml:id="uses-sqlite">
    <title><literal>sqlite</literal></title>

    <para>Possible arguments: (none), <literal>2</literal>,
      <literal>3</literal></para>

    <para>Add a dependency on <application>SQLite</application>.  The
      default version used is 3, but version 2 is also possible using
      the <literal>:2</literal> modifier.</para>
  </sect1>

  <sect1 xml:id="uses-ssl">
    <title><literal>ssl</literal></title>

    <para>Possible arguments: (none), <literal>build</literal>,
      <literal>run</literal></para>

    <para>Provide support for <application>OpenSSL</application>.
      A build- or run-time only dependency can be specified using
      <literal>build</literal> or <literal>run</literal>.
      These variables are available for the port's use, they are also
      added to <varname>MAKE_ENV</varname>:</para>

    <variablelist>
      <varlistentry>
	<term><varname>OPENSSLBASE</varname></term>

	<listitem>
	  <para>Path to the OpenSSL installation base.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>OPENSSLDIR</varname></term>

	<listitem>
	  <para>Path to <application>OpenSSL</application>'s
	    configuration files.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>OPENSSLLIB</varname></term>

	<listitem>
	  <para>Path to the <application>OpenSSL</application>
	    libraries.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>OPENSSLINC</varname></term>

	<listitem>
	  <para>Path to the <application>OpenSSL</application>
	    includes.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>OPENSSLRPATH</varname></term>

	<listitem>
	  <para>If defined, the path the linker needs to use to find
	    the <application>OpenSSL</application> libraries.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <tip>
      <para>If a port does not build with an
	<application>OpenSSL</application> flavor, set the
	<varname>BROKEN_SSL</varname> variable, and possibly the
	<varname>BROKEN_SSL_REASON_<replaceable>flavor</replaceable></varname>:</para>

      <programlisting>BROKEN_SSL=	libressl
BROKEN_SSL_REASON_libressl=	needs features only available in OpenSSL</programlisting>
    </tip>
  </sect1>

  <sect1 xml:id="uses-tar">
    <title><literal>tar</literal></title>

    <para>Possible arguments: (none), <literal>Z</literal>,
      <literal>bz2</literal>, <literal>bzip2</literal>,
      <literal>lzma</literal>, <literal>tbz</literal>,
      <literal>tbz2</literal>,
      <literal>tgz</literal>, <literal>txz</literal>,
      <literal>xz</literal></para>

    <para>Set <varname>EXTRACT_SUFX</varname> to
      <literal>.tar</literal>, <literal>.tar.Z</literal>,
      <literal>.tar.bz2</literal>, <literal>.tar.bz2</literal>,
      <literal>.tar.lzma</literal>, <literal>.tbz</literal>,
      <literal>.tbz2</literal>,
      <literal>.tgz</literal>, <literal>.txz</literal> or
      <literal>.tar.xz</literal> respectively.</para>
  </sect1>

  <sect1 xml:id="uses-tcl">
    <title><literal>tcl</literal></title>

    <para>Possible arguments: <replaceable>version</replaceable>,
      <literal>wrapper</literal>, <literal>build</literal>,
      <literal>run</literal>, <literal>tea</literal></para>

    <para>Add a dependency on <application>Tcl</application>.  A
      specific version can be requested using
      <replaceable>version</replaceable>.  The version can be empty,
      one or more exact version numbers (currently
      <literal>84</literal>, <literal>85</literal>, or
      <literal>86</literal>), or a minimal version number (currently
      <literal>84+</literal>, <literal>85+</literal> or
      <literal>86+</literal>).  To only request a non version specific
      wrapper, use <literal>wrapper</literal>.  A build- or run-time
      only dependency can be specified using <literal>build</literal>
      or <literal>run</literal>.  To build the port using the
      <application>Tcl Extension Architecture</application>, use
      <literal>tea</literal>.  After including
      <filename>bsd.port.pre.mk</filename> the port can inspect the
      results using these variables:</para>

    <itemizedlist>
      <listitem>
	<para><varname>TCL_VER</varname>: chosen major.minor version
	  of <application>Tcl</application></para>
      </listitem>

      <listitem>
	<para><varname>TCLSH</varname>: full path of the
	  <application>Tcl</application> interpreter</para>
      </listitem>

      <listitem>
	<para><varname>TCL_LIBDIR</varname>: path of the
	  <application>Tcl</application> libraries</para>
      </listitem>

      <listitem>
	<para><varname>TCL_INCLUDEDIR</varname>: path of the
	  <application>Tcl</application> C header files</para>
      </listitem>

      <listitem>
	<para><varname>TK_VER</varname>: chosen major.minor version of
	  <application>Tk</application></para>
      </listitem>

      <listitem>
	<para><varname>WISH</varname>: full path of the
	  <application>Tk</application> interpreter</para>
      </listitem>

      <listitem>
	<para><varname>TK_LIBDIR</varname>: path of the
	  <application>Tk</application> libraries</para>
      </listitem>

      <listitem>
	<para><varname>TK_INCLUDEDIR</varname>: path of the
	  <application>Tk</application> C header files</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="uses-terminfo">
    <title><literal>terminfo</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Adds <link
	linkend="plist-keywords-terminfo"><literal>@terminfo</literal></link>
      to the <filename>plist</filename>.  Use when the port installs
      <filename><replaceable>*</replaceable>.terminfo</filename> files
      in <filename>${PREFIX}/share/misc</filename>.</para>
  </sect1>

  <sect1 xml:id="uses-tk">
    <title><literal>tk</literal></title>

    <para>Same as arguments for <literal>tcl</literal></para>

    <para>Small wrapper when using both <application>Tcl</application>
      and <application>Tk</application>.  The same variables are
      returned as when using <application>Tcl</application>.</para>
  </sect1>

  <sect1 xml:id="uses-uidfix">
    <title><literal>uidfix</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Changes some default behavior (mostly variables) of
      the build system to allow installing this port as a normal
      user.  Try this in the port before using <link
	linkend="uses-fakeroot">USES=fakeroot</link> or
      patching.</para>
  </sect1>

  <sect1 xml:id="uses-uniquefiles">
    <title><literal>uniquefiles</literal></title>

    <para>Possible arguments: (none), <literal>dirs</literal></para>

    <para>Make files or directories 'unique', by adding a prefix or
      suffix.  If the <literal>dirs</literal> argument is used, the
      port needs a prefix (and only a prefix) based on
      <varname>UNIQUE_PREFIX</varname> for standard directories
      <varname>DOCSDIR</varname>, <varname>EXAMPLESDIR</varname>,
      <varname>DATADIR</varname>, <varname>WWWDIR</varname>,
      <varname>ETCDIR</varname>.  These variables are available for
      ports:</para>

    <itemizedlist>
      <listitem>
	<para><varname>UNIQUE_PREFIX</varname>: The prefix to be used
	  for directories and files.  Default:
	  <varname>${PKGNAMEPREFIX}</varname>.</para>
      </listitem>

      <listitem>
	<para><varname>UNIQUE_PREFIX_FILES</varname>: A list of files
	  that need to be prefixed.  Default: empty.</para>
      </listitem>

      <listitem>
	<para><varname>UNIQUE_SUFFIX</varname>: The suffix to be used
	  for files.  Default:
	  <varname>${PKGNAMESUFFIX}</varname>.</para>
      </listitem>

      <listitem>
	<para><varname>UNIQUE_SUFFIX_FILES</varname>: A list of files
	  that need to be suffixed.  Default: empty.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="uses-varnish">
    <title><literal>varnish</literal></title>

    <para>Possible arguments: <literal>4</literal>,
      <literal>5</literal></para>

    <para>Handle dependencies on <application>Varnish
	Cache</application>.  <literal>4</literal> will add a
      dependency on <package role="port">www/varnish4</package>.
      <literal>5</literal> will add a dependency on <package
	role="port">www/varnish5</package>.</para>
  </sect1>

  <sect1 xml:id="uses-webplugin">
    <title><literal>webplugin</literal></title>

    <para>Possible arguments: (none), <literal>ARGS</literal></para>

    <para>Automatically create and remove symbolic links for each
      application that supports the webplugin framework.
      <literal>ARGS</literal> can be one of:</para>

    <itemizedlist>
      <listitem>
	<para><literal>gecko</literal>: support plug-ins based on
	  Gecko</para>
      </listitem>

      <listitem>
	<para><literal>native</literal>: support plug-ins for Gecko,
	  Opera, and WebKit-GTK</para>
      </listitem>

      <listitem>
	<para><literal>linux</literal>: support Linux plug-ins</para>
      </listitem>

      <listitem>
	<para><literal>all</literal> (default, implicit): support all
	  plug-in types</para>
      </listitem>

      <listitem>
	<para>(individual entries): support only the browsers
	  listed</para>
      </listitem>
    </itemizedlist>

    <para>These variables can be adjusted:</para>

    <itemizedlist>
      <listitem>
	<para><varname>WEBPLUGIN_FILES</varname>: No default, must be
	  set manually.  The plug-in files to install.</para>
      </listitem>

      <listitem>
	<para><varname>WEBPLUGIN_DIR</varname>: The directory to
	  install the plug-in files to, default
	  <filename><replaceable>PREFIX</replaceable>/lib/browser_plugins/<replaceable>WEBPLUGIN_NAME</replaceable></filename>.
	  Set this if the port installs plug-in files outside of the
	  default directory to prevent broken symbolic links.</para>
      </listitem>

      <listitem>
	<para><varname>WEBPLUGIN_NAME</varname>: The final directory
	  to install the plug-in files into, default
	  <varname>PKGBASE</varname>.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="uses-xfce">
    <title><literal>xfce</literal></title>

    <para>Possible arguments: (none), <literal>gtk2</literal></para>

    <para>Provide support for <application>Xfce</application> related
      ports.  See <xref linkend="using-xfce"/> for details.</para>

    <para>The <literal>gtk2</literal> argument specifies that the port
      requires <application>GTK2</application> support.  It adds
      additional features provided by some core components, for
      example, <package role="port">x11/libxfce4menu</package> and
      <package role="port">x11-wm/xfce4-panel</package>.</para>
  </sect1>

  <sect1 xml:id="uses-xorg">
    <title><literal>xorg</literal></title>

    <para>Possible arguments: (none)</para>

    <para>Provides an easy way to depend on
      <application>X.org</application> components.  The components
      should be listed in <varname>USE_XORG</varname>.  The available
      components are:</para>

    <table frame="none" xml:id="using-x11-components">
      <title>Available X.Org Components</title>

      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Name</entry>
	    <entry>Description</entry>
	  </row>
	</thead>

	<!-- From any ports checkout, run
	  for m in $(make -C x11/libX11 -V XORG_MODULES:O); do
	      port=$(make -C x11/libX11 -V "${m}_LIB_PC_DEPENDS:C/^.*://")
	      if [ -z "$port" ]; then
	          port=$(make -C x11/libX11 -V "${m}_BUILD_DEPENDS:C/^.*://")
	      fi
	      description=$(make -C "$port" -V COMMENT)
	      printf "<row>\n  <entry><literal>$m</literal></entry>\n  <entry>$description</entry>\n</row>\n\n"
	  done
	  -->
	<tbody>
	  <row>
	    <entry><literal>dmx</literal></entry>
	    <entry>DMX extension library</entry>
	  </row>

	  <row>
	    <entry><literal>fontenc</literal></entry>
	    <entry>The fontenc Library</entry>
	  </row>

	  <row>
	    <entry><literal>fontutil</literal></entry>
	    <entry>Create an index of X font files in a directory</entry>
	  </row>

	  <row>
	    <entry><literal>ice</literal></entry>
	    <entry>Inter Client Exchange library for X11</entry>
	  </row>

	  <row>
	    <entry><literal>libfs</literal></entry>
	    <entry>The FS library</entry>
	  </row>

	  <row>
	    <entry><literal>pciaccess</literal></entry>
	    <entry>Generic PCI access library</entry>
	  </row>

	  <row>
	    <entry><literal>pixman</literal></entry>
	    <entry>Low-level pixel manipulation library</entry>
	  </row>

	  <row>
	    <entry><literal>sm</literal></entry>
	    <entry>Session Management library for X11</entry>
	  </row>

	  <row>
	    <entry><literal>x11</literal></entry>
	    <entry>X11 library</entry>
	  </row>

	  <row>
	    <entry><literal>xau</literal></entry>
	    <entry>Authentication Protocol library for X11</entry>
	  </row>

	  <row>
	    <entry><literal>xaw</literal></entry>
	    <entry>X Athena Widgets library</entry>
	  </row>

	  <row>
	    <entry><literal>xaw6</literal></entry>
	    <entry>X Athena Widgets library</entry>
	  </row>

	  <row>
	    <entry><literal>xaw7</literal></entry>
	    <entry>X Athena Widgets library</entry>
	  </row>

	  <row>
	    <entry><literal>xbitmaps</literal></entry>
	    <entry>X.Org bitmaps data</entry>
	  </row>

	  <row>
	    <entry><literal>xcb</literal></entry>
	    <entry>The X protocol C-language Binding (XCB) library</entry>
	  </row>

	  <row>
	    <entry><literal>xcomposite</literal></entry>
	    <entry>X Composite extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xcursor</literal></entry>
	    <entry>X client-side cursor loading library</entry>
	  </row>

	  <row>
	    <entry><literal>xdamage</literal></entry>
	    <entry>X Damage extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xdmcp</literal></entry>
	    <entry>X Display Manager Control Protocol library</entry>
	  </row>

	  <row>
	    <entry><literal>xext</literal></entry>
	    <entry>X11 Extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xfixes</literal></entry>
	    <entry>X Fixes extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xfont</literal></entry>
	    <entry>X font library</entry>
	  </row>

	  <row>
	    <entry><literal>xfont2</literal></entry>
	    <entry>X font library</entry>
	  </row>

	  <row>
	    <entry><literal>xft</literal></entry>
	    <entry>Client-sided font API for X applications</entry>
	  </row>

	  <row>
	    <entry><literal>xi</literal></entry>
	    <entry>X Input extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xinerama</literal></entry>
	    <entry>X11 Xinerama library</entry>
	  </row>

	  <row>
	    <entry><literal>xkbfile</literal></entry>
	    <entry>XKB file library</entry>
	  </row>

	  <row>
	    <entry><literal>xmu</literal></entry>
	    <entry>X Miscellaneous Utilities libraries</entry>
	  </row>

	  <row>
	    <entry><literal>xmuu</literal></entry>
	    <entry>X Miscellaneous Utilities libraries</entry>
	  </row>

	  <row>
	    <entry><literal>xorg-macros</literal></entry>
	    <entry>X.Org development aclocal macros</entry>
	  </row>

	  <row>
	    <entry><literal>xorg-server</literal></entry>
	    <entry>X.Org X server and related programs</entry>
	  </row>

	  <row>
	    <entry><literal>xorgproto</literal></entry>
	    <entry>xorg protocol headers</entry>
	  </row>

	  <row>
	    <entry><literal>xpm</literal></entry>
	    <entry>X Pixmap library</entry>
	  </row>

	  <row>
	    <entry><literal>xpresent</literal></entry>
	    <entry>X Present Extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xrandr</literal></entry>
	    <entry>X Resize and Rotate extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xrender</literal></entry>
	    <entry>X Render extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xres</literal></entry>
	    <entry>X Resource usage library</entry>
	  </row>

	  <row>
	    <entry><literal>xscrnsaver</literal></entry>
	    <entry>The XScrnSaver library</entry>
	  </row>

	  <row>
	    <entry><literal>xshmfence</literal></entry>
	    <entry>Shared memory 'SyncFence' synchronization primitive</entry>
	  </row>

	  <row>
	    <entry><literal>xt</literal></entry>
	    <entry>X Toolkit library</entry>
	  </row>

	  <row>
	    <entry><literal>xtrans</literal></entry>
	    <entry>Abstract network code for X</entry>
	  </row>

	  <row>
	    <entry><literal>xtst</literal></entry>
	    <entry>X Test extension</entry>
	  </row>

	  <row>
	    <entry><literal>xv</literal></entry>
	    <entry>X Video Extension library</entry>
	  </row>

	  <row>
	    <entry><literal>xvmc</literal></entry>
	    <entry>X Video Extension Motion Compensation library</entry>
	  </row>

	  <row>
	    <entry><literal>xxf86dga</literal></entry>
	    <entry>X DGA Extension</entry>
	  </row>

	  <row>
	    <entry><literal>xxf86vm</literal></entry>
	    <entry>X Vidmode Extension</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </sect1>

  <sect1 xml:id="uses-xorg-cat">
    <title><literal>xorg-cat</literal></title>

    <para>Possible arguments: <literal>app</literal>, <literal>data</literal>,
      <literal>doc</literal>, <literal>driver</literal>,
      <literal>font</literal>, <literal>lib</literal>, <literal>proto</literal>,
      <literal>util</literal>, <literal>xserver</literal> and (none) or one off
      <literal>autotools</literal> (default), <literal>meson</literal></para>

    <para>Provide support for building <application>Xorg</application>
      components.  It takes care of setting up common dependencies and an
      appropriate configuration environment needed.  This is intended only
      for <application>Xorg</application> components.</para>

    <para>The category has to match upstream categories.</para>

    <para>The second argument is the build system to use.
      <application>autotools</application> is the default, but
      <application>meson</application> is also supported.</para>
  </sect1>

  <sect1 xml:id="uses-zip">
    <title><literal>zip</literal></title>

    <para>Possible arguments: (none),
      <literal>infozip</literal></para>

    <para>Indicates that the distribution files use the ZIP
      compression algorithm.  For files using the InfoZip algorithm
      the <literal>infozip</literal> argument must be passed to set
      the appropriate dependencies.</para>
  </sect1>
</chapter>