Merge pull request #1 from pallene-lang/dev

Initial merge

.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+# This is the configuration file for our CI via Github Actions.
+#
+# The result of all executions of the github actions is logged in the "Actions" tab at the top of
+# the repository. If the jobs aren't running as they should, check there to see if you didn't
+# introduce a syntax error in the YAML file or something like that.
+#
+# Useful reference:
+#   - https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions
+#   - https://github.com/actions/checkout
+
+name: Github Actions CI
+
+# Github Actions can be infuriatingly obtuse at times. I don't know exactly why we need both the
+# push and the pull_request events. It's wasteful, but at least does what we want.
+#
+# - only push:         doesn't run checks if an external fork opens a pull request
+# - only pull_request: doesn't work with caching
+# - both events:       runs the same checks twice, wasting compute time
+on:
+    push:
+        branches: [ master ]
+    pull_request:
+        branches: [ master ]
+
+env:
+    LUA_VERSION: 5.4.6-2
+    LUAROCKS_VERSION: 3.9.0
+
+jobs:
+    lint:
+        name: Lint
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v2
+
+            - name: Install Lua
+              run: |
+                  wget -O - https://github.com/pallene-lang/lua-internals/archive/refs/tags/${{env.LUA_VERSION}}.tar.gz | tar xzf -
+                  cd lua-internals-${{env.LUA_VERSION}}
+                  make linux
+                  sudo make install
+
+            - name: Install Luarocks
+              run: |
+                  wget -O - https://luarocks.org/releases/luarocks-${{env.LUAROCKS_VERSION}}.tar.gz | tar xzf -
+                  cd luarocks-${{env.LUAROCKS_VERSION}}
+                  ./configure --with-lua=/usr/local
+                  make
+                  sudo make install
+
+            - name: Install Luacheck
+              run: luarocks install --local luacheck
+
+            - name: Run Luacheck
+              run: |
+                  eval "$(luarocks path)"
+                  ./run-lint
+
+    test:
+        name: Test
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v2
+
+            - name: Install Lua
+              run: |
+                  wget -O - https://github.com/pallene-lang/lua-internals/archive/refs/tags/${{env.LUA_VERSION}}.tar.gz | tar xzf -
+                  cd lua-internals-${{env.LUA_VERSION}}
+                  make linux
+                  sudo make install
+
+            - name: Install Luarocks
+              run: |
+                  wget -O - https://luarocks.org/releases/luarocks-${{env.LUAROCKS_VERSION}}.tar.gz | tar xzf -
+                  cd luarocks-${{env.LUAROCKS_VERSION}}
+                  ./configure --with-lua=/usr/local
+                  make
+                  sudo make install
+
+            - name: Build
+              run: luarocks --local make
+
+            - name: Install Busted
+              run: luarocks --local install busted
+
+            - name: Run Tests
+              run: |
+                  eval "$(luarocks path)"
+                  busted -o gtest -v ./spec

.gitignore

@@ -0,0 +1,3 @@
+*.o
+*.a
+*.so

.luacheckrc

@@ -0,0 +1,36 @@
+-- vim: set filetype=lua : --
+
+-- Luacheck configuration file [1]
+--
+-- Please install Luacheck to your system with Luarocks:
+--
+--    luarocks install luacheck
+--
+-- To run Luackeck, please use our linter script, which also runs additional checks:
+--
+--    ./run-lint
+--
+-- For vim integration, I recommend ALE [2]. It supports luacheck out of the box
+-- For other editors such as Sublime, Atom, Emacs, Brackets, and VS Code,
+-- consult the instructions in the Luacheck documentation [3].
+--
+-- [1] https://luacheck.readthedocs.io/en/stable/config.html
+-- [2] https://github.com/dense-analysis/ale
+-- [3] https://github.com/mpeterv/luacheck#editor-support
+
+ignore = {
+    "212/self", -- Unused argument "self"
+
+    "411/ok",    -- Redefining local "ok"
+    "411/errs?", -- Redefining local "err" or "errs"
+
+    "421/ok",    -- Shadowing local "ok"
+    "421/errs?", -- Shadowing local "err" or "errs"
+
+    "542", -- Empty if branch.
+    "6..", -- Whitespace warnings
+}
+
+files["spec"] = {
+    std = "+busted"
+}

