~matthiasbeyer/butido

ref: 1a6511b138c86dd1304555d9b1ddccf716aa7ce1 butido/doc/scripting.md -rw-r--r-- 3.7 KiB
1a6511b1Matthias Beyer Merge branch 'source-download-timeout' into next 1 year, 20 days ago

#Scripting

This document describes the scripting in butido.

First of all, the scripts butido runs are not set to be bash or any other programming language. Technically, writing your packaging scripts in anything that can be called with a shebang is possible (because butido takes the shebang from the config when compining the script).

BUT the scripts for all packages must be the same scripting language, it is not possible to write one package in bash and some other package in python and make butido automatically chose the right interpreter for the shebang.

Besides from that, there are no hard requirements but only some that make your life easier.

The following sections describe some output lines butido can parse and understand to get metadata for your build.

These can be either printed via echo or via the script helpers provided for each kind of output. Note that the script helper is equivalent to writing the echo output yourself and is just added for convenience.

Helpers for other scripting languages besides bash do not exist (yet?).

#State

Your script can finish with two states. These states MUST be set from your script, otherwise, butido will not be able to know whether your build was successfull or not.

  • Printed: echo "#BUTIDO:STATE:OK" for a successfull exit echo '#BUTIDO:STATE:ERR:"errormessage"' for erroneous exit
  • Helper {{state "OK"}} for a successfull exit {{state "ERR" "message"}} for erroneous exit

#Phases

The configuration file features a field where you can define "phases" of the packaging script. These phases are nothing more than commented sections of your script. Butido concatenates all configured phases to one huge script. These phases can help you organizing what is happening, for example you can have a phase for unpacking the sources, one for preparing the build, one for building and finally one for packaging. The upper limit of number of phases is not restricted, but at least one must exist.

Phases can be announced to the CLI frontend via printing

  • Bash: echo '#BUTIDO:PHASE:<phasename>'
  • Helper: {{phase "<phasename>"}} using the helper provided by butido.

Only the latest phase will be shown to the user. The phase name will also be shown to the user if the packaging script fails, so they can find the location of the error faster.

#Progress

The script can also print progress information to the CLI frontend. This progress information is nothing more than a number (0..100) that is used to update the progress bar.

It can be updated using

  • Bash: echo '#BUTIDO:PROGRESS:<number>'
  • Helper: {{progress <number>}}

This feature is completely a quality-of-life feature to give the caller of butido a visual feedback about the progress of a packaging script. For the packaging progress itself it is not required.

(Butido might get functionality to infer the progress information based on earlier builds of the same package using heuristics. This might or might not deprecate this feature).

#Other helpers

The (handlebars) templating engine we use to provide helpers for the package script building provides some basic helpers, e.g.:

  • if-else
  • each
  • boolean helpers for if conditions

For a full list see the handlebars documentation. The "logging" feature of handlebars is not enabled, thus, the logging helpers are not included.

butido provides some more helpers:

  • join for joining several strings to one string: {{join "foo" "bar}} -> foobar Arguments can also be variables.

  • joinwith for joining several strings to one string seperated {{joinwith ", " "foo" "bar}} -> foo, bar Arguments can also be variables.