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