CreatingABootstrap

Creating a Bootstrap File

Making changes to the core language (as defined in joxa/compiler.jxa) is a bit of a delicate dance or perhaps its better to say its like redesigning, building and installing the engine of a jet while the jet is doing mach 3 over the Mohave desert. That is to say, that its delicate and easy to mess up. The goal of this document is to show the way you should work on Joxa along with some tips and tricks to reduce the pain when things go wrong.

Making the Changes

You absolutely want each of your changes to be small and self contained. As you finish each discrete change you want to create a commit for that change. Being able to go back to a minimal working set is critically important.

Steps to Making the Change

1. Make your changes to the way compiler.jxa processes files. NOTE: do not yet make the syntax changes to compiler.jxa. That is don't make code in compiler.jxa match whatever syntax you have added to core.

2. Make sure it works.

   A. Adjust the tests to your new syntax, make sure they pass (cucumber, eunit, proper).

   B. Make sure the compiler can compile itself. Make a copy of compiler.jxa somewhere and run the compiler on that in bootstrap mode. You can run the following in the project root to do this.

    $> make bootstrap-test
   

3. Assuming everything works and the compiler can now build itself, you need to create a new jxa_bootstrap helper module. You do that by compiling the compiler with itself with the --bootstrap and --ast flags. This will output a ./joxa/compiler.ast to the project root. That contains the raw erlang terms that make up the core AST for the compiler. Copy that (yes all 27-28 thousand lines) into jxa_bootstrap.erl. (You may want to use vim for this, emacs gets hung up on the syntax highlighting with a file that big), replace the AST that is there with the new AST. Use find and replace to replace instances of 'joxa.compiler' with Name.

4. Now make the code in joxa/compiler.jxa match the syntax changes you just finished making. Run the following tests, they all must pass for things to be accepted.

    $> sinan cucumber
    $> sinan eunit
    $> sinan proper
   

Assuming that all the tests pass you are now golden and have your changes bootstrapped into the system.