Why you should care about your git repository structure and file names

Cody Tilkins — Sun, 28 Feb 2021 22:43:48 +0000

In modern day, a majority of programmers have adopted git, npm, apt, snap, and whatever have you. There are some of us who care about the structure of repositories, and some who just stick a few hundred files in a directory, slap on cmake/make/.package/etc and call it good.

This topic is fairly obvious. Have you ever entered a massive repository with the aspiration to contribute, but couldn't find a single thing? Have you ever had to rely on git frontends search engines? Have you ever had to delve into issues/PRs because you couldn't find where a certain file was located? Have you ever walked away from a project with an 'ummm' because you broke your scroll wheel? Have you ever not been able to implement cmake in a relatively easy way due the sheer amount of files spread everywhere?

When you have a public non-read-only repository, it is guaranteed to grow. That is the beauty of open source and you should embrace free software. What can organization bring to you?

Subdirectories

If you use cmake or make, you are probably familiar with the appeal of having one subdirectory per target in a solution and shared in a separate subdirectory, built as a separate target.

Programs like cmake or make don't offer much support in the way of build trees and working directory support. This is a pity really, but as a developer I guarantee you've been to hell and back implementing cmake and make build files on top of your build tree. A developer's pipe dream is just to shove *.source into a single binary and it just pops out something usable. CMake is the worst of the two due to having next to zero implementation documentation - something you have to pick up from studying actual scripts.

Shortly said, you will likely want to eventually implement make or cmake so you should keep each target separate in a solution so that you can accurately reference shared reliably while having zero possibility to link or use files from other targets. Imagine the upkeep the Lua team has to go through. If you check out their makefile, you will note they have about 5 solutions [lua.exe, luac.exe, auxlib, lualib, lua.dll] built out of the root of the project. They use gcc -MM... to generate their tree and manually amend it to the makefile. Wouldn't it be nice to... you know... gcc -o lua.exe *.c -l...?

Entry Points

Clicking through a new repository, your first instinct probably is 'where is the main'. This goes hand and hand with two different, but similar points. File and Folder naming.

I'm sure you all want to stick your files in a folder called foo and call all your files bar-n.source, but did you know this is malpractice and a sin? Commit (get it) blasphemy no more!

You should conform with your language's file naming conventions when it comes to entry points. If you don't, users may end up including the wrong file, assuming your project is broken, and at worst npm uninstall your_repo. This is most notable in c, c++, javascript and python. It could be extended to many other languages. Please don't hide your entry point.

Leave a comment below with which folder you think holds the entry point to this program.

How to build, use, and execute Lua code and files from LuaConsole

Cody Tilkins — Sun, 28 Feb 2021 04:54:43 +0000

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. 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

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,

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

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"

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.

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

print('hello world!')

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

These are various ways to launch a .lua file:

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!

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.

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!

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!

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!

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!

# ./
# 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:

luaw helloworld5.lua helloworld6.lua -E "print(1)" -e "print(2)" -lhelloworld3.lua -Lhelloworld4.lua -p -n 1 2 3

And it just works.

DEV Community: Cody Tilkins