How to Avoid Breaking the Rascal Bootstrap

We are currently at the brink of switching to a development cycle where we critically depend on previously compiled code (e.g. Kernel, ParserGenerator). This page is intended to get an overall picture of breaking changes and how to remedy them.

Please:

• Add missing scenarios
• Correct scenarios
• Add validation per scenario (how has this scenario been tested?)

Scenarios that will break the bootstrap:

• Changing parameters of commandline tools rascalc, rascalTests, compileMuLibrary Validated

Since the Bootstrap script depends on these parameters, and it calls both the previous versions from the jar and the new versions in the bin folder, the commandline parameters must never change without an intermediate step.

Workaround:

1. Support transition in Bootstrap script by case distinction of phase 1 and phase 2 (to use old parameters) and phase 3 and phase 4 to use the new parameters.
2. Bootstrap and release
3. Change Bootstrap script to remove case distinctions
4. Bootstrap and release

Scenarios that cannot break the bootstrap:

• Changing Rascal functions other than Kernel functions

• Changing Java code that is unrelated to serialization

• Adding a Rascal language feature (e.g. coroutines) Note: any changes to the existing implementation should be handled according to the above approaches.

• Changing IValue or Type internally, i.e. no API changes

• Adding new IValues or Types

Scenarios to be validated/checked (break or not break):

• Changing name/signature of Kernel functions

  Approach:

  1. First follow below working bootstrap: "Add new kernel function"
  2. Release a stable version
  3. Then follow below working bootstrap: "Remove unused kernel function"

• Renaming a RascalPrimitive or MuPrimitive.

  Approach:

  1. Keep old declaration (? why is this necessary)
  2. Add new declaration for renamed version.
  3. Bootstrap.
  4. Replace in the compiler uses of old name by new name.
  5. Bootstrap.
  6. Remove declaration of old name.
  7. Bootstrap.

• Changing the signature of a RascalPrimitive or MuPrimitive

  Approach:

  1. Add a test in the body of the primitive whether dealing with the old or the new signature, keep the implementation of the old signature and add the implementation for the new signature.
  2. Bootstrap.
  3. Replace in the compiler uses of old signature by new one.
  4. Bootstrap.
  5. Remove support for old signature from the body of the primitive.
  6. Bootstrap.

• Adding field to a serialized Java class, e.g. RVMExecutable

  Approach: add optional field to the schema of the serialization file format

• Deleting field from a serialized class

  Approach: make corresponding field in schema of the serialization file format deprecated

• Changing a constructor in the RVM datatype

  Approach: add new version and make old version deprecated

• Switching to automatic compression: |compressed+file:///.../Fac.rvm.ser.gz| to |file:///.../Fac.rvm.ser.gz|

  Approach: unclear

• Switching serialization format BinaryReader+FST => FlatBuffers Approach: this looks like a huge event; no clear solution

• Moving the compiler sources to another location

  Approach: this looks like a huge event; no clear solution

• Deleting a Rascal language feature (e.g. annotations)

  Approach:

  1. Remove all uses of the feature from any Rascal code used for bootstrapping (e.g. Kernel, ParserGenerator, ...).
  2. Bootstrap.
  3. Remove the implementation of feature to be deleted.
  4. Bootstrap.