183 lines
5.8 KiB
Markdown
183 lines
5.8 KiB
Markdown
|
# Cross-Compiling FreeType
|
||
|
|
||
|
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.md] 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.81 or newer is required. [INSTALL_UNIX.md 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
|
||
|
|
||
|
```bash
|
||
|
./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
|
||
|
|
||
|
```bash
|
||
|
env CC=mips-ip22-linux-gcc ./configure # BAD
|
||
|
```
|
||
|
or
|
||
|
|
||
|
```bash
|
||
|
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.
|
||
|
|
||
|
- 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:
|
||
|
```bash
|
||
|
./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.
|
||
|
|
||
|
- 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:
|
||
|
```bash
|
||
|
./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
|
||
|
|
||
|
```bash
|
||
|
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 (C) 2006-2023 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.
|
||
|
```
|
||
|
|
||
|
<!---->
|
||
|
[INSTALL_UNIX.md]: ./INSTALL_UNIX.md
|