2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
4 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
5 <!ENTITY version SYSTEM "version.xml">
7 <chapter id="install-harfbuzz">
8 <title>Installing HarfBuzz</title>
10 <section id="download">
11 <title id="download.title">Downloading HarfBuzz</title>
13 The HarfBuzz source code is hosted at <ulink
14 url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>. The
15 same source tree is also available at the
17 url="http://cgit.freedesktop.org/harfbuzz/">Freedesktop.org</ulink>
21 Tarball releases and Win32 binary bundles (which include the
22 libharfbuzz DLL, hb-view.exe, hb-shape.exe, and all
23 dependencies) of HarfBuzz can be downloaded from <ulink
24 url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz/releases</ulink>
26 <ulink url="http://www.freedesktop.org/software/harfbuzz/release/">Freedesktop.org</ulink>.
29 Release notes are posted with each new release to provide an
30 overview of the changes. The project <ulink url="https://github.com/harfbuzz/harfbuzz/issues">tracks bug
31 reports and other issues</ulink> on GitHub. Discussion and
32 questions are welcome on the <ulink
33 url="http://freedesktop.org/mailman/listinfo/harfbuzz/">HarfBuzz
37 The API included in the <filename
38 class='headerfile'>hb.h</filename> file will not change in a
39 compatibility-breaking way in any release. However, other,
40 peripheral headers are more likely to go through minor
41 modifications. We will do our best to never change APIs in an
42 incompatible way. We will <emphasis>never</emphasis> break the ABI.
46 <section id="building">
47 <title>Building HarfBuzz</title>
49 <section id="building.linux">
50 <title>Building on Linux</title>
52 <emphasis>(1)</emphasis> To build HarfBuzz on Linux, you must first install the
53 development packages for FreeType, Cairo, and GLib. The exact
54 commands required for this step will vary depending on
55 the Linux distribution you use.
58 For example, on an Ubuntu or Debian system, you would run:
60 <command>sudo apt install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
62 On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run:
64 <command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
70 <emphasis>(2)</emphasis> The next step depends on whether you
71 are building from the source in a downloaded release tarball or
72 from the source directly from the git repository.
75 <emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz
76 source code in a tarball, you can now extract the source.
79 From a shell in the top-level directory of the extracted source
80 code, you can run <command>./configure</command> followed by
81 <command>make</command> as with any other standard package.
84 This should leave you with a shared
85 library in the <filename>src/</filename> directory, and a few
86 utility programs including <command>hb-view</command> and
87 <command>hb-shape</command> under the <filename>util/</filename>
91 <emphasis>(2)(b)</emphasis> If you are building from the source in the HarfBuzz git
92 repository, rather than installing from a downloaded tarball
93 release, then you must install two more auxiliary tools before you
94 can build for the first time: <package>pkg-config</package> and
95 <ulink url="http://www.complang.org/ragel/">ragel</ulink>.
98 On Ubuntu or Debian, run:
100 <command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
102 On Fedora, RHEL, CentOS, run:
104 <command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
109 With <package>pkg-config</package> and <package>ragel</package>
110 installed, you can now run <command>./autogen.sh</command>,
111 followed by <command>./configure</command> and
112 <command>make</command> to build HarfBuzz.
117 <section id="building.windows">
118 <title>Building on Windows</title>
121 On Windows, consider using Microsoft's free <ulink
122 url="https://github.com/Microsoft/vcpkg">vcpkg</ulink> utility
123 to build HarfBuzz, its dependencies, and other open-source
127 If you need to build HarfBuzz from source, first put the
128 <package>ragel</package> binary on your
129 <literal>PATH</literal>, then follow the appveyor CI cmake
131 url="https://github.com/harfbuzz/harfbuzz/blob/master/appveyor.yml">build
132 instructions</ulink>.
137 <section id="building.macos">
138 <title>Building on macOS</title>
141 There are two ways to build HarfBuzz on Mac systems: MacPorts
142 and Homebrew. The process is similar to the process used on a
146 <emphasis>(1)</emphasis> You must first install the
147 development packages for FreeType, Cairo, and GLib. If you are
148 using MacPorts, you should run:
150 <command>sudo port install</command> <package>freetype glib2 cairo</package>
154 If you are using Homebrew, you should run:
156 <command>brew install</command> <package>freetype glib cairo</package>
160 <emphasis>(2)</emphasis> The next step depends on whether you are building from the
161 source in a downloaded release tarball or from the source directly
162 from the git repository.
165 <emphasis>(2)(a)</emphasis> If you are installing HarfBuzz
166 from a downloaded tarball release, extract the tarball and
167 open a Terminal in the extracted source-code directory. Run:
169 <command>./configure</command>
173 <command>make</command>
178 <emphasis>(2)(b)</emphasis> Alternatively, if you are building
179 HarfBuzz from the source in the HarfBuzz git repository, then
180 you must install several built-time dependencies before
184 using MacPorts, you should run:
186 <command>sudo port install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
188 to install the build dependencies.
190 <para>If you are using Homebrew, you should run:
192 <command>brew install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
194 Finally, you can run:
196 <command>./autogen.sh</command>
200 <emphasis>(3)</emphasis> You can now build HarfBuzz (on either
201 a MacPorts or a Homebrew system) by running:
203 <command>./configure</command>
207 <command>make</command>
211 This should leave you with a shared
212 library in the <filename>src/</filename> directory, and a few
213 utility programs including <command>hb-view</command> and
214 <command>hb-shape</command> under the <filename>util/</filename>
220 <section id="configuration">
221 <title>Configuration options</title>
224 The instructions in the "Building HarfBuzz" section will build
225 the source code under its default configuration. If needed,
226 the following additional configuration options are available.
230 <?dbfo list-presentation="blocks"?>
232 <term><command>--with-libstdc++</command></term>
235 Allow linking with libstdc++. <emphasis>(Default = no)</emphasis>
238 This option enables or disables linking HarfBuzz to the
239 system's libstdc++ library.
245 <term><command>--with-glib</command></term>
248 Use <ulink url="https://developer.gnome.org/glib/">GLib</ulink>. <emphasis>(Default = auto)</emphasis>
251 This option enables or disables usage of the GLib
252 library. The default setting is to check for the
253 presence of GLib and, if it is found, build with
254 GLib support. GLib is native to GNU/Linux systems but is
255 available on other operating system as well.
261 <term><command>--with-gobject</command></term>
264 Use <ulink url="https://developer.gnome.org/gobject/stable/">GObject</ulink>. <emphasis>(Default = no)</emphasis>
267 This option enables or disables usage of the GObject
268 library. The default setting is to check for the
269 presence of GObject and, if it is found, build with
270 GObject support. GObject is native to GNU/Linux systems but is
271 available on other operating system as well.
277 <term><command>--with-cairo</command></term>
280 Use <ulink url="https://cairographics.org/">Cairo</ulink>. <emphasis>(Default = auto)</emphasis>
283 This option enables or disables usage of the Cairo
284 graphics-rendering library. The default setting is to
285 check for the presence of Cairo and, if it is found,
286 build with Cairo support.
289 Note: Cairo is used only by the HarfBuzz
290 command-line utilities, and not by the HarfBuzz library.
296 <term><command>--with-fontconfig</command></term>
299 Use <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">Fontconfig</ulink>. <emphasis>(Default = auto)</emphasis>
302 This option enables or disables usage of the Fontconfig
303 library, which provides font-matching functions and
304 provides access to font properties. The default setting
305 is to check for the presence of Fontconfig and, if it is
306 found, build with Fontconfig support.
309 Note: Fontconfig is used only by the HarfBuzz
310 command-line utilities, and not by the HarfBuzz library.
316 <term><command>--with-icu</command></term>
319 Use the <ulink url="http://site.icu-project.org/home">ICU</ulink> library. <emphasis>(Default = auto)</emphasis>
322 This option enables or disables usage of the
323 <emphasis>International Components for
324 Unicode</emphasis> (ICU) library, which provides access
325 to Unicode Character Database (UCD) properties as well
326 as normalization and conversion functions. The default
327 setting is to check for the presence of ICU and, if it
328 is found, build with ICU support.
334 <term><command>--with-ucdn</command></term>
337 Use HarfBuzz's <ulink url="https://github.com/harfbuzz/harfbuzz/tree/master/src/hb-ucdn">built-in UCDN library</ulink>. <emphasis>(Default = auto)</emphasis>
340 The HarfBuzz source tree includes a <emphasis>Unicode
341 Database and Normalization</emphasis> (UCDN) library
342 that provides access to basic character properties in
343 the Unicode Character Database (UCD) as well as low-level
344 normalization functions. HarfBuzz can be built without
345 this UCDN support if the usage of a different UCDN
352 <term><command>--with-graphite2</command></term>
355 Use the <ulink url="http://graphite.sil.org/">Graphite2</ulink> library. <emphasis>(Default = no)</emphasis>
358 This option enables or disables usage of the Graphite2
359 library, which provides support for the Graphite shaping
366 <term><command>--with-freetype</command></term>
369 Use the <ulink url="https://www.freetype.org/">FreeType</ulink> library. <emphasis>(Default = auto)</emphasis>
372 This option enables or disables usage of the FreeType
373 font-rendering library. The default setting is to check for the
374 presence of FreeType and, if it is found, build with
381 <term><command>--with-uniscribe</command></term>
385 url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink>
386 library (experimental). <emphasis>(Default = no)</emphasis>
389 This option enables or disables usage of the Uniscribe
390 font-rendering library. Uniscribe is available on
391 Windows systems. Uniscribe support is used only for
392 testing purposes and does not need to be enabled for
393 HarfBuzz to run on Windows systems.
399 <term><command>--with-directwrite</command></term>
402 Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/directwrite/direct-write-portal">DirectWrite</ulink> library (experimental). <emphasis>(Default = no)</emphasis>
405 This option enables or disables usage of the DirectWrite
406 font-rendering library. DirectWrite is available on
407 Windows systems. DirectWrite support is used only for
408 testing purposes and does not need to be enabled for
409 HarfBuzz to run on Windows systems.
415 <term><command>--with-coretext</command></term>
418 Use the <ulink url="https://developer.apple.com/documentation/coretext">CoreText</ulink> library. <emphasis>(Default = no)</emphasis>
421 This option enables or disables usage of the CoreText
422 library. CoreText is available on macOS and iOS systems.