About building a build.lua

[jlaurens]

What a package developper, who's knowledge is strictly limited to LaTeX, should be told in order to help him write his first build.lua and use it?
The actual documentation focuses on a public who is sufficiently comfortable with lua. If possible, a pair of advice would help. An example can be something in the spirit of "a one minute introduction to lua to write a build.lua" but that is not a requirement.

[josephwright]

The major aim of l3build is to avoid needing Lua programming at all for users. The major use case is to set up build.lua file which is essentially a set of config variables. That is covered in the manual with some examples. Indeed, I feel we arguably should drop the bit about 'older compatibility', as probably today support for texlua build.lua ... should be removed not just deprecated.

Could you say where the current docs are lacking exactly?

[jlaurens]

I did not really mean to change l3build.dtx. I was thinking more of some step by step example,
Imagine a new target

l3build playground

which only purpose is to copy one of the test bundles to the current directory (asking the name eventually)
then newcomers would cd to that dir and run various l3build targets.
Then change the build.lua eventually.

The only limitation would be the upload mechanism that should be restricted.

[wspr]

Hi Jérôme — Indeed, I’ve thought in the past something like “l3build init” would be nice to set up a “canonical” example document using (say) the current directory name as the name of the module. I guess as long as we have a few canonical examples that people can try we will avoid “bike shedding” exactly what the “init” command does :)

[davidcarlisle]

I'm not convinced as the only thing the init target should do (if we got the defaults right) is have a single line build.lua that contains module = "whatever" (Sadly I couldn't find any of my build.lua that are just that but I always claim "special circumstances" (such as "place the files where Heiko chose to place them 10 years previously") which mean there are extra settings in the file but I would say the design is that you only need to set the module.

[FrankMittelbach]

Personally I wouldn't mind getting a default build.lua set up with a number of common variables set maybe with -- var = default. I often have to adjust the check engines or the number of typeset runs and a few other things even for fairly simple setups. One could even argue that it should contain all defaults behind comment lines, because for me at least it would make adjustments simpler than looking through the documentation and hunt for a variable there.