Updated documentation
This commit is contained in:
parent
b35b17bb32
commit
63d72c8d22
39
docs/readme.md
Normal file
39
docs/readme.md
Normal file
@ -0,0 +1,39 @@
|
|||||||
|
# q
|
||||||
|
|
||||||
|
A programming language that compiles down to machine code.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- Fast compilation
|
||||||
|
- High performance
|
||||||
|
- Small executables
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git clone https://git.akyoto.dev/cli/q
|
||||||
|
cd q
|
||||||
|
go build
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```shell
|
||||||
|
./q run examples/hello
|
||||||
|
```
|
||||||
|
|
||||||
|
Builds an executable from `examples/hello` and runs it.
|
||||||
|
|
||||||
|
## Links
|
||||||
|
|
||||||
|
- [Chat](https://matrix.to/#/#community:akyoto.dev)
|
||||||
|
- [Donate](https://buy.stripe.com/4gw7vf5Jxflf83m7st)
|
||||||
|
- [Todo](/docs/todo.md)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
Please see the [license documentation](https://akyoto.dev/license).
|
||||||
|
|
||||||
|
## Copyright
|
||||||
|
|
||||||
|
© 2023 Eduard Urbach
|
80
docs/todo.md
Normal file
80
docs/todo.md
Normal file
@ -0,0 +1,80 @@
|
|||||||
|
## Todo
|
||||||
|
|
||||||
|
### Compiler
|
||||||
|
|
||||||
|
- [x] Tokenizer
|
||||||
|
- [x] Scanner
|
||||||
|
- [x] Functions
|
||||||
|
- [x] Variables
|
||||||
|
- [x] Error messages
|
||||||
|
- [x] Expression parser
|
||||||
|
- [x] Function calls
|
||||||
|
- [x] Parallel compilation
|
||||||
|
- [x] Syscalls
|
||||||
|
- [x] Variable lifetimes
|
||||||
|
- [x] Branches
|
||||||
|
- [x] Loops
|
||||||
|
- [x] Hexadecimal, octal and binary literals
|
||||||
|
- [x] Escape sequences
|
||||||
|
- [x] Multiple return values
|
||||||
|
- [ ] Type system
|
||||||
|
- [ ] Type operator `?`
|
||||||
|
- [ ] Data structures
|
||||||
|
- [ ] Slices
|
||||||
|
- [ ] Floating-point arithmetic
|
||||||
|
- [ ] Error handling
|
||||||
|
- [ ] Threading library
|
||||||
|
- [ ] Self-hosted compiler
|
||||||
|
|
||||||
|
### Keywords
|
||||||
|
|
||||||
|
- [x] `assert`
|
||||||
|
- [x] `else`
|
||||||
|
- [ ] `for`
|
||||||
|
- [x] `if`
|
||||||
|
- [x] `import`
|
||||||
|
- [x] `loop`
|
||||||
|
- [x] `return`
|
||||||
|
- [x] `switch`
|
||||||
|
|
||||||
|
### Optimizations
|
||||||
|
|
||||||
|
- [x] Exclude unused functions
|
||||||
|
- [x] Constant folding
|
||||||
|
- [ ] Constant propagation
|
||||||
|
- [ ] Function call inlining
|
||||||
|
- [ ] Loop unrolls
|
||||||
|
- [ ] Assembler optimization backend
|
||||||
|
|
||||||
|
### Linter
|
||||||
|
|
||||||
|
- [x] Unused variables
|
||||||
|
- [x] Unused parameters
|
||||||
|
- [x] Unused imports
|
||||||
|
- [ ] Unnecessary newlines
|
||||||
|
- [ ] Ineffective assignments
|
||||||
|
|
||||||
|
### Operators
|
||||||
|
|
||||||
|
- [x] `=`, `:=`
|
||||||
|
- [x] `+`, `-`, `*`, `/`, `%`
|
||||||
|
- [x] `+=`, `-=`, `*=`, `/=`, `%=`
|
||||||
|
- [x] `&`, `|`, `^`
|
||||||
|
- [x] `&=`, `|=`, `^=`
|
||||||
|
- [x] `<<`, `>>`
|
||||||
|
- [x] `<<=`, `>>=`
|
||||||
|
- [x] `==`, `!=`, `<`, `<=`, `>`, `>=`
|
||||||
|
- [x] `&&`, `||`
|
||||||
|
- [ ] `!`, `-`
|
||||||
|
|
||||||
|
### Architecture
|
||||||
|
|
||||||
|
- [ ] arm64
|
||||||
|
- [ ] riscv
|
||||||
|
- [x] x64
|
||||||
|
|
||||||
|
### Platform
|
||||||
|
|
||||||
|
- [x] Linux
|
||||||
|
- [x] Mac
|
||||||
|
- [ ] Windows
|
@ -1,135 +1,16 @@
|
|||||||
# q
|
|
||||||
|
|
||||||
A programming language for use in systems programming, game development and web servers.
|
|
||||||
|
|
||||||
## Features
|
|
||||||
|
|
||||||
* Fast compilation
|
|
||||||
* Small executables
|
|
||||||
* High performance
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git clone https://git.akyoto.dev/cli/q
|
|
||||||
cd q
|
|
||||||
go build
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
Build an executable from `examples/hello` and run it:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
./q run examples/hello
|
|
||||||
```
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
```shell
|
|
||||||
go test ./... -v -cover
|
|
||||||
```
|
|
||||||
|
|
||||||
## Benchmarks
|
|
||||||
|
|
||||||
```shell
|
|
||||||
go test ./tests -run='^$' -bench=. -benchmem
|
|
||||||
```
|
|
||||||
|
|
||||||
## Todo
|
|
||||||
|
|
||||||
### Compiler
|
|
||||||
|
|
||||||
- [x] Tokenizer
|
|
||||||
- [x] Scanner
|
|
||||||
- [x] Functions
|
|
||||||
- [x] Variables
|
|
||||||
- [x] Error messages
|
|
||||||
- [x] Expression parser
|
|
||||||
- [x] Function calls
|
|
||||||
- [x] Parallel compilation
|
|
||||||
- [x] Syscalls
|
|
||||||
- [x] Variable lifetimes
|
|
||||||
- [x] Branches
|
|
||||||
- [x] Loops
|
|
||||||
- [x] Hexadecimal, octal and binary literals
|
|
||||||
- [x] Escape sequences
|
|
||||||
- [x] Multiple return values
|
|
||||||
- [ ] Type system
|
|
||||||
- [ ] Type operator `?`
|
|
||||||
- [ ] Data structures
|
|
||||||
- [ ] Slices
|
|
||||||
- [ ] Floating-point arithmetic
|
|
||||||
- [ ] Error handling
|
|
||||||
- [ ] Threading library
|
|
||||||
- [ ] Self-hosted compiler
|
|
||||||
|
|
||||||
### Keywords
|
|
||||||
|
|
||||||
- [x] `assert`
|
|
||||||
- [x] `else`
|
|
||||||
- [ ] `for`
|
|
||||||
- [x] `if`
|
|
||||||
- [x] `import`
|
|
||||||
- [x] `loop`
|
|
||||||
- [x] `return`
|
|
||||||
- [x] `switch`
|
|
||||||
|
|
||||||
### Optimizations
|
|
||||||
|
|
||||||
- [x] Exclude unused functions
|
|
||||||
- [x] Constant folding
|
|
||||||
- [ ] Constant propagation
|
|
||||||
- [ ] Function call inlining
|
|
||||||
- [ ] Loop unrolls
|
|
||||||
- [ ] Assembler optimization backend
|
|
||||||
|
|
||||||
### Linter
|
|
||||||
|
|
||||||
- [x] Unused variables
|
|
||||||
- [x] Unused parameters
|
|
||||||
- [x] Unused imports
|
|
||||||
- [ ] Unnecessary newlines
|
|
||||||
- [ ] Ineffective assignments
|
|
||||||
|
|
||||||
### Operators
|
|
||||||
|
|
||||||
- [x] `=`, `:=`
|
|
||||||
- [x] `+`, `-`, `*`, `/`, `%`
|
|
||||||
- [x] `+=`, `-=`, `*=`, `/=`, `%=`
|
|
||||||
- [x] `&`, `|`, `^`
|
|
||||||
- [x] `&=`, `|=`, `^=`
|
|
||||||
- [x] `<<`, `>>`
|
|
||||||
- [x] `<<=`, `>>=`
|
|
||||||
- [x] `==`, `!=`, `<`, `<=`, `>`, `>=`
|
|
||||||
- [x] `&&`, `||`
|
|
||||||
- [ ] `!`, `-`
|
|
||||||
|
|
||||||
### Architecture
|
|
||||||
|
|
||||||
- [ ] arm64
|
|
||||||
- [ ] riscv
|
|
||||||
- [x] x64
|
|
||||||
|
|
||||||
### Platform
|
|
||||||
|
|
||||||
- [x] Linux
|
|
||||||
- [x] Mac
|
|
||||||
- [ ] Windows
|
|
||||||
|
|
||||||
## Documentation
|
## Documentation
|
||||||
|
|
||||||
### [main.go](main.go)
|
### [main.go](/main.go)
|
||||||
|
|
||||||
Entry point. It simply calls `cli.Main` which we can use for testing.
|
Entry point. It simply calls `cli.Main` which we can use for testing.
|
||||||
|
|
||||||
### [src/cli/Main.go](src/cli/Main.go)
|
### [src/cli/Main.go](/src/cli/Main.go)
|
||||||
|
|
||||||
The command line interface expects a command like `build` as the first argument.
|
The command line interface expects a command like `build` as the first argument.
|
||||||
Commands are implemented as functions in the [src/cli](src/cli) directory.
|
Commands are implemented as functions in the [src/cli](src/cli) directory.
|
||||||
Each command has its own set of parameters.
|
Each command has its own set of parameters.
|
||||||
|
|
||||||
### [src/cli/Build.go](src/cli/Build.go)
|
### [src/cli/Build.go](/src/cli/Build.go)
|
||||||
|
|
||||||
The build command creates a new `Build` instance with the given directory and calls the `Run` method.
|
The build command creates a new `Build` instance with the given directory and calls the `Run` method.
|
||||||
|
|
||||||
@ -156,7 +37,7 @@ Adding the `-v` or `--verbose` flag shows verbose compiler information:
|
|||||||
q build examples/hello -v
|
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.
|
||||||
The name of the executable will be equal to the name of the build directory.
|
The name of the executable will be equal to the name of the build directory.
|
||||||
@ -176,24 +57,16 @@ 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.
|
||||||
|
|
||||||
### [src/core/Function.go](src/core/Function.go)
|
### [src/core/Function.go](/src/core/Function.go)
|
||||||
|
|
||||||
This is the "heart" of the compiler.
|
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`.
|
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.
|
You can think of AST nodes as the individual statements in your source code.
|
||||||
|
|
||||||
### [src/ast/Parse.go](src/ast/Parse.go)
|
### [src/ast/Parse.go](/src/ast/Parse.go)
|
||||||
|
|
||||||
This is what generates the AST from tokens.
|
This is what generates the AST from tokens.
|
||||||
|
|
||||||
### [src/expression/Parse.go](src/expression/Parse.go)
|
### [src/expression/Parse.go](/src/expression/Parse.go)
|
||||||
|
|
||||||
This is what generates expressions from tokens.
|
This is what generates expressions from tokens.
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
Please see the [license documentation](https://akyoto.dev/license).
|
|
||||||
|
|
||||||
## Copyright
|
|
||||||
|
|
||||||
© 2023 Eduard Urbach
|
|
11
tests/readme.md
Normal file
11
tests/readme.md
Normal file
@ -0,0 +1,11 @@
|
|||||||
|
## Tests
|
||||||
|
|
||||||
|
```shell
|
||||||
|
go test ./... -v -cover
|
||||||
|
```
|
||||||
|
|
||||||
|
## Benchmarks
|
||||||
|
|
||||||
|
```shell
|
||||||
|
go test ./tests -run='^$' -bench=. -benchmem
|
||||||
|
```
|
Loading…
Reference in New Issue
Block a user