table of contents
KAS(1) | kas | KAS(1) |
NAME¶
kas - a setup tool for bitbake based projects
INTRODUCTION¶
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.
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
USER GUIDE¶
Usage¶
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
- 3.
- Interactive configuration:
$ cd $PROJECT_DIR/meta-project $ kas menu $ kas build # optional, if not triggered via kas menu
Plugins¶
kas sub-commands are implemented by a series of plugins. Each plugin typically provides a single command.
- kas-build(1)
- build the project
- kas-checkout(1)
- checkout all repos without building
- kas-dump(1)
- dump the flattened configuration or lockfiles
- kas-for-all-repos(1)
- run a command in each repository
- kas-menu(1)
- interactive menu to configure the build
- kas-shell(1)
- start a shell in the build environment
Project Configuration¶
The project configuration file describes the build environment and the layers to be used. It is the main input to kas. For details, see kas-project-config(1)
Credential Handling¶
kas provides various mechanisms to inject credentials into the build. For details, see kas-credentials(1).
COMMAND LINE USAGE¶
kas - setup tool for bitbake based project
usage: kas [-h] [--version] [-d] [-l {debug,info,warning,error,critical}]
{build,checkout,dump,for-all-repos,shell,menu} ...
Positional Arguments¶
- cmd
- Possible choices: build, checkout, dump, for-all-repos, shell, menu
sub command help
Named Arguments¶
- --version
- show program's version number and exit
- -d, --debug
- Enable debug logging (deprecated, use --log-level debug).
- -l, --log-level
- Possible choices: debug, info, warning, error, critical
Set log level (default: info)
Default: "info"
Environment Variables¶
kas uses a number of environment variables to configure its behavior. The Variables Glossary provides an overview, wherein the tuple (C,K,E) denotes the scope of the variable.
Variable Scope¶
kas-container (C)
The variable is processed or forwarded by the kas-container script. For some variables, the variable is re-written to the container's directory layout.
NOTE:
kas (K)
The variable is processed by kas itself. Some variables (e.g. the credentials for the awscli) are re-written to configuration files to also support older versions of the tooling.
build environment (E)
The variable is exported into the build environment. In this environment, the bitbake command is executed.
Variables Glossary¶
Environment variables | Description |
KAS_WORK_DIR (C, K) | The path of the kas work directory, current work directory is the default. |
KAS_BUILD_DIR (C, K) | The path build directory, ${KAS_WORK_DIR}/build is the default. |
KAS_REPO_REF_DIR (C, K) | The path to the repository reference directory. Repositories in this directory are used as references when cloning. In order for kas to find those repositories, they have to be named in a specific way. The repo URLs are translated like this: "https://github.com/siemens/meta-iot2000.git" resolves to the name "github.com.siemens.meta-iot2000.git". Repositories that are not found will be cloned below this directory. Multiple instances of kas can simultaneously work on the same directory, as long as the underlying filesystem is POSIX compatible. |
KAS_DISTRO KAS_MACHINE KAS_TARGET KAS_TASK (C, K) | This overwrites the respective setting in the configuration file. |
KAS_PREMIRRORS (C, K) | Specifies alternatives for repo URLs. Just like bitbake PREMIRRORS, this variable consists of new-line separated entries. Each entry defines a regular expression to match a URL and, space-separated, its replacement. E.g.: "http://.*.someurl.io/ http://localmirror.net/" |
DISTRO_APT_PREMIRRORS (C) | Specifies alternatives for apt URLs. Just like KAS_PREMIRRORS. |
SSH_PRIVATE_KEY (K) | Variable containing the private key that should be added to an internal ssh-agent. This key cannot be password protected. This setting is useful for CI build servers. On desktop machines, an ssh-agent running outside the kas environment is more useful. |
SSH_PRIVATE_KEY_FILE (K) | Path to the private key file that should be added to an internal ssh-agent. This key cannot be password protected. This setting is useful for CI build servers. On desktop machines, an ssh-agent running outside the kas environment is more useful. |
SSH_AUTH_SOCK (C,K,E) | SSH authentication socket. Used for cloning over SSH (alternative to SSH_PRIVATE_KEY or SSH_PRIVATE_KEY_FILE). |
DL_DIR SSTATE_DIR SSTATE_MIRRORS (C,K,E) | Environment variables that are transferred to the bitbake environment. |
TMPDIR (K,E) | Directory for temporary files. |
http_proxy https_proxy ftp_proxy no_proxy (C,K,E) | These variables define the proxy configuration bitbake should use. |
GIT_PROXY_COMMAND (E) NO_PROXY (C,K,E) | Set proxy for native git fetches. NO_PROXY is evaluated by OpenEmbedded's oe-git-proxy script. |
SHELL (C,K,E) | The shell to start when using the shell plugin. |
TERM (C,K,E) | The terminal options used in the shell plugin. |
AWS_CONFIG_FILE AWS_ROLE_ARN AWS_SHARED_CREDENTIALS_FILE AWS_WEB_IDENTITY_TOKEN_FILE (K,C) | Path to the awscli configuration and credentials files that are copied to the kas home dir. |
GIT_CREDENTIAL_HELPER GIT_CREDENTIAL_USEHTTPPATH (K,C) | Allows to set and configure the git credential helper in the .gitconfig of the kas user. |
GITCONFIG_FILE (K,C) | Path to a .gitconfig file which will be copied to the kas home dir as .gitconfig. |
NETRC_FILE (K,C) | Path to a .netrc file which will be copied to the kas home dir as .netrc. |
CI_SERVER_HOST CI_JOB_TOKEN (K) | Environment variables from gitlab CI, if set .netrc is configured to allow fetching from the gitlab instance. An entry will be appended in case NETRC_FILE was given as well. Note that if the file already contains an entry for that host most tools would probably take that first one. |
GITHUB_ACTIONS (K) | Environment variables from github actions. If set to true, .gitconfig is automatically imported. For details, see GITCONFIG_FILE. |
BB_NUMBER_THREADS PARALLEL_MAKE (C,K,E) | Environment variables to control the concurrency. |
For details about the access of remote resources, see Credential Handling.
SEE ALSO¶
KAS¶
Part of the kas(1) suite.
AUTHOR¶
Daniel Wagner, Jan Kiszka, Claudius Heine
COPYRIGHT¶
Siemens AG, 2017-2024
April 10, 2024 | 4.3.2 |