Skip to content

Latest commit

 

History

History
42 lines (26 loc) · 2.19 KB

CONTRIBUTING.md

File metadata and controls

42 lines (26 loc) · 2.19 KB
Raw

Contributing

To get up and running you'll need Ruby installed on your system. Once you do, run the following commands after cloning the repository:

bundle install
git submodule init
git submodule update --remote
cd dfhack
git submodule init library/xml
git submodule update library/xml
cd ..
ruby lib/generate.rb

If everything went well there should be no errors. When developing you'll need to re-run the last command to see changes.

From here on you can either open a new test lua file or point your dfhack-scripts environment at your local copy of the repository.

The aim of this project is to fully automatically generate LuaLS definition files for the entirety of the DFHack Lua environment. This means parsing XML files in df-structures, Lua files present in the DFHack library, and C++ files defining metatables for use in Lua.

Currently files located in the base library directory are not automatically generated and must be edited manually.

Files generated by the script (generate.rb) are marked as such on their first line. Those files should never be edited by hand as any changes will be lost when the script is next ran.

Once set up, you can follow the normal "installation" instructions, but simply point the language server at the dist folder.

Structure files are output to the base dist directory, only the base.lua file is meant to be manually edited.

VSCode

Using the Build Task shortcut Ctrl+Shift+B you can automatically run generate.rb.

LuaLS

The Lua language server provides extra functionality for code editors to make editing Lua easier. Part of this is dynamic type hinting, which can be helpful in the discovery and documentation of code. It can also provide diagnostic errors and warnings when types are misused.

Loosely structure guidelines for creating types that I follow:

  • Generics are commonly mis-interpreted by the language server, use explitic classes where possible i.e ---@class MyFooTable vs. ---@class MyTable<Foo>: { [ integer ]: Foo }
  • Use ---@nodiscard liberally for functions with no side-effects