AUTHORS.md

@@ -0,0 +1,7 @@
+Pallene Tracer Authors
+----------------------
+
+Here we thank the many people who have contributed code to this project.
+This list was last updated in 2024-07-07, using `compute-authors.lua`.
+
+SD Asif Hossein

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2018-2024 The Pallene Developers
+Copyright (c) 1994-2024 Lua.org, PUC-Rio.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,30 @@
+# Copyright (c) 2024, The Pallene Developers
+# Pallene Tracer is licensed under the MIT license.
+# Please refer to the LICENSE and AUTHORS files for details
+# SPDX-License-Identifier: MIT 
+
+CC := gcc
+INSTALL_DIR    := /usr/local
+INSTALL_INCDIR := $(INSTALL_DIR)/include
+INSTALL_LIBDIR := $(INSTALL_DIR)/lib
+
+.PHONY: install ptracer_header libptracer uninstall clean
+
+install: ptracer_header libptracer
+	cp libptracer.so $(INSTALL_LIBDIR)
+
+# We need the `ptracer.h` header to be installed first.
+ptracer_header: 
+	cp lib/ptracer.h $(INSTALL_INCDIR)
+
+libptracer:
+	$(CC) -fPIC -O2 -shared src/ptracer.c -o libptracer.so
+
+uninstall: 
+	rm -rf $(INSTALL_INCDIR)/ptracer.h
+	rm -rf $(INSTALL_LIBDIR)/libptracer.so
+
+clean: 
+	rm -rf ptinit/*.o
+	rm -rf examples/*/*.so
+	rm -rf *.so

examples/fibonacci/Makefile

@@ -0,0 +1,15 @@
+# Copyright (c) 2024, The Pallene Developers
+# Pallene Tracer is licensed under the MIT license.
+# Please refer to the LICENSE and AUTHORS files for details
+# SPDX-License-Identifier: MIT 
+
+CC := gcc
+
+.PHONY : all debug
+.SILENT:
+
+all: 
+	$(CC) -fPIC $(CFLAGS) -shared module.c -o module.so
+
+debug: 
+	$(CC) -fPIC $(CFLAGS) -DMODULE_DEBUG -shared module.c -o module.so

examples/fibonacci/main.lua

@@ -0,0 +1,9 @@
+-- Copyright (c) 2024, The Pallene Developers
+-- Pallene Tracer is licensed under the MIT license.
+-- Please refer to the LICENSE and AUTHORS files for details
+-- SPDX-License-Identifier: MIT
+
+local mod = require "module"
+print(mod.fib(40))
+-- Uncomment this and trigger an error. You can debug using the 'pallene-debug' script.
+-- print(mod.fib(40.0))

examples/fibonacci/module.c

