kraken <aspect>
Experimental
Kraken aspects are an experimental feature that might undergo breaking changes. Use with care!
Overview
Aspects are a new way to interface with the Kraken CLI and control task execution starting with kraken-build v0.46.0.
An aspect represents a set of tasks that achieve a similar goal (think "linting", "type checking", etc.) and gives them a dedicated CLI with a dedicated behaviour for task selection and furthermore allows some level of in-place configuration of the tasks without modifying the build scripts.
For aspects to be usable, the tasks you want to run through an aspect must explicitly support it an the options that are available for that aspect.
The following aspects are currently available (see also ASPECTS).
Options for aspect commands
The kraken <aspect> commands take all the options available to kraken run in addition to the options you can
see outlined in the command usage below, with a precedence to the kraken run options.
That means you can mix for example the -v or -X,--exclude-subgraph options with the aspect options, but when
they overlap, the pseudo argument -- must be specified, such as for the --help argument.
kraken lint --helpwill give you the options that are shared by all aspect commands.kraken lint -- --helpwill give you the options for the lint aspect specifically.
Shared aspect options
usage: kraken build [-h] [-v] [-q] [-b PATH] [-p PATH] [-x TASK] [-X TASK] [-s] [-0] [args ...]
The `build` aspect. Use `-- --help` to see aspect-specific options.
positional arguments:
args Arguments for the aspect
options:
-h, --help show this help message and exit
logging options:
-v increase the log level (can be specified multiple times)
-q decrease the log level (can be specified multiple times)
build options:
-b PATH, --build-dir PATH the build directory to write to [default: build]
-p PATH, --project-dir PATH the root directory of the project. If this is specified, it should point to an
existing directory that contains a build script and it must be the same or a parent
of the current directory. When invoked with this option, task references are
resolved relative to the Kraken project that is represented by the current working
directory. (note: this option is automatically passed when using kraken-wrapper as
it finds the respective project automatically).
run options:
-x TASK, --exclude TASK exclude one or more tasks
-X TASK, --exclude-subgraph TASK exclude the entire subgraphs of one or more tasks
-s, --skip-build just load the project, do not build
-0, --allow-no-tasks don't error if no tasks got selected
The build aspect
Usage: BuildAspect [ARGS] [OPTIONS]
Execute a task or build a given artifact.
Support of the options depends on the selected target.
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ --help -h Display this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ * TARGET --target A single Kraken tasks and/or output path. If a │
│ basic name is used (e.g. main), it will be │
│ treated as a target name. Use e.g. ./main to │
│ reference a local file called main. [required] │
│ --outfile When selecting a task that produces a single │
│ output file, it may support altering the path it │
│ is placed in via this option. Some tasks may │
│ produce a folder instead. │
│ --release --no-release Some tasks may distinguish between debug and │
│ release builds. Using this option is equal to │
│ setting --build-mode=release. [default: False] │
│ --debug --no-debug Some tasks may distinguish between debug and │
│ release builds. Using this option is equal to │
│ setting --build-mode=debug. [default: False] │
│ --build-mode │
│ --symlink --no-symlink Define whether symlinks should be created when │
│ writing the result paths of the task or not. │
╰──────────────────────────────────────────────────────────────────────────────╯
The fmt aspect
Usage: FmtAspect [ARGS] [OPTIONS]
Perform formatting on code in the project.
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ --help -h Display this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ PATHS --paths --empty-paths Narrow the set of files to format down to these │
│ paths. If not specified, it's equivalent of │
│ passing "." [default: [PosixPath('.')]] │
│ --check --no-check Instead of formatting files, only whether the │
│ files _would_ be formatted, and error if there │
│ are any. [default: False] │
╰──────────────────────────────────────────────────────────────────────────────╯
The lint aspect
Usage: LintAspect [ARGS] [OPTIONS]
Perform linting on the code in a project.
Linting concerns the process of checking the code for semantic, stylistic and
specific formatting issues that could lead to bugs or make the code harder to
read and maintain. This aspect provides a common interface for tasks that
implement such checks.
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ --help -h Display this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ PATHS --paths --empty-paths Narrow the set of files to lint down to these │
│ paths. If not specified, it's equivalent of │
│ passing "." [default: [PosixPath('.')]] │
│ --fix --no-fix Automatically fix issues where possible. │
│ [default: False] │
│ --unsafe-fix --no-unsafe-fix Automatically fix issues where possible, even │
│ if it may lead to unsafe changes. This is a │
│ more aggressive option and should be used with │
│ caution. [default: False] │
╰──────────────────────────────────────────────────────────────────────────────╯
The check aspect
Usage: CheckAspect [ARGS] [OPTIONS]
Perform type checking on the code in a project.
Type checking concerns itself only with the correctness of code with respect to
its type definitions.
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ --help -h Display this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ PATHS --paths --empty-paths Narrow the set of files to check down to these │
│ paths. If not specified, it's equivalent of │
│ passing "." [default: [PosixPath('.')]] │
╰──────────────────────────────────────────────────────────────────────────────╯
The test aspect
Usage: TestAspect [ARGS] [OPTIONS]
Execute tests in your code base.
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ --help -h Display this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ PATHS --paths --empty-paths Narrow the set test sources down to these │
│ paths. If not specified, it's equivalent of │
│ passing "." [default: [PosixPath('.')]] │
│ --filter --empty-filter One or more tokens to filter by. Tests that │
│ include either one of these tokens will be run. │
│ [default: []] │
╰──────────────────────────────────────────────────────────────────────────────╯
The invoke aspect
Note
The RunAspect is called invoke on the CLI because the kraken run
command is already occupied.
Usage: RunAspect [ARGS] [OPTIONS]
Invoke a task that represents something runnable and which optionally accepts
additional arguments.
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ --help -h Display this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ ARGS Additional arguments to pass to the runnable. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ * TASK --task The name of the task to invoke. [required] │
╰──────────────────────────────────────────────────────────────────────────────╯