HarfBuzz text shaping engine
http://harfbuzz.github.io/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
370 lines
14 KiB
370 lines
14 KiB
<?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 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>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>-Dfontconfig=enabled</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>-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://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>
|
|
|