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