How to build, use, and execute Lua code and files from LuaConsole
Tags: lua, repl, luaconsole
Published: 2021-02-28 04:54:43

LuaConsole is a powerful command line application (CLI) for Windows, Linux, and Mac which boasts various amounts of usability through switches and convention conformance over the default PUC-Lua and LuaJIT CLI. All the while it supports all major Lua versions (lua-5.1.x to lua-5.4.x) to be executed from a single binary file! It doesn't stop there, however, as it also supports the major package management repositories such as LuaDIST (deprecated) and LuaRocks! It supports MSVS(MSVC), GNU GCC/MingW64, and llvm (with a little set up).

# Download & Install/Build LuaConsole
## Downloading
LuaConsole can be found at the [Github Repository](https://github.com/tilkinsc/LuaConsole). If you are on windows, you can select 'Releases' from the side bar and download a pre-built copy.

## Installing
LuaConsole is a self-contained package for both Linux and Windows.

### Makefile
The makefile is in place to help developers familiar with the conventions use the scripts inside the repository. If you are unfamiliar with Makefile, follow along to the next `Windows` or `Linux` sections.

PLAT: Windows, MSVS, Unix, MacOS, or Linux
LUA_VER: luajit, lua-5.4.2, etc

Note: Windows uses MinGW64, MSVS uses cl.exe, Linux uses GCC
```bash
make PLAT=Linux LUA_VER=luajit driver
make PLAT=Linux LUA_VER=lua-5.4.2 package
make PLAT=Linux LUA_VER=lua-5.3.6 package
make PLAT=Linux LUA_VER=lua-5.2.4 package
make PLAT=Linux LUA_VER=lua-5.1.5 package
make PLAT=Linux "PREFIX=./install_dir/" install
```

### Windows
You will need to migrate the downloaded folder somewhere in your system and set up your environment variables. This is a simple task. LuaConsole is a 64bit application, so it belongs in `C:\Program Files`.

If you are building from source,
```batch
git clone https://www.github.com/tilkinsc/LuaConsole
pushd LuaConsole
prereqs.bat download
build.mingw.bat driver luajit
build.mingw.bat package lua-5.4.2
build.mingw.bat package lua-5.3.6
build.mingw.bat package lua-5.2.4
build.mingw.bat package lua-5.1.5
# lua-5.0.x is unsupported at this time
popd
# binaries are built to LuaConsole/bin/Release
```

![Program Files](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lvjvcbpmtoqq3e49qv3q.png)

I decided to create a folder called 'LuaConsole'. The full path would be, `C:\Program Files\LuaConsole`.

Next, you want to set up LuaConsole so that you can just execute the program without specifying the path each time. This is trivial - just edit your environment variables. You can do this through the UI or in a console with `setx "path=%path%;C:\Program Files\LuaConsole"`

 ![alt text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b4wfut5y5b3pcz06w2lg.png)
 
### Linux
Building in Linux is very straight forward. Simply download the prerequisites, followed by building the driver with a default lua version, and finally building all the lua versions you will use. Don't worry about it too much, as you can add more lua packages later. I prefer to use the bash scripts. To learn more about the scripts, they listen to `--help` or check out the [LuaConsole Wiki](https://github.com/tilkinsc/LuaConsole/wiki).
```bash
git clone https://www.github.com/tilkinsc/LuaConsole
pushd LuaConsole
./prereqs.sh download
./build.linux.sh driver luajit
./build.linux.sh package lua-5.4.2
./build.linux.sh package lua-5.3.6
./build.linux.sh package lua-5.2.4
./build.linux.sh package lua-5.1.5
# lua-5.0.x is unsupported at this time
popd
# binaries are build to ./LuaConsole/bin/Release
```
LuaConsole is a self-contained program unless you add the liblua*.so files into a library path or set up a library path for them. liblclua*.so must stay next to the executable, as they are dynamically loaded. You can configure `export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH` for now to test and use it.

# Executing Lua Files
Simply launch the program from terminal or console!

Here is a test script in case you came unprepared:

test_script.lua
```lua
print('hello world!')
```

There is also a test program in `LuaConsole/res/testing.lua`.

These are various ways to launch a .lua file:
```bash
luaw test_script.lua
luaw -ltest_script.lua
luaw -e "dofile('test_script.lua')"
type test_script.lua | luaw -
cat test_script.lua | luaw -
```

# Extra Features
LuaConsole has many more features than the default PUC-Lua CLI application. The possibilities are endless! Try `luaw --help` to learn more! Don't worry too much about how you send arguments in - LuaConsole will accept arguments with `/` and `-`.

*Start in REPL mode or analyze the environment after a script.* REPL stands for Read Execute Print Loop. Perhaps you want to test a single line of code. Perhaps you want to procedurally program something. For those familiar with GNU GDB, Lua doesn't really have something to debug an environment. LuaConsole introduced the ability to use REPL mode and for you to command how you use it! This is achieved with the -p switch. This means you can take a look at global variables, their values, and tons more - straight from a REPL!

```bash
luaw
luaw -p
luaw some_file.lua -p
luaw -lsome_file.lua -p
```

*Do not print any copyright information.* This is good if you want to use Lua to capture output of the scripts - doing math for example. Use the -c switch.

```bash
luaw -c -e "print(1 + 2)"
```

*Change Lua versions.* Sometimes scripts are only supported in 5.2.x or 5.3.x and above. This is likely due to the developer wanting to use the bits core library. Simply use the -w switch and specify the version you want to use. For luajit, specify `luajit`. For lua-5.3.5, supply `lua-5.3.5`. It's that easy!

```bash
luaw -w luajit -e "print(1 + 2)"
luaw -w lua-5.3.5 -e "print(1 + 2)"
```

*Create a global variable for your script to use.* Sometimes you just want a variable that you can change easily from the CLI. You may want to feed some data into Lua, or you just want a boolean. LuaConsole has your back with the -D switch. Simply use the format, `-Dvariable=value`. A bonus: it will correctly type your variable's value and it can even span tables!

```bash
luaw -Dexample=5 -e "print(1 + example)"
luaw -Dtab.var=5 -e "print(1 + tab.var)"
```

*Supply arguments through the `arg` variable or tuple `...` notation.* Perhaps you are making a script to be run like a command line application. You would find yourself using the -n switch in LuaConsole. Be aware that you need to use it at the end, or else you will translate switches as arguments!

```bash
luaw -e "for i, v in next, arg do print(i, v) end" -n a b c d
```

*Change directories.* You just cd'd or pushd'd into a subdirectory to run a script, but you have a lot of relative paths you don't want to change from the root. This is where the -s variable comes in to play. Simply use the format, `-s C:\start_dir` and you are on your way!

```bash
# ./
# some_dir/test.lua
# main.lua
pushd some_dir
luaw -e "dofile('main.lua')" -s ..
popd
```

Have fun playing around with LuaConsole! A final footnote, there is a difference between `-E and -e` and `-L and -l`. This is in place to determine which script or piece of code runs when. You can make an abomination like this:

```bash
luaw helloworld5.lua helloworld6.lua -E "print(1)" -e "print(2)" -lhelloworld3.lua -Lhelloworld4.lua -p -n 1 2 3
```
And it just works.