The Build System

Architectures, Platforms, Targets, and Projects

The LK build system thinks of the world in four layers.

Projects are what you ask make to build. They are a set of modules (typically apps and libraries) built for a Target. They are defined in project/<name>.mk. The Target is selected via TARGET := <name> in this makefile or an included makefile (in the case where multiple projects share a common configuration). You choose your project by either passing it to make on the commandline (make <name>) or putting a PROJECT := <name> directive in local.mk.

Targets are typically a specific PCB (or family of extremely closely related PCBs, maybe differing just a little, detectable by some revision resistors or the like). They belong to a Platform and are defined in target/<name>/rules.mk. The Platform is selected via PLATFORM := <name> in this makefile.

Platforms typically are Systems-on-Chip (either individual or related families). They belong to an Architecture and are defined in platform/<name>/rules.mk. The Architecture is selected via ARCH := <name> in this makefile.

Architectures are a specific CPU or CPU family (ARM Cortex M3, Intel IA32, etc).

Example Project

An example project is stm32f4-discovery-test. The Target there is stm32f4-discovery (the ST development board of the same name). Its Platform is stm32f4xx, a family of ST microcontrollers. STM32_CHIP is set to stm32f407 for things that may be specific to that chip. Some GLOBAL_DEFINES are configured here as well, like HSE_VALUE which is the frequency of the crystal — a platform-specific definition. The Platform stm32f4xx sets ARCH as arm and ARM_CPU (specific to arm architecture) to cortex-m4, as well as configuring other platform-specific values.

The above configuration information lives in the following files in the lk source tree:

• project/stm32f4-discovery-test.mk

• target/stm32f4-discovery.mk

• platform/stm32f4xx/rules.mk

• arch/arm/rules.mk

Building Outside the LK Tree

The build system provides a mechanism to overlay additional projects, targets, platforms, apps, libs, etc, from sibling directory hierarchies. This allows you to more easily build and maintain projects that are not part of the main lk tree.

For example, say you have LK checked out in an lk directory, and next to that you have a mystuff directory (a checkout of your own source tree). It can contain your own projects, libraries, and apps, like so:

mystuff/project/toaster-oven.mk
mystuff/target/toaster-oven/{rules.mk, init.c, ...}
mystuff/app/toaster-ui/{rules.mk, main.c, ...}
mystuff/lib/cool-lcd/{rules.mk, lcddriver.c, ...}
mystuff/lib/pid-controller/...

If you copy lk/makefile to mystuff/makefile and create lk_inc.mk like so:

where are we?

LOCAL_DIR := mystuff # the top path that LKINC and LKROOT are relative to LKMAKEROOT := .. # where to find lk, relative to LKMAKEROOT LKROOT := lk # where to find overlay(s), relative to LKMAKEROOT LKINC := $(LOCAL_DIR) # default project and home for build-* output DEFAULT_PROJECT ?= toaster-oven BUILDROOT ?= $(LOCAL_DIR)

You can then cd to mystuff and run make to build your project. You don’t need to modify anything in the main lk tree, so it’s easy to keep that up to date — no need to fork it, merge or rebase your changes, etc.