1<?xml version="1.0"?> 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"> 6]> 7<chapter id="install-harfbuzz"> 8 <title>Installing HarfBuzz</title> 9 10 <section id="download"> 11 <title id="download.title">Downloading HarfBuzz</title> 12 <para> 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 16 <ulink 17 url="http://cgit.freedesktop.org/harfbuzz/">Freedesktop.org</ulink> 18 site. 19 </para> 20 <para> 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> 25 or from 26 <ulink url="http://www.freedesktop.org/software/harfbuzz/release/">Freedesktop.org</ulink>. 27 </para> 28 <para> 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 34 mailing list</ulink>. 35 </para> 36 <para> 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. 43 </para> 44 </section> 45 46 <section id="building"> 47 <title>Building HarfBuzz</title> 48 49 <section id="building.linux"> 50 <title>Building on Linux</title> 51 <para> 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. 56 </para> 57 <para> 58 For example, on an Ubuntu or Debian system, you would run: 59 <programlisting> 60 <command>sudo apt install</command> <package>gcc g++ 61 libfreetype6-dev libglib2.0-dev libcairo2-dev</package> 62 </programlisting> 63 On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run: 64 <programlisting> 65 <command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package> 66 </programlisting> 67 68 </para> 69 70 <para> 71 <emphasis>(2)</emphasis> The next step depends on whether you 72 are building from the source in a downloaded release tarball or 73 from the source directly from the git repository. 74 </para> 75 <para> 76 <emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz 77 source code in a tarball, you can now extract the source. 78 </para> 79 <para> 80 From a shell in the top-level directory of the extracted source 81 code, you can run <command>./configure</command> followed by 82 <command>make</command> as with any other standard package. 83 </para> 84 <para> 85 This should leave you with a shared 86 library in the <filename>src/</filename> directory, and a few 87 utility programs including <command>hb-view</command> and 88 <command>hb-shape</command> under the <filename>util/</filename> 89 directory. 90 </para> 91 <para> 92 <emphasis>(2)(b)</emphasis> If you are building from the source in the HarfBuzz git 93 repository, rather than installing from a downloaded tarball 94 release, then you must install two more auxiliary tools before you 95 can build for the first time: <package>pkg-config</package> and 96 <ulink url="http://www.complang.org/ragel/">ragel</ulink>. 97 </para> 98 <para> 99 On Ubuntu or Debian, run: 100 <programlisting> 101 <command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package> 102 </programlisting> 103 On Fedora, RHEL, CentOS, run: 104 <programlisting> 105 <command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package> 106 </programlisting> 107 108 </para> 109 <para> 110 With <package>pkg-config</package> and <package>ragel</package> 111 installed, you can now run <command>./autogen.sh</command>, 112 followed by <command>./configure</command> and 113 <command>make</command> to build HarfBuzz. 114 </para> 115 </section> 116 117 118 <section id="building.windows"> 119 <title>Building on Windows</title> 120 121 <para> 122 On Windows, consider using Microsoft's free <ulink 123 url="https://github.com/Microsoft/vcpkg">vcpkg</ulink> utility 124 to build HarfBuzz, its dependencies, and other open-source 125 libraries. 126 </para> 127 <para> 128 If you need to build HarfBuzz from source, first put the 129 <program>ragel</program> binary on your 130 <literal>PATH</literal>, then follow the appveyor CI cmake 131 <ulink 132 url="https://github.com/harfbuzz/harfbuzz/blob/master/appveyor.yml">build 133 instructions</ulink>. 134 </para> 135 </section> 136 137 138 <section id="building.macos"> 139 <title>Building on macOS</title> 140 141 <para> 142 There are two ways to build HarfBuzz on Mac systems: MacPorts 143 and Homebrew. The process is similar to the process used on a 144 Linux system. 145 </para> 146 <para> 147 <emphasis>(1)</emphasis> You must first install the 148 development packages for FreeType, Cairo, and GLib. If you are 149 using MacPorts, you should run: 150 <programlisting> 151 <command>sudo port install</command> <package>freetype glib2 cairo</package> 152 </programlisting> 153 </para> 154 <para> 155 If you are using Homebrew, you should run: 156 <programlisting> 157 <command>brew install</command> <package>freetype glib cairo</package> 158 </programlisting> 159 </para> 160 <para> 161 <emphasis>(2)</emphasis> The next step depends on whether you are building from the 162 source in a downloaded release tarball or from the source directly 163 from the git repository. 164 </para> 165 <para> 166 <emphasis>(2)(a)</emphasis> If you are installing HarfBuzz 167 from a downloaded tarball release, extract the tarball and 168 open a Terminal in the extracted source-code directory. Run: 169 <programlisting> 170 <command>./configure</command> 171 </programlisting> 172 followed by: 173 <programlisting> 174 <command>make</command> 175 </programlisting> 176 to build HarfBuzz. 177 </para> 178 <para> 179 <emphasis>(2)(b)</emphasis> Alternatively, if you are building 180 HarfBuzz from the source in the HarfBuzz git repository, then 181 you must install several built-time dependencies before 182 proceeding. 183 </para> 184 <para>If you are 185 using MacPorts, you should run: 186 <programlisting> 187 <command>sudo port install</command> <package>autoconf 188 automake libtool pkgconfig ragel gtk-doc</package> 189 </programlisting> 190 to install the build dependencies. 191 </para> 192 <para>If you are using Homebrew, you should run: 193 <programlisting> 194 <command>brew install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package> 195 </programlisting> 196 Finally, you can run: 197 <programlisting> 198 <command>./autogen.sh</command> 199 </programlisting> 200 </para> 201 <para> 202 <emphasis>(3)</emphasis> You can now build HarfBuzz (on either 203 a MacPorts or a Homebrew system) by running: 204 <programlisting> 205 <command>./configure</command> 206 </programlisting> 207 followed by: 208 <programlisting> 209 <command>make</command> 210 </programlisting> 211 </para> 212 <para> 213 This should leave you with a shared 214 library in the <filename>src/</filename> directory, and a few 215 utility programs including <command>hb-view</command> and 216 <command>hb-shape</command> under the <filename>util/</filename> 217 directory. 218 </para> 219 220 </section> 221 222 <section id="configuration"> 223 <title>Configuration options</title> 224 225 <para> 226 The instructions in the "Building HarfBuzz" section will build 227 the source code under its default configuration. If needed, 228 the following additional configuration options are available. 229 </para> 230 231 <variablelist> 232 <varlistentry> 233 <term>--with-libstdc++</term> 234 <listitem> 235 <para> 236 Allow linking with libstdc++. <emphasis>(Default = no)</emphasis> 237 </para> 238 <para> 239 This option enables or disables linking HarfBuzz to the 240 system's libstdc++ library. 241 </para> 242 </listitem> 243 </varlistentry> 244 245 <varlistentry> 246 <term>--with-glib</term> 247 <listitem> 248 <para> 249 Use <ulink url="https://developer.gnome.org/glib/">GLib</ulink>. <emphasis>(Default = auto)</emphasis> 250 </para> 251 <para> 252 This option enables or disables usage of the GLib 253 library. The default setting is to check for the 254 presence of GLib and, if it is found, build with 255 GLib support. GLib is native to GNU/Linux systems but is 256 available on other operating system as well. 257 </para> 258 </listitem> 259 </varlistentry> 260 261 <varlistentry> 262 <term>--with-gobject</term> 263 <listitem> 264 <para> 265 Use <ulink url="https://developer.gnome.org/gobject/stable/">GObject</ulink>. <emphasis>(Default = no)</emphasis> 266 </para> 267 <para> 268 This option enables or disables usage of the GObject 269 library. The default setting is to check for the 270 presence of GObject and, if it is found, build with 271 GObject support. GObject is native to GNU/Linux systems but is 272 available on other operating system as well. 273 </para> 274 </listitem> 275 </varlistentry> 276 277 <varlistentry> 278 <term>--with-cairo</term> 279 <listitem> 280 <para> 281 Use <ulink url="https://cairographics.org/">Cairo</ulink>. <emphasis>(Default = auto)</emphasis> 282 </para> 283 <para> 284 This option enables or disables usage of the Cairo 285 graphics-rendering library. The default setting is to 286 check for the presence of Cairo and, if it is found, 287 build with Cairo support. 288 </para> 289 <para> 290 Note: Cairo is used only by the HarfBuzz 291 command-line utilities, and not by the HarfBuzz library. 292 </para> 293 </listitem> 294 </varlistentry> 295 296 <varlistentry> 297 <term>--with-fontconfig</term> 298 <listitem> 299 <para> 300 Use <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">Fontconfig</ulink>. <emphasis>(Default = auto)</emphasis> 301 </para> 302 <para> 303 This option enables or disables usage of the Fontconfig 304 library, which provides font-matching functions and 305 provides access to font properties. The default setting 306 is to check for the presence of Fontconfig and, if it is 307 found, build with Fontconfig support. 308 </para> 309 <para> 310 Note: Fontconfig is used only by the HarfBuzz 311 command-line utilities, and not by the HarfBuzz library. 312 </para> 313 </listitem> 314 </varlistentry> 315 316 <varlistentry> 317 <term>--with-icu</term> 318 <listitem> 319 <para> 320 Use the <ulink url="http://site.icu-project.org/home">ICU</ulink> library. <emphasis>(Default = auto)</emphasis> 321 </para> 322 <para> 323 This option enables or disables usage of the 324 <emphasis>International Components for 325 Unicode</emphasis> (ICU) library, which provides access 326 to Unicode Character Database (UCD) properties as well 327 as normalization and conversion functions. The default 328 setting is to check for the presence of ICU and, if it 329 is found, build with ICU support. 330 </para> 331 </listitem> 332 </varlistentry> 333 334 <varlistentry> 335 <term>--with-ucdn</term> 336 <listitem> 337 <para> 338 Use HarfBuzz's <ulink url="https://github.com/harfbuzz/harfbuzz/tree/master/src/hb-ucdn">built-in UCDN library</ulink>. <emphasis>(Default = auto)</emphasis> 339 </para> 340 <para> 341 The HarfBuzz source tree includes a <emphasis>Unicode 342 Database and Normalization</emphasis> (UCDN) library 343 that provides access to basic character properties in 344 the Unicode Character Database (UCD) as well as low-level 345 normalization functions. HarfBuzz can be built without 346 this UCDN support if the usage of a different UCDN 347 library is desired. 348 </para> 349 </listitem> 350 </varlistentry> 351 352 <varlistentry> 353 <term>--with-graphite2</term> 354 <listitem> 355 <para> 356 Use the <ulink url="http://graphite.sil.org/">Graphite2</ulink> library. <emphasis>(Default = no)</emphasis> 357 </para> 358 <para> 359 This option enables or disables usage of the Graphite2 360 library, which provides support for the Graphite shaping 361 model. 362 </para> 363 </listitem> 364 </varlistentry> 365 366 <varlistentry> 367 <term>--with-freetype</term> 368 <listitem> 369 <para> 370 Use the <ulink url="https://www.freetype.org/">FreeType</ulink> library. <emphasis>(Default = auto)</emphasis> 371 </para> 372 <para> 373 This option enables or disables usage of the FreeType 374 font-rendering library. The default setting is to check for the 375 presence of FreeType and, if it is found, build with 376 FreeType support. 377 </para> 378 </listitem> 379 </varlistentry> 380 381 <varlistentry> 382 <term>--with-uniscribe</term> 383 <listitem> 384 <para> 385 Use the <ulink 386 url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink> 387 library (experimental). <emphasis>(Default = no)</emphasis> 388 </para> 389 <para> 390 This option enables or disables usage of the Uniscribe 391 font-rendering library. Uniscribe is available on 392 Windows systems. Uniscribe support is used only for 393 testing purposes and does not need to be enabled for 394 HarfBuzz to run on Windows systems. 395 </para> 396 </listitem> 397 </varlistentry> 398 399 <varlistentry> 400 <term>--with-directwrite</term> 401 <listitem> 402 <para> 403 Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/directwrite/direct-write-portal">DirectWrite</ulink> library (experimental). <emphasis>(Default = no)</emphasis> 404 </para> 405 <para> 406 This option enables or disables usage of the DirectWrite 407 font-rendering library. DirectWrite is available on 408 Windows systems. DirectWrite support is used only for 409 testing purposes and does not need to be enabled for 410 HarfBuzz to run on Windows systems. 411 </para> 412 </listitem> 413 </varlistentry> 414 415 <varlistentry> 416 <term>--with-coretext</term> 417 <listitem> 418 <para> 419 Use the <ulink url="https://developer.apple.com/documentation/coretext">CoreText</ulink> library. <emphasis>(Default = no)</emphasis> 420 </para> 421 <para> 422 This option enables or disables usage of the CoreText 423 library. CoreText is available on macOS and iOS systems. 424 </para> 425 </listitem> 426 </varlistentry> 427 </variablelist> 428 </section> 429 430 </section> 431</chapter> 432