Phobos

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.

Lua Bytecode

Phobos currently only supports bytecode for Lua 5.2 with this header.

Running Phobos

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)

Library (not really supported)

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.

Factorio

Factorio Mod

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.

Compiling for Factorio

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

Compiling

main.lua is the entry point for compiling. Use --help for information on it's arguments.

Disassembling (partially implemented)

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.

Disassembly Language (not implemented)

Phobos is planned to be able to parse some form of disassembly language to then generate bytecode basically one to one.

Formatting (not implemented)

Phobos is planned to be able to format your code.

Refactoring (not implemented)

Phobos is planned to be able to run refactoring scripts based on AST to, well, refactor code.

Phobos Debug Symbols

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.

Language Extensions (not implemented)

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.

Type System (not implemented)

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.

Safe Chaining Operators (not implemented)

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

Block Initializer Clauses (not implemented)

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

Compact Expression-body Lambda (not implemented)

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]

And More (not implemented)

There are lots of ideas for language extensions which are not listed here in the readme yet.

Libraries, Dependencies and Licenses

Phobos itself is licensed under the MIT License, see LICENSE.txt.

Serpent MIT License, Copyright (c) 2012-2018 Paul Kulchenko (paul AT kulchenko DOT com) (email "encrypted" for scraping reasons)
LFSClasses The Unlicense
LuaPath The Unlicense
FactorioSumnekoLuaPlugin MIT License, Copyright (c) 2021-2022 Jan Mischak, justarandomgeek

For license details see the LICENSE_THIRD_PARTY.txt file and or the linked repositories above.

Contributors

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.

Contributing

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.

Building from Source

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 or windows
the relative path to the phobos files to be run. So out/src/debug, out/src/release or src (as long as src is still using .lua files)
the relative path to the lua file to run. So in this case scripts/build_src.lua or scripts/build_factorio_mod.lua

The launch scripts have a good amount of comments to assist in understanding and troubleshooting.

Running from Source

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.

justchen1369 / phobos