cli/q
Code Issues Pull Requests Activity

Improved documentation

Browse Source
This commit is contained in:
Eduard Urbach 2024-06-19 12:19:32 +02:00
parent 76db8feee3
commit 9b50c917e9
Signed by: akyoto
GPG Key ID: C874F672B1AF20C0
1 changed files with 20 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@ -17,19 +17,13 @@ go build
## Usage ## Usage
Build a Linux ELF executable from `examples/hello`: Build a Linux x86-64 ELF executable from `examples/hello`:
```shell ```shell
./q build examples/hello ./q build examples/hello
./examples/hello/hello ./examples/hello/hello
``` ```
To produce verbose output, add the `-v` flag:
```shell
./q build examples/hello -v
```
## Documentation ## Documentation
### [main.go](main.go) ### [main.go](main.go)
@ -57,6 +51,12 @@ q build examples/hello
q build examples/hello --dry q build examples/hello --dry
``` ```
To produce verbose output, add the `-v` flag which shows the generated assembly instructions:
```shell
q build examples/hello -v
```
### [src/build/Build.go](src/build/Build.go) ### [src/build/Build.go](src/build/Build.go)
The `Build` type defines all the information needed to start building an executable file. The `Build` type defines all the information needed to start building an executable file.
@ -64,16 +64,24 @@ 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. `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. Every source file is scanned in its own goroutine for performance reasons.
Parallelization here is possible because the order of code in a directory is not significant. Parallelization here is possible because the order of files in a directory is not significant.
The main function is meanwhile waiting for new function objects to arrive from the scanners. The main thread is meanwhile waiting for new function objects to arrive from the scanners.
Once a function has arrived, it will create another goroutine for the function compilation. Once a function has arrived, it will be stored for compilation later.
The function will then be translated to generic assembler instructions. 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. 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 x86-64 machine code from the generic instruction set. The final assembler resolves label addresses, optimizes the performance and generates the specific x86-64 machine code from the generic instruction set.
The `Run` method is currently not fully implemented. ### [src/build/Function.go](src/build/Function.go)
This is the "heart" of the compiler.
Each function runs `f.Compile()` which organizes the source code into instructions that are then compiled via `f.CompileInstruction`.
You can think of instructions as the individual lines in your source code, but instructions can also span over multiple lines.
## Tests ## Tests