docs/usermanual-install-harfbuzz.xml - third_party/harfbuzz - Git at Google


            
            <?xml version="1.0"?>

            
            <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"

            
                           "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [

            
              <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">

            
              <!ENTITY version SYSTEM "version.xml">

            
            ]>

            
            <chapter id="install-harfbuzz">

            
              <title>Installing HarfBuzz</title>


              <section id="download">

            
                <title id="download.title">Downloading HarfBuzz</title>

            
                <para>

            
                  The HarfBuzz source code is hosted at <ulink

            
                  url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>.

            
                </para>

            
                <para>

            
                  Tarball releases and Win32 binary bundles (which include the

            
                  libharfbuzz DLL, hb-view.exe, hb-shape.exe, and all

            
                  dependencies) of HarfBuzz can be downloaded from <ulink

            
                  url="https://github.com/harfbuzz/harfbuzz/releases">github.com/harfbuzz/harfbuzz/releases</ulink>.

            
                </para>

            
                <para>

            
                  Release notes are posted with each new release to provide an

            
                  overview of the changes. The project <ulink url="https://github.com/harfbuzz/harfbuzz/issues">tracks bug

            
                  reports and other issues</ulink> on GitHub. Discussion and

            
                  questions are welcome on <ulink

            
                  url="https://github.com/harfbuzz/harfbuzz/discussions">GitHub</ulink> as well.

            
                </para>

            
                <para>

            
                  The API included in the <filename

            
                  class='headerfile'>hb.h</filename> file will not change in a

            
                  compatibility-breaking way in any release. However, other,

            
                  peripheral headers are more likely to go through minor

            
                  modifications. We will do our best to never change APIs in an

            
                  incompatible way. We will <emphasis>never</emphasis> break the ABI.

            
                </para>

            
              </section>


              <section id="building">

            
                <title>Building HarfBuzz</title>


                <section id="building.linux">

            
                  <title>Building on Linux</title>

            
                <para>

            
                  <emphasis>(1)</emphasis> To build HarfBuzz on Linux, you must first install the

            
                  development packages for FreeType, Cairo, and GLib. The exact

            
                  commands required for this step will vary depending on

            
                  the Linux distribution you use.

            
                </para>

            
                <para>

            
                  For example, on an Ubuntu or Debian system, you would run:

            
                  <programlisting><command>sudo apt install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package></programlisting>

            
                  On Fedora, RHEL, CentOS, or other Red-Hat&ndash;based systems, you would run:

            
                  <programlisting><command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package></programlisting>


                </para>


                <para>

            
                  <emphasis>(2)</emphasis> The next step depends on whether you

            
                  are building from the source in a downloaded release tarball or

            
                  from the source directly from the git repository.

            
                </para>

            
                <para>

            
                  <emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz

            
                  source code in a tarball, you can now extract the source.

            
                </para>

            
                <para>

            
                  From a shell in the top-level directory of the extracted source

            
                  code, you can run <command>meson build</command> followed by

            
                  <command>meson compile -C build</command> as with any other standard package.

            
                </para>

            
                <para>

            
                  This should leave you with a shared

            
                  library in the <filename>src/</filename> directory, and a few

            
                  utility programs including <command>hb-view</command> and

            
                  <command>hb-shape</command> under the <filename>util/</filename>

            
                  directory.

            
                </para>

            
                <para>

            
                  <emphasis>(2)(b)</emphasis> If you are building from the source in the HarfBuzz git

            
                  repository, rather than installing from a downloaded tarball

            
                  release, then you must install two more auxiliary tools before you

            
                  can build for the first time: <package>pkg-config</package>.

            
                </para>

            
                <para>

            
                  On Ubuntu or Debian, run:

            
                  <programlisting><command>sudo apt-get install</command> <package>meson pkg-config gtk-doc-tools</package></programlisting>

            
                  On Fedora, RHEL, CentOS, run:

            
                  <programlisting><command>sudo yum install</command> <package>meson pkgconfig gtk-doc</package></programlisting>


                </para>

            
                <para>

            
                  With <package>pkg-config</package> installed, you can now run

            
                  <command>meson build</command> then

            
                  <command>meson compile -C build</command> to build HarfBuzz.

            
                </para>

            
                </section>


                <section id="building.windows">

            
                  <title>Building on Windows</title>


                  <para>

            
                    <ulink url="https://mesonbuild.com/Getting-meson.html">Install meson</ulink>

            
                    and run (from the console) <command>meson build</command> (by default

            
                    bundled dependencies are not built, <command>--wrap-mode=default</command>

            
                    overrides this), then <command>meson compile -C build</command> to

            
            	build HarfBuzz.

            
                  </para>

            
                </section>


                <section id="building.macos">

            
                  <title>Building on macOS</title>


                  <para>

            
            	There are two ways to build HarfBuzz on Mac systems: MacPorts

            
            	and Homebrew. The process is similar to the process used on a

            
            	Linux system.

            
                  </para>

            
                  <para>

            
            	<emphasis>(1)</emphasis> You must first install the

            
            	development packages for FreeType, Cairo, and GLib. If you are

            
            	using MacPorts, you should run:

            
                  <programlisting><command>sudo port install</command> <package>freetype glib2 cairo</package></programlisting>

            
                  </para>

            
                  <para>

            
            	If you are using Homebrew, you should run:

            
            	<programlisting><command>brew install</command> <package>freetype glib cairo</package></programlisting>

            
                  </para>

            
                  <para>

            
            	<emphasis>(2)</emphasis> The next step depends on whether you are building from the

            
            	source in a downloaded release tarball or from the source directly

            
            	from the git repository.

            
                  </para>

            
                  <para>

            
            	<emphasis>(2)(a)</emphasis> If you are installing HarfBuzz

            
            	from a downloaded tarball release, extract the tarball and

            
            	open a Terminal in the extracted source-code directory. Run:

            
            	<programlisting><command>meson build</command></programlisting>

            
            	followed by:

            
            	<programlisting><command>meson compile -C build</command></programlisting>

            
            	to build HarfBuzz.

            
                  </para>

            
                  <para>

            
            	<emphasis>(2)(b)</emphasis> Alternatively, if you are building

            
            	HarfBuzz from the source in the HarfBuzz git repository, then

            
            	you must install several built-time dependencies before

            
            	proceeding.

            
                  </para>

            
                  <para>If you are

            
            	using MacPorts, you should run:

            
                  <programlisting><command>sudo port install</command> <package>meson pkgconfig gtk-doc</package></programlisting>

            
                  to install the build dependencies.

            
                  </para>

            
                  <para>If you are using Homebrew, you should run:

            
            	<programlisting><command>brew install</command> <package>meson pkgconfig gtk-doc</package></programlisting>

            
                  	Finally, you can run:

            
            	<programlisting><command>meson build</command></programlisting>

            
                  </para>

            
                  <para>

            
            	<emphasis>(3)</emphasis> You can now build HarfBuzz (on either

            
            	a MacPorts or a Homebrew system) by running:

            
            	<programlisting><command>meson build</command></programlisting>

            
            	followed by:

            
            	<programlisting><command>meson compile -C build</command></programlisting>

            
                  </para>

            
                  <para>

            
            	This should leave you with a shared

            
            	library in the <filename>src/</filename> directory, and a few

            
            	utility programs including <command>hb-view</command> and

            
            	<command>hb-shape</command> under the <filename>util/</filename>

            
            	directory.

            
                  </para>


                </section>


                <section id="configuration">

            
                  <title>Configuration options</title>


                  <para>

            
            	The instructions in the "Building HarfBuzz" section will build

            
            	the source code under its default configuration. If needed,

            
            	the following additional configuration options are available.

            
                  </para>


                  <variablelist>

            
            	<?dbfo list-presentation="blocks"?>

            
            	<varlistentry>

            
            	  <term><command>-Dglib=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	     Use <ulink url="https://developer.gnome.org/glib/">GLib</ulink>. <emphasis>(Default = auto)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the GLib

            
            	      library.  The default setting is to check for the

            
            	      presence of GLib and, if it is found, build with

            
            	      GLib support. GLib is native to GNU/Linux systems but is

            
            	      available on other operating system as well.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Dgobject=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use <ulink url="https://developer.gnome.org/gobject/stable/">GObject</ulink>. <emphasis>(Default = no)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the GObject

            
            	      library. The default setting is to check for the

            
            	      presence of GObject and, if it is found, build with

            
            	      GObject support. GObject is native to GNU/Linux systems but is

            
            	      available on other operating system as well.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Dcairo=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use <ulink url="https://cairographics.org/">Cairo</ulink>. <emphasis>(Default = auto)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the Cairo

            
            	      graphics-rendering library. The default setting is to

            
            	      check for the presence of Cairo and, if it is found,

            
            	      build with Cairo support.

            
            	    </para>

            
            	    <para>

            
            	      Note: Cairo is used only by the HarfBuzz

            
            	      command-line utilities, and not by the HarfBuzz library.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Dicu=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use the <ulink url="http://site.icu-project.org/home">ICU</ulink> library. <emphasis>(Default = auto)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the

            
            	      <emphasis>International Components for

            
            	      Unicode</emphasis> (ICU) library, which provides access

            
            	      to Unicode Character Database (UCD) properties as well

            
            	      as normalization and conversion functions. The default

            
            	      setting is to check for the presence of ICU and, if it

            
            	      is found, build with ICU support.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Dgraphite=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use the <ulink url="http://graphite.sil.org/">Graphite2</ulink> library. <emphasis>(Default = no)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the Graphite2

            
            	      library, which provides support for the Graphite shaping

            
            	      model.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Dfreetype=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use the <ulink url="https://www.freetype.org/">FreeType</ulink> library. <emphasis>(Default = auto)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the FreeType

            
            	      font-rendering library. The default setting is to check for the

            
            	      presence of FreeType and, if it is found, build with

            
            	      FreeType support.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Dgdi=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use the <ulink

            
            	      url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink>

            
            	      library (experimental). <emphasis>(Default = no)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the Uniscribe

            
            	      font-rendering library. Uniscribe is available on

            
            	      Windows systems. Uniscribe support is used only for

            
            	      testing purposes and does not need to be enabled for

            
            	      HarfBuzz to run on Windows systems.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Ddirectwrite=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/directwrite/direct-write-portal">DirectWrite</ulink> library (experimental). <emphasis>(Default = no)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the DirectWrite

            
            	      font-rendering library. DirectWrite is available on

            
            	      Windows systems. DirectWrite support is used only for

            
            	      testing purposes and does not need to be enabled for

            
            	      HarfBuzz to run on Windows systems.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Dcoretext=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use the <ulink url="https://developer.apple.com/documentation/coretext">CoreText</ulink> library. <emphasis>(Default = no)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables or disables usage of the CoreText

            
            	      library. CoreText is available on macOS and iOS systems.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>


            	<varlistentry>

            
            	  <term><command>-Ddocs=enabled</command></term>

            
            	  <listitem>

            
            	    <para>

            
            	      Use <ulink url="https://github.com/GNOME/gtk-doc">GTK-Doc</ulink>. <emphasis>(Default = no)</emphasis>

            
            	    </para>

            
            	    <para>

            
            	      This option enables the building of the documentation.

            
            	    </para>

            
            	  </listitem>

            
            	</varlistentry>

            
                  </variablelist>

            
                </section>


                <section id="building.world">

            
                  <title>Single-file build with <filename>harfbuzz-world.cc</filename></title>

            
                  <para>

            
            	For projects that want HarfBuzz embedded without any

            
            	build-system glue, the source ships a single-file

            
            	amalgamation at <filename>src/harfbuzz-world.cc</filename>

            
            	that <code>#include</code>s every <code>.cc</code> in the

            
            	library so the whole thing compiles as one translation

            
            	unit.  Pair it with the <literal>HB_TINY</literal> /

            
            	<literal>HB_HAS_*</literal> compile-time switches (see

            
            	<link linkend="configuration">Configuration options</link>

            
            	above) to pick which subsystems get pulled in.

            
                  </para>

            
                  <para>

            
            	A live in-browser playground built against this exact

            
            	file lives at

            
            	<ulink url="https://harfbuzz-world.cc/">harfbuzz-world.cc</ulink>;

            
            	its

            
            	<ulink url="https://github.com/harfbuzz/harfbuzz-world.cc">source</ulink>

            
            	is a worked example of dropping HarfBuzz into a project.

            
                  </para>

            
                </section>


              </section>

            
            </chapter>
	<?xml version="1.0"?>
	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
	<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
	<!ENTITY version SYSTEM "version.xml">
	]>
	<chapter id="install-harfbuzz">
	<title>Installing HarfBuzz</title>

	<section id="download">
	<title id="download.title">Downloading HarfBuzz</title>
	<para>
	The HarfBuzz source code is hosted at <ulink
	url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>.
	</para>
	<para>
	Tarball releases and Win32 binary bundles (which include the
	libharfbuzz DLL, hb-view.exe, hb-shape.exe, and all
	dependencies) of HarfBuzz can be downloaded from <ulink
	url="https://github.com/harfbuzz/harfbuzz/releases">github.com/harfbuzz/harfbuzz/releases</ulink>.
	</para>
	<para>
	Release notes are posted with each new release to provide an
	overview of the changes. The project <ulink url="https://github.com/harfbuzz/harfbuzz/issues">tracks bug
	reports and other issues</ulink> on GitHub. Discussion and
	questions are welcome on <ulink
	url="https://github.com/harfbuzz/harfbuzz/discussions">GitHub</ulink> as well.
	</para>
	<para>
	The API included in the <filename
	class='headerfile'>hb.h</filename> file will not change in a
	compatibility-breaking way in any release. However, other,
	peripheral headers are more likely to go through minor
	modifications. We will do our best to never change APIs in an
	incompatible way. We will <emphasis>never</emphasis> break the ABI.
	</para>
	</section>

	<section id="building">
	<title>Building HarfBuzz</title>

	<section id="building.linux">
	<title>Building on Linux</title>
	<para>
	<emphasis>(1)</emphasis> To build HarfBuzz on Linux, you must first install the
	development packages for FreeType, Cairo, and GLib. The exact
	commands required for this step will vary depending on
	the Linux distribution you use.
	</para>
	<para>
	For example, on an Ubuntu or Debian system, you would run:
	<programlisting><command>sudo apt install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package></programlisting>
	On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run:
	<programlisting><command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package></programlisting>

	</para>

	<para>
	<emphasis>(2)</emphasis> The next step depends on whether you
	are building from the source in a downloaded release tarball or
	from the source directly from the git repository.
	</para>
	<para>
	<emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz
	source code in a tarball, you can now extract the source.
	</para>
	<para>
	From a shell in the top-level directory of the extracted source
	code, you can run <command>meson build</command> followed by
	<command>meson compile -C build</command> as with any other standard package.
	</para>
	<para>
	This should leave you with a shared
	library in the <filename>src/</filename> directory, and a few
	utility programs including <command>hb-view</command> and
	<command>hb-shape</command> under the <filename>util/</filename>
	directory.
	</para>
	<para>
	<emphasis>(2)(b)</emphasis> If you are building from the source in the HarfBuzz git
	repository, rather than installing from a downloaded tarball
	release, then you must install two more auxiliary tools before you
	can build for the first time: <package>pkg-config</package>.
	</para>
	<para>
	On Ubuntu or Debian, run:
	<programlisting><command>sudo apt-get install</command> <package>meson pkg-config gtk-doc-tools</package></programlisting>
	On Fedora, RHEL, CentOS, run:
	<programlisting><command>sudo yum install</command> <package>meson pkgconfig gtk-doc</package></programlisting>

	</para>
	<para>
	With <package>pkg-config</package> installed, you can now run
	<command>meson build</command> then
	<command>meson compile -C build</command> to build HarfBuzz.
	</para>
	</section>


	<section id="building.windows">
	<title>Building on Windows</title>

	<para>
	<ulink url="https://mesonbuild.com/Getting-meson.html">Install meson</ulink>
	and run (from the console) <command>meson build</command> (by default
	bundled dependencies are not built, <command>--wrap-mode=default</command>
	overrides this), then <command>meson compile -C build</command> to
	build HarfBuzz.
	</para>
	</section>


	<section id="building.macos">
	<title>Building on macOS</title>

	<para>
	There are two ways to build HarfBuzz on Mac systems: MacPorts
	and Homebrew. The process is similar to the process used on a
	Linux system.
	</para>
	<para>
	<emphasis>(1)</emphasis> You must first install the
	development packages for FreeType, Cairo, and GLib. If you are
	using MacPorts, you should run:
	<programlisting><command>sudo port install</command> <package>freetype glib2 cairo</package></programlisting>
	</para>
	<para>
	If you are using Homebrew, you should run:
	<programlisting><command>brew install</command> <package>freetype glib cairo</package></programlisting>
	</para>
	<para>
	<emphasis>(2)</emphasis> The next step depends on whether you are building from the
	source in a downloaded release tarball or from the source directly
	from the git repository.
	</para>
	<para>
	<emphasis>(2)(a)</emphasis> If you are installing HarfBuzz
	from a downloaded tarball release, extract the tarball and
	open a Terminal in the extracted source-code directory. Run:
	<programlisting><command>meson build</command></programlisting>
	followed by:
	<programlisting><command>meson compile -C build</command></programlisting>
	to build HarfBuzz.
	</para>
	<para>
	<emphasis>(2)(b)</emphasis> Alternatively, if you are building
	HarfBuzz from the source in the HarfBuzz git repository, then
	you must install several built-time dependencies before
	proceeding.
	</para>
	<para>If you are
	using MacPorts, you should run:
	<programlisting><command>sudo port install</command> <package>meson pkgconfig gtk-doc</package></programlisting>
	to install the build dependencies.
	</para>
	<para>If you are using Homebrew, you should run:
	<programlisting><command>brew install</command> <package>meson pkgconfig gtk-doc</package></programlisting>
	Finally, you can run:
	<programlisting><command>meson build</command></programlisting>
	</para>
	<para>
	<emphasis>(3)</emphasis> You can now build HarfBuzz (on either
	a MacPorts or a Homebrew system) by running:
	<programlisting><command>meson build</command></programlisting>
	followed by:
	<programlisting><command>meson compile -C build</command></programlisting>
	</para>
	<para>
	This should leave you with a shared
	library in the <filename>src/</filename> directory, and a few
	utility programs including <command>hb-view</command> and
	<command>hb-shape</command> under the <filename>util/</filename>
	directory.
	</para>

	</section>

	<section id="configuration">
	<title>Configuration options</title>

	<para>
	The instructions in the "Building HarfBuzz" section will build
	the source code under its default configuration. If needed,
	the following additional configuration options are available.
	</para>

	<variablelist>
	<?dbfo list-presentation="blocks"?>
	<varlistentry>
	<term><command>-Dglib=enabled</command></term>
	<listitem>
	<para>
	Use <ulink url="https://developer.gnome.org/glib/">GLib</ulink>. <emphasis>(Default = auto)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the GLib
	library. The default setting is to check for the
	presence of GLib and, if it is found, build with
	GLib support. GLib is native to GNU/Linux systems but is
	available on other operating system as well.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Dgobject=enabled</command></term>
	<listitem>
	<para>
	Use <ulink url="https://developer.gnome.org/gobject/stable/">GObject</ulink>. <emphasis>(Default = no)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the GObject
	library. The default setting is to check for the
	presence of GObject and, if it is found, build with
	GObject support. GObject is native to GNU/Linux systems but is
	available on other operating system as well.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Dcairo=enabled</command></term>
	<listitem>
	<para>
	Use <ulink url="https://cairographics.org/">Cairo</ulink>. <emphasis>(Default = auto)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the Cairo
	graphics-rendering library. The default setting is to
	check for the presence of Cairo and, if it is found,
	build with Cairo support.
	</para>
	<para>
	Note: Cairo is used only by the HarfBuzz
	command-line utilities, and not by the HarfBuzz library.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Dicu=enabled</command></term>
	<listitem>
	<para>
	Use the <ulink url="http://site.icu-project.org/home">ICU</ulink> library. <emphasis>(Default = auto)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the
	<emphasis>International Components for
	Unicode</emphasis> (ICU) library, which provides access
	to Unicode Character Database (UCD) properties as well
	as normalization and conversion functions. The default
	setting is to check for the presence of ICU and, if it
	is found, build with ICU support.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Dgraphite=enabled</command></term>
	<listitem>
	<para>
	Use the <ulink url="http://graphite.sil.org/">Graphite2</ulink> library. <emphasis>(Default = no)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the Graphite2
	library, which provides support for the Graphite shaping
	model.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Dfreetype=enabled</command></term>
	<listitem>
	<para>
	Use the <ulink url="https://www.freetype.org/">FreeType</ulink> library. <emphasis>(Default = auto)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the FreeType
	font-rendering library. The default setting is to check for the
	presence of FreeType and, if it is found, build with
	FreeType support.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Dgdi=enabled</command></term>
	<listitem>
	<para>
	Use the <ulink
	url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink>
	library (experimental). <emphasis>(Default = no)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the Uniscribe
	font-rendering library. Uniscribe is available on
	Windows systems. Uniscribe support is used only for
	testing purposes and does not need to be enabled for
	HarfBuzz to run on Windows systems.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Ddirectwrite=enabled</command></term>
	<listitem>
	<para>
	Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/directwrite/direct-write-portal">DirectWrite</ulink> library (experimental). <emphasis>(Default = no)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the DirectWrite
	font-rendering library. DirectWrite is available on
	Windows systems. DirectWrite support is used only for
	testing purposes and does not need to be enabled for
	HarfBuzz to run on Windows systems.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Dcoretext=enabled</command></term>
	<listitem>
	<para>
	Use the <ulink url="https://developer.apple.com/documentation/coretext">CoreText</ulink> library. <emphasis>(Default = no)</emphasis>
	</para>
	<para>
	This option enables or disables usage of the CoreText
	library. CoreText is available on macOS and iOS systems.
	</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>-Ddocs=enabled</command></term>
	<listitem>
	<para>
	Use <ulink url="https://github.com/GNOME/gtk-doc">GTK-Doc</ulink>. <emphasis>(Default = no)</emphasis>
	</para>
	<para>
	This option enables the building of the documentation.
	</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</section>

	<section id="building.world">
	<title>Single-file build with <filename>harfbuzz-world.cc</filename></title>
	<para>
	For projects that want HarfBuzz embedded without any
	build-system glue, the source ships a single-file
	amalgamation at <filename>src/harfbuzz-world.cc</filename>
	that <code>#include</code>s every <code>.cc</code> in the
	library so the whole thing compiles as one translation
	unit. Pair it with the <literal>HB_TINY</literal> /
	<literal>HB_HAS_*</literal> compile-time switches (see
	<link linkend="configuration">Configuration options</link>
	above) to pick which subsystems get pulled in.
	</para>
	<para>
	A live in-browser playground built against this exact
	file lives at
	<ulink url="https://harfbuzz-world.cc/">harfbuzz-world.cc</ulink>;
	its
	<ulink url="https://github.com/harfbuzz/harfbuzz-world.cc">source</ulink>
	is a worked example of dropping HarfBuzz into a project.
	</para>
	</section>

	</section>
	</chapter>