docs/usermanual-install-harfbuzz.xml

   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&ndash;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-ucdn</command></term>
 335           <listitem>
 336             <para>
 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>
 338             </para>
 339             <para>
 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
 346               library is desired.
 347             </para>
 348           </listitem>
 349         </varlistentry>
 350
 351         <varlistentry>
 352           <term><command>--with-graphite2</command></term>
 353           <listitem>
 354             <para>
 355               Use the <ulink url="http://graphite.sil.org/">Graphite2</ulink> library. <emphasis>(Default = no)</emphasis>
 356             </para>
 357             <para>
 358               This option enables or disables usage of the Graphite2
 359               library, which provides support for the Graphite shaping
 360               model.
 361             </para>
 362           </listitem>
 363         </varlistentry>
 364
 365         <varlistentry>
 366           <term><command>--with-freetype</command></term>
 367           <listitem>
 368             <para>
 369               Use the <ulink url="https://www.freetype.org/">FreeType</ulink> library. <emphasis>(Default = auto)</emphasis>
 370             </para>
 371             <para>
 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
 375               FreeType support.
 376             </para>
 377           </listitem>
 378         </varlistentry>
 379
 380         <varlistentry>
 381           <term><command>--with-uniscribe</command></term>
 382           <listitem>
 383             <para>
 384               Use the <ulink
 385               url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink>
 386               library (experimental). <emphasis>(Default = no)</emphasis>
 387             </para>
 388             <para>
 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.
 394             </para>
 395           </listitem>
 396         </varlistentry>
 397
 398         <varlistentry>
 399           <term><command>--with-directwrite</command></term>
 400           <listitem>
 401             <para>
 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>
 403             </para>
 404             <para>
 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.
 410             </para>
 411           </listitem>
 412         </varlistentry>
 413
 414         <varlistentry>
 415           <term><command>--with-coretext</command></term>
 416           <listitem>
 417             <para>
 418               Use the <ulink url="https://developer.apple.com/documentation/coretext">CoreText</ulink> library. <emphasis>(Default = no)</emphasis>
 419             </para>
 420             <para>
 421               This option enables or disables usage of the CoreText
 422               library. CoreText is available on macOS and iOS systems.
 423             </para>
 424           </listitem>
 425         </varlistentry>
 426
 427         <varlistentry>
 428           <term><command>--enable-gtk-doc</command></term>
 429           <listitem>
 430             <para>
 431               Use <ulink url="https://www.gtk.org/gtk-doc/">GTK-Doc</ulink>. <emphasis>(Default = no)</emphasis>
 432             </para>
 433             <para>
 434               This option enables the building of the documentation.
 435             </para>
 436           </listitem>
 437         </varlistentry>
 438       </variablelist>
 439     </section>
 440
 441   </section>
 442 </chapter>