Welcome to Fakebox

Fakebox is a cross-compilation toolkit similar to great Scratchbox, but done simpler.

How it works

Don't believe? Here's exactly what Fakebox does to emulate "Linux in Linux":

  • change $PATH so shell chooses development tools from Fakebox wrappers instead of /usr/bin, etc.
  • most of these wrappers are symbolic links to one simple shell script which basically just adds toolchain prefix
  • replaces uname with trivial shell script which returns contents of $FB_UNAME
  • registers a binfmt_misc wrapper so binaries compiled for the target CPU architecture are executed via qemu emulation, in the target root filesystem

How it's better than Scratchbox


  • does not translate all filesystem paths yet, only those toolchain-related, but generally it's sufficient,
  • does not replace the underlying Linux kernel, of course,
  • probably needs some more work on handling border cases and b0rken software build systems.


How to start with Fakebox

  1. Create a new directory for your fresh, new Linux distribution:
    cooper@fbi:~$ mkdir turbobuntu
    cooper@fbi:~$ cd turbobuntu
  2. Download Fakebox to ./fakebox/ subdirectory.
  3. Create a directory for your target, e.g. ./mips/.
  4. Copy *.conf files to ./mips/ and edit fakebox.conf:
    cooper@fbi:~/turbobuntu$ cp fakebox/*.conf mips/
    cooper@fbi:~/turbobuntu$ vim mips/fakebox.conf
  5. Put your toolchain in ./toolchain/, so e.g. GCC is available under ./toolchain/bin/ (remember to set FB_PREFIX in fakebox.conf).
  6. Start Fakebox:
    cooper@fbi:~/turbobuntu$ ./fakebox/fakebox mips
    Setting up fakebox environment...
    Welcome to Fakebox!
    cooper@mips:~/turbobuntu$ uname -a
    Linux OpenWrt #1 Fri Mar 16 19:16:54 CET 2007 mips unknown
    cooper@mips:~/turbobuntu$ gcc --version
    mips-linux-uclibc-gcc (GCC) 3.4.6 (OpenWrt-2.0)
    Copyright (C) 2006 Free Software Foundation, Inc.
    This is free software; see the source for copying conditions.  There is NO
  7. Be sure to have the following line at top of your sudoers(5) if you wish to use sudo(8) and if it by default purges your environment variables (may be distro-specific):
    Defaults        !env_reset

Environmental variables

On startup Fakebox reads all $FB_TOP/$FB_TARGET/*.conf files and exports all variables that start with a CAPITAL letter.

  • $FAKEBOX - always =1 while in Fakebox
  • $FB_TOP - absolute path to your project, ie. the directory containing fakebox/ directory and your targets - e.g. /home/pjf/turbobuntu
  • $FB_TARGET - name of your target - e.g. mips
  • $FB_QEMU - qemu emulation to use
  • $FB_TOOLCHAIN - absolute path to toolchain - e.g. /home/pjf/turbobuntu/mips/toolchain
  • $FB_PREFIX - filename prefix before gcc and other tools in $FB_TOOLCHAIN/bin/ (optional in newer versions)
  • $FB_FTPAGENT - command to use to fetch tarballs in makepkg
  • $FB_PKGDW - absolute path to fetch sources to - e.g. /home/pjf/turbobuntu/src
  • $FB_PKGDEST - absolute path to put built packages in - e.g. /home/pjf/turbobuntu/mips/build
  • $FB_ROOTFS - virtual / directory to use for "local" installpkg - e.g. /home/pjf/turbobuntu/mips/rootfs
  • $FB_CCACHE - if =1, run cc, gcc and g++ through ccache

Diagnosis/service variables

  • $FB_OFF - if set, switch toolchain to /usr/bin (useful for compiling e.g. menuconfig in linux while in fakebox)
  • $FB_DEBUG - incrementally turn on following features:
    • 1 - log to stderr all calls to wrapper
    • 2 - log to stderr full path to underlying toolchain tools we call from the wrapper
    • 3 - log to stderr full qemu commands


  • $FB_PATH - paths to prepend to new $PATH
  • $FB_LEAVE_PATH - if 1, don't touch the $PATH variable at all
  • $FB_QEMU_PATH - path to qemu, if needed (ie. not in $PATH)
  • $FB_WRAP_ADD - options to add to calls from the wrapper
  • $FB_USE_SYSROOT_OPT - if 1, use --sysroot=$FB_ROOTFS in gcc, ld etc., otherwise fall-back on updating -I and -L options
  • $FB_BINFMT_QEMUWRAP - path to use instead of $FB_TOP/fakebox/wrappers/qemuwrap in binfmt_misc
Last modified 11 years ago Last modified on 03/12/10 13:57:03