gemstone/README.md

164 lines
5.7 KiB
Markdown
Raw Normal View History

2024-02-04 15:23:32 +00:00
<div align="center">
2024-06-05 19:25:31 +00:00
<img alt="gemstone logo" src="https://github.com/Servostar/gemstone/assets/72654954/fdb37c1b-81ca-4e6a-a9e9-c46effb12dae" width="75%">
<br>
<p>
Open source programming language compiler based on LLVM, GLib and GNU Bison/Flex
<br>
capable of multi target cross compilation powered by simple build system.
</p>
<br>
<img src="https://img.shields.io/github/actions/workflow/status/Servostar/gemstone/build-check-sdk.yaml?label=Linux"/>
<img src="https://img.shields.io/github/actions/workflow/status/Servostar/gemstone/msys2-cross-compile.yml?label=Windows"/>
<img src="https://img.shields.io/github/license/Servostar/gemstone"/>
<img src="https://img.shields.io/github/languages/count/Servostar/gemstone"/>
<img src="https://img.shields.io/github/languages/top/Servostar/gemstone"/>
2024-07-19 19:59:59 +00:00
<br>
<img src="https://img.shields.io/badge/c-%2300599C.svg?style=flat&logo=c&logoColor=white"/>
<img src="https://img.shields.io/badge/CMake-%23008FBA.svg?&logo=cmake&color=064F8C&logoColor=white"/>
<img src="https://img.shields.io/badge/LLVM-%20?style=flat&color=262D3A&logo=llvm&logoColor=white"/>
2024-06-05 19:25:31 +00:00
</div>
## About
2024-06-05 19:25:31 +00:00
Gemstone is a programming language compiler (short: GSC) written in C based on flex and GNU bison.
2024-06-06 20:39:04 +00:00
It uses LLVM to produce optimized native binaries for many platforms and uses its own builtin build system for more complex project management.
2024-02-04 15:23:32 +00:00
2024-07-19 05:20:27 +00:00
## Architecture
Gemstone is a LALR enabled non-reentrant compiler utilizing a linear flow of components. The compiler has multiple stages of operation, each representing a crucial step in compilation.
```mermaid
---
title: GSC Architecture Overview
---
flowchart LR
lex["`**Lexical Analysis**
tokenization via flex`"]
bison["`**Syntax Analysis**
parsing via bison`"]
set["`**Semantic Analysis**
parse tree generation`"]
llvm["`**Codegen**
code generation via LLVM`"]
driver["`**Linking**
Linkage via Clang/GCC`"]
start(("Start")) --> lex
subgraph compile AST
lex --> bison
end
subgraph Validation
bison --> import{"Import/Include?"}
import --> |yes| ast[[compile AST]] --> merge["Merge AST"] --> import
import --> |no| set
set --> llvm
end
stop(("End"))
subgraph Codegen
llvm --> lib{"Produce Library?"}
lib -->|no| driver --> executable(["Executable"])
lib -->|yes| library(["Library"])
end
library --> stop
executable --> stop
```
2024-04-24 21:58:15 +00:00
## Dependencies (build)
### Windows 11
#### MSYS2
2024-04-24 21:58:15 +00:00
Install MSYS2 under Windows 11. Open the MingGW64 environment.
Install the following packages:
```
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-glib2 bison flex mingw-w64-x86_64-llvm cmake git make
```
Clone the repository and build the gemstone compiler:
```
cmake . && make release
```
2024-04-24 21:58:15 +00:00
### GNU/Linux
Requires:
- GCC
- CMake
- Make
- bison
- flex
- LLVM
- Glib 2.0
2024-04-24 21:58:15 +00:00
## Writing Tests
Since the project is build and configured through CMake it makes sense to rely for tests
on CTest. All tests are located in the subfolder `tests`. In this directory is a CMakeLists.txt which specifies which tests
are to be run. Actual tests are located in folders within tests and contain a final CMakeLists.txt which specifies what to run
for a single test.
```
tests
└─ test_group1
└─ CMakeLists.txt # specify tests in this group
└─ ... # test files of group 1
└─ test_group2
└─ CMakeLists.txt # specify tests in this group
└─ ... # test files of group 2
└─ CMakeLists.txt # specify test groups to run
CMakeLists.txt # build configuration
```
## Development with VSCode/Codium
Recommended extensions for getting a decent experience are the following:
- https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd
- https://marketplace.visualstudio.com/items?itemName=daohong-emilio.yash
- https://marketplace.visualstudio.com/items?itemName=cschlosser.doxdocgen
- https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
- https://marketplace.visualstudio.com/items?itemName=twxs.cmake
In order to remove false error messages from clangd CMake has to be run once in order generate compile_commands.json.
2024-02-04 15:23:32 +00:00
## Build
The build pipeline is configured with CMake in the file CMakeLists.txt.
In order to avoid dependency and configuration issues the recommended way to build is by using the provided docker containers.
All tools required for building (`cmake`, `make`, `gcc`, `lex`, `yacc`) are installed inside the SDK container (see Dockerfile sdk/Dockerfile).
For creating the build pipeline build the Dockerfile in the root folder of this repository. This takes the current SDK and copies the source files into the home of the build user.
Then the make targets are generated. Running `make release` will build gemstone from source in release mode.
The generated binaries can be found either in `bin/release/gsc` or `bin/debug/gsc` depending on the chosen target.
The following graph visualizes the build pipeline:
2024-07-19 20:07:35 +00:00
```mermaid
flowchart LR
subgraph Docker
alpine[Alpine Linux] --> sdk[SDK] --> dev[Devkit]
end
subgraph Build
dev --> |generate parser| bison[Bison]
dev --> |generate lexer| flex[Flex]
bison --> cc[GCC/Clang/MSVC]
flex --> cc
cc --> debug
cc --> release
cc --> check
end
2024-02-04 15:23:32 +00:00
```
## Docker images
Currently, the SDK is based on Almalinux 9.3, an open source distro binary compatible to RHEL 9.3.
2024-02-04 15:27:53 +00:00
The following images can be found in the offical repository at [Docker Hub](https://hub.docker.com/r/servostar/gemstone):
2024-02-04 15:23:32 +00:00
- SDK
2024-04-24 21:58:15 +00:00
- Devkit