# Installing HarfBuzz

## Downloading HarfBuzz

The HarfBuzz source code is hosted at github.com/harfbuzz/harfbuzz. The same source tree is also available at the Freedesktop.org site.

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 github.com/harfbuzz/harfbuzz/releases or from Freedesktop.org.

Release notes are posted with each new release to provide an overview of the changes. The project tracks bug reports and other issues on GitHub. Discussion and questions are welcome on the HarfBuzz mailing list.

The API included in the `hb.h` 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 never break the ABI.

## Building HarfBuzz

### Building on Linux

(1) 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.

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

    	sudo apt install gcc g++
    	libfreetype6-dev libglib2.0-dev libcairo2-dev

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

    	sudo yum install gcc gcc-c++ freetype-devel glib2-devel cairo-devel

(2) 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.

(2)(a) If you downloaded the HarfBuzz source code in a tarball, you can now extract the source.

From a shell in the top-level directory of the extracted source code, you can run `./configure` followed by `make` as with any other standard package.

This should leave you with a shared library in the `src/` directory, and a few utility programs including `hb-view` and `hb-shape` under the `util/` directory.

(2)(b) 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: `pkg-config` and ragel.

On Ubuntu or Debian, run:

    	sudo apt-get install autoconf automake libtool pkg-config ragel gtk-doc-tools

On Fedora, RHEL, CentOS, run:

    	sudo yum install autoconf automake libtool pkgconfig ragel gtk-doc

With `pkg-config` and `ragel` installed, you can now run `./autogen.sh`, followed by `./configure` and `make` to build HarfBuzz.

### Building on Windows

On Windows, consider using Microsoft's free vcpkg utility to build HarfBuzz, its dependencies, and other open-source libraries.

If you need to build HarfBuzz from source, first put the ragel binary on your `PATH`, then follow the appveyor CI cmake build instructions.

### Building on macOS

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.

(1) You must first install the development packages for FreeType, Cairo, and GLib. If you are using MacPorts, you should run:

    	sudo port install freetype glib2 cairo

If you are using Homebrew, you should run:

    	  brew install freetype glib cairo

(2) 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.

(2)(a) If you are installing HarfBuzz from a downloaded tarball release, extract the tarball and open a Terminal in the extracted source-code directory. Run:

    	  ./configure

followed by:

    	  make

to build HarfBuzz.

(2)(b) Alternatively, if you are building HarfBuzz from the source in the HarfBuzz git repository, then you must install several built-time dependencies before proceeding.

If you are using MacPorts, you should run:

    	sudo port install autoconf
    	automake libtool pkgconfig ragel gtk-doc

to install the build dependencies.

If you are using Homebrew, you should run:

    	  brew install autoconf automake libtool pkgconfig ragel gtk-doc

Finally, you can run:

    	  ./autogen.sh

(3) You can now build HarfBuzz (on either a MacPorts or a Homebrew system) by running:

    	  ./configure

followed by:

    	  make

This should leave you with a shared library in the `src/` directory, and a few utility programs including `hb-view` and `hb-shape` under the `util/` directory.

### Configuration options

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.

--with-libstdc++

  Allow linking with libstdc++. (Default = no)

  This option enables or disables linking HarfBuzz to the system's libstdc++ library.

--with-glib

  Use GLib. (Default = auto)

  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.

--with-gobject

  Use GObject. (Default = no)

  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.

--with-cairo

  Use Cairo. (Default = auto)

  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.

  Note: Cairo is used only by the HarfBuzz command-line utilities, and not by the HarfBuzz library.

--with-fontconfig

  Use Fontconfig. (Default = auto)

  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.

  Note: Fontconfig is used only by the HarfBuzz command-line utilities, and not by the HarfBuzz library.

--with-icu

  Use the ICU library. (Default = auto)

  This option enables or disables usage of the International Components for Unicode (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.

--with-ucdn

  Use HarfBuzz's built-in UCDN library. (Default = auto)

  The HarfBuzz source tree includes a Unicode Database and Normalization (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.

--with-graphite2

  Use the Graphite2 library. (Default = no)

  This option enables or disables usage of the Graphite2 library, which provides support for the Graphite shaping model.

--with-freetype

  Use the FreeType library. (Default = auto)

  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.

--with-uniscribe

  Use the Uniscribe library (experimental). (Default = no)

  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.

--with-directwrite

  Use the DirectWrite library (experimental). (Default = no)

  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.

--with-coretext

  Use the CoreText library. (Default = no)

  This option enables or disables usage of the CoreText library. CoreText is available on macOS and iOS systems.