'\" t
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "KAS" "1" "Apr 10, 2024" "4.3.2" "kas"
.SH NAME
kas \- a setup tool for bitbake based projects
.SH INTRODUCTION
.sp
This tool provides an easy mechanism to setup bitbake based
projects.
.sp
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.
.sp
Key features provided by the build tool:
.INDENT 0.0
.IP \(bu 2
clone and checkout bitbake layers
.IP \(bu 2
create default bitbake settings (machine, arch, ...)
.IP \(bu 2
launch minimal build environment, reducing risk of host contamination
.IP \(bu 2
initiate bitbake build process
.UNINDENT
.SH USER GUIDE
.SS Usage
.sp
Start build:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ kas build /path/to/kas\-project.yml
.EE
.UNINDENT
.UNINDENT
.sp
Alternatively, experienced bitbake users can invoke usual \fBbitbake\fP steps
manually, e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ kas shell /path/to/kas\-project.yml \-c \(aqbitbake dosfsutils\-native\(aq
.EE
.UNINDENT
.UNINDENT
.sp
kas will place downloads and build artifacts under the current directory when
being invoked. You can specify a different location via the environment
variable \fIKAS_WORK_DIR\fP\&.
.SS Use Cases
.INDENT 0.0
.IP 1. 3
Initial build/setup:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
$ mkdir $PROJECT_DIR
$ cd $PROJECT_DIR
$ git clone $PROJECT_URL meta\-project
$ kas build meta\-project/kas\-project.yml
.EE
.UNINDENT
.UNINDENT
.IP 2. 3
Update/rebuild:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
$ cd $PROJECT_DIR/meta\-project
$ git pull
$ kas build kas\-project.yml
.EE
.UNINDENT
.UNINDENT
.IP 3. 3
Interactive configuration:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
$ cd $PROJECT_DIR/meta\-project
$ kas menu
$ kas build  # optional, if not triggered via kas menu
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.SS Plugins
.sp
kas sub\-commands are implemented by a series of plugins. Each plugin
typically provides a single command.
.INDENT 0.0
.TP
.B \fBkas\-build(1)\fP
build the project
.TP
.B \fBkas\-checkout(1)\fP
checkout all repos without building
.TP
.B \fBkas\-dump(1)\fP
dump the flattened configuration or lockfiles
.TP
.B \fBkas\-for\-all\-repos(1)\fP
run a command in each repository
.TP
.B \fBkas\-menu(1)\fP
interactive menu to configure the build
.TP
.B \fBkas\-shell(1)\fP
start a shell in the build environment
.UNINDENT
.SS Project Configuration
.sp
The project configuration file describes the build environment and the layers
to be used. It is the main input to kas.
For details, see \fBkas\-project\-config(1)\fP
.SS Credential Handling
.sp
kas provides various mechanisms to inject credentials into the build.
For details, see \fBkas\-credentials(1)\fP\&.
.SH COMMAND LINE USAGE
.sp
kas \- setup tool for bitbake based project

.INDENT 0.0
.INDENT 3.5
.sp
.EX
usage: kas [\-h] [\-\-version] [\-d] [\-l {debug,info,warning,error,critical}]
           {build,checkout,dump,for\-all\-repos,shell,menu} ...
.EE
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B cmd
Possible choices: build, checkout, dump, for\-all\-repos, shell, menu
.sp
sub command help
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-\-version
show program\(aqs version number and exit
.TP
.B \-d, \-\-debug
Enable debug logging (deprecated, use \-\-log\-level debug).
.TP
.B \-l, \-\-log\-level
Possible choices: debug, info, warning, error, critical
.sp
Set log level (default: info)
.sp
Default: \(dqinfo\(dq
.UNINDENT
.SS Environment Variables
.sp
kas uses a number of environment variables to configure its behavior.
The \fI\%Variables Glossary\fP provides an overview, wherein the tuple (C,K,E)
denotes the scope of the variable.
.SS Variable Scope
.sp
\fBkas\-container (C)\fP
.sp
The variable is processed or forwarded by the \fBkas\-container\fP script.
For some variables, the variable is re\-written to the container\(aqs
directory layout.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBenv\fP section of the \fIproject configuration\fP can be used to make
arbitrary environment variables available to the build environment. When
invoking the build via \fBkas\-container\fP, make sure to also forward the
corresponding environment variables into the container.
.UNINDENT
.UNINDENT
.sp
\fBkas (K)\fP
.sp
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.
.sp
\fBbuild environment (E)\fP
.sp
The variable is exported into the build environment. In this environment, the
\fBbitbake\fP command is executed.
.SS Variables Glossary
.TS
center;
|l|l|.
_
T{
Environment variables
T}	T{
Description
T}
_
T{
\fBKAS_WORK_DIR\fP
(C, K)
T}	T{
The path of the kas work directory, current work
directory is the default.
T}
_
T{
\fBKAS_BUILD_DIR\fP
(C, K)
T}	T{
The path build directory,
\fB${KAS_WORK_DIR}/build\fP is the default.
T}
_
T{
\fBKAS_REPO_REF_DIR\fP
(C, K)
T}	T{
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:
\(dq\fI\%https://github.com/siemens/meta\-iot2000.git\fP\(dq
resolves to the name
\(dqgithub.com.siemens.meta\-iot2000.git\(dq.
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.
T}
_
T{
\fBKAS_DISTRO\fP
\fBKAS_MACHINE\fP
\fBKAS_TARGET\fP
\fBKAS_TASK\fP
(C, K)
T}	T{
This overwrites the respective setting in the
configuration file.
T}
_
T{
\fBKAS_PREMIRRORS\fP
(C, K)
T}	T{
Specifies alternatives for repo URLs. Just like
bitbake \fBPREMIRRORS\fP, 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.:
\(dq\fI\%http://.*.someurl.io/\fP \fI\%http://localmirror.net/\fP\(dq
T}
_
T{
\fBDISTRO_APT_PREMIRRORS\fP
(C)
T}	T{
Specifies alternatives for apt URLs. Just like
\fBKAS_PREMIRRORS\fP\&.
T}
_
T{
\fBSSH_PRIVATE_KEY\fP
(K)
T}	T{
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.
T}
_
T{
\fBSSH_PRIVATE_KEY_FILE\fP
(K)
T}	T{
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.
T}
_
T{
\fBSSH_AUTH_SOCK\fP
(C,K,E)
T}	T{
SSH authentication socket. Used for cloning over
SSH (alternative to \fBSSH_PRIVATE_KEY\fP or
\fBSSH_PRIVATE_KEY_FILE\fP).
T}
_
T{
\fBDL_DIR\fP
\fBSSTATE_DIR\fP
\fBSSTATE_MIRRORS\fP
(C,K,E)
T}	T{
Environment variables that are transferred to
the bitbake environment.
T}
_
T{
\fBTMPDIR\fP (K,E)
T}	T{
Directory for temporary files.
T}
_
T{
\fBhttp_proxy\fP
\fBhttps_proxy\fP
\fBftp_proxy\fP
\fBno_proxy\fP
(C,K,E)
T}	T{
These variables define the proxy configuration
bitbake should use.
T}
_
T{
\fBGIT_PROXY_COMMAND\fP (E)
\fBNO_PROXY\fP (C,K,E)
T}	T{
Set proxy for native git fetches. \fBNO_PROXY\fP
is evaluated by OpenEmbedded\(aqs oe\-git\-proxy
script.
T}
_
T{
\fBSHELL\fP
(C,K,E)
T}	T{
The shell to start when using the \fIshell\fP
plugin.
T}
_
T{
\fBTERM\fP
(C,K,E)
T}	T{
The terminal options used in the \fIshell\fP plugin.
T}
_
T{
\fBAWS_CONFIG_FILE\fP
\fBAWS_ROLE_ARN\fP
\fBAWS_SHARED_CREDENTIALS_FILE\fP
\fBAWS_WEB_IDENTITY_TOKEN_FILE\fP
(K,C)
T}	T{
Path to the awscli configuration and credentials
files that are copied to the kas home dir.
T}
_
T{
\fBGIT_CREDENTIAL_HELPER\fP \fBGIT_CREDENTIAL_USEHTTPPATH\fP
(K,C)
T}	T{
Allows to set and configure the git credential
helper in the \fI\&.gitconfig\fP of the kas user.
T}
_
T{
\fBGITCONFIG_FILE\fP
(K,C)
T}	T{
Path to a \fI\&.gitconfig\fP file which will be
copied to the kas home dir as \fI\&.gitconfig\fP\&.
T}
_
T{
\fBNETRC_FILE\fP
(K,C)
T}	T{
Path to a .netrc file which will be copied to
the kas home dir as .netrc.
T}
_
T{
\fBCI_SERVER_HOST\fP
\fBCI_JOB_TOKEN\fP
(K)
T}	T{
Environment variables from gitlab CI, if set
\&.netrc is configured to allow fetching from
the gitlab instance. An entry will be appended
in case \fBNETRC_FILE\fP was given as well. Note
that if the file already contains an entry for
that host most tools would probably take that
first one.
T}
_
T{
\fBGITHUB_ACTIONS\fP
(K)
T}	T{
Environment variables from github actions. If
set to \fItrue\fP, \fI\&.gitconfig\fP is automatically
imported. For details, see \fBGITCONFIG_FILE\fP\&.
T}
_
T{
\fBBB_NUMBER_THREADS\fP
\fBPARALLEL_MAKE\fP
(C,K,E)
T}	T{
Environment variables to control the concurrency.
T}
_
.TE
.sp
For details about the access of remote resources, see
\fI\%Credential Handling\fP\&.
.SH SEE ALSO
.sp
\fBkas\-project\-config(1)\fP,
\fBkas\-build(1)\fP,
\fBkas\-credentials(1)\fP
.SH KAS
.sp
Part of the \fBkas(1)\fP suite.
.SH AUTHOR
Daniel Wagner, Jan Kiszka, Claudius Heine
.SH COPYRIGHT
Siemens AG, 2017-2024
.\" Generated by docutils manpage writer.
.