Merge pull request #626 from pallene-lang/traceback-doc

Notes on using Tracebacks and Pallene Tracer adoption

doc/traceback.md

@@ -0,0 +1,39 @@
+<h1 align="center">Tracebacks in Pallene</h1>
+
+For debugging purposes, function call tracing can be enabled. Pallene uses [Pallene Tracer](https://github.com/pallene-lang/pallene-tracer) to enable function stack-trace which can be generated in case of runtime errors.
+
+## How to Enable Function Call Tracing
+
+To enable function call tracing, simply pass the `--use-traceback` flag while compiling a Pallene translation.
+
+```
+pallenec foo.pln --use-traceback
+```
+
+## Generate Stack-trace
+
+Enabling function tracing in Pallene will only accumulate call-frames in Pallene Tracer call-stack, a separate self-maintained call-stack synchronous with Lua call-stack. To take advantage of the generated tracebacks, the Lua script has to be ran using Pallene Tracer Lua frontend, `pt-lua`.
+
+```
+pt-lua main.lua args ...
+```
+
+## Adoption of Pallene Tracer in Pallene
+
+To know about how Pallene Tracer works, refer to the [documentation](https://github.com/pallene-lang/pallene-tracer/tree/main/docs/MANUAL.md).
+
+Pallene uses custom set of macros as Pallene is AOT compiled to C from a different source. These macros are defined in at the very beginning of `pallenelib.lua` under Pallene source tree.
+
+Pallene uses the Dispatch mechanism mentioned in the Pallene Tracer docs. Therefore, all Lua entry point function dispatches to respective Pallene entry point function (C interface function).
+
+These macros are adopted to each and every compiled \[to C\] function depending on the entry point type. The `PALLENE_LUA_FRAMEENTER` is used at the beginning of the each Lua entry point function, pushing a Lua entry point call-frame. Lua entry point functions do not require FRAMEEXIT.
+
+The Pallene/C entry point function on the other hand, has to maintain proper FRAMEENTER and FRAMEEXIT, at the beginning of the function and prior to return statement respectively by calling `PALLENE_C_FRAMEENTER` and `PALLENE_FRAMEEXIT` respectively. The Pallene entry point functions has to utilize the `PALLENE_SETLINE` macro to properly set line numbers prior calling a new function or invoking Lua runtime error.
+
+The macros were properly generated by making changes to `lua_entry_point_definition` and `pallene_entry_point_definition` functions respectively in `coder.lua`, also ensuring proper FRAMEEXIT at the end in case of void Pallene entry points.
+
+The `PALLENE_SETLINE` macro was adopted by changing the code generator of `CallStatic` and `CallDyn` IR case, which should allow proper call of `PALLENE_SETLINE` prior Pallene -> Pallene or Pallene -> Lua function calls. The macro is also used accordingly in case of invoking runtime errors.
+
+The Pallene Tracer call-stack and to-be-closed finalizer object is passed through the Pallene Full-userdata global, which is then enclosed to Lua entry point functions as Upvalues. The call-stack passed to Pallene entry points upon dispatch. Pallene entry points do not need to utilize the finalizer object.
+
+The `--use-traceback` flag is parsed in `pallenec.lua` and passed to the Code Generation compiler pass via `flags` table. The flags table then stored as a property in Coder class. When function traceback is enabled through `--use-traceback` flag, the `use_traceback` field is set to `true` in flags table, which is then used to increase the argument numbers in arity check (because of to-be-closed finalizer object is pushed onto the value-stack upon FRAMEENTER) and to define `PT_DEBUG` macro to enable debug mode in Pallene Tracer.