with architecture name.

Typically, {{ic|./configure}} would have at least following parameters:

{{bc|1=
_target=''your_target''
_sysroot=/usr/lib/${_target}
...
./configure \
    --prefix=${_sysroot} \
    --sysroot=${_sysroot} \
    --bindir=/usr/bin
}}

where {{ic|''your_target''}} can be, e.g., "i686-pc-mingw32".

== Example ==

This is PKGBUILD for binutils for MinGW. Things worth noticing are:

* specifying root directory of the cross-environment
* usage of {{ic|${_pkgname} }}, {{ic|${_target} }} and {{ic|${_sysroot} }} variables to make the code more readable
* removal of the duplicated/conflicting files

{{bc|<nowiki>
# Maintainer: Allan McRae <allan@archlinux.org>

# cross toolchain build order: binutils, headers, gcc (pass 1), w32api, mingwrt, gcc (pass 2)

_target=i686-pc-mingw32
_sysroot=/usr/lib/${_target}

pkgname=${_target}-binutils
_pkgname=binutils
pkgver=2.19.1
pkgrel=1
pkgdesc="MinGW Windows binutils"
arch=('i686' 'x86_64')
url="http://www.gnu.org/software/binutils/"
license=('GPL')
depends=('glibc>=2.10.1' 'zlib')
options=('!libtool' '!distcc' '!ccache')
source=(http://ftp.gnu.org/gnu/${_pkgname}/${_pkgname}-${pkgver}.tar.bz2)
md5sums=('09a8c5821a2dfdbb20665bc0bd680791')

build() {
  cd ${_pkgname}-${pkgver}
  mkdir binutils-build && cd binutils-build

  ../configure --prefix=${_sysroot} --bindir=/usr/bin \
    --with-sysroot=${_sysroot} \
    --build=$CHOST --host=$CHOST --target=${_target} \
    --with-gcc --with-gnu-as --with-gnu-ld \
    --enable-shared --without-included-gettext \
    --disable-nls --disable-debug --disable-win32-registry
  make
  make DESTDIR=${pkgdir}/ install
  
  # clean-up cross compiler root
  rm -r ${pkgdir}/${_sysroot}/{info,man}
}
</nowiki>}}

{{Note|During cross-toolchain building always execute {{ic|configure}} and '''make''' commands from dedicated directory (so-called out-of-tree compilation) and remove whole {{ic|src}} directory after slightest change in [[PKGBUILD]].}}

== Hows and whys ==

=== Why not installing into /opt ===

Two reasons:

# First, according to File Hierarchy Standard, these files just belong somewhere to {{ic|/usr}}. Period.
# Second, installing into {{ic|/opt}} is a last measure when there is no other option.

=== What is that "out-of-path executables" thing? ===

This weird thing allows easier cross-compiling. Sometimes, project Makefiles do not use {{ic|CC}} & co. variables and instead use '''gcc''' directly. If you just want to try to cross-compile such project, editing the Makefile could be a very lengthy operation. However, changing the {{ic|$PATH}} to use "our" executables first is a very quick solution. You would then run {{ic|1=PATH=/usr/''arch''/bin/:$PATH make}} instead of {{ic|make}}.

== Troubleshooting ==

=== What to do if compilation fails without clear message? ===

For error, occurred during running {{ic|configure}}, read {{ic|$srcdir/''pkgname''-build/config.log}}. For error, occurred during compilation, scroll console log up or search for word "error".

=== What does this error [error message] means? ===

Most probably you made some of non-obvious errors:

* Too many or too few configuration flags. Try to use already proven set of flags.
* Dependencies are corrupted. For example misplaced or missing binutils files may result in cryptic error during gcc configuration.
* You did not add {{ic|1=export CFLAGS=""}} to your {{ic|build()}} function (see [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=25672 bug 25672] in GCC Bugzilla).
* Some {{Ic|--prefix}}/{{ic|--with-sysroot}} combination may require directories to be writable (non-obvious from clfs guides).
* sysroot does nor yet has kernel/libc headers.
* If google-fu does not help, immediately abandon current configuration and try more stable/proven one.

=== Why do files get installed in wrong places? ===

Various methods of running generic {{ic|make install}} line results in different results. For example, some make targets may not provide {{ic|DESTDIR}} support and instead require {{ic|install_root}} usage. The same for {{ic|tooldir}}, {{ic|prefix}} and other similar arguments. Sometimes providing parameters as arguments instead of environment variables, e.g

 ./configure CC=arm-elf-gcc

instead of

 CC=arm-elf-gcc ./configure

and vice versa may result in different outcomes (often caused by recursive self-invocation of configure/make).

== See also ==

* https://wiki.osdev.org/GCC_Cross-Compiler