-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
115 changed files
with
3,881 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
--- | ||
sidebar_position: 1 | ||
--- | ||
|
||
# Introduction for Jayvee Developers | ||
|
||
## How to contribute | ||
|
||
In order to contribute to the Jayvee project, please have a look at our [contribution guide](https://github.com/jvalue/jayvee/blob/main/CONTRIBUTING.md). Before planning a contribution, please read the [design principles](./05-design-principles.md) and consider if your changes fit the vision expressed there. | ||
|
||
The overall project is licensed under the `AGPL-3.0-only` license and is compliant to the [REUSE Specification](https://reuse.software/spec/) by the [Free Software Foundation Europe](https://fsfe.org/). | ||
Because of this, contributions are required to adhere to the license and follow that specification. | ||
More details on this topic can be found [here](./02-dev-processes/03-licensing-and-copyright.md). | ||
|
||
And last but not least, please read and follow our [code of conduct](https://github.com/jvalue/jayvee/blob/main/CODE_OF_CONDUCT.md). | ||
|
||
## Project overview | ||
|
||
The Jayvee repository is located [here](https://github.com/jvalue/jayvee) on GitHub. | ||
It uses an [Nx mono-repository](https://nx.dev/) setup and contains all related projects, most notably the Jayvee language server and interpreter. | ||
Please have a look at the [architecture overview](./03-architecture-overview.md) for more details. | ||
|
||
## Prerequisites | ||
|
||
Node.js and npm are required for development. | ||
It is recommended to use their LTS version to avoid any potential compatibility issues. | ||
Also, refer to this [quick start guide](https://github.com/jvalue/jayvee#development-quickstart) for developers. | ||
|
||
In order to run the Jayvee VS Code extension during development, VS Code is required as IDE. | ||
Using VS Code also allows installing the [Langium VS Code extension](https://marketplace.visualstudio.com/items?itemName=langium.langium-vscode) for better IDE support when working with Langium grammar files. | ||
|
||
## Resources for getting started | ||
|
||
### Langium | ||
|
||
- [**Langium documentation**](https://langium.org/docs/) | ||
- Practical examples using Langium: | ||
- [Langium examples](https://github.com/langium/langium/tree/main/examples): Official example languages by Langium | ||
- [Langium's grammar language](https://github.com/langium/langium/tree/main/packages/langium): The implementation of Langium's own grammar language | ||
- [Language server for SQL](https://github.com/langium/langium-sql): An implementation of a language server for SQL | ||
- [MiniLogo DSL](https://github.com/langium/langium-minilogo): A domain-specific language for drawing pictures | ||
- [Lox language](https://github.com/langium/langium-lox): An implementation of the Lox scripting language (also see the "Crafting Interpreters" book below) | ||
- [SimpleUI DSL](https://github.com/TypeFox/langium-ui-framework): A domain-specific language for generating user interfaces | ||
- [STPA-DSL](https://github.com/kieler/stpa): A domain-specific language for System-Theoretic Process Analysis | ||
- [Langium playground](https://langium.org/playground/): A tool for testing Langium grammars and visualizing resulting ASTs | ||
- [Typefox blog](https://www.typefox.io/blog/): A blog by the company behind Langium, mostly posting Langium-related content. | ||
|
||
### Building compilers / interpreters / DSLs | ||
|
||
- [Crafting Interpreters](https://craftinginterpreters.com/contents.html): A book by Robert Nystrom on implementing an interpreter for the Lox scripting language | ||
- [DSL Engineering](https://voelter.de/dslbook/markusvoelter-dslengineering-1.0.pdf): A book by Markus Voelter on designing, implementing and using domain-specific languages | ||
- [Awesome Compilers](https://github.com/aalhour/awesome-compilers#readme): A list featuring many resources on compilers and interpreters |
3 changes: 3 additions & 0 deletions
3
apps/docs/versioned_docs/version-0.3.0/dev/01-intro.md.license
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
|
||
SPDX-License-Identifier: AGPL-3.0-only |
13 changes: 13 additions & 0 deletions
13
apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/01-rfc-process.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
--- | ||
title: Language Design Process (RFCs) | ||
sidebar_position: 1 | ||
--- | ||
|
||
We use RFCs to discuss changes to the language before implementing them. You can have a look at all closed (accepted / rejected) RFCs [here](https://github.com/jvalue/jayvee/pulls?q=is%3Apr+is%3Aclosed+RFC+), and all RFCs under discussion [here](https://github.com/jvalue/jayvee/pulls?q=is%3Apr+is%3Aopen+RFC). | ||
|
||
If you want to contribute an RFC please follow these steps: | ||
1. Make a copy of the **template** at `rfc/0000-rfc-template.md` and place it into the `rfc` folder. | ||
2. Create a draft for the RFC on a new branch. Follow the `TODOs` in template to do so. | ||
3. Open a pull request with prefix `RFC <number>` in the title. | ||
4. Address the reviews. Consider opening a new PR if major things need to be addressed and the discussion log becomes too confusing. | ||
5. Once accepted, create an issue with the necessary steps to implement the RFC. |
3 changes: 3 additions & 0 deletions
3
apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/01-rfc-process.md.license
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
|
||
SPDX-License-Identifier: AGPL-3.0-only |
25 changes: 25 additions & 0 deletions
25
...versioned_docs/version-0.3.0/dev/02-dev-processes/02-debug-vs-code-extension.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
--- | ||
title: Debugging via the VS Code extension | ||
sidebar_position: 2 | ||
--- | ||
|
||
The VS Code extension of Jayvee can be used to interactively debug the language server. | ||
During development, when using VS Code as IDE, another instance of VS Code can be opened which has the most recent, locally built VS Code extension loaded. | ||
This can be achieved using the launch configuration `Run extension` the `Run and Debug` side-menu of VS Code or by pressing the `F5` key if that launch configuration is already selected there. | ||
|
||
Note that there is no file watching mechanism involved. | ||
So in order to reflect changes to the source code, the additional VS Code instance has to be **closed and reopened** as described above. | ||
|
||
## How to attach a debugger | ||
|
||
1. Use the launch configuration `Run extension` to open the additional VS Code instance with the extension loaded | ||
2. Use the launch configuration `Attach to Language Server` to attach the debugger | ||
|
||
Any set breakpoints should now be marked as active and pause the execution once they are reached. | ||
|
||
## How to view logs of the language server | ||
|
||
In the additional VS Code instance, it is possible to view the logs of the language server. | ||
They might also be helpful for debugging since any uncaught errors are logged with their stack trace by the Langium framework. | ||
|
||
To view the logs, open the bottom panel called `Output` and select `Jayvee` in the dropdown menu. |
3 changes: 3 additions & 0 deletions
3
...s/versioned_docs/version-0.3.0/dev/02-dev-processes/02-debug-vs-code-extension.md.license
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
|
||
SPDX-License-Identifier: AGPL-3.0-only |
69 changes: 69 additions & 0 deletions
69
...versioned_docs/version-0.3.0/dev/02-dev-processes/03-licensing-and-copyright.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,69 @@ | ||
--- | ||
title: Licensing and copyright | ||
sidebar_position: 3 | ||
--- | ||
|
||
The [Jayvee repository](https://github.com/jvalue/jayvee) is REUSE compliant, meaning that it fulfills the | ||
[REUSE Specification](https://reuse.software/spec/) by the [Free Software Foundation Europe](https://fsfe.org/) (FSFE). | ||
This makes clear under which license each project file is licensed under and who owns the copyright, not only for | ||
humans but also for machines. | ||
|
||
This is done by explicitly adding copyright and licensing information to each file of the project. This is achieved | ||
by either using a comment header or a separate `*.license` file in case comments are not possible. | ||
|
||
See <https://reuse.software/> more information. | ||
|
||
## What license is used in this project and who is the copyright holder? | ||
|
||
The entire project is licensed under [AGPL-3.0-only](https://spdx.org/licenses/AGPL-3.0-only.html), the | ||
license file can be found [here](https://github.com/jvalue/jayvee/blob/main/LICENSES/AGPL-3.0-only.txt). | ||
The copyright holder is the [Friedrich-Alexander-Universität Erlangen-Nürnberg](https://www.fau.eu/). | ||
|
||
## How to submit a REUSE compliant contribution? | ||
|
||
In case you want to contribute to the project, you will need to ensure that all of your contributed files are REUSE | ||
compliant. In order to achieve this, you need to add a key-value pair for both copyright and licensing information | ||
following this schema: | ||
|
||
``` | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
SPDX-License-Identifier: AGPL-3.0-only | ||
``` | ||
|
||
In case a file allows comments, use single-line comments to add the copyright and licensing information at the top | ||
of the file. Otherwise, create a corresponding `*.license` file with the text above as its content. You can have a | ||
look at some existing project files to get an impression on it is done in practice. | ||
|
||
For files with common file extensions, you can use the [reuse CLI tool](https://github.com/fsfe/reuse-tool) to add | ||
licensing and copyright information automatically. | ||
|
||
For more details, you can have a look at the [Getting Started tutorial](https://reuse.software/tutorial/) on the REUSE | ||
website. | ||
|
||
## How to validate REUSE compliance? | ||
|
||
When you make a contribution and open a new pull request, the CI checks whether your contribution is REUSE compliant | ||
using the [reuse CLI tool](https://github.com/fsfe/reuse-tool). | ||
|
||
In order to validate REUSE compliance in your local development environment, you have to install the | ||
[reuse CLI tool](https://github.com/fsfe/reuse-tool) and run the following command in the projects' root folder: | ||
|
||
```bash | ||
reuse lint | ||
``` | ||
|
||
You can also set up a pre-commit hook, so the above command is run before each commit. | ||
See [here](https://reuse.readthedocs.io/en/latest/readme.html#run-as-pre-commit-hook) for details on how to set it up. | ||
|
||
## How to hide `*.license` files in IDEs | ||
|
||
During development, the file explorer of your IDE may be cluttered due to the numerous `*.license` files in the | ||
project. Luckily, most IDEs allow hiding certain files, e.g. by specifying a pattern to exclude them from the | ||
explorer. | ||
|
||
Below, you can find instructions on how to hide `*.license` files in commonly used IDEs: | ||
- **Visual Studio Code**: Add `**/*.license` to the | ||
[`files.exclude` setting](https://code.visualstudio.com/docs/getstarted/userinterface#_explorer) | ||
- **WebStorm**: Add `*.license` to the | ||
[excluded files setting](https://www.jetbrains.com/help/webstorm/configuring-project-structure.html#exclude-by-pattern) |
3 changes: 3 additions & 0 deletions
3
...s/versioned_docs/version-0.3.0/dev/02-dev-processes/03-licensing-and-copyright.md.license
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
|
||
SPDX-License-Identifier: AGPL-3.0-only |
22 changes: 22 additions & 0 deletions
22
.../versioned_docs/version-0.3.0/dev/02-dev-processes/04-release-jayvee-version.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
--- | ||
title: Releasing a new Jayvee version | ||
sidebar_position: 4 | ||
--- | ||
|
||
## Version Numbers | ||
|
||
In this early stage of the project we do not yet follow [semantic versioning](https://semver.org/) since we expect the introduction of breaking changes frequently. | ||
To indicate that, we only release alpha versions where the `version` is incremented with every release. | ||
- For the npm packages, we use the version `0.0.<version>`. | ||
- For the GitHub releases, we use the git tag `v0.0.<version>-alpha`. | ||
|
||
## Jayvee Release Procedure | ||
|
||
For releasing a new version of Jayvee, you need to complete the following steps: | ||
|
||
1. Increment the version in the `package.json` file. | ||
2. Run `npm i` to update the `package-lock.json`. | ||
3. Run `npx nx run docs:version-snapshot` to generate a snapshot of the docs for the previous version. | ||
4. If you are on a feature or dev branch, merge into main. | ||
5. Create a GitHub release on the main branch. Attach a changelog. | ||
6. The CI/CD will deal with the rest. |
3 changes: 3 additions & 0 deletions
3
...cs/versioned_docs/version-0.3.0/dev/02-dev-processes/04-release-jayvee-version.md.license
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
|
||
SPDX-License-Identifier: AGPL-3.0-only |
8 changes: 8 additions & 0 deletions
8
apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/_category_.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
{ | ||
"label": "Development Process", | ||
"position": 2, | ||
"link": { | ||
"type": "generated-index", | ||
"description": "Here you can find general processes around developing Jayvee." | ||
} | ||
} |
3 changes: 3 additions & 0 deletions
3
apps/docs/versioned_docs/version-0.3.0/dev/02-dev-processes/_category_.json.license
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
|
||
SPDX-License-Identifier: AGPL-3.0-only |
43 changes: 43 additions & 0 deletions
43
apps/docs/versioned_docs/version-0.3.0/dev/03-architecture-overview.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
--- | ||
title: Architecture overview | ||
sidebar_position: 4 | ||
--- | ||
|
||
Jayvee has a clear separation between the language itself and its execution. | ||
This guide gives an overview of the overall architecture. | ||
|
||
## Language Server | ||
|
||
On the pure language side, the central project is the [language server](https://github.com/jvalue/jayvee/tree/main/libs/language-server) which is heavily built upon the [Langium framework](https://langium.org/). | ||
It contains the syntax definition (i.e. the grammar) and is capable of performing static semantic analysis on models, so invalid models can be rejected and errors are reported to the user. | ||
It uses the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) for communicating with IDEs in order to provide common features such as diagnostics, auto completion and much more. | ||
|
||
## Interpreter | ||
|
||
The Jayvee [interpreter](https://github.com/jvalue/jayvee/tree/main/apps/interpreter) on the other hand is capable of running Jayvee models. | ||
Therefore, it uses the language server as a library to perform lexing, parsing and semantic analysis on given models. | ||
In case no errors were found during these phases, it executes the model by interpreting it. | ||
This means that models are not compiled to any other language, like a compiler does, but rather directly executed on the fly without any code generation involved. | ||
The interpreter comes with a command-line interface (CLI) for users, so they are able to execute Jayvee models easily. | ||
|
||
The following diagram visualizes the architecture described so far: | ||
|
||
```mermaid | ||
graph LR | ||
model[Jayvee Model] --> lexical(Lexical Analysis) | ||
subgraph Jayvee Interpreter | ||
subgraph Jayvee Language Server | ||
subgraph Langium Framework | ||
lexical --> syntax(Syntax Analysis) | ||
end | ||
syntax --> semantic(Semantic Analysis) | ||
end | ||
semantic --> interpretation(Interpretation) | ||
end | ||
``` | ||
|
||
## Jayvee Extensions | ||
|
||
Lastly, there are Jayvee extensions for adding additional features to Jayvee. | ||
See [here](./04-guides/06-jayvee-extensions.md) for more details. | ||
It is worth pointing out that extensions also follow the separation between language and execution described above. |
3 changes: 3 additions & 0 deletions
3
apps/docs/versioned_docs/version-0.3.0/dev/03-architecture-overview.md.license
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
|
||
SPDX-License-Identifier: AGPL-3.0-only |
34 changes: 34 additions & 0 deletions
34
apps/docs/versioned_docs/version-0.3.0/dev/04-guides/01-jayvee-grammar.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
--- | ||
title: The Jayvee grammar | ||
sidebar_position: 1 | ||
--- | ||
|
||
The grammar of Jayvee describes the syntax and structure of the language. | ||
It is located in the language server project. | ||
The grammar itself is written in [Langium's own grammar language](https://langium.org/docs/grammar-language/) which is similar to [Xtext](https://www.eclipse.org/Xtext/) grammars. | ||
Such grammar files are easily identifiable via their `.langium` file extension. | ||
|
||
The grammar is used to generate TypeScript interfaces that represent the Abstract Syntax Tree (AST) and different, semantically equivalent files to define syntax highlighting for different applications. | ||
For instance, a [TextMate](https://macromates.com/manual/en/language_grammars) file is generated for the syntax highlighting in the Jayvee VS Code extension whereas a [Monarch](https://microsoft.github.io/monaco-editor/monarch.html) file is generated for the syntax highlighting in the Monaco editor. | ||
|
||
For further information on the grammar language of Langium, visit the corresponding [Langium documentation](https://langium.org/docs/grammar-language/). | ||
|
||
## Working with the grammar | ||
|
||
To run the code generation, either use `npm run generate` for solely the code generation or `npm run build` for an entire build. The code generation also generates further code, like the standard library. | ||
|
||
Whenever the grammar is changed and the code generation is run during development, it is advisory to **close and reopen the IDE**, so the changes are noticed and the file indexing is updated. | ||
|
||
## How to rename AST nodes | ||
|
||
Renaming AST nodes is not as straight forward as one might initially assume. | ||
When renaming individual rules in the grammar, just the generated TypeScript code in `ast.ts` will reflect the renaming, but not the rest of the codebase. | ||
|
||
The following steps explain how to rename an AST node, so the change is reflected in the entire codebase. As an example, an AST node called `A` is supposed to be renamed to `B`: | ||
|
||
- Open the `ast.ts` file in the language server project | ||
- Locate the `A` interface / type and the `isA` typeguard | ||
- Use the rename feature by the IDE to perform the renaming from `A` to `B` and from `isA` to `isB` | ||
- Open the grammar and locate the `A` rule | ||
- Use the rename feature by the Langium VS Code extension to perform the renaming from `A` to `B` | ||
- Run `npm run generate` |
3 changes: 3 additions & 0 deletions
3
apps/docs/versioned_docs/version-0.3.0/dev/04-guides/01-jayvee-grammar.md.license
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg | ||
|
||
SPDX-License-Identifier: AGPL-3.0-only |
Oops, something went wrong.