Minor documentation comments

[devurandom]

• Can you sort the "Lake as a Lua Library" and "Globals" sections alphabetically? There also seems to be some duplication going on in the Globals section...
• Might be nice to spell PLAT out as PLATFORM and make "Windows" its value, instead of duplicating that into a WINDOWS variable
• The MSVC variable could instead become a value of a COMPILER variable
• Does Lake have a concept of CPP- and LDFLAGS?
• Does it import these from the environment?
• What is C_LINK_DLL? And C_EXE_EXPORT?
• Does C_LIBSTATIC make all libs static? I.e. *.a?
• The other globals there are also rather cryptic...
• In general: Have a look at CMake and see how to do it badly, by cluttering it with variables adhering to no scheme and without obvious meaning.

[stevedonovan]

I have a tendency to prefer shorter words, and this sometimes goes too far; it really should be PLATFORM, and the extra global flag WINDOWS can be always replaced with PLATFORM='Windows' tests, ditto for COMPILER. (There is a global CC)

The list of accepted fields at lake line 2733 should be sorted alphabetically and pasted as is into the docs. Would be easier then to see that flags (alias cflags) is our old friend CFLAGS and libflags is LDFLAGS. (an alias of lflags would be consistent here). These fields can of course be overused, e.g. rather use defines to provide a list of preprocessor macros, etc.

I thought about importing globals from the environment but decided that it was a recipe for confusion, although a lot of programs do this. There is precisely one environment variable, LAKE_PARMS which can contain VAR=VALUE pairs separated by semi-colons. (It occurs to me now that this is not the bash-friendly option.) We could have CFLAGS etc globals but heaven knows there's already enough globals going on - and I'm very aware of how confusing CMake can be ;)

(known globals map is at line 2055)

C_LINK_DLL has been changed to lang.LINK_DLL since properly it depends on the language. It is the link flag needed to generate a shared library, so it's e.g. '/DLL' for MSVC, '-shared' for GCC unless we're on OS X when it's ' -dynamiclib -undefined dynamic_lookup'.

For Linux, we have c.EXE_EXPORT = ' -Wl,-E' - for programs like the Lua standalone executable that need to export their symbols - it's not applicable to Windows where there are other mechanisms for this.

c.LIBSTATIC = '-static' for GCC so it follows the usual rules. We can do better than this.

I'm going to bring out a new version soon, and I have a few decisions to make. There's a global COMBINE which controls whether a tool should try to process as many files as it can. But it can't work with odir AFAIK and I'm thinking of making it false by default. Instead, we get better throughput by the more traditional strategy of spawning multiple parallel instances of the compiler. Any thoughts on this choice?

[devurandom]

For the reordering of program_flags I created a pullrequest (#18). I am not entirely sure about this being the best way to document it, though. Mostly because all kinds of fields are mixed now, i.e. fields describing the program type (static, dynamic), cflags, fields describing the build process (odir), etc. For the sourcecode it seems better this way, but for the docs it might be better to go with smaller sections (similar to the OSX section there).

Re: Env, Globals

I will go a bit offtopic (docs) here, so please tell me if I shall open a separate bug on this.

I once saw a nice concept (I think it was waf) for how to solve this issue: Put all these flags together into one configuration table. There could be a default configuration in lake.config, which can be initialised from the environment (i.e. via os.getenv). lake.program could use this table by default (e.g. passed as an upvalue when creating the lake module table), but allow passing a different config as a parameter. For fields it cannot find in the parameter, it could again do a lookup in lake.config. This would simplify work for the user, since he does not have to create/inherit a complete config via lake.config.clone or whatever, but can do stuff like lake.program(config={compiler=clang}, ...). That would get you rid of most of the globals, as well as creating a handy way to configure the buildprocess, even for multiple programs with different required setups in one lakefile.

Re: known_globals

It seems this variable is never used? What is it for? Could it be turned into a table of ENVVAR="default value if missing"? That would make it also include its own documentation.

---

What is the difference between lang.LINK_DLL and lang.LIBSTATIC? I see none - they are both linker flags, but have a different naming scheme, not mentioning "linker flag" at all.

---

When I read the docs about lang.EXE_EXPORT, since it came with no description, I wondered what "export an executable" might be. Maybe name it lang.LFLAGS_EXPORT_ALL to make the purpose clearer? (Though "all" could be confused with the --export-all-symbols flag of ld.)

---

If you say there is no performance benefit in using -combine (the optimisation benefit of which can also be created by using LTO) and it might even have some issues, then I see no reason to keep it.

[devurandom]

P.S: Can the parts of the docs be generated from Lake's sourcecode itself? That might make "pasted as is into the docs" obsolete.

[stevedonovan]

I like the idea of docs being generated from the source. I maintain LDoc which is pretty flexible and it can be taught per-project tricks. The flags would be easier to understand if they were put into nice categories so that humans don't have to do that search-long-list thing which they're not so good at.