Browse Source

Wrote section on bootstrapping

Yentl Van Tendeloo 3 years ago
parent
commit
ed79cc7f5f
1 changed files with 43 additions and 5 deletions
  1. 43 5
      doc/bootstrap.rst

+ 43 - 5
doc/bootstrap.rst

@@ -1,20 +1,58 @@
 Bootstrap
 =========
 
-Explain what the bootstrapping actually does
+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
 ------------
 
-Explain the initial files and possibly link to them as well
+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
 --------------
 
-Explain the initial models and how they link together
-Explain the bootstrap compiler for 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
 ---------------------------
 
-Explain how to alter bootstrap files and what needs to be done to change it
+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.