Skip to content

Commit 95b9246

Browse files
committed
Add some more docs: simplegraphic api, native busted
1 parent b51012e commit 95b9246

1 file changed

Lines changed: 16 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,12 @@ such as [VSCodium](https://vscodium.com) or [Eclipse Theia](https://theia-ide.or
138138

139139
Another alternative on VSCode is to use [sumneko's Lua language server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) along with [actboy168's debugger](https://marketplace.visualstudio.com/items?itemName=actboy168.lua-debug). These can potentially offer more features than EmmyLua, such as conditional breakpoints.
140140

141+
## Runtime environment
142+
143+
It is recommended that you configure your IDE to include `src/_SimpleGraphic.def.lua` somehow. Path of Building runs inside a special Lua environment via SimpleGraphic which implements a small API. These are not defined inside the project, which means that the aforementioned meta/hint file is required for the IDE to know which functions exist. As the file is not included in code, it must be explicitly mentioned as a library in whichever language server you are using, or otherwise it will not be read.
144+
145+
This file is normally not executed, but does contain basic implementations for parts of the API, which allows many parts of PoB to work without running inside SimpleGraphic. If you wish to test individual changes, it might be possible to do so through a script using Luajit directly. To do so, see HeadlessWrapper.lua for an example. It should be noted that some parts of the API (such as subscripts) are not implemented, which means some parts of PoB are unusable.
146+
141147
### Visual Studio Code
142148

143149
1. Create a new <kbd>Debug Configuration</kbd> of type <kbd>EmmyLua New Debug</kbd>
@@ -244,6 +250,9 @@ If you prefer to not use EmmyLua, the following configuration works well for Sum
244250

245251
// this has lua 5.3 code which produces errors, but doesn't actually run
246252
"src/runtime/lua/sha1/*",
253+
254+
// avoid overriding the below library setting
255+
"src/_SimpleGraphic.def.lua",
247256
],
248257
"Lua.diagnostics.disable": ["inject-field"],
249258
// disables diagnostics even when you open one of the above
@@ -296,6 +305,13 @@ More tests can be added to this folder to test specific functionality, or new te
296305

297306
Please try to include tests for your new features in your pull request. Additionally, if your pr breaks a test that should be passing please update it accordingly.
298307

308+
It can also be a good idea to install `busted` locally as it tends to be faster to execute:
309+
310+
1. Install Luajit (due to PoB accessing the jit library, it non-Luajit versions might not work)
311+
2. Install [Luarocks](https://luarocks.org/) (for example, through Scoop or your Linux package manager)
312+
3. Run `luarocks install busted`
313+
4. Run `busted --lua=luajit` to run the tests. You can also use e.g. `-p TestUtils_spec.lua` to run a specific file.
314+
299315
### Debugging tests
300316
When running tests with a docker container it is possible to use EmmyLua for debugging. Paste in the following right under `function launch:OnInit()` in `./src/Launch.lua`:
301317
```lua

0 commit comments

Comments
 (0)