This document contains instructions on how to cross-build the FreeType | |
library on Unix systems, for example, building binaries for Linux/MIPS | |
on FreeBSD/i386. Before reading this document, please consult the | |
file `INSTALL.UNIX' for required tools and the basic self-building | |
procedure. | |
1. Required Tools | |
----------------- | |
For self-building the FreeType library on a Unix system, GNU Make | |
3.80 or newer is required. `INSTALL.UNIX' contains hints how to | |
check the installed `make'. | |
The GNU C compiler to cross-build the target system is required. | |
Currently, using a non-GNU cross compiler is untested. The cross | |
compiler is expected to be installed with a system prefix. For | |
example, if your building system is FreeBSD/i386 and the target | |
system is Linux/MIPS, the cross compiler should be installed with | |
the name `mips-ip22-linuxelf-gcc'. | |
A C compiler for a self-build is required also, to build a tool | |
(`apinames') that is executed during the build procedure. Non-GNU | |
self compilers are acceptable, but such a setup is untested. | |
2. Configuration | |
---------------- | |
2.1. Building and target system | |
To configure a cross-build, the options `--host=<system>' and | |
`--build=<system>' must be passed to the `configure' script. | |
For example, if your build system is FreeBSD/i386 and the target | |
system is Linux/MIPS, say | |
./configure \ | |
--build=i386-unknown-freebsd \ | |
--host=mips-ip22-linuxelf \ | |
[other options] | |
It should be noted that `--host=<system>' specifies the system | |
where the built binaries will be executed, not the system where | |
the build actually happens. Older versions of GNU autoconf use | |
the option pair `--host=' and `--target='. This is broken and | |
doesn't work. Similarly, an explicit CC specification like | |
env CC=mips-ip22-linux-gcc ./configure # BAD | |
or | |
env CC=/usr/local/mips-ip22-linux/bin/gcc ./configure # BAD | |
doesn't work either; such a configuration confuses the | |
`configure' script while trying to find the cross and native C | |
compilers. | |
2.2. The prefix to install FreeType2 | |
Setting `--prefix=<prefix>' properly is important. The prefix | |
to install FreeType2 is written into the `freetype-config' | |
script and `freetype2.pc' configuration file. | |
If the built FreeType 2 library is used as a part of the | |
cross-building system, the prefix is expected to be different | |
from the self-building system. For example, a configuration | |
with `--prefix=/usr/local' installs binaries into the | |
system-wide `/usr/local' directory, which then can't be executed | |
due to the incorrect architecture. This causes confusion in | |
configuration of all applications that use FreeType2. Instead, | |
use a prefix to install the cross-build into a separate system | |
tree, for example, `--prefix=/usr/local/mips-ip22-linux/'. | |
On the other hand, if the built FreeType 2 library is used as a | |
part of the target system, the prefix to install should reflect | |
the file system structure of the target system. | |
2.3. Library dependencies | |
FreeType normally depends on external libraries like `libpng' or | |
`libharfbuzz'. The easiest case is to deactivate all such | |
dependencies using the `--without-XXX' configuration options. | |
However, if you want to use those libraries, you should ensure | |
that they are available both on the target system and as | |
(cross-compiled) libraries on the build system. | |
FreeType uses `pkg-config' to find most of the libraries; the | |
other libraries it links to are expected in the standard system | |
directories. Since the default pkg-config's meta-information | |
files (like `harfbuzz.pc') of the build platform don't work, use | |
one of the two possible solutions below. | |
o Use pkg-config's meta-information files that are adjusted to | |
cross-compile and cross-link with the target platform's | |
libraries. Make sure those files are found before the build | |
system's default files. Example: | |
./configure \ | |
--build=i386-unknown-freebsd \ | |
--host=mips-ip22-linuxelf \ | |
PKG_CONFIG_LIBDIR="/usr/local/mips-ip22-linux/lib/pkgconfig" \ | |
[other options] | |
See the manpage of `pkg-config' for more details. | |
o Set variables like LIBPNG_LIBS as additional options to the | |
`configure' script, overriding the values `pkg-config' would | |
provide. `configure --help' shows the available environment | |
variables. Example: | |
./configure \ | |
--build=i386-unknown-freebsd \ | |
--host=mips-ip22-linuxelf \ | |
LIBPNG_CFLAGS="-I/usr/local/mips-ip22-linux/include" \ | |
LIBPNG_LIBS="-L/usr/local/mips-ip22-linux/lib -lpng12" \ | |
[other options] | |
3. Building command | |
------------------- | |
If the configuration finishes successfully, invoking GNU make | |
builds FreeType2. Just say | |
make | |
or | |
gmake | |
depending on the name the GNU make binary actually has. | |
4. Installation | |
--------------- | |
Saying | |
make install | |
as usual to install FreeType2 into the directory tree specified by | |
the argument of the `--prefix' option. | |
As noted in section 2.2, FreeType2 is sometimes configured to be | |
installed into the system directory of the target system, and | |
should not be installed in the cross-building system. In such | |
cases, the make variable `DESTDIR' is useful to change the root | |
directory in the installation. For example, after | |
make DESTDIR=/mnt/target_system_root/ install | |
the built FreeType2 library files are installed into the directory | |
`/mnt/target_system_root/<prefix_in_configure>/lib'. | |
5. TODO | |
------- | |
Cross building between Cygwin (or MSys) and Unix must be tested. | |
---------------------------------------------------------------------- | |
Copyright 2006-2015 by | |
suzuki toshiya, David Turner, Robert Wilhelm, and Werner Lemberg. | |
This file is part of the FreeType project, and may only be used, | |
modified, and distributed under the terms of the FreeType project | |
license, LICENSE.TXT. By continuing to use, modify, or distribute | |
this file you indicate that you have read the license and understand | |
and accept it fully. | |
--- end of INSTALL.CROSS --- |