docs/INSTALL.CROSS

   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
   5 procedure.
   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
 166 Copyright 2006-2018 by
 167 suzuki toshiya, David Turner, Robert Wilhelm, and Werner Lemberg.
 168
 169
 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
 174 and accept it fully.
 175
 176
 177 --- end of INSTALL.CROSS ---