Module lakelibs

Global functions available with Lake.

Functions

warning (reason, ...) write out a warning message, where reason is a string.format string.
quit (reason, ...) put out a warning and quit the script immediately, after finalization.
choose (cond, v1, v2) return either v1 or v2 depending on cond.
pick (a, b) return a if it isn’t nil, otherwise b
L (t) expands sublists and removes holes.
dump (t, msg) for debug purposes: dump out a table with optional message
target (name, deps, cmd, upfront) create a target with dependencies and a command or action.
action (name, f, ...) a target with no dependencies and a function action.
default (targets) defines the default target for this lakefile.
rule (out_ext, in_ext, cmd, label) create a rule object for generating targets.

Tables

ENV Pseudo-table for getting and setting environment variables.

Functions operating on files

file.time (fname) get the modification time of a file fname.
file.copy (src, dest) copy src to dest, creating destination path if needed.
file.write (name, text) write text to a file name
file.read (name) read contents of name
file.touch (name) update the timestamp of name – create if necessary.
file.temp () create a new temporary file
file.temp_copy (s, ext) write s to a temporary file, returning the filename.

Path manipulation functions

path.isdir (P) is P a directory?
path.isfile (P) is P a file?
path.isabs (P) is P an absolute path?
path.abs (...) make an absolute path
path.get_files (files, dir, pat, recurse) update an input table files with all files from dir that match pat.
path.is_mask (pat) is pat a file mask?
path.files_from_mask (mask, recurse) given a file mask, grab all the matching files.
path.get_directories (dir) get all the directories in dir
path.mask (mask) iterator over path.files_from_mask
path.dirs (dir) iterator over path.get_directories
path.splitpath (path) given path, return the directory part and a file part.
path.splitext (path) given path, return the root part and the extension part if there’s no extension part, the second value will be empty
path.dirname (P, strict) return the directory part of P.
path.basename (path) return the file part of path
path.extension_of (path) return the extension of path
path.expanduser (path) expand initial ‘~’ to user’s home path
path.replace_extension (path, ext) given a file, replace its extension with ext
path.mkdir (p) make a directory, making any subdirs as necessary.

General Utilities

utils.clock () wall clock time since start of session.
utils.sleep (msec) pause the process for a given number of millisecs.
utils.split (s, re) split a string using a delimiter (default spaces).
utils.split2 (s, delim) split a string into two parts with a delimiter.
utils.split_list (s) split a string with items separated by commas or spaces.
utils.copy_table (t) make a shallow copy of a table.
utils.append_table (t1, t2) update first table using key/val pairs from second table.
utils.execute (cmd, quiet) compatible wrapper over os.execute .
utils.subst (str, exclude, T) this expands any $(VAR) occurances in s (where VAR is a global varialable).
utils.substitute (str, T) like utils.subst , but no exclude list.
utils.shell_nl (cmd, ...) this executes a shell command cmd, which may contain % string.format specifiers, in which case any extra arguments are used.
utils.shell (cmd, ...) a convenient function which gets rid of the trailing line-feed from utils.shell_nl .
utils.forall (ls, action) calls action on all elements of ls.
utils.remove (items) delete a list of files.
utils.remove_files (mask) uses system file remove command on a file mask.
utils.make_callable (obj, fun) make a table callable with a supplied function.
utils.which (prog) return full path of program on path if it exists.

List manipulation functions

list.extend (l1, l2) append elements of l2 to ‘l1.
list.extend_unique (l1, l2) append elements of l2 to ‘l1uniquely.
list.append_unique (l, v) only append if v is not already in l
list.copy (l1) shallow copy.
list.erase (l1, l2) erase elements of l1 equal to any of l2
list.index (ls, val) return the index of val in the list.
list.find (ls, field, value) find an element where the field is value.
list (ls) used to iterate over a list, which may be given as a string.
list.column (ls, f) extract a column from a list of tables using an index f.
list.parm_concat (ls, istart) build a quoted string suitable for a shell command.

Access to internal Lake functionality

lake.set_log (f) redirect logging.
lake.register (lang, extra) register a new language.
lake.deps_arg (deps, base, returns_strings) any string separated with ‘ ’ or ‘,’ will be converted into an appropriate list.
lake.expand_args (src, ext, recurse, base) like deps_arg but will expand a wildcard expression into a list of files.
lake.phony (deps, cmd) a phony target with dependecies deps and command cmd.
lake.all_targets () a copy of all the targets.
lake.is_remote (file) is a file remote?
lake.download (url, pathname) download url into an optional local pathname.
lake.install_plugin (parm) Install a need, language or general plugin.
lake.chdir (path) change Lake directory to path.
lake.concurrent_jobs (nj) set the number of threads to use when building.
lake.on_exit (hook) hook will be called when Lake finalizes.
lake.go () start evaluating dependencies.
lake.run (prog, args, istart) run a program or a target, given some arguments.
lake.set_flags (parms) set global flags properly.
lake.output_filter (lang, filter) set a compiler output filter.
lake.define_need (name, callback) provide a definition for a need.
lake.define_pkg_need (name, package) specify a need to be satisfied with pkg-config.
lake.append_to_field (t, name, value) append the list value to t[name].
lake.add_program_option (options) add new program options.
lake.add_prog (lang) create lang.program
lake.add_shared (lang) create lang.shared
lake.add_library (lang) create lang.lib
lake.add_group (lang) create lang.group
lake.compiler_version (cc) version of current compiler.


