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/releases">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 <ulink
  27       url="https://github.com/harfbuzz/harfbuzz/discussions">GitHub</ulink> as well.
  28     </para>
  29     <para>
  30       The API included in the <filename
  31       class='headerfile'>hb.h</filename> file will not change in a
  32       compatibility-breaking way in any release. However, other,
  33       peripheral headers are more likely to go through minor
  34       modifications. We will do our best to never change APIs in an
  35       incompatible way. We will <emphasis>never</emphasis> break the ABI.
  36     </para>
  37   </section>
  38
  39   <section id="building">
  40     <title>Building HarfBuzz</title>
  41
  42     <section id="building.linux">
  43       <title>Building on Linux</title>
  44     <para>
  45       <emphasis>(1)</emphasis> To build HarfBuzz on Linux, you must first install the
  46       development packages for FreeType, Cairo, and GLib. The exact
  47       commands required for this step will vary depending on
  48       the Linux distribution you use.
  49     </para>
  50     <para>
  51       For example, on an Ubuntu or Debian system, you would run:
  52       <programlisting><command>sudo apt install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package></programlisting>
  53       On Fedora, RHEL, CentOS, or other Red-Hat&ndash;based systems, you would run:
  54       <programlisting><command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package></programlisting>
  55
  56     </para>
  57
  58     <para>
  59       <emphasis>(2)</emphasis> The next step depends on whether you
  60       are building from the source in a downloaded release tarball or
  61       from the source directly from the git repository.
  62     </para>
  63     <para>
  64       <emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz
  65       source code in a tarball, you can now extract the source.
  66     </para>
  67     <para>
  68       From a shell in the top-level directory of the extracted source
  69       code, you can run <command>meson build</command> followed by
  70       <command>meson compile -C build</command> as with any other standard package.
  71     </para>
  72     <para>
  73       This should leave you with a shared
  74       library in the <filename>src/</filename> directory, and a few
  75       utility programs including <command>hb-view</command> and
  76       <command>hb-shape</command> under the <filename>util/</filename>
  77       directory.
  78     </para>
  79     <para>
  80       <emphasis>(2)(b)</emphasis> If you are building from the source in the HarfBuzz git
  81       repository, rather than installing from a downloaded tarball
  82       release, then you must install two more auxiliary tools before you
  83       can build for the first time: <package>pkg-config</package>.
  84     </para>
  85     <para>
  86       On Ubuntu or Debian, run:
  87       <programlisting><command>sudo apt-get install</command> <package>meson pkg-config gtk-doc-tools</package></programlisting>
  88       On Fedora, RHEL, CentOS, run:
  89       <programlisting><command>sudo yum install</command> <package>meson pkgconfig gtk-doc</package></programlisting>
  90
  91     </para>
  92     <para>
  93       With <package>pkg-config</package> installed, you can now run
  94       <command>meson build</command> then
  95       <command>meson compile -C build</command> to build HarfBuzz.
  96     </para>
  97     </section>
  98
  99
 100     <section id="building.windows">
 101       <title>Building on Windows</title>
 102
 103       <para>
 104         <ulink url="https://mesonbuild.com/Getting-meson.html">Install meson</ulink>
 105         and run (from the console) <command>meson build</command> (by default
 106         bundled dependencies are not built, <command>--wrap-mode=default</command>
 107         overrides this), then <command>meson compile -C build</command> to
 108         build HarfBuzz.
 109       </para>
 110     </section>
 111
 112
 113     <section id="building.macos">
 114       <title>Building on macOS</title>
 115
 116       <para>
 117         There are two ways to build HarfBuzz on Mac systems: MacPorts
 118         and Homebrew. The process is similar to the process used on a
 119         Linux system.
 120       </para>
 121       <para>
 122         <emphasis>(1)</emphasis> You must first install the
 123         development packages for FreeType, Cairo, and GLib. If you are
 124         using MacPorts, you should run:
 125       <programlisting><command>sudo port install</command> <package>freetype glib2 cairo</package></programlisting>
 126       </para>
 127       <para>
 128         If you are using Homebrew, you should run:
 129         <programlisting><command>brew install</command> <package>freetype glib cairo</package></programlisting>
 130       </para>
 131       <para>
 132         <emphasis>(2)</emphasis> The next step depends on whether you are building from the
 133         source in a downloaded release tarball or from the source directly
 134         from the git repository.
 135       </para>
 136       <para>
 137         <emphasis>(2)(a)</emphasis> If you are installing HarfBuzz
 138         from a downloaded tarball release, extract the tarball and
 139         open a Terminal in the extracted source-code directory. Run:
 140         <programlisting><command>meson build</command></programlisting>
 141         followed by:
 142         <programlisting><command>meson compile -C build</command></programlisting>
 143         to build HarfBuzz.
 144       </para>
 145       <para>
 146         <emphasis>(2)(b)</emphasis> Alternatively, if you are building
 147         HarfBuzz from the source in the HarfBuzz git repository, then
 148         you must install several built-time dependencies before
 149         proceeding.
 150       </para>
 151       <para>If you are
 152         using MacPorts, you should run:
 153       <programlisting><command>sudo port install</command> <package>meson pkgconfig gtk-doc</package></programlisting>
 154       to install the build dependencies.
 155       </para>
 156       <para>If you are using Homebrew, you should run:
 157         <programlisting><command>brew install</command> <package>meson pkgconfig gtk-doc</package></programlisting>
 158         Finally, you can run:
 159         <programlisting><command>meson build</command></programlisting>
 160       </para>
 161       <para>
 162         <emphasis>(3)</emphasis> You can now build HarfBuzz (on either
 163         a MacPorts or a Homebrew system) by running:
 164         <programlisting><command>meson build</command></programlisting>
 165         followed by:
 166         <programlisting><command>meson compile -C build</command></programlisting>
 167       </para>
 168       <para>
 169         This should leave you with a shared
 170         library in the <filename>src/</filename> directory, and a few
 171         utility programs including <command>hb-view</command> and
 172         <command>hb-shape</command> under the <filename>util/</filename>
 173         directory.
 174       </para>
 175
 176     </section>
 177
 178     <section id="configuration">
 179       <title>Configuration options</title>
 180
 181       <para>
 182         The instructions in the "Building HarfBuzz" section will build
 183         the source code under its default configuration. If needed,
 184         the following additional configuration options are available.
 185       </para>
 186
 187       <variablelist>
 188         <?dbfo list-presentation="blocks"?>
 189         <varlistentry>
 190           <term><command>-Dglib=enabled</command></term>
 191           <listitem>
 192             <para>
 193              Use <ulink url="https://developer.gnome.org/glib/">GLib</ulink>. <emphasis>(Default = auto)</emphasis>
 194             </para>
 195             <para>
 196               This option enables or disables usage of the GLib
 197               library.  The default setting is to check for the
 198               presence of GLib and, if it is found, build with
 199               GLib support. GLib is native to GNU/Linux systems but is
 200               available on other operating system as well.
 201             </para>
 202           </listitem>
 203         </varlistentry>
 204
 205         <varlistentry>
 206           <term><command>-Dgobject=enabled</command></term>
 207           <listitem>
 208             <para>
 209               Use <ulink url="https://developer.gnome.org/gobject/stable/">GObject</ulink>. <emphasis>(Default = no)</emphasis>
 210             </para>
 211             <para>
 212               This option enables or disables usage of the GObject
 213               library. The default setting is to check for the
 214               presence of GObject and, if it is found, build with
 215               GObject support. GObject is native to GNU/Linux systems but is
 216               available on other operating system as well.
 217             </para>
 218           </listitem>
 219         </varlistentry>
 220
 221         <varlistentry>
 222           <term><command>-Dcairo=enabled</command></term>
 223           <listitem>
 224             <para>
 225               Use <ulink url="https://cairographics.org/">Cairo</ulink>. <emphasis>(Default = auto)</emphasis>
 226             </para>
 227             <para>
 228               This option enables or disables usage of the Cairo
 229               graphics-rendering library. The default setting is to
 230               check for the presence of Cairo and, if it is found,
 231               build with Cairo support.
 232             </para>
 233             <para>
 234               Note: Cairo is used only by the HarfBuzz
 235               command-line utilities, and not by the HarfBuzz library.
 236             </para>
 237           </listitem>
 238         </varlistentry>
 239
 240         <varlistentry>
 241           <term><command>-Dicu=enabled</command></term>
 242           <listitem>
 243             <para>
 244               Use the <ulink url="http://site.icu-project.org/home">ICU</ulink> library. <emphasis>(Default = auto)</emphasis>
 245             </para>
 246             <para>
 247               This option enables or disables usage of the
 248               <emphasis>International Components for
 249               Unicode</emphasis> (ICU) library, which provides access
 250               to Unicode Character Database (UCD) properties as well
 251               as normalization and conversion functions. The default
 252               setting is to check for the presence of ICU and, if it
 253               is found, build with ICU support.
 254             </para>
 255           </listitem>
 256         </varlistentry>
 257
 258         <varlistentry>
 259           <term><command>-Dgraphite=enabled</command></term>
 260           <listitem>
 261             <para>
 262               Use the <ulink url="http://graphite.sil.org/">Graphite2</ulink> library. <emphasis>(Default = no)</emphasis>
 263             </para>
 264             <para>
 265               This option enables or disables usage of the Graphite2
 266               library, which provides support for the Graphite shaping
 267               model.
 268             </para>
 269           </listitem>
 270         </varlistentry>
 271
 272         <varlistentry>
 273           <term><command>-Dfreetype=enabled</command></term>
 274           <listitem>
 275             <para>
 276               Use the <ulink url="https://www.freetype.org/">FreeType</ulink> library. <emphasis>(Default = auto)</emphasis>
 277             </para>
 278             <para>
 279               This option enables or disables usage of the FreeType
 280               font-rendering library. The default setting is to check for the
 281               presence of FreeType and, if it is found, build with
 282               FreeType support.
 283             </para>
 284           </listitem>
 285         </varlistentry>
 286
 287         <varlistentry>
 288           <term><command>-Dgdi=enabled</command></term>
 289           <listitem>
 290             <para>
 291               Use the <ulink
 292               url="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe">Uniscribe</ulink>
 293               library (experimental). <emphasis>(Default = no)</emphasis>
 294             </para>
 295             <para>
 296               This option enables or disables usage of the Uniscribe
 297               font-rendering library. Uniscribe is available on
 298               Windows systems. Uniscribe support is used only for
 299               testing purposes and does not need to be enabled for
 300               HarfBuzz to run on Windows systems.
 301             </para>
 302           </listitem>
 303         </varlistentry>
 304
 305         <varlistentry>
 306           <term><command>-Ddirectwrite=enabled</command></term>
 307           <listitem>
 308             <para>
 309               Use the <ulink url="https://docs.microsoft.com/en-us/windows/desktop/directwrite/direct-write-portal">DirectWrite</ulink> library (experimental). <emphasis>(Default = no)</emphasis>
 310             </para>
 311             <para>
 312               This option enables or disables usage of the DirectWrite
 313               font-rendering library. DirectWrite is available on
 314               Windows systems. DirectWrite support is used only for
 315               testing purposes and does not need to be enabled for
 316               HarfBuzz to run on Windows systems.
 317             </para>
 318           </listitem>
 319         </varlistentry>
 320
 321         <varlistentry>
 322           <term><command>-Dcoretext=enabled</command></term>
 323           <listitem>
 324             <para>
 325               Use the <ulink url="https://developer.apple.com/documentation/coretext">CoreText</ulink> library. <emphasis>(Default = no)</emphasis>
 326             </para>
 327             <para>
 328               This option enables or disables usage of the CoreText
 329               library. CoreText is available on macOS and iOS systems.
 330             </para>
 331           </listitem>
 332         </varlistentry>
 333
 334         <varlistentry>
 335           <term><command>-Ddocs=enabled</command></term>
 336           <listitem>
 337             <para>
 338               Use <ulink url="https://github.com/GNOME/gtk-doc">GTK-Doc</ulink>. <emphasis>(Default = no)</emphasis>
 339             </para>
 340             <para>
 341               This option enables the building of the documentation.
 342             </para>
 343           </listitem>
 344         </varlistentry>
 345       </variablelist>
 346     </section>
 347
 348   </section>
 349 </chapter>