From 92e4175bbd441181a38648532b73dcdbfe18ea5e Mon Sep 17 00:00:00 2001 From: Eduard Urbach Date: Tue, 28 Jan 2025 14:04:30 +0100 Subject: [PATCH] Improved documentation --- src/build/readme.md | 19 ++++++++++++ src/cli/readme.md | 34 ++++++++++++++++++++++ src/core/readme.md | 5 ++++ src/readme.md | 71 --------------------------------------------- 4 files changed, 58 insertions(+), 71 deletions(-) create mode 100644 src/build/readme.md create mode 100644 src/cli/readme.md create mode 100644 src/core/readme.md diff --git a/src/build/readme.md b/src/build/readme.md new file mode 100644 index 0000000..2d30e68 --- /dev/null +++ b/src/build/readme.md @@ -0,0 +1,19 @@ +### [Build.go](Build.go) + +The `Build` type defines all the information needed to start building an executable file. +The name of the executable will be equal to the name of the build directory. + +`Run` starts the build which will scan all `.q` source files in the build directory. +Every source file is scanned in its own goroutine for performance reasons. +Parallelization here is possible because the order of files in a directory is not significant. + +The main thread is meanwhile waiting for new function objects to arrive from the scanners. +Once a function has arrived, it will be stored for compilation later. +We need to wait with the compilation step until we have enough information about all identifiers from the scan. + +Then all the functions that were scanned will be compiled in parallel. +We create a separate goroutine for each function compilation. +Each function will then be translated to generic assembler instructions. + +All the functions that are required to run the program will be added to the final assembler. +The final assembler resolves label addresses, optimizes the performance and generates the specific machine code from the generic instruction set. \ No newline at end of file diff --git a/src/cli/readme.md b/src/cli/readme.md new file mode 100644 index 0000000..262701d --- /dev/null +++ b/src/cli/readme.md @@ -0,0 +1,34 @@ +### [Main.go](Main.go) + +Entry point. + +The command line interface expects a command like `build` as the first argument. +Commands are implemented as functions in the `cli` directory. +Each command has its own set of parameters. + +### [Build.go](Build.go) + +The build command creates a new `Build` instance with the given directory and calls the `Run` method. + +If no directory is specified, it will use the current directory. + +If the `--dry` flag is specified, it will perform all tasks except the final write to disk. +This flag should be used in most tests and benchmarks to avoid needless disk writes. + +```shell +q build +q build examples/hello +q build examples/hello --dry +``` + +Adding the `-a` or `--assembler` flag shows the generated assembly instructions: + +```shell +q build examples/hello -a +``` + +Adding the `-v` or `--verbose` flag shows verbose compiler information: + +```shell +q build examples/hello -v +``` \ No newline at end of file diff --git a/src/core/readme.md b/src/core/readme.md new file mode 100644 index 0000000..da1e2c2 --- /dev/null +++ b/src/core/readme.md @@ -0,0 +1,5 @@ +## [Function.go](Function.go) + +This is the "heart" of the compiler. +Each function runs [Compile](Compile.go) which organizes the source code into an abstract syntax tree that is then compiled via [CompileAST](CompileAST.go). +You can think of AST nodes as the individual statements in your source code. \ No newline at end of file diff --git a/src/readme.md b/src/readme.md index 59c7d81..6483efc 100644 --- a/src/readme.md +++ b/src/readme.md @@ -25,74 +25,3 @@ - [token](token) - Converts a file to tokens with the `Tokenize` function - [types](types) - Type system (w.i.p.) - [x64](x64) - x86-64 implementation - -# Documentation - -## [cli/Main.go](cli/Main.go) - -Entry point. - -The command line interface expects a command like `build` as the first argument. -Commands are implemented as functions in the [cli](cli) directory. -Each command has its own set of parameters. - -## [cli/Build.go](cli/Build.go) - -The build command creates a new `Build` instance with the given directory and calls the `Run` method. - -If no directory is specified, it will use the current directory. - -If the `--dry` flag is specified, it will perform all tasks except the final write to disk. -This flag should be used in most tests and benchmarks to avoid needless disk writes. - -```shell -q build -q build examples/hello -q build examples/hello --dry -``` - -Adding the `-a` or `--assembler` flag shows the generated assembly instructions: - -```shell -q build examples/hello -a -``` - -Adding the `-v` or `--verbose` flag shows verbose compiler information: - -```shell -q build examples/hello -v -``` - -## [build/Build.go](build/Build.go) - -The `Build` type defines all the information needed to start building an executable file. -The name of the executable will be equal to the name of the build directory. - -`Run` starts the build which will scan all `.q` source files in the build directory. -Every source file is scanned in its own goroutine for performance reasons. -Parallelization here is possible because the order of files in a directory is not significant. - -The main thread is meanwhile waiting for new function objects to arrive from the scanners. -Once a function has arrived, it will be stored for compilation later. -We need to wait with the compilation step until we have enough information about all identifiers from the scan. - -Then all the functions that were scanned will be compiled in parallel. -We create a separate goroutine for each function compilation. -Each function will then be translated to generic assembler instructions. - -All the functions that are required to run the program will be added to the final assembler. -The final assembler resolves label addresses, optimizes the performance and generates the specific machine code from the generic instruction set. - -## [core/Function.go](core/Function.go) - -This is the "heart" of the compiler. -Each function runs `f.Compile` which organizes the source code into an abstract syntax tree that is then compiled via `f.CompileAST`. -You can think of AST nodes as the individual statements in your source code. - -## [ast/Parse.go](ast/Parse.go) - -This is what generates the AST from tokens. - -## [expression/Parse.go](expression/Parse.go) - -This is what generates expressions from tokens. \ No newline at end of file