| <?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>. The |
| same source tree is also available at the |
| <ulink |
| url="http://cgit.freedesktop.org/harfbuzz/">Freedesktop.org</ulink> |
| site. |
| </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">github.com/harfbuzz/harfbuzz/releases</ulink> |
| or from |
| <ulink url="http://www.freedesktop.org/software/harfbuzz/release/">Freedesktop.org</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 the <ulink |
| url="http://freedesktop.org/mailman/listinfo/harfbuzz/">HarfBuzz |
| mailing list</ulink>. |
| </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>./configure</command> followed by |
| <command>make</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> and |
| <ulink url="http://www.complang.org/ragel/">ragel</ulink>. |
| </para> |
| <para> |
| On Ubuntu or Debian, run: |
| <programlisting> |
| <command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package> |
| </programlisting> |
| On Fedora, RHEL, CentOS, run: |
| <programlisting> |
| <command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package> |
| </programlisting> |
| |
| </para> |
| <para> |
| With <package>pkg-config</package> and <package>ragel</package> |
| installed, you can now run <command>./autogen.sh</command>, |
| followed by <command>./configure</command> and |
| <command>make</command> to build HarfBuzz. |
| </para> |
| </section> |
| |
| |
| <section id="building.windows"> |
| <title>Building on Windows</title> |
| |
| <para> |
| On Windows, consider using Microsoft's free <ulink |
| url="https://github.com/Microsoft/vcpkg">vcpkg</ulink> utility |
| to build HarfBuzz, its dependencies, and other open-source |
| libraries. |
| </para> |
| <para> |
| If you need to build HarfBuzz from source, first put the |
| <package>ragel</package> binary on your |
| <literal>PATH</literal>, then follow the appveyor CI cmake |
| <ulink |
| url="https://github.com/harfbuzz/harfbuzz/blob/master/appveyor.yml">build |
| instructions</ulink>. |
| </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>./configure</command> |
| </programlisting> |
| followed by: |
| <programlisting> |
| <command>make</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>autoconf automake libtool pkgconfig ragel 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>autoconf automake libtool pkgconfig ragel gtk-doc</package> |
| </programlisting> |
| Finally, you can run: |
| <programlisting> |
| <command>./autogen.sh</command> |
| </programlisting> |
| </para> |
| <para> |
| <emphasis>(3)</emphasis> You can now build HarfBuzz (on either |
| a MacPorts or a Homebrew system) by running: |
| <programlisting> |
| <command>./configure</command> |
| </programlisting> |
| followed by: |
| <programlisting> |
| <command>make</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>--with-libstdc++</command></term> |
| <listitem> |
| <para> |
| Allow linking with libstdc++. <emphasis>(Default = no)</emphasis> |
| </para> |
| <para> |
| This option enables or disables linking HarfBuzz to the |
| system's libstdc++ library. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>--with-glib</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>--with-gobject</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>--with-cairo</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>--with-fontconfig</command></term> |
| <listitem> |
| <para> |
| Use <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">Fontconfig</ulink>. <emphasis>(Default = auto)</emphasis> |
| </para> |
| <para> |
| This option enables or disables usage of the Fontconfig |
| library, which provides font-matching functions and |
| provides access to font properties. The default setting |
| is to check for the presence of Fontconfig and, if it is |
| found, build with Fontconfig support. |
| </para> |
| <para> |
| Note: Fontconfig is used only by the HarfBuzz |
| command-line utilities, and not by the HarfBuzz library. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>--with-icu</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>--with-ucdn</command></term> |
| <listitem> |
| <para> |
| Use HarfBuzz's <ulink url="https://github.com/harfbuzz/harfbuzz/tree/master/src/hb-ucdn">built-in UCDN library</ulink>. <emphasis>(Default = auto)</emphasis> |
| </para> |
| <para> |
| The HarfBuzz source tree includes a <emphasis>Unicode |
| Database and Normalization</emphasis> (UCDN) library |
| that provides access to basic character properties in |
| the Unicode Character Database (UCD) as well as low-level |
| normalization functions. HarfBuzz can be built without |
| this UCDN support if the usage of a different UCDN |
| library is desired. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>--with-graphite2</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>--with-freetype</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>--with-uniscribe</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>--with-directwrite</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>--with-coretext</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>--enable-gtk-doc</command></term> |
| <listitem> |
| <para> |
| Use <ulink url="https://www.gtk.org/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> |
