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