Lua Notes

1. NELUA_INIT
2. global neluacfg.lua
3. project-local .neluacfg.lua
4. tooling .neluacfg.*.lua
5. Configuration keys

NELUA_INIT

The contents of this environment variable are run when nelua starts up. This is actually the very first thing that happens when nelua starts up, barring toplevel code that executes as libraries are loaded.

global neluacfg.lua

This is hardcoded to $HOME/.config/nelua/neluacfg.lua

Example contents from github discussions:

return {
  cc="ccache gcc",
  cflags="-Wall -Wextra",
  add_path={
    '/home/bart/projects/nelua/nelua-decl/libs/?/?.nelua',
  }
}

Note that this is executed Lua code, which is run rather early (so, no pragmas table to check, for example). For example, here is a global configuration that does nothing except give nelua's CLI a useless feature:

for i, a in ipairs(arg) do
  if a == '-hello' then
    print('hello from global configuration!')
    table.remove(arg, i)
  end
end
return {}

As used:

$ nelua -i ''
$ nelua -i '' -hello
hello from global configuration!
$ nelua -hello -i '' -hello
hello from global configuration!
hello from global configuration!
$ nelua -hello -i 'print "???"' -hello
hello from global configuration!
hello from global configuration!
???

project-local .neluacfg.lua

This file is exactly the same as the global configuration file, but is pulled from the current working directory when nelua's run for per-project settings. This makes it a more interesting place to put 'build system' type commands:

if #arg == 1 then
  if arg[1] == 'clean' then
    print 'removing: example'
    os.remove 'example'
    arg = {'-i', ''}
  elseif arg[1] == 'windows' then
    arg = {'--cc', 'zig cc --target=x86_64-windows', '-o', 'example.exe', 'example.nelua'}
  end
end
return {}

As used:

$ nelua -i 'print "no change to normal operation"'
no change to normal operation
$ nelua clean
removing: example
$ nelua windows
... compilation output ...

tooling .neluacfg.*.lua

In addition to .neluacfg.lua, these files are also read. This is apparently to distinguish the human-maintained Lua contents of .neluacfg.lua, from tooling-generated files. An example is .neluacfg.ppm.lua, generated by linkpy/pancake-pm to add package-managed dependencies to a project.

Configuration keys

likely options

• cache_dir - cache dir, by default $HOME/.cache/nelua
• cc - the C compiler to use
• cflags - C flags to use
• ldflags - linker flags
• runner - string of a command to use to run the compiled code, rather than trying to run the compilation result directly. e.g., wasmer, emrun -- but also: valgrind, perf
• add_path - array, additional paths to add
• pragma - array, additional pragmas to add

less likely options

• release - boolean, release build
• maximum_performance - boolean, benchmarking options
• debug - boolean, runs the program through gdb and gets a stack trace if it crashes
• verbose - boolean, verbose output
• generator - either 'c', or 'lua' for the unmaintained Lua code generation
• lib_path - the path of internal Nelua libs, by default the 'lib' directory of where Nelua was built/installed
• more_timing - boolean, show detailed timing information
• no_cache - boolean, disable cache
• no_color - boolean, disable color (.e.g, in error messages)
• no_warning - boolean, suppress warnings
• path - module search path (better to set add_path instead)
• quiet - (hidden) be quiet
• sanitize - boolean, use libsanitize
• strip_bin - boolean, strip resultin binary
• stripflags - additional flags to pass when stripping
• timing - show compile timing information

unlikely options

• analyze - boolean, if set the analyzed AST is printed (and nothing else is done)
• compile_assembly, assembly - boolean
• compile_binary, binary - boolean
• compile_code, code - boolean
• compile_object, object - boolean
• compile_shared_lib, shared_lib - boolean
• compile_static_lib, static_lib - boolean
• eval - code to use (instead of a file on the CLI)
• lint - check for syntax errors only
• lua - (hidden) Lua interpreter to use when running
• lua_options - (hidden) options for Lua interpreter
• lua_version - (hidden) string, sets the version of the target Lua for Lua codegen
• lualib_path - the path of the internal Lua libs, by default the 'lualib' directory of where Nelua was built/installed
• output - name of the output file
• script - boolean, run a Lua script instead of compiling Nelua code