Go to file
Jan Kiszka c65657cac6 Remove state tracking, use KAS_WORK_DIR env variable
Config.has_changed didn't work reliably so far, so the state cache was
only allowing to associate a work directory with configuration file.
However this was rather unintuitive, specifically when moving the work
dir to a different home - nothing told the user about the persistent
association.

We therefore agreed to remove the state cache for now. It can be
reintroduced at any time once a consistent usage model exists.

To establish a relationship to a work directory inside a shell session,
kas now evaluates the KAS_WORK_DIR environment variable.

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
2017-06-19 12:54:24 +02:00
kas Remove state tracking, use KAS_WORK_DIR env variable 2017-06-19 12:54:24 +02:00
.gitignore Initial public release 2017-06-14 15:21:19 +02:00
.travis.yml Add docker image build via Travis CI 2017-06-17 23:46:22 +02:00
CHANGELOG.md Initial public release 2017-06-14 15:21:19 +02:00
CONTRIBUTING.md Initial public release 2017-06-14 15:21:19 +02:00
docker-entrypoint docker: Rename USER_ID variable 2017-06-19 10:47:02 +02:00
Dockerfile Update PyYAML dependencies 2017-06-15 10:07:13 +02:00
LICENSE Initial public release 2017-06-14 15:21:19 +02:00
README.md Remove state tracking, use KAS_WORK_DIR env variable 2017-06-19 12:54:24 +02:00
run-kas Initial public release 2017-06-14 15:21:19 +02:00
setup.py Make __version__ available in the whole module 2017-06-19 12:26:08 +02:00

Setup tool for bitbake based projects

This tool provides an easy mechanism to setup bitbake based projects.

The OpenEmbedded tooling support starts at step 2 with bitbake. The downloading of sources and then configuration has to be done by hand. Usually, this is explained in a README. Instead kas is using a project configuration file and does the download and configuration phase.

Currently supported Yocto versions:

  • 2.1 (Krogoth)
  • 2.2 (Morty)

Older or newer versions may work as well but haven't been tested intensively.

Key features provided by the build tool:

  • clone and checkout bitbake layers
  • create default bitbake settings (machine, arch, ...)
  • launch minimal build environment, reducing risk of host contamination
  • initiate bitbake build process

Dependencies & installation

This projects depends on

  • Python 3
  • PyYAML

If you need Python 2 support consider sending patches. The most obvious place to start is to use the trollius package intead of asyncio.

To install kas into your python site-package repository, run

$ sudo pip install

Usage

There are three options for using kas:

  • Install it locally via pip to get the kas command.
  • Use the docker image. In this case run the commands in the examples below within docker run -it <kas-image> sh or bind-mount the project into the container.
  • Use the run-kas wrapper from this directory. In this case replace kas in the examples below with path/to/run-kas.

Start build:

$ kas build /path/to/kas-project.yml

Alternatively, experienced bitbake users can invoke usual bitbake steps manually, e.g.

$ kas shell /path/to/kas-project.yml -c 'bitbake dosfsutils-native'

kas will place downloads and build artifacts under the current directory when being invoked. You can specify a different location via the environment variable KAS_WORK_DIR.

Use Cases

  1. Initial build/setup

    $ mkdir $PROJECT_DIR
    $ cd $PROJECT_DIR
    $ git clone $PROJECT_URL meta-project
    $ kas build meta-project/kas-project.yml
    
  2. Update/rebuild

    $ cd $PROJECT_DIR/meta-project
    $ git pull
    $ kas build kas-project.yml
    

Project Configuration

Two types of input formats supported. For an product image a the static configuration can be used. In case several different configuration should be supported the dynamic configuration file can be used.

Static project configuration

Currently there is supports for JSON and Yaml.

{
    "machine": "qemu",
    "distro": "poky",
    "repos": [
        { "url": "" },
        { "url": "https://git.yoctoproject.org/git/poky",
          "refspec": "krogoth",
          "sublayers": [ "meta", "meta-poky", "meta-yocto-bsp"]}
    ]
}

A minimal input file consist out of 'machine', 'distro', and 'repos'.

Additionally, you can add 'bblayers_conf_header' and 'local_conf_header' which are arrays of strings, e.g.

    "bblayers_conf_header": ["POKY_BBLAYERS_CONF_VERSION = \"2\"",
                             "BBPATH = \"${TOPDIR}\"",
                             "BBFILES ?= \"\""],
    "local_conf_header": ["PATCHRESOLVE = \"noop\"",
                          "CONF_VERSION = \"1\"",
                          "IMAGE_FSTYPES = \"tar\""]

Dynamic project configuration

The dynamic project configuration is plain Python with following mandatory functions which need to be provided:

def get_machine(config):
    return 'qemu'


def get_distro(config):
    return 'poky'


def get_repos(target):
    repos = []

    repos.append(Repo(
        url='URL',
        refspec='REFSPEC'))

    repos.append(Repo(
        url='https://git.yoctoproject.org/git/poky',
        refspec='krogoth',
        sublayers=['meta', 'meta-poky', 'meta-yocto-bsp'])))

    return repos

Additionally, get_bblayers_conf_header(), get_local_conf_header() can be added.

def get_bblayers_conf_header():
    return """POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
"""


def get_local_conf_header():
    return """PATCHRESOLVE = "noop"
CONF_VERSION = "1"
IMAGE_FSTYPES = "tar"
"""

Furthermore, you can add pre and post hooks (*_prepend, *_append) for the exection steps in kas core, e.g.

def build_prepend(config):
    # disable distro check
    with open(config.build_dir + '/conf/sanity.conf', 'w') as f:
        f.write('\n')


def build_append(config):
    if 'CI' in os.environ:
        build_native_package(config)
        run_wic(config)

TODO: Document the complete configuration API.

Environment variables

KAS_REPO_RED_DIR should point to a directory that contains repositories that should be used as references. In order for kas to find those repositories, they have to be named correctly. Those names are derived from the repo url in the kas config. (E.g. url: "https://github.com/siemens/meta-iot2000.git" resolves to the name "github.com.siemens.meta-iot2000.git")

Development

This project uses pip to manage the package. If you want to work on the project yourself you can create the necessary links via:

$ sudo pip install -e .

That will install a backlink /usr/bin/kas to this project. Now you are able to call it from anywhere.

Docker image build

Just run

$ docker build -t <image_name> .

When you need a proxy to access the internet, add --build-arg http_proxy=<http_proxy> --build-arg https_proxy=<https_proxy> to the call.

Community Resources

Project home:

Source code:

Mailing list: