EmbToolkit will be handy if you want to develop applications and generate firmware for a highly customized/specialized embedded linux product.EmbToolkit is known to work and generate toolchain, build root filesystem under the following host development machines OS:

GNU/Linux based distributions

FreeBSD (other BSD may work, but not tested)

Mac OS X

2. Prerequisites

Most of prerequisites listed here are likely already installed in your distribution.
This is a check list before reporting issue.

2.1. common prerequisites

In order to configure EmbToolkit and build your toolchain, you will need the following softwares (among others)
installed on your host computer:

gcc or clang (or any other gcc compatible): C and C++ compilers

QT3 or QT4: development libraries and headers (if you want to use make xconfig for QT based configuration GUI)

ncurses: development libraries and headers (if you want to use make menuconfig for ncurses based configuration GUI)

gawk (not nawk: if you already have nawk installed, you must also install gawk)

bison

flex

texinfo

Subversion (if you want to build eglibc based toolchain)

git (if you want to build git version of some packages)

gnu make (GNU Make 3.81 or later)

patch

python

wget

And finally you must have enough free disk space in your host development machine (not the target).
At the moment of writing a full install of EmbToolkit (build of all packages, all supported programming
languages and eglibc used as C library) requires 5 GB of free disk space.

Please report any other prerequisites not listed here

2.2. Distributions specific prerequisites

Fedora

Beside the above prerequisites, under Fedora, you also need the following packages not installed by default:

libxi development package (library and headers).

XML::Parser perl module.

FreeBSD

Under FreeBSD make sure you have installed:

Gnu make and use gmake as command to build/rebuild etc…

Mac OS X

EmbToolkit can be used under Mac OS X with the following requirements:

EmbToolkit should be used in a case sensitive disk partition

Ubuntu

Ubuntu 12.04 LTS

Beside the above prerequisites, under Ubuntu as of 12.04 LTS, you also need the following packages not installed by default:

XML::Parser perl module.

2.3. Recommended packages

Shell: bash is recommended but not mandatory

3. Quick start guide

Do not run EmbToolkit as root on your host development machine.

Make sure you have all [prerequisites] installed prior trying to use EmbToolkit

3.3. Start building your toolchain/root filesystem

This will start a long build process (so be patient) and will generate, depending on what was configured:

A toolchain/SDK

a root filesystem

3.4. Root filesystem rebuild after config change

$ make rootfs_build

4. EmbToolkit Toolchain

EmbToolkit is versatile enough to allow generation of toolchain based on various components combination.
You can configure it, for example, to generate toolchain based on a one of supported C libraries associated
with one or both supported compiler infrastructures (clang/llvm and gcc).
The configuration of the toolchain takes place in Toolchain Configuration in the main GUI window.

4.1. How to use the toolchain

The toolchain generated by EmbToolkit is located in tools-<arch>/bin directory.
Where <arch> depends on the architecture and the core CPU variant selected at EmbToolkit configuration time.

The toolchain is also packaged in a toolchain-xxx.tar.bz2 file located in generated/ directory, allowing its use
outside of EmbToolkit.
The packaged toolchain contains the following directories:

sysroot-<arch>:
This directory contains SDK parts that will end up in your target root filesystem (C library, binaries, etc.)
and development files (headers, static libraries, etc.)

tools-<arch>:
This directory contains the toolchain components intended to run in your host development machine (compilers, static linker, etc.)

4.2. Components of the toolchain

Compiler infrastructures

EmbToolkit gives you the ability to choose to generate GCC or CLANG/LLVM based toolchain (cross compiler), or both.
This is a major change in cross compilation area and EmbToolkit is the first OpenSource build system allowing this.

GCC compiler infrastructure

gcc compiler infrastructure is the classical one supported by EmbToolkit.
Each version of gcc comes with patch set applied to the vanilla version, to ensure that the generated
toolchain has latest bug fixes available and that your are working with the best gcc toolchain available
for a given version.

CLANG/LLVM compiler infrastructure

The clang/llvm compiler infrastructure generated by EmbToolkit comes with some useful tools to help developers
to instrument the code they write, on ne example of such tools is the clang static analyzer.

If you use EmbToolkit build system you can instrument your packages at build time as follow:

Standard C++ libraries

Add debugging tools in the generated toolchain

GDB: The GNU Project Debugger

strace: trace system calls and signals

ltrace: library call tracer

Multilb toolchain

EmbToolkit does not support build of multilib toolchain.

5. Generate a root filesystem

EmbToolkit does not cover all types of root filesystem or partitioning on a flash device you may want.
Therefore the root filesystem generated must be considered to be there for testing purpose only.
However, nothing prevent you to customize how EmbToolkit generates root filesystem to fulfill your needs.
The whole root filesystem generation process is in core/mk/rootfs/rootfs.mk Makefile (see rootfs_build target).

