docs/html/building.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Building HarfBuzz: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="install-harfbuzz.html" title="Installing HarfBuzz">
   9 <link rel="prev" href="install-harfbuzz.html" title="Installing HarfBuzz">
  10 <link rel="next" href="getting-started.html" title="Getting started with HarfBuzz">
  11 <meta name="generator" content="GTK-Doc V1.25 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="install-harfbuzz.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="install-harfbuzz.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="getting-started.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="section">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="building"></a>Building HarfBuzz</h2></div></div></div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="building.linux"></a>Building on Linux</h3></div></div></div>
  28 <p>
  29       <span class="emphasis"><em>(1)</em></span> To build HarfBuzz on Linux, you must first install the
  30       development packages for FreeType, Cairo, and GLib. The exact
  31       commands required for this step will vary depending on
  32       the Linux distribution you use.
  33     </p>
  34 <p>
  35       For example, on an Ubuntu or Debian system, you would run:
  36       </p>
  37 <pre class="programlisting">
  38         <span class="command"><strong>sudo apt install</strong></span> <span class="package">gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</span>
  39       </pre>
  40 <p>
  41       On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run:
  42       </p>
  43 <pre class="programlisting">
  44         <span class="command"><strong>sudo yum install</strong></span> <span class="package">gcc gcc-c++ freetype-devel glib2-devel cairo-devel</span>
  45       </pre>
  46 <p>
  47
  48     </p>
  49 <p>
  50       <span class="emphasis"><em>(2)</em></span> The next step depends on whether you
  51       are building from the source in a downloaded release tarball or
  52       from the source directly from the git repository.
  53     </p>
  54 <p>
  55       <span class="emphasis"><em>(2)(a)</em></span> If you downloaded the HarfBuzz
  56       source code in a tarball, you can now extract the source.
  57     </p>
  58 <p>
  59       From a shell in the top-level directory of the extracted source
  60       code, you can run <span class="command"><strong>./configure</strong></span> followed by
  61       <span class="command"><strong>make</strong></span> as with any other standard package.
  62     </p>
  63 <p>
  64       This should leave you with a shared
  65       library in the <code class="filename">src/</code> directory, and a few
  66       utility programs including <span class="command"><strong>hb-view</strong></span> and
  67       <span class="command"><strong>hb-shape</strong></span> under the <code class="filename">util/</code>
  68       directory.
  69     </p>
  70 <p>
  71       <span class="emphasis"><em>(2)(b)</em></span> If you are building from the source in the HarfBuzz git
  72       repository, rather than installing from a downloaded tarball
  73       release, then you must install two more auxiliary tools before you
  74       can build for the first time: <span class="package">pkg-config</span> and
  75       <a class="ulink" href="http://www.complang.org/ragel/" target="_top">ragel</a>.
  76     </p>
  77 <p>
  78       On Ubuntu or Debian, run:
  79       </p>
  80 <pre class="programlisting">
  81         <span class="command"><strong>sudo apt-get install</strong></span> <span class="package">autoconf automake libtool pkg-config ragel gtk-doc-tools</span>
  82       </pre>
  83 <p>
  84       On Fedora, RHEL, CentOS, run:
  85       </p>
  86 <pre class="programlisting">
  87         <span class="command"><strong>sudo yum install</strong></span> <span class="package">autoconf automake libtool pkgconfig ragel gtk-doc</span>
  88       </pre>
  89 <p>
  90
  91     </p>
  92 <p>
  93       With <span class="package">pkg-config</span> and <span class="package">ragel</span>
  94       installed, you can now run <span class="command"><strong>./autogen.sh</strong></span>,
  95       followed by <span class="command"><strong>./configure</strong></span> and
  96       <span class="command"><strong>make</strong></span> to build HarfBuzz.
  97     </p>
  98 </div>
  99 <div class="section">
 100 <div class="titlepage"><div><div><h3 class="title">
 101 <a name="building.windows"></a>Building on Windows</h3></div></div></div>
 102 <p>
 103         On Windows, consider using Microsoft's free <a class="ulink" href="https://github.com/Microsoft/vcpkg" target="_top">vcpkg</a> utility
 104         to build HarfBuzz, its dependencies, and other open-source
 105         libraries.
 106       </p>
 107 <p>
 108         If you need to build HarfBuzz from source, first put the
 109         <span class="package">ragel</span> binary on your
 110         <code class="literal">PATH</code>, then follow the appveyor CI cmake
 111         <a class="ulink" href="https://github.com/harfbuzz/harfbuzz/blob/master/appveyor.yml" target="_top">build
 112         instructions</a>.
 113       </p>
 114 </div>
 115 <div class="section">
 116 <div class="titlepage"><div><div><h3 class="title">
 117 <a name="building.macos"></a>Building on macOS</h3></div></div></div>
 118 <p>
 119         There are two ways to build HarfBuzz on Mac systems: MacPorts
 120         and Homebrew. The process is similar to the process used on a
 121         Linux system.
 122       </p>
 123 <p>
 124         <span class="emphasis"><em>(1)</em></span> You must first install the
 125         development packages for FreeType, Cairo, and GLib. If you are
 126         using MacPorts, you should run:
 127       </p>
 128 <pre class="programlisting">
 129         <span class="command"><strong>sudo port install</strong></span> <span class="package">freetype glib2 cairo</span>
 130       </pre>
 131 <p>
 132       </p>
 133 <p>
 134         If you are using Homebrew, you should run:
 135         </p>
 136 <pre class="programlisting">
 137           <span class="command"><strong>brew install</strong></span> <span class="package">freetype glib cairo</span>
 138         </pre>
 139 <p>
 140       </p>
 141 <p>
 142         <span class="emphasis"><em>(2)</em></span> The next step depends on whether you are building from the
 143         source in a downloaded release tarball or from the source directly
 144         from the git repository.
 145       </p>
 146 <p>
 147         <span class="emphasis"><em>(2)(a)</em></span> If you are installing HarfBuzz
 148         from a downloaded tarball release, extract the tarball and
 149         open a Terminal in the extracted source-code directory. Run:
 150         </p>
 151 <pre class="programlisting">
 152           <span class="command"><strong>./configure</strong></span>
 153         </pre>
 154 <p>
 155         followed by:
 156         </p>
 157 <pre class="programlisting">
 158           <span class="command"><strong>make</strong></span>
 159         </pre>
 160 <p>
 161         to build HarfBuzz.
 162       </p>
 163 <p>
 164         <span class="emphasis"><em>(2)(b)</em></span> Alternatively, if you are building
 165         HarfBuzz from the source in the HarfBuzz git repository, then
 166         you must install several built-time dependencies before
 167         proceeding.
 168       </p>
 169 <p>If you are
 170         using MacPorts, you should run:
 171       </p>
 172 <pre class="programlisting">
 173         <span class="command"><strong>sudo port install</strong></span> <span class="package">autoconf automake libtool pkgconfig ragel gtk-doc</span>
 174       </pre>
 175 <p>
 176       to install the build dependencies.
 177       </p>
 178 <p>If you are using Homebrew, you should run:
 179         </p>
 180 <pre class="programlisting">
 181           <span class="command"><strong>brew install</strong></span> <span class="package">autoconf automake libtool pkgconfig ragel gtk-doc</span>
 182         </pre>
 183 <p>
 184         Finally, you can run:
 185         </p>
 186 <pre class="programlisting">
 187           <span class="command"><strong>./autogen.sh</strong></span>
 188         </pre>
 189 <p>
 190       </p>
 191 <p>
 192         <span class="emphasis"><em>(3)</em></span> You can now build HarfBuzz (on either
 193         a MacPorts or a Homebrew system) by running:
 194         </p>
 195 <pre class="programlisting">
 196           <span class="command"><strong>./configure</strong></span>
 197         </pre>
 198 <p>
 199         followed by:
 200         </p>
 201 <pre class="programlisting">
 202           <span class="command"><strong>make</strong></span>
 203         </pre>
 204 <p>
 205       </p>
 206 <p>
 207         This should leave you with a shared
 208         library in the <code class="filename">src/</code> directory, and a few
 209         utility programs including <span class="command"><strong>hb-view</strong></span> and
 210         <span class="command"><strong>hb-shape</strong></span> under the <code class="filename">util/</code>
 211         directory.
 212       </p>
 213 </div>
 214 <div class="section">
 215 <div class="titlepage"><div><div><h3 class="title">
 216 <a name="configuration"></a>Configuration options</h3></div></div></div>
 217 <p>
 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       </p>
 222 <div class="variablelist"><table border="0" class="variablelist">
 223 <colgroup>
 224 <col align="left" valign="top">
 225 <col>
 226 </colgroup>
 227 <tbody>
 228 <tr>
 229 <td><p><span class="term"><span class="command"><strong>--with-libstdc++</strong></span></span></p></td>
 230 <td>
 231 <p>
 232               Allow linking with libstdc++. <span class="emphasis"><em>(Default = no)</em></span>
 233             </p>
 234 <p>
 235               This option enables or disables linking HarfBuzz to the
 236               system's libstdc++ library.
 237             </p>
 238 </td>
 239 </tr>
 240 <tr>
 241 <td><p><span class="term"><span class="command"><strong>--with-glib</strong></span></span></p></td>
 242 <td>
 243 <p>
 244              Use <a class="ulink" href="https://developer.gnome.org/glib/" target="_top">GLib</a>. <span class="emphasis"><em>(Default = auto)</em></span>
 245             </p>
 246 <p>
 247               This option enables or disables usage of the GLib
 248               library.  The default setting is to check for the
 249               presence of GLib and, if it is found, build with
 250               GLib support. GLib is native to GNU/Linux systems but is
 251               available on other operating system as well.
 252             </p>
 253 </td>
 254 </tr>
 255 <tr>
 256 <td><p><span class="term"><span class="command"><strong>--with-gobject</strong></span></span></p></td>
 257 <td>
 258 <p>
 259               Use <a class="ulink" href="https://developer.gnome.org/gobject/stable/" target="_top">GObject</a>. <span class="emphasis"><em>(Default = no)</em></span>
 260             </p>
 261 <p>
 262               This option enables or disables usage of the GObject
 263               library. The default setting is to check for the
 264               presence of GObject and, if it is found, build with
 265               GObject support. GObject is native to GNU/Linux systems but is
 266               available on other operating system as well.
 267             </p>
 268 </td>
 269 </tr>
 270 <tr>
 271 <td><p><span class="term"><span class="command"><strong>--with-cairo</strong></span></span></p></td>
 272 <td>
 273 <p>
 274               Use <a class="ulink" href="https://cairographics.org/" target="_top">Cairo</a>. <span class="emphasis"><em>(Default = auto)</em></span>
 275             </p>
 276 <p>
 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             </p>
 282 <p>
 283               Note: Cairo is used only by the HarfBuzz
 284               command-line utilities, and not by the HarfBuzz library.
 285             </p>
 286 </td>
 287 </tr>
 288 <tr>
 289 <td><p><span class="term"><span class="command"><strong>--with-fontconfig</strong></span></span></p></td>
 290 <td>
 291 <p>
 292               Use <a class="ulink" href="https://www.freedesktop.org/wiki/Software/fontconfig/" target="_top">Fontconfig</a>. <span class="emphasis"><em>(Default = auto)</em></span>
 293             </p>
 294 <p>
 295               This option enables or disables usage of the Fontconfig
 296               library, which provides font-matching functions and
 297               provides access to font properties. The default setting
 298               is to check for the presence of Fontconfig and, if it is
 299               found, build with Fontconfig support.
 300             </p>
 301 <p>
 302               Note: Fontconfig is used only by the HarfBuzz
 303               command-line utilities, and not by the HarfBuzz library.
 304             </p>
 305 </td>
 306 </tr>
 307 <tr>
 308 <td><p><span class="term"><span class="command"><strong>--with-icu</strong></span></span></p></td>
 309 <td>
 310 <p>
 311               Use the <a class="ulink" href="http://site.icu-project.org/home" target="_top">ICU</a> library. <span class="emphasis"><em>(Default = auto)</em></span>
 312             </p>
 313 <p>
 314               This option enables or disables usage of the
 315               <span class="emphasis"><em>International Components for
 316               Unicode</em></span> (ICU) library, which provides access
 317               to Unicode Character Database (UCD) properties as well
 318               as normalization and conversion functions. The default
 319               setting is to check for the presence of ICU and, if it
 320               is found, build with ICU support.
 321             </p>
 322 </td>
 323 </tr>
 324 <tr>
 325 <td><p><span class="term"><span class="command"><strong>--with-ucdn</strong></span></span></p></td>
 326 <td>
 327 <p>
 328               Use HarfBuzz's <a class="ulink" href="https://github.com/harfbuzz/harfbuzz/tree/master/src/hb-ucdn" target="_top">built-in UCDN library</a>. <span class="emphasis"><em>(Default = auto)</em></span>
 329             </p>
 330 <p>
 331               The HarfBuzz source tree includes a <span class="emphasis"><em>Unicode
 332               Database and Normalization</em></span> (UCDN) library
 333               that provides access to basic character properties in
 334               the Unicode Character Database (UCD) as well as low-level
 335               normalization functions. HarfBuzz can be built without
 336               this UCDN support if the usage of a different UCDN
 337               library is desired.
 338             </p>
 339 </td>
 340 </tr>
 341 <tr>
 342 <td><p><span class="term"><span class="command"><strong>--with-graphite2</strong></span></span></p></td>
 343 <td>
 344 <p>
 345               Use the <a class="ulink" href="http://graphite.sil.org/" target="_top">Graphite2</a> library. <span class="emphasis"><em>(Default = no)</em></span>
 346             </p>
 347 <p>
 348               This option enables or disables usage of the Graphite2
 349               library, which provides support for the Graphite shaping
 350               model.
 351             </p>
 352 </td>
 353 </tr>
 354 <tr>
 355 <td><p><span class="term"><span class="command"><strong>--with-freetype</strong></span></span></p></td>
 356 <td>
 357 <p>
 358               Use the <a class="ulink" href="https://www.freetype.org/" target="_top">FreeType</a> library. <span class="emphasis"><em>(Default = auto)</em></span>
 359             </p>
 360 <p>
 361               This option enables or disables usage of the FreeType
 362               font-rendering library. The default setting is to check for the
 363               presence of FreeType and, if it is found, build with
 364               FreeType support.
 365             </p>
 366 </td>
 367 </tr>
 368 <tr>
 369 <td><p><span class="term"><span class="command"><strong>--with-uniscribe</strong></span></span></p></td>
 370 <td>
 371 <p>
 372               Use the <a class="ulink" href="https://docs.microsoft.com/en-us/windows/desktop/intl/uniscribe" target="_top">Uniscribe</a>
 373               library (experimental). <span class="emphasis"><em>(Default = no)</em></span>
 374             </p>
 375 <p>
 376               This option enables or disables usage of the Uniscribe
 377               font-rendering library. Uniscribe is available on
 378               Windows systems. Uniscribe support is used only for
 379               testing purposes and does not need to be enabled for
 380               HarfBuzz to run on Windows systems.
 381             </p>
 382 </td>
 383 </tr>
 384 <tr>
 385 <td><p><span class="term"><span class="command"><strong>--with-directwrite</strong></span></span></p></td>
 386 <td>
 387 <p>
 388               Use the <a class="ulink" href="https://docs.microsoft.com/en-us/windows/desktop/directwrite/direct-write-portal" target="_top">DirectWrite</a> library (experimental). <span class="emphasis"><em>(Default = no)</em></span>
 389             </p>
 390 <p>
 391               This option enables or disables usage of the DirectWrite
 392               font-rendering library. DirectWrite is available on
 393               Windows systems. DirectWrite support is used only for
 394               testing purposes and does not need to be enabled for
 395               HarfBuzz to run on Windows systems.
 396             </p>
 397 </td>
 398 </tr>
 399 <tr>
 400 <td><p><span class="term"><span class="command"><strong>--with-coretext</strong></span></span></p></td>
 401 <td>
 402 <p>
 403               Use the <a class="ulink" href="https://developer.apple.com/documentation/coretext" target="_top">CoreText</a> library. <span class="emphasis"><em>(Default = no)</em></span>
 404             </p>
 405 <p>
 406               This option enables or disables usage of the CoreText
 407               library. CoreText is available on macOS and iOS systems.
 408             </p>
 409 </td>
 410 </tr>
 411 </tbody>
 412 </table></div>
 413 </div>
 414 </div>
 415 <div class="footer">
 416 <hr>Generated by GTK-Doc V1.25</div>
 417 </body>
 418 </html>