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++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package> 61 </programlisting> 62 On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run: 63 <programlisting> 64 <command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package> 65 </programlisting> 66 67 </para> 68 69 <para> 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. 73 </para> 74 <para> 75 <emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz 76 source code in a tarball, you can now extract the source. 77 </para> 78 <para> 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. 82 </para> 83 <para> 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> 88 directory. 89 </para> 90 <para> 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>. 96 </para> 97 <para> 98 On Ubuntu or Debian, run: 99 <programlisting> 100 <command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package> 101 </programlisting> 102 On Fedora, RHEL, CentOS, run: 103 <programlisting> 104 <command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package> 105 </programlisting> 106 107 </para> 108 <para> 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. 113 </para> 114 </section> 115 116 117 <section id="building.windows"> 118 <title>Building on Windows</title> 119 120 <para> 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 124 libraries. 125 </para> 126 <para> 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 130 <ulink 131 url="https://github.com/harfbuzz/harfbuzz/blob/master/appveyor.yml">build 132 instructions</ulink>. 133 </para> 134 </section> 135 136 137 <section id="building.macos"> 138 <title>Building on macOS</title> 139 140 <para> 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 143 Linux system. 144 </para> 145 <para> 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: 149 <programlisting> 150 <command>sudo port install</command> <package>freetype glib2 cairo</package> 151 </programlisting> 152 </para> 153 <para> 154 If you are using Homebrew, you should run: 155 <programlisting> 156 <command>brew install</command> <package>freetype glib cairo</package> 157 </programlisting> 158 </para> 159 <para> 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. 163 </para> 164 <para> 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: 168 <programlisting> 169 <command>./configure</command> 170 </programlisting> 171 followed by: 172 <programlisting> 173 <command>make</command> 174 </programlisting> 175 to build HarfBuzz. 176 </para> 177 <para> 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 181 proceeding. 182 </para> 183 <para>If you are 184 using MacPorts, you should run: 185 <programlisting> 186 <command>sudo port install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package> 187 </programlisting> 188 to install the build dependencies. 189 </para> 190 <para>If you are using Homebrew, you should run: 191 <programlisting> 192 <command>brew install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package> 193 </programlisting> 194 Finally, you can run: 195 <programlisting> 196 <command>./autogen.sh</command> 197 </programlisting> 198 </para> 199 <para> 200 <emphasis>(3)</emphasis> You can now build HarfBuzz (on either 201 a MacPorts or a Homebrew system) by running: 202 <programlisting> 203 <command>./configure</command> 204 </programlisting> 205 followed by: 206 <programlisting> 207 <command>make</command> 208 </programlisting> 209 </para> 210 <para> 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> 215 directory. 216 </para> 217 218 </section> 219 220 <section id="configuration"> 221 <title>Configuration options</title> 222 223 <para> 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. 227 </para> 228 229 <variablelist> 230 <?dbfo list-presentation="blocks"?> 231 <varlistentry> 232 <term><command>--with-libstdc++</command></term> 233 <listitem> 234 <para> 235 Allow linking with libstdc++. <emphasis>(Default = no)</emphasis> 236 </para> 237 <para> 238 This option enables or disables linking HarfBuzz to the 239 system's libstdc++ library. 240 </para> 241 </listitem> 242 </varlistentry> 243 244 <varlistentry> 245 <term><command>--with-glib</command></term> 246 <listitem> 247 <para> 248 Use <ulink url="https://developer.gnome.org/glib/">GLib</ulink>. <emphasis>(Default = auto)</emphasis> 249 </para> 250 <para> 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. 256 </para> 257 </listitem> 258 </varlistentry> 259 260 <varlistentry> 261 <term><command>--with-gobject</command></term> 262 <listitem> 263 <para> 264 Use <ulink url="https://developer.gnome.org/gobject/stable/">GObject</ulink>. <emphasis>(Default = no)</emphasis> 265 </para> 266 <para> 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. 272 </para> 273 </listitem> 274 </varlistentry> 275 276 <varlistentry> 277 <term><command>--with-cairo</command></term> 278 <listitem> 279 <para> 280 Use <ulink url="https://cairographics.org/">Cairo</ulink>. <emphasis>(Default = auto)</emphasis> 281 </para> 282 <para> 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. 287 </para> 288 <para> 289 Note: Cairo is used only by the HarfBuzz 290 command-line utilities, and not by the HarfBuzz library. 291 </para> 292 </listitem> 293 </varlistentry> 294 295 <varlistentry> 296 <term><command>--with-fontconfig</command></term> 297 <listitem> 298 <para> 299 Use <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">Fontconfig</ulink>. <emphasis>(Default = auto)</emphasis> 300 </para> 301 <para> 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. 307 </para> 308 <para> 309 Note: Fontconfig is used only by the HarfBuzz 310 command-line utilities, and not by the HarfBuzz library. 311 </para> 312 </listitem> 313 </varlistentry> 314 315 <varlistentry> 316 <term><command>--with-icu</command></term> 317 <listitem> 318 <para> 319 Use the <ulink url="http://site.icu-project.org/home">ICU</ulink> library. <emphasis>(Default = auto)</emphasis> 320 </para> 321 <para> 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. 329 </para> 330 </listitem> 331 </varlistentry> 332 333 <varlistentry> 334 <term><command>--with-graphite2</command></term> 335 <listitem> 336 <para> 337 Use the <ulink url="http://graphite.sil.org/">Graphite2</ulink> library. <emphasis>(Default = no)</emphasis> 338 </para> 339 <para> 340 This option enables or disables usage of the Graphite2 341 library, which provides support for the Graphite shaping 342 model. 343 </para> 344 </listitem> 345 </varlistentry> 346 347 <varlistentry> 348 <term><command>--with-freetype</command></term> 349 <listitem> 350 <para> 351 Use the <ulink url="https://www.freetype.org/">FreeType</ulink> library. <emphasis>(Default = auto)</emphasis> 352 </para> 353 <para> 354 This option enables or disables usage of the FreeType 355 font-rendering library. The default setting is to check for the 356 presence of FreeType and, if it is found, build with 357 FreeType support. 358 </para> 359 </listitem> 360 </varlistentry> 361 362 <varlistentry> 363 <term><command>--with-uniscribe</command></term> 364 <listitem> 365 <para> 366 Use the <ulink 367 url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink> 368 library (experimental). <emphasis>(Default = no)</emphasis> 369 </para> 370 <para> 371 This option enables or disables usage of the Uniscribe 372 font-rendering library. Uniscribe is available on 373 Windows systems. Uniscribe support is used only for 374 testing purposes and does not need to be enabled for 375 HarfBuzz to run on Windows systems. 376 </para> 377 </listitem> 378 </varlistentry> 379 380 <varlistentry> 381 <term><command>--with-directwrite</command></term> 382 <listitem> 383 <para> 384 Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/directwrite/direct-write-portal">DirectWrite</ulink> library (experimental). <emphasis>(Default = no)</emphasis> 385 </para> 386 <para> 387 This option enables or disables usage of the DirectWrite 388 font-rendering library. DirectWrite is available on 389 Windows systems. DirectWrite support is used only for 390 testing purposes and does not need to be enabled for 391 HarfBuzz to run on Windows systems. 392 </para> 393 </listitem> 394 </varlistentry> 395 396 <varlistentry> 397 <term><command>--with-coretext</command></term> 398 <listitem> 399 <para> 400 Use the <ulink url="https://developer.apple.com/documentation/coretext">CoreText</ulink> library. <emphasis>(Default = no)</emphasis> 401 </para> 402 <para> 403 This option enables or disables usage of the CoreText 404 library. CoreText is available on macOS and iOS systems. 405 </para> 406 </listitem> 407 </varlistentry> 408 409 <varlistentry> 410 <term><command>--enable-gtk-doc</command></term> 411 <listitem> 412 <para> 413 Use <ulink url="https://www.gtk.org/gtk-doc/">GTK-Doc</ulink>. <emphasis>(Default = no)</emphasis> 414 </para> 415 <para> 416 This option enables the building of the documentation. 417 </para> 418 </listitem> 419 </varlistentry> 420 </variablelist> 421 </section> 422 423 </section> 424</chapter> 425