<?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>
</chapter>
