Should main still be exposed in the future?

[jlaurens]

I really mean
Should main be a global lua variable the user can define in build*.lua?

This question came around because in l3build.lua, there is a main = main or stdmain instruction instead of an equivalent main = stdmain. It appeared that it was a reminiscence of a former design now abandoned.
What remains is that main can be redefined in build.lua and this is not documented, neither publicly nor in source code, is it intentional? It was definitely at some point but is it still relevant?

I see 2 ways of defining a global main in build.lua, a complete rewrite or a wrapper.

A wrapper defined in build.lua would read something like

local saved_main = main
function main(target, names)
  ... do something before
  saved_main(target, names)
  ... do something after
end

That would be advantageously replaced by some kind of global before_main_hook(...) and after_main_hooks(...) (there are some hooks already). BTW, I would find more appropriate to have will_process(target, options) and did_process(target, options).

The complete rewrite really means touching seriously the core of l3build. I guess that renaming build.lua into l3build.lua in a repository and running texlua l3build.lua instead of l3build would work the same at a reasonable cost. Of course some supplemental header would be required in the local l3build.lua. Some refactoring could reduce this header to only a pair of lines.

At that point, it seems to me that in the future main should not be exposed publicly and should remain an implementation detail if any, provided some compensation like hooks. I am afraid I missed something.

[davidcarlisle]

This question came around because in l3build.lua, there is a main = main or stdmain instruction instead of an equivalent main = stdmain. It appeared that it was a reminiscence of a former design now abandoned.

@jlaurens as has been stated before this is supporting the initial design where the call is

texlua build.lua

and so build.lua is read first and those two forms are not equivalent as build.lua can define main (as in fact the latex2e one does)

So yes it could be changed but it would be a breaking change not cosmetic "cleanup" that doesn't mean that we shouldn't do it, but it is not as simple a decision as you seem to suggest.

[jlaurens]

So I took a look at latex2e build.lua, but as I could not run it locally, I could not find why it should not work the l3build ... way.

Anyway, for a big break I would be inclined to use a python2/python3 like approach for a 100% backwards support.

People already using l3build could still use it at 0 cost.
New people would be encouraged to use an extended l3buildx.

There is also the l3build --legacy ... approach to switch to some "legacy" mode but at first glance it would require more work.

[josephwright]

So I took a look at latex2e build.lua, but as I could not run it locally, I could not find why it should not work the l3build ... way.

Huh? That one is run routinely by the team, and on Travis-CI: did you checkout the 2e repo?

Anyway, for a big break I would be inclined to use a python2/python3 like approach for a 100% backwards support.

Er, that worked so well for them! More seriously, we don't have quite the same need to avoid all change. The key is to keep the .tlg files the same if at all possible, and to document any changes. Beyond that, we can be flexible provided we know what's changing.

[jlaurens]

Sorry, I was not able to run it locally just because of an inappropriate system configuration of mine.

[josephwright]

Sorry, I was not able to run it locally just because of an inappropriate system configuration of mine.

Ah. The point with that top-level build.lua file is it really only uses the file system and arg parsing parts of l3build, so it has an entirely customised main(). I did originally think of writing a stand-alone build.lua without l3build at all, but that was more of a pain than it was worth.

[josephwright]

At that point, it seems to me that in the future main should not be exposed publicly and should remain an implementation detail if any, provided some compensation like hooks. I am afraid I missed something.

I follow the query but come to a very different conclusion :)

The aim here was that main() is the out wrapper function not only in l3build but (by convention) in many programs. Admittedly, this probably should be explicit in the documentation.

The need for a stdmain() existed as that allows l3build to provide a 'normal case' function in the texlua build.lua approach, but also allowed for an entirely customised main() where required: see for example https://github.com/latex3/latex3/blob/master/build.lua. That need has been reduced by moving from an entirely hard-coded list of targets in stdmain() to a table-based approach, but I don't think it's been eliminated.

Probably, today with the l3build/texlua l3build.lua approach, we likely don't need stdmain, and can simply document that users can re-define main() should they need to. (This presupposes we drop support for texlua build.lua, which as @davidcarlisle says is a breaking change, but one we can consider.) That should of course be documented, but that's very different from dropping main() as a global function!