[ft-devel] Re: autoconf-based cross-building patch ([ft] FT2 Cross-compile Error)

[mpsuzuki]

Dear Werner,

On Thu, 12 Oct 2006 16:25:34 +0200 (CEST)
Werner LEMBERG <address@hidden> wrote:

>> I see, I will add freetype2/doc/CROSSDEV.GNU for 8.3
>> naming convention - at present, cross-building is only
>> for Unix-like systems, such platform specific document
>> is out of 8.3 convention? I think the name INSTALL.CROSS
>> is better and easier to know what it is.
>
>Well, I think today it is sufficient just to obey that names stripped
>to 8.3 stay unique.  So INSTALL.CROSS is just fine.

I see. Following is my manuscript for INSTALL.CROSS,
Please give me comment.

I thought I should refer some reliable document to guide
cross building by GNU autoconf, but I could not hit upon
- most of cross-building howto-documents (and automated
scripts) are strenuously written from scratch, soon left
over, and obsoleted. For a document in freetype2 package,
I thought refering nothing is better than refering a
document which can be obsoleted in future.


Regards,
mpsuzuki

========================================================

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 this document, see INSTALL.UNIX for required
tools and basic self-building procedure.


  1. Required Tools
  -----------------

    As self-building on Unix system, GNU Make 3.78.1 or newer is
    required. INSTALL.UNIX contains how to check the installed `make'.

    GNU C compiler to cross-build for target system is required. At
    present, non-GNU cross compiler is not tested. The cross compiler
    is expected to be installed with system-prefix. For example,
    when your building system is FreeBSD/i386 and the target system
    is Linux/MIPS, the cross compiler should be installed with name:
    "mips-ip22-linuxelf-gcc".

    Also C compiler for self-build is required. Non-GNU self compiler
    is acceptable, but not tested yet. This is used to build a tool
    that is executed in building procedure.


  2. Configuration
  ----------------

    2-1. Building and target system
    -------------------------------

      To configure for cross-build, the options `--host=<system>' and
      `--build=<system>' must be passed to configure. For example,
      when your building system is FreeBSD/i386 and the target system
      is Linux/MIPS,

        ./configure \
          --build=i386-unknown-freebsd \
          --host=mips-ip22-linuxelf \
          [other options]

      It should be noted that `--host=<system>' specifies the system
      that built binaries are executed, not the system of "host to
      cross-build". In legacy GNU autoconf, the options `--host=' and
      `--target=' are used, it is broken and obsoleted. Either explicit
      CC specification like `env CC=mips-ip22-linux-gcc ./configure'
      or `env CC=/usr/local/mips-ip22-linux/bin/gcc ./configure' do
      not work, such configuration makes configure confused to find
      cross and native C compilers.


    2-2. Prefix to install FreeType2
    --------------------------------

      Setting `--prefix=<prefix>' properly is important. The prefix to
      install FreeType2 is written in freetype-config and freetype2.pc.

      If the built FreeType2 is used as a part of cross-building system,
      the prefix is expected to be different from self-building system.
      For example, configuration with `--prefix=/usr/local' will install
      unexecutable binaries into system wide `/usr/local', thus it
      causes a confusion in configuration of the application using
      FreeType2. Configure to install cross-building system tree (for
      example, `--prefix=/usr/local/mips-ip22-linux/') is better.

      On the other hand, if the built FreeType2 is used a part of target
      system, the prefix to install should reflect file system structure
      of the target system.


  3. Build
  --------

    If the configuration finishes successfuly, invoking GNU make builds
    FreeType2, like,

      make

    or

      gmake

    
  4. Install
  ----------

    Invoking GNU make for the target `install', built FreeType2 is
    directly installed into the directory configured by `--prefix='.

    As noted in 2-2, sometimes FreeType2 is configured to be installed
    system directory of the target system, and should not be installed
    into the cross-building system. In such case, a make variable
    `DESTDIR' is useful to change the root directory in installation.
    For example, invoking make with `DESTDIR=' option, like

      make DESTDIR=/mnt/target_system_root/ install

    the built FreeType2 files are installed into
    `/mnt/target_system_root/<prefix_in_configure>/lib' etc.
    

  5. TODO
  -------

    Cross building between Cygwin (or MSys) and Unix must be tested.

----------------------------------------------------------------------

Copyright 2006 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.


--- end of INSTALL.CROSS ---