A Reliable Real-Time Operating System & Application Framework
(c) 2012-2014 James Walmsley james@fullfat-fs.co.uk
Currently released under GNU GPL version 2.0 See LICENSE for more information.
.dbuild - Dark Builder build system. (BitThunder edition).
arch - Contains architecture specific code & bootstrapping for the OS.
+ $(ARCH) - Contains common architecture components, e.g. NVIC/GIC drivers for ARM.
+ mach/$(SUBARCH) - Machine sub-architectures, e.g. zynq, or cortex-m3/stm32 etc etc.
doc - Documentation...
drivers - Architecture independent drivers, e.g. I2C/USB/PCIe devices etc.
kernel - Contains the RTOS scheduler (FreeRTOS).
lib - Contains all BitThunder library code, i.e. the stuff not implementing the OS. Useful structures etc.
os - Contains all of the BitThunder platform independent OS code.
From now on the master branch is locked into a stable development cycle. All work must be carried out on feature branches in the form:
feature/{username|shortcode}[.branchname]
Feature branches may only enter the master branch through a rebase, to keep the project history linear, during which the commit history of the feature branch should be cleaned up (or squashed if appropriate).
In order for a feature branch to be accepted into the master, it must:
- Easily rebase onto the latest master with no conflicts.
- Cleanly compile -- NO ERRORS, NO WARNINGS, output should be "pretty".
- PASS all unit tests (when we have a test system in place!).
In order to initiate the merging process, you must make a merge request. This is easily done on GitHUB using the pull request feature. For those working with me on GitLab, simply make a merge request.
Merges are made with a --no-ff merge so that all commits pertaining to a feature can be easily identified.
It MUST be possible to build the kernel using a sensible configuration from any merge-point on the master branch.
As a consequence the master branch should remain relatively stable. By stable, it is meant that the build process is not broken, and that a kernel image can be generated without much effort.
Even though the master branch can be considered stable in this respect, if you really need a stable kernel, then you should use the last marked stable tag, e.g:
stable-v1.0.0
With BitThunder its easy to get a standalone kernel up and running.
make menuconfig
make
You can create 3 types of BitThunder project.
- A standalone bitthunder kernel, usually calls an initscript on the filesystem.
- An out-of-tree project.
- A GIT managed out-of-tree project, which pulls BitThunder as a submodule.
These are simple:
make menuconfig
make
mkdir myproject # Create a directory for managing and building the new project.
cd myproject
# The next command creates an empty project with reference to the base kernel sources.
make -C ../bitthunder/ PROJECT_DIR=$(pwd) project.init
make menuconfig
make
mkdir myproject.git
cd myproject.git
make -C ../bitthunder/ PROJECT_DIR=$(pwd) project.git.init
make menuconfig
make
All projects create the following files:
$(PROJECT_DIR)/Makefile
$(PROJECT_DIR)/Kconfig
$(PROJECT_DIR)/objects.mk
$(PROJECT_DIR)/main.c
After configuration the following files will be generated:
$(PROJECT_DIR)/include/bt_bsp_config.h
$(PROJECT_DIR)/.config
The project Makefile configures a pair of variables and includes the kernel Makefile.
PROJECT_DIR - Is the directory in which the project exists. (Use $(shell pwd)).
PROJECT_CONFIG - y (default) causes the config system to include $(PROJECT_DIR)/Kconfig.
In a project, the objects.mk file lists the project objects that need to be additionally built and linked into the kernel.
To add a file to the build process you simply add a line to the objects.mk file:
objs += $(APP)/main.o
objs += $(APP)/path/to/my/object.o
include $(PROJECT_DIR)/path/to/module/objects.mk
Note you may also use configuration options (as defined in your Kconfig file) to optionally compile objects:
objs-$(BT_CONFIG_FEATURE_A_SUPPORT) += $(APP)/feature_a.o
Note
Its possible for a project to hook into the Kernel configuration system. Simply add any configuration options to this file, and they will appear under "Project Options" on the menuconfig system.
Note: PROJECT_CONFIG=y must be set in the project Makefile ($(PROJECT_DIR)/Makefile).
To begin with this file is blank. Booting the BitThunder kernel by default will cause it to only print
Welcome to BitThunder
repeatedly on the boot-logger device (boot console).
To override this behaviour, you simply need to create a function called main().
BitThunder uses a GNU Make based build system called dbuild. (Dark Builder). The core of the build-system is found under:
$(BASE)/.dbuild/
All path variables in dbuild must have a trailing slash appended (for consistency and readability).
$(BASE)/ - Root folder of the BitThunder kernel.
$(PROJECT_DIR)/ - Root of the project based on BitThunder being developed.
$(BUILD_DIR)/ - Path where all objects and dependency files will be generated.
The convention was recently changed so that all variables are consistent. You can use some sed rules to update old projects easily:
find . -name "objects.mk" | xargs sed -i 's:$(BASE):$(BASE)/:g'
find . -name "objects.mk" | xargs sed -i 's:$(PROJECT_DIR):$(PROJECT_DIR)/:g'
find . -name "objects.mk" | xargs sed -i 's:$(BUILD_DIR):$(BUILD_DIR)/:g'
$(ARCH) - The architecture variant used. e.g. arm/blackfin/mips.
$(SUBARCH) - The machine variant used. e.g. zynq.
These are used in paths of object files etc.
The build system specifies all objects to be built in the objects.mk files. Adding a new object is simple:
OBJECTS += $(BUILD_DIR)/arch/arm/mach/zynq/myobject.o
You can also use configuration variables like:
OBJECTS-$(BT_CONFIG_FEATURE_A) += $(BUILD_DIR)/feature_a/feature_a.o
To include another folder in the build system:
include $(BASE)/drivers/net/objects.mk
You can include other folders based on configuration variables like:
ifeq($(BT_CONFIG_FEATURE_A),y)
include $(BASE)/feature_a/objects.mk
endif