Module path conventions
This appendix describes the set of conventions and behavior that
luacheia uses for locating its modules.
cheia.module_paths
Under all OS's, the variable cheia.module_paths is a table with
numbered keys, giving an ordered list of directories in which to look
for luacheia modules. The first element in this table is a
platform-specific default. The environment variable LUACHEIA5_LIB
provides an optional list of directories to add to this table.
Under Unix-like OS's, the value of cheia.module_paths[1] is
typically predefined to something like "/usr/lib/luacheia5", although
this can be platform- and installation-specific. The environment
variable LUACHEIA5_LIB is a colon-separated list of additional
directories, which get added to cheia.module_paths.
Under Windows, the value of cheia.module_paths[1] is predefined to
be the directory of the program's executable file, with
"/luacheia5" appended. The environment variable LUACHEIA5_LIB
is a semicolon-separated list of additional directories, to be added
to cheia.module_paths.
For example, under Windows, if the user launches
"c:/some/path/luacheia/luacheia.exe", the first path element,
cheia.module_paths[1], will be "c:/some/path/luacheia/luacheia5".
Module names and module filenames
The function cheia.load takes a module name. For example,
cheia.load(“SDL”). The function cheia.load first converts the
dotted module name to a module filename, by appending the ".lua"
extension to the end. cheia.load then traverses the
cheia.module_paths table in numerical order, constructing a physical
pathname by combining the value of cheia.module_paths[i] and the
module filename. The function then tries to load and execute the Lua
script at that physical path. Once a file is successfully loaded this
way, the function returns.
The function cheia.loadmodule works in a similar way. Instead of
appending ".lua" to construct the relative module path,
cheia.loadmodule does a platform-specific transformation to the
filename, E.g. appending ".dll" under Windows, or ".so" under Linux.
cheia.loadmodule is intended for use only by the associated .lua
module stubs.
Examples:
-
Windows, program is "c:/program files/luacheia/luacheia.exe",
LUACHEIA5_LIB is set to "c:/luacheia_local". The directory
"c:/program files/luacheia/luacheia5" is empty. The directory
"c:/luacheia_local" happens to contain a file "SDL.lua". A LuaCheia
program executes cheia.load(“SDL”).
cheia.load first tries to load "c:/program
files/luacheia/luacheia5/SDL.lua". This fails, so the function next
tries to load "c:/luacheia_local/SDL.lua". This succeeds, so the
function returns.
-
Linux, program is "/usr/bin/luacheia", LUACHEIA5_LIB is set to
"~/luacheia". The directory "/usr/lib/luacheia5" is empty. The
directory "~/luacheia" has a file "SDL.lua". A LuaCheia program
executes cheia.load(“SDL”).
cheia.load first tries to load "/usr/lib/luacheia5/SDL.lua", which
fails. The function next tries to load "~/luacheia/SDL.lua", which
succeeds, so the function returns.
Module names and namespaces
Modules put their defined symbols in the table denoted by their name.
For example, cheia.load(“SDL”) puts its symbols in the Lua table
SDL.
(This policy is not (currently) enforced by the loader code.)
|
