kas Setup Tool

kas is a setup tool designed to automate the configuration and build process for bitbake-based projects. Unlike manual OpenEmbedded workflows where source downloading and configuration are handled by hand (often following a README), kas uses a project configuration file to automate the download and configuration phases.

Key capabilities include:

• Cloning and checking out bitbake layers.
• Creating default bitbake settings (e.g., machine, architecture).
• Launching a minimal build environment to reduce the risk of host contamination.
• Initiating the bitbake build process.

The kas CLI is extended via a plugin system where each plugin typically implements one or more sub-commands. The following sub-commands are available through the kas command line interface:

• build: Executes the build process.
• checkout: Handles repository checkouts.
• clean: Performs cleaning operations.
• cleanall: Performs deep cleaning of all components.
• cleansstate: Cleans the sstate-cache.
• diff: Compares differences.
• diff: Compares differences.
• dump: Dumps configuration or state information.
• for-all-repos: Runs a command across all repositories.
• lock: Manages locks.
• menu: Displays a command menu.
• purge: Performs purging operations.
• shell: Opens a shell within the configured environment.

Lockfiles allow you to override the commit ID of a repository defined in a .yml configuration file.

To use a lockfile, create a file named <original_filename>.lock.<extension> (e.g., kas-isar.yml -> kas-isar.lock.yml) in the same directory as the configuration file. Kas automatically detects and loads this lockfile before processing the main file.

The lockfile should contain an overrides section to specify the new commit.

# kas-isar.lock.yml
header:
  version: 14
overrides:
  repos:
    isar:
      commit: 0336610df8bb0adce76ef8c5a921c758efed9f45

To ensure tests are decoupled from the local environment, use the monkeykas fixture. This fixture cleans up the environment before each test.

Environment Variables: Do not assume values for KAS_WORK_DIR or KAS_BUILD_DIR. Instead, use these monkeykas helpers to access paths safely:

• monkeykas.get_kwd(): returns the absolute path to the current KAS_WORK_DIR.
• monkeykas.get_kbd(): returns the absolute path to the current KAS_BUILD_DIR.
• monkeykas.move_to_kwd(path): moves the specified path into the KAS_WORK_DIR if necessary.

Testing directory layouts: Use monkeykas.setenv() to temporarily set KAS_WORK_DIR and KAS_BUILD_DIR to test different directory combinations. Tests relying on these features should be marked with the dirsfromenv marker.

By default, kas places download and build artifacts in the current directory. You can control the location of these files using the following environment variables:

• KAS_WORK_DIR: Sets the base location for all work. Repositories managed by kas are stored under their path (or name if path is not set) within this directory.
• KAS_BUILD_DIR: Sets the build directory name relative to KAS_WORK_DIR. If not set, the build directory is named build.

Internal data that persists across executions is prefixed with .kas_.

KAS provides several mechanisms to inject credentials into the build environment, making them available to both KAS and the underlying build tools (like BitBake).

Key behaviors:

• Environment Variables: Credentials provided via environment variables are automatically forwarded to the build environment.
• File-based Credentials: Files like .netrc are only copied into the isolated environment if explicitly requested by setting the corresponding environment variable.
• Isolation: Because KAS may need to modify configuration files to inject credentials, it often copies these files into the isolated environment first to avoid mutating the host's original files.

Every kas configuration file must contain a header that provides context to the kas tool. Key header elements include:

• version: An integer representing the configuration format version. kas uses this to ensure compatibility with the file. This version is incremented whenever the format changes.
• machine: Specifies the target machine, as defined in the BitBake local.conf.
• distro: Specifies the distribution name, as defined in the BitBake local.conf.
• bblayers (implied): Configuration files include the repository locations for layers to be added to bblayers.conf.