Docs: update and linearize build instructions; add installation overview material.

This commit is contained in:
Nathan Willis 2018-10-10 16:38:22 -05:00 committed by Khaled Hosny
parent 088755f9e6
commit 97c1c46cd2
1 changed files with 197 additions and 50 deletions

View File

@ -1,70 +1,217 @@
<chapter id="install-harfbuzz">
<title>Install HarfBuzz</title>
<title>Installing HarfBuzz</title>
<section id="download">
<title id="download.title">Download</title>
<title id="download.title">Downloading HarfBuzz</title>
<para>
For tarball releases of HarfBuzz, look
<ulink url="http://www.freedesktop.org/software/harfbuzz/release/">here</ulink>.
At the same place you will
also find Win32 binary bundles that include libharfbuzz DLL, hb-view.exe,
hb-shape.exe, and all dependencies.
The HarfBuzz source code is hosted at <ulink
url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz</ulink>. The
same source tree is also available at the
<ulink
url="http://cgit.freedesktop.org/harfbuzz/">Freedesktop.org</ulink>
site.
</para>
<para>
The canonical source tree is available
<ulink url="http://cgit.freedesktop.org/harfbuzz/">here</ulink>.
Also available on <ulink url="https://github.com/harfbuzz/harfbuzz">github</ulink>.
Tarball releases and Win32 binary bundles (which include the
libharfbuzz DLL, hb-view.exe, hb-shape.exe, and all
dependencies) of HarfBuzz can be downloaded from <ulink
url="https://github.com/harfbuzz/harfbuzz">github.com/harfbuzz/harfbuzz/releases</ulink>
or from
<ulink url="http://www.freedesktop.org/software/harfbuzz/release/">Freedesktop.org</ulink>.
</para>
<para>
The API that comes with <filename class='headerfile'>hb.h</filename> will
not change incompatibly. Other, peripheral, headers are more likely to go
through minor modifications, but again, will do our best to never change
API in an incompatible way. We will never break the ABI.
Release notes are posted with each new release to provide an
overview of the changes. The project <ulink url="https://github.com/harfbuzz/harfbuzz/issues">tracks bug
reports and other issues</ulink> on GitHub. Discussion and
questions are welcome on the <ulink
url="http://freedesktop.org/mailman/listinfo/harfbuzz/">HarfBuzz
mailing list</ulink>.
</para>
<para>
If you are not sure whether Pango or HarfBuzz is right for you, read
<ulink url="http://mces.blogspot.in/2009/11/pango-vs-harfbuzz.html">this</ulink>.
The API included in the <filename
class='headerfile'>hb.h</filename> file will not change in a
compatibility-breaking way in any release. However, other,
peripheral headers are more likely to go through minor
modifications. We will do our best to never change APIs in an
incompatible way. We will <emphasis>never</emphasis> break the ABI.
</para>
</section>
<section id="building">
<title>Building</title>
<title>Building HarfBuzz</title>
<section id="building.linux">
<title>Building on Linux</title>
<para>
On Linux, install the development packages for FreeType, Cairo, and GLib.
For example, on Ubuntu / Debian, you would do:
<programlisting>
<command>sudo apt-get install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
</programlisting>
whereas on Fedora, RHEL, CentOS, and other Red Hat based systems you would do:
<programlisting>
<command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
</programlisting>
or using MacPorts:
<programlisting>
<command>sudo port install</command> <package>freetype glib2 cairo</package>
</programlisting>
<emphasis>(1)</emphasis> To build HarfBuzz on Linux, you must first install the
development packages for FreeType, Cairo, and GLib. The exact
commands required for this step will vary depending on
the Linux distribution you use.
</para>
<para>
If you are using a tarball, you can now proceed to running
<command>configure</command> and <command>make</command> as with any
other standard package. That should leave you with a shared library in
<filename>src/</filename>, and a few utility programs including hb-view
and hb-shape under <filename>util/</filename>.
For example, on an Ubuntu or Debian system, you would run:
<programlisting>
<command>sudo apt install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
</programlisting>
On Fedora, RHEL, CentOS, or other Red-Hat&ndash;based systems, you would run:
<programlisting>
<command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
</programlisting>
</para>
<para>
<emphasis>(2)</emphasis> The next step depends on whether you
are building from the source in a downloaded release tarball or
from the source directly from the git repository.
</para>
<para>
If you are bootstrapping from git, you need a few more tools before you
can run <filename>autogen.sh</filename> for the first time. Namely,
pkg-config and <ulink url="http://www.complang.org/ragel/">ragel</ulink>.
Again, on Ubuntu / Debian:
<programlisting>
<command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
</programlisting>
and on Fedora, RHEL, CentOS:
<programlisting>
<command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
</programlisting>
or using MacPorts:
<programlisting>
<command>sudo port install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
</programlisting>
<emphasis>(2)(a)</emphasis> If you downloaded the HarfBuzz
source code in a tarball, you can now extract the source.
</para>
<para>
From a shell in the top-level directory of the extracted source
code, you can run <command>./configure</command> followed by
<command>make</command> as with any other standard package.
</para>
<para>
This should leave you with a shared
library in the <filename>src/</filename> directory, and a few
utility programs including <command>hb-view</command> and
<command>hb-shape</command> under the <filename>util/</filename>
directory.
</para>
<para>
<emphasis>(2)(b)</emphasis> If you are building from the source in the HarfBuzz git
repository, rather than installing from a downloaded tarball
release, then you must install two more auxiliary tools before you
can build for the first time: <package>pkg-config</package> and
<ulink url="http://www.complang.org/ragel/">ragel</ulink>.
</para>
<para>
On Ubuntu or Debian, run:
<programlisting>
<command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
</programlisting>
On Fedora, RHEL, CentOS, run:
<programlisting>
<command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
</programlisting>
</para>
<para>
With <package>pkg-config</package> and <package>ragel</package>
installed, you can now run <command>./autogen.sh</command>,
followed by <command>./configure</command> and
<command>make</command> to build HarfBuzz.
</para>
</section>
<section id="building.windows">
<title>Building on Windows</title>
<para>
On Windows, consider using Microsoft's free <ulink
url="https://github.com/Microsoft/vcpkg">vcpkg</ulink> utility
to build HarfBuzz, its dependencies, and other open-source
libraries.
</para>
<para>
If you need to build HarfBuzz from source, first put the
<program>ragel</program> binary on your
<literal>PATH</literal>, then follow the appveyor CI cmake
<ulink
url="https://github.com/harfbuzz/harfbuzz/blob/master/appveyor.yml">build
instructions</ulink>.
</para>
</section>
<section id="building.macos">
<title>Building on macOS</title>
<para>
There are two ways to build HarfBuzz on Mac systems: MacPorts
and Homebrew. The process is similar to the process used on a
Linux system.
</para>
<para>
<emphasis>(1)</emphasis> You must first install the
development packages for FreeType, Cairo, and GLib. If you are
using MacPorts, you should run:
<programlisting>
<command>sudo port install</command> <package>freetype glib2 cairo</package>
</programlisting>
</para>
<para>
If you are using Homebrew, you should run:
<programlisting>
<command>brew install</command> <package>freetype glib cairo</package>
</programlisting>
</para>
<para>
<emphasis>(2)</emphasis> The next step depends on whether you are building from the
source in a downloaded release tarball or from the source directly
from the git repository.
</para>
<para>
<emphasis>(2)(a)</emphasis> If you are installing HarfBuzz
from a downloaded tarball release, extract the tarball and
open a Terminal in the extracted source-code directory. Run:
<programlisting>
<command>./configure</command>
</programlisting>
followed by:
<programlisting>
<command>make</command>
</programlisting>
to build HarfBuzz.
</para>
<para>
<emphasis>(2)(b)</emphasis> Alternatively, if you are building
HarfBuzz from the source in the HarfBuzz git repository, then
you must install several built-time dependencies before
proceeding.
</para>
<para>If you are
using MacPorts, you should run:
<programlisting>
<command>sudo port install</command> <package>autoconf
automake libtool pkgconfig ragel gtk-doc</package>
</programlisting>
to install the build dependencies.
</para>
<para>If you are using Homebrew, you should run:
<programlisting>
<command>brew install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
</programlisting>
Finally, you can run:
<programlisting>
<command>./autogen.sh</command>
</programlisting>
</para>
<para>
<emphasis>(3)</emphasis> You can now build HarfBuzz (on either
a MacPorts or a Homebrew system) by running:
<programlisting>
<command>./configure</command>
</programlisting>
followed by:
<programlisting>
<command>make</command>
</programlisting>
</para>
<para>
This should leave you with a shared
library in the <filename>src/</filename> directory, and a few
utility programs including <command>hb-view</command> and
<command>hb-shape</command> under the <filename>util/</filename>
directory.
</para>
</section>
</section>
</chapter>