1 This document contains instructions on how to cross-build the FreeType
2 library on Unix systems, for example, building binaries for Linux/MIPS
3 on FreeBSD/i386. Before reading this document, please consult the
4 file `INSTALL.UNIX' for required tools and the basic self-building
11 For self-building the FreeType library on a Unix system, GNU Make
12 3.81 or newer is required. `INSTALL.UNIX' contains hints how to
13 check the installed `make'.
15 The GNU C compiler to cross-build the target system is required.
16 Currently, using a non-GNU cross compiler is untested. The cross
17 compiler is expected to be installed with a system prefix. For
18 example, if your building system is FreeBSD/i386 and the target
19 system is Linux/MIPS, the cross compiler should be installed with
20 the name `mips-ip22-linuxelf-gcc'.
22 A C compiler for a self-build is required also, to build a tool
23 (`apinames') that is executed during the build procedure. Non-GNU
24 self compilers are acceptable, but such a setup is untested.
30 2.1. Building and target system
32 To configure a cross-build, the options `--host=<system>' and
33 `--build=<system>' must be passed to the `configure' script.
34 For example, if your build system is FreeBSD/i386 and the target
35 system is Linux/MIPS, say
38 --build=i386-unknown-freebsd \
39 --host=mips-ip22-linuxelf \
42 It should be noted that `--host=<system>' specifies the system
43 where the built binaries will be executed, not the system where
44 the build actually happens. Older versions of GNU autoconf use
45 the option pair `--host=' and `--target='. This is broken and
46 doesn't work. Similarly, an explicit CC specification like
48 env CC=mips-ip22-linux-gcc ./configure # BAD
52 env CC=/usr/local/mips-ip22-linux/bin/gcc ./configure # BAD
54 doesn't work either; such a configuration confuses the
55 `configure' script while trying to find the cross and native C
59 2.2. The prefix to install FreeType2
61 Setting `--prefix=<prefix>' properly is important. The prefix
62 to install FreeType2 is written into the `freetype-config'
63 script and `freetype2.pc' configuration file.
65 If the built FreeType 2 library is used as a part of the
66 cross-building system, the prefix is expected to be different
67 from the self-building system. For example, a configuration
68 with `--prefix=/usr/local' installs binaries into the
69 system-wide `/usr/local' directory, which then can't be executed
70 due to the incorrect architecture. This causes confusion in
71 configuration of all applications that use FreeType2. Instead,
72 use a prefix to install the cross-build into a separate system
73 tree, for example, `--prefix=/usr/local/mips-ip22-linux/'.
75 On the other hand, if the built FreeType 2 library is used as a
76 part of the target system, the prefix to install should reflect
77 the file system structure of the target system.
80 2.3. Library dependencies
82 FreeType normally depends on external libraries like `libpng' or
83 `libharfbuzz'. The easiest case is to deactivate all such
84 dependencies using the `--without-XXX' configuration options.
85 However, if you want to use those libraries, you should ensure
86 that they are available both on the target system and as
87 (cross-compiled) libraries on the build system.
89 FreeType uses `pkg-config' to find most of the libraries; the
90 other libraries it links to are expected in the standard system
91 directories. Since the default pkg-config's meta-information
92 files (like `harfbuzz.pc') of the build platform don't work, use
93 one of the two possible solutions below.
95 o Use pkg-config's meta-information files that are adjusted to
96 cross-compile and cross-link with the target platform's
97 libraries. Make sure those files are found before the build
98 system's default files. Example:
101 --build=i386-unknown-freebsd \
102 --host=mips-ip22-linuxelf \
103 PKG_CONFIG_LIBDIR="/usr/local/mips-ip22-linux/lib/pkgconfig" \
106 See the manpage of `pkg-config' for more details.
108 o Set variables like LIBPNG_LIBS as additional options to the
109 `configure' script, overriding the values `pkg-config' would
110 provide. `configure --help' shows the available environment
114 --build=i386-unknown-freebsd \
115 --host=mips-ip22-linuxelf \
116 LIBPNG_CFLAGS="-I/usr/local/mips-ip22-linux/include" \
117 LIBPNG_LIBS="-L/usr/local/mips-ip22-linux/lib -lpng12" \
124 If the configuration finishes successfully, invoking GNU make
125 builds FreeType2. Just say
133 depending on the name the GNU make binary actually has.
143 as usual to install FreeType2 into the directory tree specified by
144 the argument of the `--prefix' option.
146 As noted in section 2.2, FreeType2 is sometimes configured to be
147 installed into the system directory of the target system, and
148 should not be installed in the cross-building system. In such
149 cases, the make variable `DESTDIR' is useful to change the root
150 directory in the installation. For example, after
152 make DESTDIR=/mnt/target_system_root/ install
154 the built FreeType2 library files are installed into the directory
155 `/mnt/target_system_root/<prefix_in_configure>/lib'.
161 Cross building between Cygwin (or MSys) and Unix must be tested.
164 ----------------------------------------------------------------------
166 Copyright (C) 2006-2023 by
167 suzuki toshiya, David Turner, Robert Wilhelm, and Werner Lemberg.
170 This file is part of the FreeType project, and may only be used,
171 modified, and distributed under the terms of the FreeType project
172 license, LICENSE.TXT. By continuing to use, modify, or distribute
173 this file you indicate that you have read the license and understand
177 --- end of INSTALL.CROSS ---