From b84dff4c9410fd0b5232c9050d37fdb21fd40816 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nathana=C3=ABl=20Courant?= Date: Mon, 7 Dec 2020 18:07:44 +0100 Subject: [PATCH 1/4] Add READMEs --- README.md | 7 +++++++ interpreter/README.md | 8 ++++++++ miniml/compiler/README.md | 16 ++++++++++++++++ 3 files changed, 31 insertions(+) create mode 100644 README.md create mode 100644 interpreter/README.md create mode 100644 miniml/compiler/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4ebd504 --- /dev/null +++ b/README.md @@ -0,0 +1,7 @@ +# camlboot: An OCaml bootstrap experiment + +camlboot is an experiment on the boostraping of the OCaml compiler. It is composed of: + +- An interpreter of OCaml, in the folder `interpreter/`, which is able to interpret the OCaml compiler. This interpreter is written in a subset of OCaml called miniml, for which a compiler is available as part of the experiment. +- A compiler for miniml, in the folder `miniml/compiler/`. This compiler compiles miniml to OCaml bytecode, which is then executed by the OCaml runtime. It is written in scheme (more specifically, guile), since the objective is to bootstrap OCaml. +- An handwritten lexer for the bootstrapping of ocamllex, in the folder `lex/`. This lexer is able to perform the lexing of ocamllex's own `lexer.mll`, the first step towards the bootstrap of ocamllex, and then OCaml. diff --git a/interpreter/README.md b/interpreter/README.md new file mode 100644 index 0000000..98cb06e --- /dev/null +++ b/interpreter/README.md @@ -0,0 +1,8 @@ +# OCaml interpreter + +This folder contains an interpreter for OCaml, written in miniml. It aims to be as correct as possible while only using the untyped representation of the program. + +It has three main modes: +- `./interp ocamlc`, which will interpret the compiler sources to get a replacement for `ocamlc`, +- `./interp ocamlopt`, which will interpret the compiler sources to get a replacement for `ocamlopt`, +- `./interp files [list of files]`, which will interpret the list of files given as argument. diff --git a/miniml/compiler/README.md b/miniml/compiler/README.md new file mode 100644 index 0000000..5c8de7e --- /dev/null +++ b/miniml/compiler/README.md @@ -0,0 +1,16 @@ +# miniml compiler + +The file `compile.scm` is a single-file compiler for the miniml language, written in Scheme. It targets the OCaml bytecode for the version 4.07.0 of the OCaml compiler. + +It is used as such: +```bash +$ guile compile.scm file.ml -o file.byte +``` +The file `file.byte` will then contain executable OCaml bytecode, which can be run using `ocamlrun` from version 4.07.0 of the OCaml compiler (in this repository's `ocaml-src/` submodule). + +It can only process a single file of input; in case you wish to use multiple files, you must first bundle them all into a single `.ml` file, putting the contents of file `x.ml` between `module X = struct`/`end` delimiters. + +All OCaml external functions can be used with `external` declarations, but primitives work differently: they call a single bytecode instruction, with the instruction number specified in the external declaration; see `hello.ml` for examples. + +`miniml` is completely untyped, and error reporting during compilation is very limited. However, since syntax and semantics are almost completely compatible with OCaml, in most cases you can just use OCaml to find the syntax or type error. + From e469c51a3a9e1e5e17c1d343e30e6d5b3cc66216 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nathana=C3=ABl=20Courant?= Date: Mon, 7 Dec 2020 21:23:57 +0100 Subject: [PATCH 2/4] Fix typos in README after review --- README.md | 6 +++--- interpreter/README.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4ebd504..88274a7 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,6 @@ camlboot is an experiment on the boostraping of the OCaml compiler. It is composed of: -- An interpreter of OCaml, in the folder `interpreter/`, which is able to interpret the OCaml compiler. This interpreter is written in a subset of OCaml called miniml, for which a compiler is available as part of the experiment. -- A compiler for miniml, in the folder `miniml/compiler/`. This compiler compiles miniml to OCaml bytecode, which is then executed by the OCaml runtime. It is written in scheme (more specifically, guile), since the objective is to bootstrap OCaml. -- An handwritten lexer for the bootstrapping of ocamllex, in the folder `lex/`. This lexer is able to perform the lexing of ocamllex's own `lexer.mll`, the first step towards the bootstrap of ocamllex, and then OCaml. +- An interpreter of OCaml, in the directory `interpreter/`, which is able to interpret the OCaml compiler. This interpreter is written in a subset of OCaml called miniml, for which a compiler is available as part of the experiment. +- A compiler for miniml, in the directory `miniml/compiler/`. This compiler compiles miniml to OCaml bytecode, which is then executed by the OCaml runtime. It is written in scheme (more specifically, guile), since the objective is to bootstrap OCaml. +- A handwritten lexer for the bootstrapping of ocamllex, in the directory `lex/`. This lexer is able to perform the lexing of ocamllex's own `lexer.mll`, the first step towards the bootstrap of ocamllex, and then OCaml. diff --git a/interpreter/README.md b/interpreter/README.md index 98cb06e..2fabdb7 100644 --- a/interpreter/README.md +++ b/interpreter/README.md @@ -1,6 +1,6 @@ # OCaml interpreter -This folder contains an interpreter for OCaml, written in miniml. It aims to be as correct as possible while only using the untyped representation of the program. +This directory contains an interpreter for OCaml, written in miniml. It aims to be as correct as possible while only using the untyped representation of the program. It has three main modes: - `./interp ocamlc`, which will interpret the compiler sources to get a replacement for `ocamlc`, From 23bd6558731a006eba30d48920405d7a7fef8580 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nathana=C3=ABl=20Courant?= Date: Mon, 7 Dec 2020 21:26:42 +0100 Subject: [PATCH 3/4] Add comment about the interpreter needing a few more features than the current version of miniml --- interpreter/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/interpreter/README.md b/interpreter/README.md index 2fabdb7..77dc763 100644 --- a/interpreter/README.md +++ b/interpreter/README.md @@ -6,3 +6,5 @@ It has three main modes: - `./interp ocamlc`, which will interpret the compiler sources to get a replacement for `ocamlc`, - `./interp ocamlopt`, which will interpret the compiler sources to get a replacement for `ocamlopt`, - `./interp files [list of files]`, which will interpret the list of files given as argument. + +For now, it is written in a subset of OCaml a bit larger than miniml, but we are working on making it compatible with miniml by avoiding the use of unnecessary features and adding other features to miniml. From a590b6b5ea8e59a453f173da70673922c3775d8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nathana=C3=ABl=20Courant?= Date: Mon, 7 Dec 2020 22:00:09 +0100 Subject: [PATCH 4/4] Add links to OCaml and guile's homepages, add comment about guile being already bootstrapped --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 88274a7..8218ab3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # camlboot: An OCaml bootstrap experiment -camlboot is an experiment on the boostraping of the OCaml compiler. It is composed of: +camlboot is an experiment on the boostraping of the [OCaml](https://ocaml.org/) compiler. It is composed of: - An interpreter of OCaml, in the directory `interpreter/`, which is able to interpret the OCaml compiler. This interpreter is written in a subset of OCaml called miniml, for which a compiler is available as part of the experiment. -- A compiler for miniml, in the directory `miniml/compiler/`. This compiler compiles miniml to OCaml bytecode, which is then executed by the OCaml runtime. It is written in scheme (more specifically, guile), since the objective is to bootstrap OCaml. +- A compiler for miniml, in the directory `miniml/compiler/`. This compiler compiles miniml to OCaml bytecode, which is then executed by the OCaml runtime. It is written in scheme (more specifically, [guile](https://www.gnu.org/software/guile/)), since the goal is to bootstrap OCaml. Note that guile is itself bootstrapped directly from gcc, and building OCaml needs a C compiler as well, so we effectively bootstrap OCaml from gcc. - A handwritten lexer for the bootstrapping of ocamllex, in the directory `lex/`. This lexer is able to perform the lexing of ocamllex's own `lexer.mll`, the first step towards the bootstrap of ocamllex, and then OCaml.