Functions

warning (reason, ...)
write out a warning message, where reason is a string.format string.
quit (reason, ...)
put out a warning and quit the script immediately, after finalization.
choose (cond, v1, v2)
return either v1 or v2 depending on cond. alias IF
pick (a, b)
return a if it isn’t nil, otherwise b
L (t)
expands sublists and removes holes. Any strings delimited with spaces or commas are also split into lists using lake.deps_arg .

Usage:

  • L'one two' == {'one','two'}
  • L{IF(X,'a'),IF(Y,{'one','two'}} == {'one','two'} if X is false, Y is true
dump (t, msg)
for debug purposes: dump out a table with optional message
target (name, deps, cmd, upfront)
create a target with dependencies and a command or action. deps is a list as defined by lake.deps_args, and cmd may be a string (a command to be executed) or a Lua function. target.boo(deps,cmd) is another way of writing target('boo',deps,cmd)
action (name, f, ...)
a target with no dependencies and a function action. name may be omitted, for a target with autogenerated name. Extra arguments will be passed to the function.
default (targets)
defines the default target for this lakefile. It is passed a list of targets as dependencies.
rule (out_ext, in_ext, cmd, label)
create a rule object for generating targets. This maps input files with extension in_ext to output files with extension out_ext, using an action cmd Most of the customization of rules comes from setting a lang field.

Tables

ENV
Pseudo-table for getting and setting environment variables. Note that setting environment variables requires either winapi or luaposix.

Functions operating on files

Functions operating on files.
file.time (fname)
get the modification time of a file fname.
file.copy (src, dest)
copy src to dest, creating destination path if needed.
file.write (name, text)
write text to a file name
file.read (name)
read contents of name
file.touch (name)
update the timestamp of name – create if necessary.
file.temp ()
create a new temporary file
file.temp_copy (s, ext)
write s to a temporary file, returning the filename. Will apply the extension ext to the file if supplied.

Path manipulation functions

Path manipulation functions
path.isdir (P)
is P a directory?
path.isfile (P)
is P a file?
path.isabs (P)
is P an absolute path?
path.abs (...)
make an absolute path
path.get_files (files, dir, pat, recurse)
update an input table files with all files from dir that match pat. Here pat is a Lua string pattern, and recurse means follow directories.
path.is_mask (pat)
is pat a file mask? Note: only ‘*’ is understood!
path.files_from_mask (mask, recurse)
given a file mask, grab all the matching files. mask may contain a directory part, and recurse means follow directories.
path.get_directories (dir)
get all the directories in dir
path.mask (mask)
iterator over path.files_from_mask
path.dirs (dir)
iterator over path.get_directories
path.splitpath (path)
given path, return the directory part and a file part. if there’s no directory part, the first value will be empty
path.splitext (path)
given path, return the root part and the extension part if there’s no extension part, the second value will be empty
path.dirname (P, strict)
return the directory part of P. If strict and the path is already a directory, return that
path.basename (path)
return the file part of path
path.extension_of (path)
return the extension of path
path.expanduser (path)
expand initial ‘~’ to user’s home path
path.replace_extension (path, ext)
given a file, replace its extension with ext
path.mkdir (p)
make a directory, making any subdirs as necessary.

General Utilities

General Utilities.
utils.clock ()
wall clock time since start of session. (This requires posix on Unix systems)
utils.sleep (msec)
pause the process for a given number of millisecs. (Requires posix' orwinapi)
utils.split (s, re)
split a string using a delimiter (default spaces).
utils.split2 (s, delim)
split a string into two parts with a delimiter.
utils.split_list (s)
split a string with items separated by commas or spaces. This honours \ escapes on Unix and double-quotes on Windows.
utils.copy_table (t)
make a shallow copy of a table.
utils.append_table (t1, t2)
update first table using key/val pairs from second table.
utils.execute (cmd, quiet)
compatible wrapper over os.execute . quiet prevents any console output.
utils.subst (str, exclude, T)
this expands any $(VAR) occurances in s (where VAR is a global varialable). If VAR is not present, then the expansion is just the empty string, unless it is on the exclude list, where it remains unchanged, ready for further expansion at a later stage.
utils.substitute (str, T)
like utils.subst , but no exclude list.
utils.shell_nl (cmd, ...)
this executes a shell command cmd, which may contain % string.format specifiers, in which case any extra arguments are used. It may contain ${VAR} which will be substituted
utils.shell (cmd, ...)
a convenient function which gets rid of the trailing line-feed from utils.shell_nl .
utils.forall (ls, action)
calls action on all elements of ls. ls is expanded using lake.expand_args
utils.remove (items)
delete a list of files.
utils.remove_files (mask)
uses system file remove command on a file mask.
utils.make_callable (obj, fun)
make a table callable with a supplied function.
utils.which (prog)
return full path of program on path if it exists.

List manipulation functions

List manipulation functions
list.extend (l1, l2)
append elements of l2 to ‘l1.
list.extend_unique (l1, l2)
append elements of l2 to ‘l1uniquely.
list.append_unique (l, v)
only append if v is not already in l
list.copy (l1)
shallow copy.
list.erase (l1, l2)
erase elements of l1 equal to any of l2
list.index (ls, val)
return the index of val in the list.
list.find (ls, field, value)
find an element where the field is value.
list (ls)

used to iterate over a list, which may be given as a string. 

for val in list(ls) do ... end
for val in list 'one two three' do .. end
list.column (ls, f)
extract a column from a list of tables using an index f.
list.parm_concat (ls, istart)
build a quoted string suitable for a shell command. Can start at the indicated index istart.

Access to internal Lake functionality

Access to internal Lake functionality.
lake.set_log (f)
redirect logging. f is a function that writes to log with a newline assumed.
lake.register (lang, extra)
register a new language. extra may be a list of extra extensions.
lake.deps_arg (deps, base, returns_strings)
any string separated with ‘ ’ or ‘,’ will be converted into an appropriate list. This function is guaranteed to return a plain list, and will wrap other objects like targets and rules appropriately. Strings, targets, rules and target lists are allowed. returns_strings determines whether the result must be reduced to strings.
lake.expand_args (src, ext, recurse, base)
like deps_arg but will expand a wildcard expression into a list of files. Also expands lists as strings. If the argument is a table, it will attempt to expand each string – e.g. {'a','b c'} => {'a','b','c'}
lake.phony (deps, cmd)
a phony target with dependecies deps and command cmd.
lake.all_targets ()
a copy of all the targets. The variable ALL_TARGETS is predefined with a copy
lake.is_remote (file)
is a file remote? Currently, only if it starts with ‘get:’ or ‘http:’
lake.download (url, pathname)
download url into an optional local pathname. If pathname isn’t present, use the basename of url. Currrently only understands get: or http: and requires either wget or curl to be installed.
lake.install_plugin (parm)
Install a need, language or general plugin. A file defining a need, like ‘foo.need.lua’ or one defining a language like ‘boo.lang.lua’; general packages are ‘foo.lake.lua’ Language plugins are thereafter automatically required in config.lua. The ‘.lua’ extension is not necessary and the file may be remote (lake.is_remote )
lake.chdir (path)
change Lake directory to path. path may be ‘!’ or ‘<’ to pop the directory stack like ‘popd’ Outputs to log.
lake.concurrent_jobs (nj)
set the number of threads to use when building. Equivalent to ‘-j’ command-line flag – note the flag overrides this function. You will need either winapi or luaposix for this functionality.
lake.on_exit (hook)
hook will be called when Lake finalizes. This will happen if you call quit as well.
lake.go ()
start evaluating dependencies. This is implicitly called after loading a lakefile.
lake.run (prog, args, istart)
run a program or a target, given some arguments. It will only include arguments starting at istart, if defined. If it is a target, the target’s language may define a runner; otherwise we look for an interpreter or default to local execution of the program.
lake.set_flags (parms)
set global flags properly. parms is a table of key-value pairs which will be put into _G, and then any depenedent flags will be generated. For instance, setting PREFIX will cause the C compiler to become PREFIX..'gcc'.
lake.output_filter (lang, filter)
set a compiler output filter. Here lang is either a language and applies to all such targets, or just a target. The filter is initially called with args ({target,input,rule},'start') and thereafter is passed each line of output; if it returns a line, output that. Finally it is called with args (base,'end').
lake.define_need (name, callback)
provide a definition for a need. This is a callback which must return a table containing any or all of:

  • ‘libs’
  • ‘incdir
  • defines
  • libdir

it will be passed the name of the need, the arguments to program, and whether we want to link against the need statically

lake.define_pkg_need (name, package)
specify a need to be satisfied with pkg-config. if an alias name for package is provided, then this package is available using the alias (e.g. ‘gtk’) and must be handled by pkg-config.
lake.append_to_field (t, name, value)
append the list value to t[name]. If t[name] does not exist, make it a table first; if value is a string, then make it into a list.
lake.add_program_option (options)
add new program options. (program always checks its arguments, so this is needed to keep the check happy.)
lake.add_prog (lang)
create lang.program
lake.add_shared (lang)
create lang.shared
lake.add_library (lang)
create lang.lib
lake.add_group (lang)
create lang.group
lake.compiler_version (cc)
version of current compiler. returns a table with fields MAJOR, MINOR and REV. If cc is not specified, use the global CC.
generated by LDoc 1.3.12