Skip to content

Latest commit

 

History

History
103 lines (73 loc) · 2.97 KB

HACKING.md

File metadata and controls

103 lines (73 loc) · 2.97 KB
Raw

Hacking the RapydScript compiler

The RapydScript compiler is written in RapydScript itself and uses the RapydScript import system to modularize its code. The compiler source code is in the src directory. The compiled compiler is by default in the release directory.

In order to start hacking on the compiler, run the command

bin/rapydscript self --complete --test

This will generate a build of the compiler in the dev directory. Now, the rapydscript command will automatically use this build, rather than the one in release. If you want to go back to the release build, simply delete the dev directory.

Code organization

The way the compiler works, given some RapydScript source code:

  • The source code is lexed into a stream of tokens (src/tokenzier.pyj)

  • The tokens are parsed into a Abstract Syntax Tree (src/parse.pyj and src/ast.pyj)

  • During parsing any import statement are resolved (this is different from python, where imports happen at run-time, not compile time).

  • The Abstract Syntax Tree is transformed into the output JavaScript (src/output/*.pyj)

  • Various bits of functionality in RapydScript depend upon the Base Library (src/baselib*.pyj). This includes things like the basic container types (list/set/dict) string functions such as str.format(), etc. The baselib is automatically inserted into the start of the output JavaScript.

The RapydScript standard library can be found in src/lib. The various tools, such as the linter, gettext support, the REPL, etc. are in the tools directory.

Tests

The tests are in the test directory and can be run using the command:

rapydscript test

You can run individual test files by providing the name of the file, as

rapydscript test classes

Modifying the compiler

Edit the files in the src directory to make your changes, then use the ./try script to test them. This script will compile an updated version of the compiler with your changes, if any, and use it to run the snippet of code you pass to it.

For example:

./try 'print("Hello world")'

will compile print ("Hello world") and show you the output on stdout. You can tell it to omit the baselib, so you can focus on the output, with the -m switch, like this:

./try -m 'print("Hello world")'

You can also have it not print out the JavaScript, instead directly executing the output JavaScript with the -x switch, like this

./try -x 'print("Hello world")'

If you want to test longer sections of code, you can use the -f switch to pass in the path to a RapydScript file to compile, like this:

./try -f myfile.pyj

Once you are happy with your changes, you can build the compiler and run the test suite, all with a single command:

./build

This will build the compiler with the updated version of itself and then run the test suite. If all test pass you can commit your changes and send a pull request :)