5.1. Components of the root filesystem

The root filesystem generated by EmbToolkit mainly contains runtime libraries and other libraries and applications from packages.

Runtime libraries

Runtime libraries come from the toolchain C library and compiler runtime interface (libgcc, compiler-rt components, etc.).
These libraries are needed for any binaries dynamically linked by the toolchain compiler from EmbToolkit.
The build system will unconditionally include runtime libraries into the generated root filesystem.
These files are mainly in sysroot-<arch>/lib/ and will be stored of course in /lib/ in the root filesystem

Libraries applications configuration file and scripts from packages

EmbToolkit build system also unconditionally includes, in the generated root filesystem, any binaries, sctipts and configuration
files installed by packages in sysroot-<arch>/ hierarchy.

5.2. NFS root filesystem

NFS root filesystem is extremely useful in application and library development phase.
Indeed, no need to flash new firmware in the target device after only few changes on the code being developed.
Just copy the new library/application in NFS server directory mounted and it is available in the target device.

Mount NFS root filesystem from EmbToolkit .tar.bz2 file

Assuming you have your NFS serveur top level directory in /nfsroot, you have board named wonderful-board and EmbToolkit
located at /home/me/embtoolkit-xxx (where xxx is the version of EmbToolkit).
Setting up NFS root filesystem can be done as follow:

foo.mk: a Makefile which will be included in the EmbToolkit build system

All packages in EmbToolkit are based on this scheme, from the toolchain components (GCC, Binutils, eglibc, uClibc etc.),
to busybox and other highly configurable packages (such as Gtk+ and xorg-server).
This shows the robustness and versatility of EmbToolkit build system, without a high level of complexity (the goal being to be as simple as possible).

6.1. First step for new package inclusion

Determinate your package category/class

The first step before starting to write .mk and .kconfig files for a new package is to determinate your package class/category.
Each subdirectory in EmbToolkitpackages/ corresponds to a so called package class (for example net, database, etc.).

For example if you want to add a new package named foo among net packages, you must:

Create the two needed files

packages/net/foo/foo.mk
packages/net/foo/foo.kconfig

Include these two in EmbToolkit build system

Add the following line in packages/net/net.kconfig

source packages/net/foo/foo.kconfig

Add the following line in packages/net/net.mk, in case of target package

$(call embtk_include_pkg,foo)

And in case of host package

$(call embtk_include_hostpkg,foo)

Replace references to foo with the actual name of the package and net with the actual package class.

6.2. Writing a .kconfig config file

The .kconfig file is a configuration file, It gives details about the package displayed in EmbToolkit confuguration GUI.
This file syntax is the same as linux kconfig, see here for more details.
It is also used to enable, disable or set default options for a given package.

Here is an example of .kconfig file for a package named foo (foo.kconfig):

Set the package name. It is used internally in EmbToolkit build system

Set the package version. It is used internally in EmbToolkit build system (required for a tarball based package)

Set the package root URL. It is used to download the package tarball (if needed)

Set the package tarball file name (required for a tarball based package) to download from the root URL.

Set the package source directory name, after decompression of the package tarball (required for a tarball based package)

Set the build directory of the package (optional)

The above variables are all you need, in a .mk file, to make EmbToolkit build system download compile and install
an autotools based package using a tarball as source. In the following sections we will see what may/should be
added to build for example from GIT repository and more.

Replace references to foo and FOO with the actual name of the package.

Additional variables for Makefile based package

EmbToolit supports build of external Makefile based package that has an install target.
To build a such package, named foo for example, you need to define the following variable (in foo.mk):

define embtk_install_foo
$(call embtk_makeinstall_pkg,foo)
endef

Replace references to foo with the actual name of the package.

Additional variables for other types of packages

Custom packages build

EmbToolkit supports build of packages that are neither autotools based nor Makefile based, nor waf based
as long as you define steps to download, build and install them.

To build a such package, named foo for example, you need to define the embtk_install_foo macro and add all needed steps within.EmbToolkit.mk files are GNU Makefile, you can do the same things you would do in a regular GNU Makefile.

Replace references to FOO with the actual name of the external package.

6.4. Host packages special case

In EmbToolkit there is a convention, with some exceptions, where all host packages are namedPACKAGENAME_HOST and packagename_host, in .kconfig and .mk files.

So in the above examples, in case of host package, replace all references to FOO with FOO_HOST, and While invokingEmbToolkit build system macros, such as $(call embtk_download_pkg,foo), $(call embtk_get_pkgversion,foo)
replace references to foo with foo_host

Replace references to FOO and foo with the actual name of the package.

6.5. Build the package just added

Each package in EmbToolkit can be built separately from other build processes.

For example to build the new package named foo, issue the following command in EmbToolkit root directory: