Janet-bootstrapping-process.md

Building and Running the janet binary

The janet binary is built from a janet.c file, but that file is not present in the Janet repo --- it is generated during the bootstrapping process. That process is described below.

The Janet compiler is written in C, and so you can use gcc (or some other C compiler) to build it, but a substantial number of Janet functions and macros (see src/boot/boot.janet) are implemented in Janet itself.

The "bootstrapper" is the compiled form of boot.c.

When you compile Janet from source:

1. the bootstrapper is the compiled from boot.c

2. the bootstrapper generates a janet.c file.

   janet.c is an amalgam of the Janet C source files and of the environment created by src/boot/boot.janet (which is used as the root environment when you later run janet).

   During this bootstrapping process, the environment created by boot.janet is marshalled into a serialized form and written out as a byte array (presumably to a temporary file?).

   Note that marshal is a cfunction, and can serialize Janet data structures into a buffer (a not-generally-human-readable buffer (aka, "byte array")) that can later be unmashalled (deserialized) by the unmarshal cfunction.

3. janet.c is compiled into the janet binary, and the serialized boot.janet buffer literal is included in with the janet binary.

---

Later, when you run the janet binary, each time you run it (and before anything else happens --- before it runs your own Janet code), that serialized content of src/boot/boot.janet is unmarshalled (de-serialized) into the root environment.

---

Is that correct?

Is "byte array" a synonym for not-really-human-readable-buffer?

@uvtc I just wanted to suggest edits but I think the only way to do that with a gist is to fork the gist and update it. You can see my revised version here.

With respect to the term 'byte array', I admit it's not used in Janet's source and is possibly a term of art that I'm misusing. I merely use it to mean an array of bytes. The function janet_marshal serialises the input into a JanetBuffer and since a JanetBuffer is basically an array of uint8_t values, hence 'byte array'.