Merge pull request #534 from pallene-lang/lua-core

Rework the installation process

.github/workflows/ci.yml

@@ -7,8 +7,6 @@
 # Useful reference:
 #   - https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions
 #   - https://github.com/actions/checkout
-#   - https://github.com/leafo/gh-actions-lua
-#   - https://github.com/leafo/gh-actions-luarocks
 
 name: Github Actions CI
 
@@ -24,36 +22,68 @@ on:
     pull_request:
         branches: [ master ]
 
+env:
+    LUA_VERSION: 5.4.4
+    LUAROCKS_VERSION: 3.9.0
+
 jobs:
     lint:
         name: Lint
         runs-on: ubuntu-latest
         steps:
             - uses: actions/checkout@v2
-            - uses: leafo/[email protected]
-            - uses: leafo/[email protected]
+
+            - 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 luacheck
+              run: luarocks install --local luacheck
 
             - name: Run Luacheck
-              run: ./run-lint
+              run: |
+                  eval "$(luarocks path)"
+                  ./run-lint
 
     test:
         name: Test
         runs-on: ubuntu-latest
         steps:
             - uses: actions/checkout@v2
-            - uses: leafo/[email protected]
-            - uses: leafo/[email protected]
 
-            - name: Build
+            - 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: |
-                  luarocks make
-                  (cd vm && make linux)
+                  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 install busted
+              run: luarocks --local install busted
 
             - name: Run Tests
-              run: busted -o gtest -v ./spec
+              run: |
+                  eval "$(luarocks path)"
+                  busted -o gtest -v ./spec

CONTRIBUTING.md

@@ -29,21 +29,23 @@ $ luarocks install busted
 ```
 
 To run the test suite, run the `./run-tests` script in this project's root directory.
-Tip: if GNU parallel is installed, it can speed things up by running multiple tests in parallel.
 
 ```sh
 $ ./run-tests                       # Run all tests
 $ ./run-tests spec/parser_spec.lua  # Run just one of the test suite files
 ```
 
+**Tip:** We recommend having [GNU parallel](https://www.gnu.org/software/parallel/) installed.
+This optional dependency speeds things up by running multiple tests at the same time.
+
 The `./run-tests` script accepts the same command-line flags as `busted`.
-If you are debugging an unhandled exception in a test case, the following ones might help:
+If you are debugging an unhandled exception in a test case, the following flags might help:
 
 Flag                  | Effect
 --------------------- | --------------------------------------------------------
 ./run-tests -v        | Verbose output, including the stack trace
 ./run-tests -k        | Run all tests even if some tests are failing
-./run-tests -o gtest  | Changes the output formatting.<br>This may be clearer if you are using print statements for debugging.
+./run-tests -o gtest  | The gtest output format might be easier to read if you are using print statements for debugging.
 
 For convenience, when the test script is run without any parameters, it also runs the linter at the end.
 
@@ -77,8 +79,7 @@ To run benchmarks with LuaJIT, use the `--lua` option:
 ./benchmarks/run benchmarks/sieve/lua.lua --lua=luajit
 ```
 
-If you change the ".pln" file of a benchmark, or if you change our Pallene-to-Lua translator in "translator.lua",
-please run the `./benchmarks/generate_lua` script to regenerate the ".lua" files for the benchmarks.
+If you change the ".pln" file of a benchmark please run the `./benchmarks/generate_lua` script to regenerate the corresponding ".lua" file.
 
 # Git workflow
 

README.md

@@ -14,97 +14,85 @@ Compared to LuaJIT, Pallene aims to offer more predictable run-time performance.
 
 ## Building the Pallene Compiler
 
-In order to use this source distribution of the Pallene compiler, you need to
-install its Lua library dependencies and compile its run-time library.
+Pallene requires a special version of Lua, which you will likely need to build from source.
+You will also likely need to build and install Luarocks from source.
 
-### Prerequisites
+### Install the special Lua
 
