Phobos is planned to be an optimizing bytecode compiler for Lua with some language extensions and a type system.
See below for which features are implemented and which are planned.
Phobos currently only supports bytecode for Lua 5.2 with this header.
Download the zip for your platform from the GitHub Releases, extract all files and run it using this command in your command line or terminal:
(If your OS blocks the executable for security reasons either allow them to run in properties (on windows) or preferences (on osx/macOS), or use your own Lua and LuaFileSystem binaries with the raw Phobos package)
./lua -- main.lua -h
The working directory has to be the directory containing the main.lua file. Use the --working-dir
argument if you wish to use relative paths to said directory. Otherwise they are relative to the main.lua
file, as that is the working directory.
You could also change the LUA_PATH
and LUA_CPATH
environment variables to include the Phobos directory but beware of name collisions. (See package.path and package.cpath and maybe here)
You can use Phobos as a library. The raw package from the github releases is meant for this, though it will most likely change in the future because actually using .pho
source files from the library would be beneficial both to the programmer and the compiler.
There is also a Factorio mod on the Factorio Mod Portal and in the GitHub Releases.
It contains all files required to use Phobos at runtime (like a library), no command line tools.
(Though as mentioned in the Library section, this is most likely going to undergo changes in the future)
Additionally the mod, and only the mod, contains a control.lua
file to register commands to run Phobos in the in-game console similar to regular Lua commands. Use /help
in-game.
When compiling (see next section) for a Factorio mod you currently must use --use-load
because Factorio does not load bytecode Lua files.
Additionally it is recommended to use --source-name @__mod-name__/?
to match Factorio's source name pattern (mod-name
being your internal mod name).
If the your dev environment is setup such that the root of the .pho
source files is the same as the info.json
file then you most likely want to omit --output
to generate compiled .lua
files directly next to the source files.
An example:
MyMod
|- control.pho
|- info.json
Would look like this after compilation:
MyMod
|- control.lua
|- control.pho
|- info.json
main.lua
is the entry point for compiling. Use --help
for information on it's arguments.
There is no command line entry point for disassembling, but you can require the disassembler
file to disassemble bytecode and print out disassembly wherever you want. It automatically extracts and uses Phobos debug symbols properly.
Phobos is planned to be able to parse some form of disassembly language to then generate bytecode basically one to one.
Phobos is planned to be able to format your code.
Phobos is planned to be able to run refactoring scripts based on AST to, well, refactor code.
Phobos generated bytecode has better debug symbols. Phobos also provides extra debug information beyond what regular Lua bytecode supports (like instruction column positions). The Lua VM won't do anything with this, but other tools may read this information, such as debuggers. See phobos_debug_symbols.md for how Phobos provides this information.
Phobos syntax is based on Lua 5.2. By default Phobos will always be able to compile raw Lua, but some opt-in syntax may inevitably break compatibility with regular Lua syntax.
Phobos is planned to be type aware. The idea is that it can figure out the majority of types on it's own, but there will most likely be ways for you to explicitly tell Phobos what type something should have.
The operators ?.
, ?:
, ?[]
and ?()
to replace the common Lua idiom foo and foo.bar
. These allow more efficient re-use of intermediate results in deeply nested optional objects. ?.
, ?:
and ?[]
protect an indexing operation, while ?()
protects a function call, calling the function only if it exists (is not nil
or false
).
Modified versions of several block constructs are planned to allow defining block locals in the opening condition of the block.
if name_list = exp_list then ... end
do
local name_list = exp_list
if select(1,name_list) then ... end
end
while name_list = exp_list do ... end
do
local name_list = exp_list
while select(1,name_list) do
...
name_list = exp_list
end
end
Lua's existing function syntax is already fairly compact, but for the specific case of a function which simply returns an exp_list it can be reduced further:
(foo,bar) => foo?[bar]
There are lots of ideas for language extensions which are not listed here in the readme yet.
Phobos itself is licensed under the MIT License, see LICENSE.txt.
- Lua MIT License, Copyright (c) 1994–2021 Lua.org, PUC-Rio.
- LuaFileSystem MIT License, Copyright (c) 2003 - 2020 Kepler Project.
- Serpent MIT License, Copyright (c) 2012-2018 Paul Kulchenko (paul AT kulchenko DOT com) (email "encrypted" for scraping reasons)
- LFSClasses The Unlicense
- LuaArgParser MIT License, Copyright (c) 2021 Jan Mischak
- LuaPath The Unlicense
- FactorioSumnekoLuaPlugin MIT License, Copyright (c) 2021-2022 Jan Mischak, justarandomgeek
- minimal-no-base-mod, Copyright (c) 2020 Erik Wellmann
- JanSharpDevEnv, Copyright (c) 2020 Jan Mischak
For license details see the LICENSE_THIRD_PARTY.txt file and or the linked repositories above.
Huge thanks to justarandomgeek for starting the project in the first place (writing the majority of the first iteration of the parser and starting on the actual compiler) and then helping me understand several parts of compilers in general, the Lua VM, Lua bytecode and Lua internals.
Thanks to Therenas for providing built Lua and LuaFileSystem binaries for macOS and ensuring Phobos runs properly on macOS.
Thanks to the factorio modding community for providing input, ideas and discussion about Phobos as a whole. Without several people wanting types and no longer wanting to micro optimize their code Phobos would never have happened.
Phobos is still in it's early stages (i would say anyway) and i plan on refactoring several things multiple times over before i'd really suggest anyone to contribute to the project through PRs (pull requests). I have not written down the ideals and goals behind Phobos yet either, but one of the big points is to not feature creep. It's already a giant project in terms of ideas and plans.
Clone the repo and init and or update all submodules. something like this should work:
git submodule init
git submodule update
If you're using vscode just run the build tasks from the command pallet.
There are scripts/build_src.lua
and scripts/build_factorio_mod.lua
which have to be run through launch-scripts/phobos_dev
. The phobos_dev
script expects the current working directory to be the root of the phobos project and 3 additional positional arguments before the actual arguments that will be passed to the lua script. Those 3 args are:
- your platform, so
linux
,osx
orwindows
- the relative path to the phobos files to be run. So
out/src/debug
,out/src/release
orsrc
(as long assrc
is still using.lua
files) - the relative path to the lua file to run. So in this case
scripts/build_src.lua
orscripts/build_factorio_mod.lua
The launch scripts have a good amount of comments to assist in understanding and troubleshooting.
First build from source, see above.
Again, if you're using vscode just press F5. To select the right launch profile either use the side panel or press CTRL + P
, type debug
, then a space, and select the launch profile from there.
The Phobos
and Lua
prefixes are currently relevant since phobos itself is still written in .lua
files. That means the Lua
prefixed launch profiles will run directly from source while Pho
will use phobos itself to compile src
and then run and debug out/src/debug
. This, however, uses the Build Debug
task, which uses src
to compile itself, which means if there is a bug then you can't use that to actually debug it. This will change once I require you to have a previous version of Phobos installed to compile Phobos.
-- TODO: Running outside of vscode. Write this once the phobos
scripts get copied into the output.