Command-line interface

Craftr’s command-line interface should feel easy, quick and efficient to use. There are only flags that alter the manifest export and build process and no subcommands.

Synopsis

usage: craftr [-h] [-V] [-v] [-m MODULE] [-b] [-e] [-c] [-d PATH] [-p PATH]
              [-D <key>[=<value>]] [-I PATH] [-N ...] [-t {standard,external}]
              [--no-rc] [--rc FILE] [--strace-depth INT] [--rts]
              [--rts-at HOST:PORT]
              [targets [targets ...]]

https://github.com/craftr-build/craftr

positional arguments:
  targets

optional arguments:
  -h, --help            show this help message and exit
  -V, --version
  -v, --verbose
  -m MODULE, --module MODULE
  -b, --skip-build
  -e, --skip-export
  -c, --clean
  -d PATH, --build-dir PATH
  -p PATH, --project-dir PATH
  -D <key>[=<value>], --define <key>[=<value>]
  -I PATH, --search-path PATH
  -N ..., --ninja-args ...
  -t {standard,external}, --buildtype {standard,external}
  --no-rc
  --rc FILE
  --strace-depth INT
  --rts
  --rts-at HOST:PORT

targets

Zero or more targets to build. Target names can be absolute or relative to the main module name (beginning with a period). Targets that are referenced from modules that haven’t been imported already will be imported.

If the specified target or targets are only Python backed tasks (see craftr.task()), Ninja will not be invoked since the tasks can be executed solely on the Python side. In many cases, this is often even desired (eg. if you’re using Craftr only for tasks).

-V, --version

Display the version of Craftr and exit immediately.

-v, --verbose

Add to the verbosity level of the output. This flag can be specified mutliple times. Passing the flag once will enable debug output and show module name and line number on logging from Craftr modules. Also, stracktraces are printed for craftr.error() uses in Craftr modules.

A verbosity level of two will enable stacktraces also for logging calls with craftr.info() and craftr.warn().

This flag will also cause -v to be passed to subsequent invokations of Ninja.

-m, --module

Specify the main Craftr module that is initially loaded. If not specified, the Craftfile in the current working directory is loaded.

-b, --skip-build

Skip the build phase.

-e, --skip-export

Skip the export phase and, if possible, even the step of executing Craftr modules. If -n, --no-build is not passed, ie. building should take place, a previous invocation must have exported the Ninja build manifest before, otherwise the build can not execute.

If a manifest is present, Craftr loads the original search path (-I) and options (-D), so you don’t have to specify it on the command-line again! Craftr will act like a pure wrapper for Ninja in this case.

Note that in cases where tasks are used and required for the build step, Craftr can not skip the execution phase.

Changed in v1.1.0: Inverted behaviour.

-c, --clean

Clean the specified targets. Pass the flag twice to clean recursively which even works without explicitly specifying a target to clean.

-d, --build-dir

Specify the build directory. Craftr will automatically switch to this directory before the main module is exeucted and will stay inside it until the build is completed.

-p, --project-dir

Similar to -d, --build-dir, but this option will cause Craftr to use the current working directory as build directory and instead load the main module from the specified project directory.

-D, --define

Format: -D key[=value]

Set an option, optionally with a specific string value. This option is set in the environment variables of the Craftr process and inherit by Ninja. The key may be anything, but if it begins with a period, it will be automatically prefixed with the main module identifier.

As an example, say the Craftfile in your working directory has the identifier my_module. Using -D.debug=yes will set the environment variable my_module.debug to the string 'yes'.

If you leave out the value part, the option is set to the string value 'true'. If you keep the assignment operator without value, the option will be unset.

-I, --search-path

Add an additional search path for Craftr modules.

-N, --ninja-args

Consumes all arguments after it and passes it to the Ninja command in the build step.

-t, --buildtype {standard, external}

Switch between standard or externally controlled build. Choosing the external option will cause target generator functions to consider environment variables like CFLAGS, CPPFLAGS, LDFLAGS and LDLIBS or whatever else is applicable to the target generator you’re using.

Note

The consideration of these environment variables is completely dependent on the implementation of the target generator.

See also

The selected buildtype can be read from the craftr.Session.buildtype attribute.

--no-rc

Don’t run craftrc.py files

--rc

Specify a file that will be executed before anything else. It will be executed the same way craftrc.py files are. Can be combined with --no-rc to exclusively run the specified file.

--strace-depth

Specify the depth of the stacktrace when it is printed. This is only for stacktraces printed with the Logging. The default value is 5. Also note that frames of builtin modules are hidden from this stacktrace.

--rts

Keep alive the Craftr runtime server until you quit it with CTRL+C.

--rts-at

Specify the HOST:PORT for the Craftr runtime server instead of picking loopback and a random port.