-Before you build Pallene, you need to install a C compiler (e.g. `gcc`) and `make` on your system.
-Ubuntu users can run the following commands to install these tools.
-```
-sudo apt update
-sudo apt install build-essential
-```
-
-If you are on Linux, we also recommend that you install the Readline library.
-
-```sh
-sudo apt install libreadline-dev # for Ubuntu & Debian-based distros
-sudo dnf install readline-devel  # for Fedora
-```
-
-Another optional dependency is GNU parallel, which speeds up how long it takes to run the test suite.
+First, you need to install a Pallene-compatible version of Lua.
+This version of Lua is patched to expose some extra C APIs that Pallene needs.
+You can download it from [our other repository](https://www.github.com/pallene-lang/lua-internals).
+Make sure to get version 5.4.4, because the minor patch number is important.
 
 ```sh
-sudo apt install parallel # for Ubuntu & Debian-based distros
-sudo dnf install parallel # for Fedora
+wget https://www.github.com/pallene-lang/lua-internals/relelases/tag/v5.4.4
+tar xf lua-internals-5.4.4.tar.gz
+cd lua-internals-5.4.4
+make linux-readline -j4
+sudo make install
 ```
 
-Pallene requires Lua 5.3 or newer to be installed on your system.
-You can either install it [from source](https://www.lua.org/ftp/) or via the package manager for your Linux distro.
-If you install via the package manager then make sure to also install the Lua headers, which are often in a separate "development" package.
-
-After Lua 5.3 is installed, download the source code of LuaRocks from
-[https://github.com/luarocks/luarocks/releases](https://github.com/luarocks/luarocks/releases). Follow
-the build instructions appropriate for your platform and install it on your system.
+To check if you have installed the right version of Lua, run `lua -v`.
+It needs to say `Lua 5.x.x with core API`.
+If the message doesn't have the "with core API", that means you're using vanilla Lua.
 
-If LuaRocks is configured to use older versions of Lua, you may not be able to
-install the dependencies as described in the next section. Therefore, please
-configure LuaRocks to use Lua 5.3. You can use the following command to configure
-LuaRocks to use Lua 5.3 when compiling it:
-`./configure --lua-version=5.3`
+### Install Luarocks from source
 
-### Installing Lua dependencies
+You will probably also need to install Luarocks from source.
+We can't use the Luarocks from the package manager because that way it won't use the custom version of Lua we just installed.
 
-The easiest way to install these dependencies is with the [LuaRocks](http://luarocks.org) package manager:
+For more information on how to install Luarocks, please see the [Luarocks wiki](https://github.com/luarocks/luarocks/wiki/Installation-instructions-for-Unix).
+In the configure step, use the `--with-lua` flag to point to where we installed the custom Lua.
 
 ```sh
-$ luarocks install --local --only-deps pallene-dev-1.rockspec
+wget https://luarocks.org/releases/luarocks-3.9.0.tar.gz
+tar xf luarocks-3.9.0.tar.gz
+cd luarocks-3.9.0
+./configure --with-lua=/usr/local
+make
+sudo make install
 ```
 
-If you use the --local flag when installing packages from Luarocks, you may
-also need to configure the appropriate environment variables on your terminal configuration file.
-If you are using bash you can do (as stated in `luarocks --help path`):
+By default, Luarocks installs packages to the root directory, which requires sudo.
+If you are like me, you might prefer to intall to your home directory by default.
+
 ```sh
-$ echo 'eval `luarocks path`' >> ~/.bashrc
+# Run this one time
+luarocks config local_by_default true
 ```
-For further information, consult the [Luarocks documentation](https://github.com/luarocks/luarocks/wiki/path).
 
-### Compiling the custom interpreter
+Remember that in order for the local rocks tree to work, you must to set some environment variables
 
-Pallene must be run against a custom-built version of the Lua interpreter.
-This custom version of Lua 5.4 doesn't have to be the same one that you will use to run the compiler itself,
-or to install the Luarocks packages.
+```sh
+# Add this line to your ~/.bashrc
+eval "$(luarocks path)"
+```
 
-To compile the custom version of Lua, follow the instructions found the [Lua README](https://www.lua.org/manual/5.4/readme.html), also found in the vm/doc/readme.html file.
+### Build and install Pallene
 
-For Linux, these are the commands you need to run:
+Finally, we can use Luarocks to build and install the Pallene compiler.
+This will also download and install the necessary Lua dependencies.
 
-```sh
-cd vm
-make linux-readline -j
+```
+luarocks make pallene-dev-1.rockspec
 ```
 
-## Usage
+## Using Pallene
 
 To compile a `foo.pln` file to a `foo.so` module call `pallenec` as follows.
 
-Note: Your current working directory must be the root of this repository, due to
-[Bug #16](https://github.com/pallene-lang/pallene/issues/16).
-
-
 ```sh
-$ ./pallenec foo.pln
+$ pallenec foo.pln
 ```
 
-To run Pallene, you must currently use the bundled version of the Lua
-interpreter (again, see [Bug #16](https://github.com/pallene-lang/pallene/issues/16)).
+The resulting `foo.so` can be used by Lua via the usual `require` mechanism.
 
 ```sh
-$ ./vm/src/lua -l foo
+$ lua -l foo
 ```
 
-It is possible to change compiler optimization level, for the Pallene compiler and C compiler. Here are some examples:
+It is possible to change the compiler optimization level, for the Pallene compiler and C compiler.
+Here are some examples:
 
 ```sh
 # execute no optimization (Pallene and C compiler)
@@ -120,7 +108,7 @@ $ env CFLAGS="-O2" ./pallenec test.pln -O0
 $ ./pallenec test.pln
 ```
 
-**Note**: For the C compiler only, the setting set using `CFLAGS` override the setting set by flag `-O`.
+**Note**: For the C compiler only, the setting set using `CFLAGS` overrides the setting set by flag `-O`.
 
 For more compiler options, see `./pallenec --help`
 

benchmarks/benchlib.lua

@@ -2,7 +2,7 @@ local util = require "pallene.util"
 
 local benchlib = {}
 
-benchlib.DEFAULT_LUA = "./vm/src/lua"
+benchlib.DEFAULT_LUA = "lua"
 
 -- @param lua_path:       Lua interpreter to use
 -- @param benchmark_path: Path to the benchmark file

benchmarks/binarytrees/lua.lua

@@ -1,4 +1,4 @@
-local m;m = {}
+math.ln = math.log; local m = {}
 
 function m.BottomUpTree(depth)
     if depth > 0 then

benchmarks/conway/lua.lua

@@ -1,7 +1,7 @@
-local m, ALIVE, DEAD;m = {}
+math.ln = math.log; local m = {}
 
-ALIVE = "*"
-DEAD  = " "
+local ALIVE = "*"
+local DEAD  = " "
 
 -- Create a new grid for the simulation.
 function m.new_canvas(N, M)

benchmarks/fannkuchredux/lua.lua

@@ -1,4 +1,4 @@
-local m = {}
+math.ln = math.log; local m = {}
 
 function m.fannkuch(N)
 

doc/manual.md

@@ -36,7 +36,7 @@ $ ./pallenec sum.pln
 The `sum.so` file can be loaded from within Lua with `require`, as usual:
 
 ```
-$ ./vm/src/lua
+$ lua
 > sum = require "sum"
 > print(sum.sum_floats({10.0, 20.0, 30.0})) --> 60.0
 ```
@@ -498,11 +498,11 @@ All the functions currently require float arguments. The compiler will reject in
 At this time, math.log requires two parameters, and the compiler will reject one parameter calls.
 So as a workaround, use math.ln in place of the one parameter math.log.
 
-math.modf returns two values, an integer and a float. One minor difference from Lua is that Lua 
+math.modf returns two values, an integer and a float. One minor difference from Lua is that Lua
 may return a float for the first value if some reason it cannot return an integer, such as if
 the result is NaN (which only exists in floating point). In Pallene, the first value will always be
-converted to an integer unless the conversion fails, in which case a runtime error is raised. 
-This is also true of the return values for math.ceil and math.floor, where Pallene will always 
+converted to an integer unless the conversion fails, in which case a runtime error is raised.
+This is also true of the return values for math.ceil and math.floor, where Pallene will always
 return an integer or raise a runtime error.
 
 ## Pallene to Lua translator