Next: (maak net), Previous: (maak maak), Up: API
The command line entry point.
Two things matter here beyond parsing the options. First, a user-facing failure must read as one line, not as a Guile backtrace: every error maak raises itself is a ‘&maak-error’ (see ‘(maak dsl)’), and this module prints those as a short message with a hint. Second, the load path is assembled from several sources – the ‘-L’ flag, ‘MAAK_LOAD_PATH’, and the directory of the maak file itself – so a project can require its own modules without exporting GUILE_LOAD_PATH by hand.
Return the most descriptive string Guile attached to a caught error.
The shape of the arguments depends on who raised the error. A call to ‘error’ arrives as (#f MESSAGE () #f), where the message is the second element, while a primitive failure such as ‘(car 1)’ arrives as (#f MESSAGE (1) (1)) whose *first* string is only the name of the procedure – reporting that as the message would hide the one sentence the user needs. The second element is the message in both shapes, so it is preferred, and the remaining values are searched only when it is not a string, as when ‘throw’ is handed a key and a message but no irritants.
Return a one-line human message for a caught error.
It prefers an attached exception message, then the message among the raising values, and only then falls back to the raw key. Guile raises many errors with a format *template* (for example ‘no code for module ~S’) plus the arguments; those are filled in here so the user never sees a bare ‘~S’.
Entry point for the maak command line interface.
Parse ARGS and either print help or the version, list the tasks, or run the requested tasks. Returns the process exit status: 0 on success, 1 when the maak file or a task failed. User-facing errors print as one line; set ‘MAAK_DEBUG’ (or pass –debug) to see the Guile backtrace instead.
Print an unexpected error.
An unexpected failure is a bug in maak, or a genuine error in the maak file, rather than something maak can explain, so the message says so and points at the way to get the backtrace – and, when it is a missing module, at the way to put it on the load path.
Print a ‘&maak-error’ ERROR as a short, red, backtrace-free message.
Return whether the greeting banner should be printed for OPTIONS.
The ‘–no-banner’ flag wins over ‘–banner’, which wins over the environment: an explicit ‘–banner’ is how a reader of a script asks for the banner back after ‘MAAK_NO_BANNER’ was exported for the shell as a whole.
Return the environment files to read for OPTIONS and maak file FILE.
‘–env-file’ names them explicitly and, when given, is the only source; otherwise ‘MAAK_ENV_FILE’ is read, and failing that a ‘.env’ beside the maak file. ‘–no-env-file’ turns the whole mechanism off, which is what a reproducible run wants – the same command, no matter what a checkout happens to contain.
Return the absolute path of the maak file to load, or raise a maak error.
FILE defaults to ‘maak-default-file’ when the command line did not name one. The path is canonicalised because ‘load’ resolves a relative name against the directory of the module that calls it – from this module, ‘./maak.scm’ would be searched for as ‘maak/maak.scm’ and could load a completely different file.
Return whether the directories ‘-C/–directory’ enters should be reported.
A run that changes directory says where it ended up, because a task that ran somewhere else is the kind of thing that is worth knowing without asking. The report is what make’s ‘-w’ prints, and ‘–no-print-directory’ is the switch of make’s that turns it off – useful when the output of a run is read by something other than a person. ‘–quiet’ asks for the same silence, among other things, and so does not bring the lines back.
Return #t when STR is set to something other than 0, false or no.
A switch that lives in the environment has to be given a value, and every convention for ‘off’ is accepted rather than only the empty string.
"./maak.scm"
((file (single-char #\f) (value #t) (required? #f)) (resources (single-char #\r) (value #t) (required? #f)) (list (single-char #\l) (value #f) (required? #f)) (dry-run (single-char #\n) (value #f) (required? #f)) (quiet (single-char #\q) (value #f) (required? #f)) (tasks (single-char #\t) (value #t) (required? #f)) (directory (single-char #\C) (value #t) (required? #f)) (keep-going (single-char #\k) (value #f) (required? #f)) (ignore-errors (single-char #\i) (value #f) (required? #f)) (jobs (single-char #\j) (value #t) (required? #f)) (no-print-directory (value #f) (required? #f)) (load-path (single-char #\L) (value #t) (required? #f)) (env-file (single-char #\e) (value #t) (required? #f)) (no-env-file (value #f) (required? #f)) (banner (value #f) (required? #f)) (no-banner (value #f) (required? #f)) (version (single-char #\v) (value #f) (required? #f)) (debug (value #f) (required? #f)) (help (single-char #\h) (value #f) (required? #f)))
Next: (maak net), Previous: (maak maak), Up: API