Docs: update and linearize build instructions; add installation overview material.
This commit is contained in:
Nathan Willis
Khaled Hosny
parent
088755f9e6
commit
97c1c46cd2
|
|
@ -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:
|
||||
<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>
|
||||
For example, on an Ubuntu or Debian system, you would run:
|
||||
<programlisting>
|
||||
<command>sudo apt-get install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
|
||||
<command>sudo apt 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:
|
||||
On Fedora, RHEL, CentOS, or other Red-Hat–based systems, you would run:
|
||||
<programlisting>
|
||||
<command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
|
||||
<command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
|
||||
</programlisting>
|
||||
or using MacPorts:
|
||||
|
||||
</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 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 port install</command> <package>freetype glib2 cairo</package>
|
||||
<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 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>.
|
||||
If you are using Homebrew, you should run:
|
||||
<programlisting>
|
||||
<command>brew install</command> <package>freetype glib cairo</package>
|
||||
</programlisting>
|
||||
</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:
|
||||
<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>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
|
||||
<command>./configure</command>
|
||||
</programlisting>
|
||||
and on Fedora, RHEL, CentOS:
|
||||
followed by:
|
||||
<programlisting>
|
||||
<command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
|
||||
<command>make</command>
|
||||
</programlisting>
|
||||
or using MacPorts:
|
||||
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>
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue