====== Add support for Lua scripts to the Loader ======
  * Student: Pedro Souza  (pedrosouza@)
  * Mentor: Wojciech Koszek  (wkoszek@)

===== Project description =====

The project aims to design and implement a modular interface for the loader script \\ 
interpreter decoupling the interpreter from the loader.

Thus one can divide the project in two tasks:
  * Design a modular interface to interpreters and adapt the already existing\\ 
interpreters (**//Simple//** and **//Forth//**) to this interface.
  * Implement a Lua interpreter with all the functionalities present in the Forth\\ 
scripts.

With this approach one want to provide a easy way to choose (at compile time) which\\ 
interpreter the loader will use, and also provide a skeleton for adding others scripting\\ 
languages.

===== Approach to solving the problem =====

==== Interface design ====
//src/sys/boot/common/interp.h//

<code>
typedef void	interp_init_t(void *ctx);
typedef int	interp_run_t(void *ctx, const char *input);
typedef int	interp_incl_t(void *ctx, const char *filename);
typedef int	interp_load_def_t(void *ctx);

struct interp {
	interp_init_t	*init;
	interp_run_t	*run;
	interp_incl_t	*incl;
	interp_load_def_t *load_configs;
	void		*context;
};
</code>

The above C code shows the interpreter interface which contains:

  * **init** Initializes the interpreter. Should be called before using any other interpreter function.

  * **run** Interpretes and runs the passed string.

  * **incl** Reads the file contents to a string and run it.

  * **load_configs** Loads the default boot configuration file. (loader.rc for Forth, loader.lua for Lua).

  * **context** Pointer to interpreter/vm context data.

==== Lua interp implementation ====

The lua interpreter is written in C and it uses some standard C functions. To embedded\\ 
Lua into to loader the missing standard C functions (not present in libstand) where added\\ 
in //src/sys/lua/src/lstd.h// and //src/sys/lua/src/lstd.c//.

With the Lua embedded into the loader the **interp** interface was implemented in \\ 
//src/sys/boot/common/interp_lua.c//.

==== Lua scripts ====

The scripts where implemented to match all the features present in the Forth scripts\\ 
except for the PNP script (//src/sys/boot/forth/pnp.4th//) which I could not find any reference\\ 
to its functions and I treated it as deprecated.

The scripts are located at //src/sys/boot/lua// together with //lutils.h// and //lutils.c//\\ 
which implements the following builtin lua functions:

  * **loader.perform(string)** Perform a loader command.
  * **loader.delay(time)** Delay function, time is passed in microsencods (1/1000 miliseconds).
  * **loader.time()** Wrapper for C time function.
  * **loader.include(filename)** Includes a lua script. Notice that it does not prevent multiple inclusion of the same file.
  * **loader.getenv(name)** Returns the value of the given environment variable as string or nil if it does not exists.
  * **io.getchar()** Wrapper for C getchar function.
  * **io.ischar()** Wrapper for ischar C function.
  * **io.gets()** Wrapper for gets C function.
  * **io.open(filename)** Opens the given file. Returns a file (Lua user_data) variable or nil in case of failure.
  * **io.close(file)** Closes the given file.
  * **io.read(file, [size])** Returns S, R where S is a string containing the file data and R the number of bytes read.\\ 
If size parameter is nil the function reads the whole file.

Besides these builtin functions all functions from Lua baselib and stringlib are provided.

List of lua scripts:

  * **config.lua**: functions to load configuration files, parse and execute it.
  * **core.lua**: functions to set verbose, ACPI, single user mode, safe mode, autoboot.
  * **loader.lua**: script loaded in the boot startup.
  * **menu.lua**: boot menu related functions.
  * **password.lua**: boot password check functions.
  * **screen.lua**: screen utility functions.

===== Deliverables =====

  * Lua interpreter module
  * Lua scripts providing advanced boot options
  * Lua parser for .conf files

===== Milestones =====

| Interpreter interface definition | **//DONE//** ||
| Adapt existing interpretes to the interface | **//DONE//** ||
| Lua interpreter working with the loader | **//DONE//** ||
| Lua loader builtin functions ||
| loader.%%**%%%%**%% functions | **//DONE//** ||
| Lua file io functions | **//DONE//** ||
| Lua base library | **//DONE//** ||
| Lua string library | **//DONE//** ||
| Kernel loading functions | **//DONE//** ||
|  ||
| Config file parsing and module loading | **//DONE//** ||
| Boot menu | **//DONE//** ||
| <del>%%PnP%% config & setup</del> | **//DEPRECATED//** ||

==== New milestones ====

| Fix //drawer.isColorEnabled()// | **//DONE//** ||
| Fix //menu.run()// proper environment variable checks | **//DONE//** ||
| Merge //menu.options.alias// with //menu.options// | **//TODO//** ||
| Fix //kernels// menu option logic | **//DONE//** ||
| Add dynamic menu options ordering (boot simple/multi) | **//TODO//** ||
| Fix ANSI vs non-ANSI coloring | **//NEED TEST//** ||

===== Testing =====

Checkout the code:

<code>
$svn co https://socsvn.freebsd.org/socsvn/soc2014/pedrosouza/lua_loader/
</code>

By default the Lua interpreter is enabled, to revert to the Forth interpreter
edit ///etc/src.conf// and add the following lines:

<code>
WITH_FORTH="yes"
WITHOUT_LUA="yes"
</code>

or if you want to disable both Lua and Forth and use the simple interpreter:

<code>
WITHOUT_FORTH="yes"
WITHOUT_LUA="yes"
</code>

Then build and install the boot loader:

<code>
$cd head/sys/boot
$make
$su
$make install
</code>

===== The Code =====
[[https://socsvn.freebsd.org/socsvn/soc2014/pedrosouza/lua_loader/]]

===== Useful links =====
[[http://www.lua.org]]