@@ -0,0 +1,121 @@
+/* 
+ * Copyright (c) 2024, The Pallene Developers
+ * Pallene Tracer is licensed under the MIT license.
+ * Please refer to the LICENSE and AUTHORS files for details
+ * SPDX-License-Identifier: MIT 
+ */
+
+#define PT_IMPLEMENTATION
+#include <ptracer.h>
+
+#ifdef MODULE_DEBUG
+/* ---------------- FOR LUA INTERFACE FUNCTIONS ---------------- */
+/* The finalizer fn will run whenever out of scope. */
+#define PREPARE_FINALIZER()                             \
+    int _base = lua_gettop(L);                          \
+    lua_pushvalue(L, lua_upvalueindex(2));              \
+    lua_toclose(L, -1)
+
+#define MODULE_LUA_FRAMEENTER(fnptr)                    \
+    pt_fnstack_t *fnstack = lua_touserdata(L,           \
+        lua_upvalueindex(1));                           \
+    pt_frame_t _frame =                                 \
+        PALLENE_TRACER_LUA_FRAME(fnptr);                \
+    pallene_tracer_frameenter(L, fnstack, &_frame);     \
+    PREPARE_FINALIZER()
+
+/* Nothing to do here. */
+#define MODULE_LUA_FRAMEEXIT()
+
+/* ---------------- FOR C INTERFACE FUNCTIONS ---------------- */
+#define MODULE_C_PROTO(signature, ...)    signature(pt_fnstack_t *fnstack, __VA_ARGS__)
+#define MODULE_C_CALL(fn_name, ...)       fn_name(fnstack, __VA_ARGS__)
+
+#define MODULE_C_FRAMEENTER()                           \
+    static pt_fn_details_t _details =                   \
+        PALLENE_TRACER_FN_DETAILS(__func__, __FILE__);  \
+    pt_frame_t _frame =                                 \
+        PALLENE_TRACER_C_FRAME(_details);               \
+    pallene_tracer_frameenter(L, fnstack, &_frame)
+
+#define MODULE_C_SETLINE()                              \
+    pallene_tracer_setline(fnstack, __LINE__ + 1)
+
+#define MODULE_C_FRAMEEXIT()                            \
+    pallene_tracer_frameexit(fnstack)
+#else
+/* ---------------- FOR LUA INTERFACE FUNCTIONS ---------------- */
+#define MODULE_LUA_FRAMEENTER(_)          int _base = lua_gettop(L);
+#define MODULE_LUA_FRAMEEXIT()
+
+/* ---------------- FOR C INTERFACE FUNCTIONS ---------------- */
+#define MODULE_C_PROTO(signature, ...)    signature(__VA_ARGS__)
+#define MODULE_C_CALL(fn_name, ...)       fn_name(__VA_ARGS__)
+
+#define MODULE_C_FRAMEENTER()
+#define MODULE_C_SETLINE()
+#define MODULE_C_FRAMEEXIT()
+#endif // MODULE_DEBUG
+
+#define MODULE_C_RET(expression)      \
+    MODULE_C_FRAMEEXIT();             \
+    return (expression)
+#define MODULE_LUA_RET(expression)    \
+    MODULE_LUA_FRAMEEXIT();           \
+    return (expression)
+
+MODULE_C_PROTO(int fib, lua_State *L, int n) {
+    MODULE_C_FRAMEENTER();
+
+    if(n <= 1) {
+        MODULE_C_RET(n);
+    }
+
+    MODULE_C_SETLINE();
+    MODULE_C_RET(MODULE_C_CALL(fib, L, n - 1) + MODULE_C_CALL(fib, L, n - 2));
+}
+
+int fib_lua(lua_State *L) {
+    MODULE_LUA_FRAMEENTER(fib_lua);
+
+    /* Check the macro definitions for '_base'. */
+    if(_base < 1) {
+        luaL_error(L, "Expected atleast 1 parameter");
+    }
+
+    lua_pushvalue(L, 1);
+    if(luai_unlikely(lua_isinteger(L, -1) == 0)) {
+        luaL_error(L, "Expected the first argument to be an integer");
+    }
+
+    /* Dispatch. */
+    int result = MODULE_C_CALL(fib, L, lua_tointeger(L, -1));
+    lua_pushinteger(L, result);
+
+    MODULE_LUA_RET(1);
+}
+
+int luaopen_module(lua_State *L) {
+#ifdef MODULE_DEBUG
+    /* Our stack. */
+    pt_fnstack_t *fnstack = pallene_tracer_init(L);
+#endif // MODULE_DEBUG
+
+    lua_newtable(L);
+    int table = lua_gettop(L);
+
+    /* ---- fib ---- */
+#ifdef MODULE_DEBUG
+    /* One very good way to integrate our stack userdatum and finalizer
+       object is by using Lua upvalues. */
+    lua_pushlightuserdata(L, fnstack);
+    /* `pallene_tracer_init` function pushes the frameexit finalizer to the stack. */
+    lua_pushvalue(L, -3);
+    lua_pushcclosure(L, fib_lua, 2);
+#else
+    lua_pushcfunction(L, fib_lua);
+#endif // MODULE_DEBUG
+    lua_setfield(L, table, "fib");
+
+    return 1;
+}