Target is essentially a Linux distribution installed on your development workstation that you're going to build and package software for. Target consists of:

  • target root, a directory where distribution's filesystem is extracted,
  • meta-information about the target that is stored inside $HOME/.ldbox directory.

Target is created by extracting contents of distribution's root filesystem contents into some directory and then running lb-init command inside this directory.

Mapping mode

Mapping mode contains the following set of rules.

  • fs_rules specify how real filesystem directories are mepped into virtual filesystem view.
  • exec_rules specify how new executables are started and how their executable name and arguments are modified.

Networking mode

Networking mode contains set of rules specifying what kind of access to network is allowed and which IP addresses a process can connect and bind to.

CPU transparency method

CPU transparency method is a method to run binaries for architectures that are incompatible to architecture of the host system. CPU transparency method is defined in lb-init command line arguments when creating a new target, so it's stored in target's metadata. Usually dynamically linked qemu is used as cpu transparency method. CPU transparency method is run inside the same emulated environment, so the same mapping and network mode rules are applied to emulated program.


If target architecture is incompatible with the host one, all target binaries can be run using CPU transparency method only. Usually this is slow because target CPU emulation is needed. For most of the frequently used Linux utilities, a host's native binary that is doing exactly the same can be used instead. For example, software build process can be sped up significantly if native versions of make, sed, grep and even bash are used instead of emulated ones. These native binaries are calles tools (or build tools).

It's important that utilities from tools were built using the same compilation flags and have exactly the same versions as emulated utilities from the target. Otherwise subtle differences os behaviour and accepted command line arguments can lead to difficult to diagnose build failures. Hence, it's advisable to use tools built for the same version of the same distribution as the one in the target.

If the target distribution is the same as the one host system runs, you can use tools directly from the system. Otherwise, you have to put tools to some directory that is different than target root. A directory containing tools is called tool root.

Native tools must have the same pathnames relatively to the tool root, as corresponding target utilities have relatively to the target root. For example, if sed utility is /usr/bin/sed in your target distribution, then it will be located in ${target_root}/usr/bin/sed (where ${target_root} is target root) on host system, so corresponding native tool should be in ${tool_root}/usr/bin/sed (where ${tool_root} is tool root).

Binaries located in tool root get their shared libraries from tool root like if they were running chrooted there, but access other files from target root, according to target's mapping modes.

Tool root is defined in lb-init command line arguments when creating a new target, so it's stored in target's metadata.


A special case of build tool is compiler and other compiler-related programs (preprocessor, assembler, link editor). The common name for all these tools is toolchain.

The full compiler pathname and additional compiler options are defined in lb-init command line arguments when creating a new target, so they are stored in target's metadata.

Compiler specified this way is used instead of target's compiler. Toolchain can be located anywhere: in target root, in tool root, or somewhere else. The mapping rules for running toolchain binaries are selected according to their location. For example, if they're located in tool root, they are run the same way as other tools from tool root.


Session is a group of processes running under ldbox's control. Usually session contains a process that was started using lb command and its descendants, but there is a way to attach to a running session and start additional processes inside it. Target and mode should be specified when starting a new session.

There can be multiple sessions running simultaneously. Some mappings inside a session can be private. For example, usually a session has its own /tmp directory, and its content is not visible in other sessions.

Note that ldbox session is not the same as Linux session. Usually, ldbox sessions run inside a Linux session of logged in user, but there is a way to start ldbox session inside new Linux session.