1This document contains instructions on how to cross-build the FreeType 2library on Unix systems, for example, building binaries for Linux/MIPS 3on FreeBSD/i386. Before reading this document, please consult the 4file `INSTALL.UNIX' for required tools and the basic self-building 5procedure. 6 7 8 1. Required Tools 9 ----------------- 10 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'. 14 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'. 21 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. 25 26 27 2. Configuration 28 ---------------- 29 30 2.1. Building and target system 31 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 36 37 ./configure \ 38 --build=i386-unknown-freebsd \ 39 --host=mips-ip22-linuxelf \ 40 [other options] 41 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 47 48 env CC=mips-ip22-linux-gcc ./configure # BAD 49 50 or 51 52 env CC=/usr/local/mips-ip22-linux/bin/gcc ./configure # BAD 53 54 doesn't work either; such a configuration confuses the 55 `configure' script while trying to find the cross and native C 56 compilers. 57 58 59 2.2. The prefix to install FreeType2 60 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. 64 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/'. 74 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. 78 79 80 2.3. Library dependencies 81 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. 88 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. 94 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: 99 100 ./configure \ 101 --build=i386-unknown-freebsd \ 102 --host=mips-ip22-linuxelf \ 103 PKG_CONFIG_LIBDIR="/usr/local/mips-ip22-linux/lib/pkgconfig" \ 104 [other options] 105 106 See the manpage of `pkg-config' for more details. 107 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 111 variables. Example: 112 113 ./configure \ 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" \ 118 [other options] 119 120 121 3. Building command 122 ------------------- 123 124 If the configuration finishes successfully, invoking GNU make 125 builds FreeType2. Just say 126 127 make 128 129 or 130 131 gmake 132 133 depending on the name the GNU make binary actually has. 134 135 136 4. Installation 137 --------------- 138 139 Saying 140 141 make install 142 143 as usual to install FreeType2 into the directory tree specified by 144 the argument of the `--prefix' option. 145 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 151 152 make DESTDIR=/mnt/target_system_root/ install 153 154 the built FreeType2 library files are installed into the directory 155 `/mnt/target_system_root/<prefix_in_configure>/lib'. 156 157 158 5. TODO 159 ------- 160 161 Cross building between Cygwin (or MSys) and Unix must be tested. 162 163 164---------------------------------------------------------------------- 165 166Copyright (C) 2006-2023 by 167suzuki toshiya, David Turner, Robert Wilhelm, and Werner Lemberg. 168 169 170This file is part of the FreeType project, and may only be used, 171modified, and distributed under the terms of the FreeType project 172license, LICENSE.TXT. By continuing to use, modify, or distribute 173this file you indicate that you have read the license and understand 174and accept it fully. 175 176 177--- end of INSTALL.CROSS --- 178