From 3788d0a175b9372b3f39bc10e5462f567000c987 Mon Sep 17 00:00:00 2001 From: Rose Hogenson Date: Fri, 22 Apr 2022 22:23:44 -0700 Subject: Add notes on the build process and CLI interface. --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/README.md b/README.md index 4d5024a..14a6f09 100644 --- a/README.md +++ b/README.md @@ -353,3 +353,41 @@ conversion step for IR2. Afterwards, we will transform all a reference into the current closure. All `` forms will be replaced by a `` that explicitly captures variables from the parent context. + +### Build process + +The idea behind the build process is to bootstrap compilation through a +Guile compatibility layer. Because we're writing R7RS scheme, Guile can +execute `csc` just fine. So building executes in phases. + +1. Use Guile to run the compiler on itself, producing a compiled + bytecode blob. +2. Run the bytecode blob on the compiler again, producing a second blob + that would in theory be identical. +3. Embed the compiler bytecode blob with the bytecode interpreter to + make a compiler executable. + +## CLI interface + +The `csc` compiler has a simple CLI interface. There are two main modes +of operation, compile-and-run, and ahead-of-time compilation. The +default is compile-and-run. + +The compiler flags are given below. + +- **`-I` *dir*.** Add *dir* to the list of directories to be searched + for libraries. A system directory will always be searched as well. A + library name is translated into a path by combining the elements with + `/`. Library files end in a `.csc` suffix, and if there is a `.cso` + precomipled object file in the same directory, it will be used instead + of the `.csc` source file. Indeed, the `.csc` source file is not + required at all if a precompiled object file is found. +- **`-o` *file*.** Write a precompiled object file to *file*. If `-o` is + specified, `csc` will operate in ahead-of-time compilation mode and + will not run the program. The output file will usually end in `.cso`. + This option can be used to precompile libraries to speed up execution, + and is used by the build process to turn the compiler into a bytecode + blob that can be embedded with the bytecode interpreter. + +The `csc` compiler also takes a filename to compile and +possibly execute. -- cgit v1.3.1