chore: Move build-toolchain into the root

Simplifies `make` maintainance calls when all is in the root.

Author: phorward

build/Makefile Makefile

@@ -1,16 +1,24 @@
 .PHONY: .FORCE
-ETARENEG=cd ../src && awk -f ../build/etareneg.awk
+ETARENEG=awk -f etareneg.awk
 
-all:
-	@echo No target specified. See README.md for details.
+help:
+	@echo "No target specified."
+	@echo "See README.md build-section for details."
 	@echo ""
-	@echo "  make builtins    update src/_builtins.rs from src/"
-	@echo "  make parser      update src/compiler/parse.rs from src/compiler/tokay.tok"
-	@echo "  make prelude     update src/compiler/prelude.rs from src/prelude.tok"
+	@echo "  make builtins  update src/_builtins.rs"
+	@echo "  make parser    update src/compiler/parser.rs from src/compiler/tokay.tok"
+	@echo "  make prelude   update src/compiler/prelude.rs from src/prelude.tok"
 	@echo ""
+	@echo "This is the Tokay source generation toolchain."
+	@echo "To just build Tokay, simply use 'cargo build'."
+
+all:
+	make prelude
+	make parser
+	make builtins
 
 # builtins --------------------------------------------------------------------
-BUILTINS=../src/_builtins.rs
+BUILTINS=src/_builtins.rs
 
 builtins: $(BUILTINS)
 
@@ -25,7 +33,7 @@ reset-builtins:
 
 
 # parser ----------------------------------------------------------------------
-PARSER=../src/compiler/parser.rs
+PARSER=src/compiler/parser.rs
 
 parser: $(PARSER)
 
@@ -39,7 +47,7 @@ reset-parser:
 	git checkout $(PARSER)
 
 # prelude ----------------------------------------------------------------------
-PRELUDE=../src/compiler/prelude.rs
+PRELUDE=src/compiler/prelude.rs
 
 prelude: $(PRELUDE)
 

README.md

@@ -180,6 +180,34 @@ Int print($1, "=>", fibonacci($1))
 
 The Tokay homepage [tokay.dev](https://tokay.dev) provides links to a quick start and documentation. The documentation source code is maintained in a [separate repository](https://github.com/tokay-lang/tokay-docs).
 
+## Building
+
+The `Makefile` located in `src/` provides tooling to build Tokay's internal parts.
+
+### `make builtins` - update Tokay's builtin registry from the Rust sources
+
+Generate the file `src/_builtins.rs` using `src/_builtins.tok`.
+
+- `make builtins` updates the content of `src/_builtins.rs` using `src/_builtins.tok` from the Rust sources.
+- `make show-builtins` dumps what would be generated by `make builtins`
+- `make reset-builtins` resets `src/_builtins.rs` from git, if something went wrong.
+
+### `make parser` - update Tokay's parser from `tokay.tok`
+
+Tokay uses a program written in itself (`src/compiler/tokay.tok`) to generate its own language parser (`src/compiler/parser.rs`) incrementally.
+
+- `make parser` updates the content of `src/compiler/parser.rs` from `src/compiler/tokay.tok`.
+- `make show-parser` dumps what would be generated by `make parser`
+- `make reset-parser` resets `src/compiler/parser.rs` from git, if something went wrong.
+
+### `make prelude` - update Tokay's prelude from `prelude.tok`
+
+Tokay needs the prelude to provide general language features and defaults.
+
+- `make prelude` updates the content of `src/compiler/prelude.rs` from `src/prelude.tok`.
+- `make show-prelude` dumps what would be generated by `make prelude`
+- `make reset-prelude` resets `src/compiler/prelude.rs` from git, if something went wrong.
+
 ## Debugging
 
 For debugging, there are two methods to use.

build/README.md

@@ -5,7 +5,7 @@
 
 use crate::builtin::Builtin;
 
-/*GENERATE cargo run -- _builtins.tok -- `find . -name "*.rs"` */
+/*GENERATE cargo run -- src/_builtins.tok -- `find src -name "*.rs"` */
 pub static BUILTINS: [Builtin; 70] = [
     Builtin {
         name: "Float",

build/etareneg.awk etareneg.awk

@@ -17,6 +17,7 @@ _ 'tokay_' kind => {
     #print(offset()["filename"], $kind, $name)
 
     mod = offset()["filename"].split("/")
+    mod.pop(0)  # remove the "src/"
     last = mod.len - 1
     mod[last] = mod[last].replace(".rs")
     if mod[last] == "mod" mod.pop()

src/_builtins.rs

@@ -1,4 +1,4 @@
-//! Tokay parser, implemented in Tokay itself.
+//! The Tokay parser, implemented in Tokay itself.
 
 use super::*;
 use crate::error::Error;
@@ -24,9 +24,9 @@ impl Parser {
             // The best way is to test grammar changes with `tokay.tok` intensely before rebuilding the
             // parser, to ensure all runs well.
 
-            // To update this file, `cd build` and run `make parser` in a shell.
+            // To update this file, run `make parser` in a shell.
 
-            /*GENERATE cargo run -- "`sed 's/ast("main")/ast2rust(ast("main"), level=3)/g' compiler/tokay.tok`" -- compiler/tokay.tok */
+            /*GENERATE cargo run -- "`sed 's/ast("main")/ast2rust(ast("main"), level=3)/g' src/compiler/tokay.tok`" -- src/compiler/tokay.tok */
             value!([
                 "emit" => "main",
                 "children" =>

src/_builtins.tok

@@ -12,7 +12,7 @@ impl Compiler {
     pub(super) fn load_prelude(&mut self) {
         // fixme: Make this lazy_static, so its created only once!
         let ast =
-            /*GENERATE cargo run -- "`sed 's/ast("main")/ast2rust(ast("main"), level=3)/g' compiler/tokay.tok`" -- prelude.tok */
+            /*GENERATE cargo run -- "`sed 's/ast("main")/ast2rust(ast("main"), level=3)/g' src/compiler/tokay.tok`" -- src/prelude.tok */
             value!([
                 "emit" => "main",
                 "children" =>

src/compiler/parser.rs

@@ -5,7 +5,7 @@
 # This Tokay program expresses Tokay's grammar in itself.
 # It is used to modify and build Tokays own language parser.
 #
-# See `build/README.md` for details.
+# See `README.md` build-section for details.
 #
 
 #ExpectAndRecover : @<P> msg=void {