default for --gen-target

[mvolkmann]

What is the default value of the --gen-target option? Does it default to the version of Lua I have installed? Is there a way I could have determined that?

[hishamhm]

That's a great question — I think our documentation is lacking there. The short version of the current behavior, represented in code, is this:

   if not gen_target then
      if _VERSION == "Lua 5.1" or _VERSION == "Lua 5.2" then
         gen_target = "5.1"
      else
         gen_target = "5.3"
      end
   end

In plain English, I guess a paragraph we could add to our documentation would be this:

The target version for code generation can be set explicitly or implicitly. If set explicitly, via the --gen-target flag of the tl CLI (or the equivalent options in the programmatic API), the generated code will target the Lua version requested: 5.1, 5.3 or 5.4. If not set explicitly, Teal will target the Lua version most compatible with the version of the Lua VM under which the compiler itself is running: for example, if running under something that reports _VERSION as "Lua 5.1" or "Lua 5.2" (which includes LuaJIT), it will generate 5.1-compatible code; if running under Lua 5.3 or greater, it will output code that uses 5.3 extensions. The stand-alone tl binaries are built using Lua 5.4, so they default to generating 5.3-compatible code. If you require the tl Lua module and use the tl.loader(), it will do the implicit version selection, picking the right choice based on the Lua version you're running it on.

Would the above be sufficiently clear?

An additional explanation: The reason why we don't target 5.4 by default on Lua 5.4 is because as of today --gen-target=5.4 is a bit of a special case that requires --gen-compat=off, as it only applies to outputting the 5.4-specific <close> attribute. For the 5.1 vs. 5.3 instead, we do generate 5.1-compatible code for almost all 5.3-style constructs used in Teal (e.g. x // y generates math.floor(x / y) if using --gen-target=5.1).

[hishamhm]

I added a revised version of the above to the docs/compiler_options.md file