Bootstrap
=========

The Modelverse bootstrap procedure compiles the core library into an intitial Modelverse State image.
This is a "bootable" configuration, meaning that as soon as this is passed on to the MvS, the MvS starts execution of the code stored in the bootstrap files.
All information related to the bootstrap files, and the core library, which is an essential part of it, can be found in the *bootstrap/* folder.

Initial Code
------------

The core library consists of some files, which are merged together during compilation.
This split is primarily done to allow for partial compilation.
Most files are just a part of the core library, and are not discussed in detail.

Initially, the file *main.alc* is found to have a *main* function, at which all tasks start execution.
The contents of these bootstrap files is not discussed here, as this could in theory be anything.

Note that, upon compilation of the bootstrap code, an additional *merged.alm* file is created, which is a merged version of all the code into a single file.

Initial Models
--------------

The bootstrap folder also contains several model files, which follow a marginally different syntax.
Instead of being only the definition of the model, these files additionally contain an import and export statement, referring to locations in the Modelverse.
These models are not compiled to model constructors, as normally the case, but are translated to Action Language code to incrementally create the model.
This generated action language is merged with the *metamodels.alt* file, which is executed upon startup of the Modelverse.

Note that these initial models cannot contain action language, as the action language constructors are not fully loaded yet upon initialization of the models.
If action language is desired, this should be added afterwards in the Modelverse.

Bootstrap Procedure
-------------------

To generate the bootstrap file, the script *scripts/generate_bootstrap.py* does the necessary steps.
In essence, the models are first compiled to action language, and all the action language is merged together into a single bootstrap file: *bootstrap.m.gz*.
Additionally, *bootstrap/bootstrap.py* adds some linking code to define all the primitives and make all of them available at the correct location within the Modelverse.
Linking is also performed between the different fragments of code, as it effectively becomes a single whole.
This file is gzipped, as otherwise it would become rather large: it is a complete dump of the MvS.

With this bootstrap state of the MvS, the Modelverse can now start up and have all the state that is required.
Note that the MvS does not write out its state changes to the file again, as this would likely become a performance bottleneck.

Altering the Bootstrap File
---------------------------

While users can update the files in the bootstrap folder directly, changes to these files require recompilation of the bootstrap file, after which the Modelverse has to be restarted.
As all tasks are also stored within the MvS, overwriting the MvS indiscriminately would erase running tasks.
Instead, the Modelverse allows users to modify the code of the bootstrap directly by overloading.
While all users can manually define and execute functions that overwrite the meaning of some built-in functions, one specific model is loaded at the start of each task.

This code model has to be stored in the modelverse at *models/core_library*.
While this was intended to serve as a means of overwriting the bootstrap functions, any possible function can be added here.

To upload the initial bootstrap file, thereby making it possible to be updated completely later on, users can execute the *scripts/upload_core.py* script.
This script uploads the complete bootstrap as a single action language model, which then represents the functions to be executed.
Note that by default the bootstrap action language code is not visible, even though this is present in the Modelverse.
This was done for performance reasons: the original bootstrap code is only typed by conformance bottom for performance reasons, and adding all typing information might be wasteful.
Nonetheless, if users require this functionality, the option exists.
