gcc-5-source 5.5.0-12ubuntu1 / usr / src / gcc-5 / debian / README.cross

Building cross-compiler Debian packages
---------------------------------------

It is possible to build C and C++ cross compilers and support libraries
from gcc-4.0 source package. This document describes how to do so.
Cross-compiler build support is not perfect yet, please send fixes
and improvements to debian-gcc@lists.debian.org and 
debian-embedded@lists.debian.org

Before you start, you should probably check available pre-built
cross-toolchain debs. Available at http://www.emdebian.org

Old patches could be reached at
  http://zigzag.lvk.cs.msu.su/~nikita/debian/
  
If they are no longer there, you may check EmDebian web site at
  http://www.emdebian.org/
or ask debian-embedded@lists.debian.org for newer location.

Please check http://bugs.debian.org/391445 if you are about building
gcc-4.3 or above.

Most of them has been merged with gcc debian sources.

0. What's wrong with toolchain-source approach

Package toolchain-source contains sources for binutils and gcc, as well as
some support scripts to build cross-compiler packages. They seem to work.

However, there is one fundamental problem with this approach.
Gcc package is actively maintained and frequently updated. These updates
do contain bug fixes and improvements, especially for non-x86 architectures.
Cross-compilers built using toolchain-source will not get those fixes unless
toolchain-source package is updated after each binutils and gcc update.
The later is not hapenning in real life. For example, toolchain-source
was upgraded from gcc-3.2 to gcc-3.3 half a year later than gcc-3.3 became
Debian default compiler.

Keeping toolchain-source package up-to-date requires lots of work, and seems
to be a waste of time. It is much better to build cross-compilers directly
from gcc source package.


1. What is needed to build a cross-compiler from gcc-4.3 source

1.1. dpkg-cross package

Dpkg-cross package contains several tools to manage cross-compile environment.

It can convert native debian library and lib-dev packages for the target
architecture to binary-all packages that keep libraries and headers under
/usr/$(TARGET)/.

Also it contains helper tools for cross-compiling debian packages. Some of
these tools are used while building libgcc1 and libstdc++ library packages.
The resulting library packages follow the same convensions as library packages
converted by dpkg-cross.

Currently, at least version 1.18 of dpkg-cross is needed for cross-gcc
package build. Version 1.32 of dpkg-cross is needed in order to build gcc-4.3.

1.2. cross-binutils for the target

You need cross-binutils for your target to build cross-compiler.
Binutils-multiarch package will not work because it does not provide cross-
assemblers.

If you don't want to use pre-built cross-binutils packages, you may build
your own from binutils debian source package, using patches posted to
bug #231707. Please use the latest of patch versions available there.

Alternatively, you may use toolchain-source package to build cross-binutils
(but in this case you will probably also want to use toolchain-source
to build cross-compiler itself). However, multilib'ed cross-compilers may
not build or work with these binutils.

1.3. libc for target

You also need libc library and development packages for the target
architecture installed.

To get those, download linux-kernel-headers, libc6, and libc6-dev binary
debs for your target, convert those using dpkg-cross -b, and install
resulting -arch-cross debs. Consult dpkg-cross manual page for more
information.

Building with/for alternative libc's is not supported yet (but this is in
TODO).

Note that if you plan to use your cross-toolchain to develop kernel drivers
or similar low-level things, you will probably also need kernel headers
for the exact kernel version that your target hardware uses.


2. Building cross-compiler packages

Get gcc-4.3 source package.

Unpack it using dpkg-source -x, and cd to the package directory.

Set GCC_TARGET environment variable to the target architectire name. Note
that currently you should use debian architecture name (i.e 'powerpc' or 'arm'),
not GNU system type (i.e. 'powerpc-linux' or 'arm-linux'). Setting GCC_TARGET
to GNU system type will cause cross-compiler build to fail.

Instead of setting GCC_TARGET, target architecture name may be put into
debian/target file. If both GCC_TARGET is defined and debian/target file
exists, GCC_TARGET is used.

Run debian/rules control. This will change debian/control file,
adjusting build-depends.  By default, the packages will not depend on the
system -base package. A variable DEB_CROSS_INDEPENDENT has been merged with DEB_CROSS variable.

You can then build with either

$ GCC_TARGET=[arch] dpkg-buildpackage -rfakeroot

3. Using crosshurd

Jeff Bailey <jbailey@raspberryginger.com> suggests alternate way to setup
environment to build cross-compiler, using 'crosshurd' package. 
Crosshurd is like debootstrap but cross-arch, and works on the Hurd,
Linux and FreeBSD.  (The name is historical).

If you setup your environment with crosshurd, you will need to fix symlinks
in lib and usr/lib to be relative instead of absolute. For example:

lrwxrwxrwx    1 root     root           20 2004-05-06 23:02 libcom_err.so -> /lib/libcom_err.so.2

Needs to be changed to:

lrwxrwxrwx    1 root     root           20 2004-05-06 23:02 libcom_err.so -> ../../lib/libcom_err.so.2

Also, if you choose this method, set the environment variable 'with_sysroot'
to point to the ABSOLUTE PATH where the crosshurd was done.

Note however that build-depends of cross-gcc and dependencies in generated
libgcc1 and libstdc++ packages assume that you use dpkg-cross to set up
your environment, and may be wrong or incomplete if you use alternate methods.
But probably you don't care.

--
Nikita V. Youshchenko <yoush@debian.org> - Jun 2004
Hector Oron Martinez  <hector.oron@gmail.com> - Oct 2006