2024-08-26 13:39:01 +02:00
..
arm64 Flattened package hierarchy 2024-08-25 20:38:22 +02:00
asm Flattened package hierarchy 2024-08-25 20:38:22 +02:00
ast Simplified file structure 2024-08-07 19:39:10 +02:00
build Improved Windows support 2024-08-14 13:41:22 +02:00
cli Improved mac support 2024-08-12 12:16:01 +02:00
compiler Flattened package hierarchy 2024-08-25 20:38:22 +02:00
config Improved Windows DLL calls 2024-08-19 11:11:45 +02:00
core Flattened package hierarchy 2024-08-25 20:38:22 +02:00
cpu Simplified file structure 2024-08-07 19:39:10 +02:00
data Simplified file structure 2024-08-07 19:39:10 +02:00
dll Improved Windows support 2024-08-19 17:25:51 +02:00
elf Flattened package hierarchy 2024-08-25 20:38:22 +02:00
errors Improved mac support 2024-08-12 12:16:01 +02:00
exe Flattened package hierarchy 2024-08-25 20:38:22 +02:00
expression Simplified file structure 2024-08-07 19:39:10 +02:00
fs Fixed incorrect paths on Windows 2024-08-14 12:27:01 +02:00
linux Flattened package hierarchy 2024-08-25 20:38:22 +02:00
mac Flattened package hierarchy 2024-08-25 20:38:22 +02:00
macho Flattened package hierarchy 2024-08-25 20:38:22 +02:00
pe Flattened package hierarchy 2024-08-25 20:38:22 +02:00
register Improved Windows DLL calls 2024-08-19 11:11:45 +02:00
riscv Flattened package hierarchy 2024-08-25 20:38:22 +02:00
scanner Flattened package hierarchy 2024-08-25 20:38:22 +02:00
scope Improved type system 2024-08-08 12:55:25 +02:00
sizeof Simplified file structure 2024-08-07 19:39:10 +02:00
token Simplified file structure 2024-08-07 19:39:10 +02:00
types Improved type system 2024-08-08 12:55:25 +02:00
windows Flattened package hierarchy 2024-08-25 20:38:22 +02:00
x64 Flattened package hierarchy 2024-08-25 20:38:22 +02:00
readme.md Updated documentation 2024-08-26 13:39:01 +02:00

Documentation

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 directory. Each command has its own set of parameters.

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.

q build
q build examples/hello
q build examples/hello --dry

Adding the -a or --assembler flag shows the generated assembly instructions:

q build examples/hello -a

Adding the -v or --verbose flag shows verbose compiler information:

q build examples/hello -v

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 x86-64 machine code from the generic instruction set.

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

This is what generates the AST from tokens.

expression/Parse.go

This is what generates expressions from tokens.