customize targets and options

[jlaurens]

The actual documentation suggests in section "5.6 Customising the target and option lists" that it is possible to customize the target and options.

Custom targets:

Instead of editing the global table target_list : function available in build.lua.

---Declare a custom command line target
---@param name string name of the target
---@param kv table named arguments including target data
function declaretarget(name, kv)
...
end

This function validates its entries.

Custom options:

In practice, it is not possible to add new options by just changing the option_list variable.

Why? the option_list global variable is initialized just before parsing the command line arguments

At least 2 approaches that do not exclude each other

An extended mode

l3build --extended|-x ... to accept any "-" argument. If an argument is not known, add an entry for it in the option list. The type of the argument is guessed from name and usage by the rules

1. name starts with "is-" ⇒ boolean
2. last argument or followed by a "-" argument ⇒ boolean
3. name ends with "s" ⇒ array of strings
4. otherwise ⇒ string

Notes

• This must be adapted to the --key=value case of course.
• easy to implement
• special option "--" required due to rule 2
• The desc field must be added in the build.lua if necessary
• module agnostic

a configuration file

A cfg.lua near build.lua is executed before the arguments are parsed.

-- cfg.lua
-- inheritcfg() -- uncomment to the module inherit from its enclosing bundle
declareoption("my-option", {
  desc = "my cutting edge option",
  short="O",
  type = "boolean",
}

Notes

• Thecfg.lua execution context is just raw texlua + the declareoption and inheritcfg function. No other l3build related material is available. In particular, this is not a location to define custom targets.
• the declareoption function eventually validate its entries
• slightly less easy to implement
• specific to a given module/bundle,
• in the future, the cfg.lua may use other early morning hooks.
• possible collision with already existing cfg.lua: suggestion for a better name? (except l3build*.lua)