diff --git a/packages/generator-langium/src/index.ts b/packages/generator-langium/src/index.ts index 6e21d1a82..2a882699a 100644 --- a/packages/generator-langium/src/index.ts +++ b/packages/generator-langium/src/index.ts @@ -184,6 +184,7 @@ export class LangiumGenerator extends Generator { '.eslintrc.json', 'tsconfig.json', 'tsconfig.build.json', + 'README.md', '.vscode' ]; for (const path of baseFiles) { @@ -200,7 +201,7 @@ export class LangiumGenerator extends Generator { const languageFiles = [ 'package.json', 'langium-config.json', - 'langium-quickstart.md', + 'README.md', 'tsconfig.json', 'tsconfig.src.json', 'vitest.config.ts', @@ -241,6 +242,7 @@ export class LangiumGenerator extends Generator { const cliFiles = [ 'package.json', 'tsconfig.json', + 'README.md', 'bin', 'src' ]; @@ -260,6 +262,7 @@ export class LangiumGenerator extends Generator { const webFiles = [ 'package.json', 'language-configuration.json', + 'README.md', 'tsconfig.json', 'index.html', 'vite.config.ts', @@ -282,6 +285,7 @@ export class LangiumGenerator extends Generator { const extensionFiles = [ '.vscodeignore', 'esbuild.mjs', + 'langium-quickstart.md', 'language-configuration.json', 'package.json', 'tsconfig.json', diff --git a/packages/generator-langium/templates/README.md b/packages/generator-langium/templates/README.md new file mode 100644 index 000000000..df087c223 --- /dev/null +++ b/packages/generator-langium/templates/README.md @@ -0,0 +1,16 @@ +# Workspace overview + +Depending on the selection during the project generation you will have one or more packages contained in the packages directory. Check the : + +- [packages/language](./packages/language/README.md) is always available and contains the language definition. +- [packages/cli](./packages/cli/README.md) *Optional* Is only available if you chose to use the command-line interface. +- [packages/extension](./packages/extension/langium-quickstart.md) *Optional* Contains the VSCode extension if you chose to create it. +- [packages/web](./packages/web/README.md) *Optional* if selected contains the language server running in a web browser and a monaco-editor with language support similar to the onm from VSCode. + +## What's in the folder? + +- [.eslintrc.json](.eslintrc.json) - Configuration file for eslint +- [.gitignore](.gitignore) - Files ignored by git +- [package.json](./package.json) - The manifest file the main workspace package +- [tsconfig.json](./tsconfig.json) - The base TypeScript compiler configuration +- [tsconfig.build.json](./package.json) - Configuration used to build the complete source code. diff --git a/packages/generator-langium/templates/package.json b/packages/generator-langium/templates/package.json index 3e85776f3..93bc7742b 100644 --- a/packages/generator-langium/templates/package.json +++ b/packages/generator-langium/templates/package.json @@ -5,8 +5,10 @@ "type": "module", "private": true, "scripts": { + "clean": "npm run clean --workspaces", "watch": "tsc -b tsconfig.build.json --watch", "build": "tsc -b tsconfig.build.json && npm run build --workspaces", + "build:clean": "npm run clean && npm run build", "lint": "eslint src --ext ts", "langium:generate": "npm run --workspace packages/language langium:generate", "langium:watch": "npm run --workspace packages/language langium:watch" @@ -16,6 +18,7 @@ "@typescript-eslint/parser": "~7.13.0", "@typescript-eslint/eslint-plugin": "~7.13.0", "eslint": "~8.57.0", + "shx": "~0.3.4", "typescript": "~5.4.5" }, "volta": { diff --git a/packages/generator-langium/templates/packages/cli/README.md b/packages/generator-langium/templates/packages/cli/README.md new file mode 100644 index 000000000..1bf4b8a6c --- /dev/null +++ b/packages/generator-langium/templates/packages/cli/README.md @@ -0,0 +1,19 @@ +# Command-line interface (CLI) + +Check [this part](https://langium.org/docs/learn/minilogo/customizing_cli/) of the Langium Minilogo Tutorial as a useful guide to the CLI. + +## What's in the folder? + +- [package.json](./package.json) - The manifest file of your cli package. +- [tsconfig.src.json](./tsconfig.src.json) - The package specific TypeScript compiler configuration extending the [base config](../../tsconfig.json) +- [tsconfig.json](./tsconfig.json) - TypeScript compiler configuration options required for proper functionality of VSCode. +- [src/cli/main.ts](src/cli/main.ts) - the entry point of the command line interface (CLI) of your language. +- [src/cli/generator.ts](src/cli/generator.ts) - the code generator used by the CLI to write output files from DSL documents. +- [src/cli/util.ts](src/cli/util.ts) - utility code for the CLI. + +If you selected the test option as well, then you have the following for file as well: + +- [tsconfig.test.json](./tsconfig.test.json) - The package specific TypeScript compiler configuration for the unit tests extending the [tsconfig.src.config](tsconfig.src.json) +- [test/linking.test.ts](test/linking.test.ts) - Unit tests checking linking. +- [test/parsing.test.ts](test/parsing.test.ts) - Unit tests regarding parsing. +- [test/validating.test.ts](test/validating.test.ts) - Unit tests regarding validation. diff --git a/packages/generator-langium/templates/packages/cli/package.json b/packages/generator-langium/templates/packages/cli/package.json index a9118e18c..46dad2d5a 100644 --- a/packages/generator-langium/templates/packages/cli/package.json +++ b/packages/generator-langium/templates/packages/cli/package.json @@ -15,7 +15,9 @@ "<%= language-id %>-cli": "./bin/cli.js" }, "scripts": { - "build": "echo 'No build step'" + "clean": "shx rm -fr *.tsbuildinfo out", + "build": "echo 'No build step'", + "build:clean": "npm run clean && npm run build" }, "dependencies": { "<%= extension-name %>-language": "0.0.1", diff --git a/packages/generator-langium/templates/packages/extension/langium-quickstart.md b/packages/generator-langium/templates/packages/extension/langium-quickstart.md new file mode 100644 index 000000000..5a1ba5105 --- /dev/null +++ b/packages/generator-langium/templates/packages/extension/langium-quickstart.md @@ -0,0 +1,37 @@ +# Langium VS Code Extension + +Welcome to your Langium VSCode extension. This folder contains all necessary files for your language extension. + +## What's in the folder? + +- [package.json](./package.json) - the manifest file in which you declare your language support. +- [tsconfig.json](./tsconfig.json) - The packages specific TypeScript compiler configuration extending the [base config](../../tsconfig.json) +- [esbuid.mjs](esbuild.mjs) - Configuration file for esbuild that is used to create the VSCode extension bundle. +- [language-configuration.json](language-configuration.json) - the language configuration used in the VS Code editor, defining the tokens that are used for comments and brackets. +- [src/language/main.ts](src/language/main.ts) - the entry point of the language server process. +- [src/extension/main.ts](src/extension/main.ts) - the main code of the extension, which is responsible for launching a language server and client. + +## Get up and running straight away + +- Run `npm run langium:generate` to generate TypeScript code from the grammar definition. +- Run `npm run build` to compile all TypeScript code. +- Press `F5` to open a new window with your extension loaded. +- Create a new file with a file name suffix matching your language. +- Verify that syntax highlighting, validation, completion etc. are working as expected. +- Run `node ./bin/cli` to see options for the CLI; `node ./bin/cli generate ` generates code for a given DSL file. + +## Make changes + +- Run `npm run watch` to have the TypeScript compiler run automatically after every change of the source files. +- Run `npm run langium:watch` to have the Langium generator run automatically after every change of the grammar declaration. +- You can relaunch the extension from the debug toolbar after making changes to the files listed above. +- You can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes. + +## Install your extension + +- To start using your extension with VS Code, copy it into the `/.vscode/extensions` folder and restart Code. +- To share your extension with the world, read the [VS Code documentation](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) about publishing an extension. + +## To Go Further + +Documentation about the Langium framework is available at diff --git a/packages/generator-langium/templates/packages/extension/package.json b/packages/generator-langium/templates/packages/extension/package.json index ca53291d7..011328af8 100644 --- a/packages/generator-langium/templates/packages/extension/package.json +++ b/packages/generator-langium/templates/packages/extension/package.json @@ -27,8 +27,10 @@ ], "main": "./out/extension/main.cjs", "scripts": { + "clean": "shx rm -fr *.tsbuildinfo out", "vscode:prepublish": "npm run build && npm run lint", "build": "tsc -b tsconfig.json && node esbuild.mjs", + "build:clean": "npm run clean && npm run build", "watch": "concurrently -n tsc,esbuild -c blue,yellow \"tsc -b tsconfig.json --watch\" \"node esbuild.mjs --watch\"" }, "dependencies": { diff --git a/packages/generator-langium/templates/packages/language/.vscode-extensions.json b/packages/generator-langium/templates/packages/language/.vscode-extensions.json deleted file mode 100644 index 7f73a0a33..000000000 --- a/packages/generator-langium/templates/packages/language/.vscode-extensions.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations. - // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp - - // List of extensions which should be recommended for users of this workspace. - "recommendations": [ - "langium.langium-vscode", - "vitest.explorer" - ] -} diff --git a/packages/generator-langium/templates/packages/language/README.md b/packages/generator-langium/templates/packages/language/README.md new file mode 100644 index 000000000..57396c287 --- /dev/null +++ b/packages/generator-langium/templates/packages/language/README.md @@ -0,0 +1,17 @@ +# The mandatory language package + +As a good entry point to our documentation, please use to this [guide](https://langium.org/docs/learn/workflow/write_grammar/). + +## What's in the folder? + +- [package.json](./package.json) - The manifest file of your language package. +- [tsconfig.json](./tsconfig.json) - The packages specific TypeScript compiler configuration extending the [base config](../../tsconfig.json) +- [src/<%= language-id %>.langium](src/<%= language-id %>.langium) - the grammar definition of your language +- [src/<%= language-id %>-module.ts](src/<%= language-id %>-module.ts) - the dependency injection module of your language implementation. Use this to register overridden and added services. +- [src/<%= language-id %>-validator.ts](src/<%= language-id %>-validator.ts) - an example validator. You should change it to reflect the semantics of your language +- [src/generated/ast.ts](src/generated/ast.ts) - Generated AST +- [src/generated/grammar.ts](src/generated/grammar.ts) - Generated Grammar +- [src/generated/module.ts](src/generated/module.ts) - Generated Module +- [src/syntaxes/<%= language-id %>.monarch.ts](src/syntaxes/<%= language-id %>.monarch.ts) - Monarch based syntax highlighting instructions +- [syntaxes/<%= language-id %>.tmLanguage.json](syntaxes/<%= language-id %>.tmLanguage.json) - Textmate based syntax highlighting instructions +- [src/index.ts](src/index.ts) Defines what is exported to other packages. diff --git a/packages/generator-langium/templates/packages/language/langium-quickstart.md b/packages/generator-langium/templates/packages/language/langium-quickstart.md deleted file mode 100644 index 746d3ceb8..000000000 --- a/packages/generator-langium/templates/packages/language/langium-quickstart.md +++ /dev/null @@ -1,41 +0,0 @@ -# Welcome to your Langium VS Code Extension - -## What's in the folder - -This folder contains all necessary files for your language extension. - -* `package.json` - the manifest file in which you declare your language support. -* `language-configuration.json` - the language configuration used in the VS Code editor, defining the tokens that are used for comments and brackets. -* `src/extension/main.ts` - the main code of the extension, which is responsible for launching a language server and client. -* `src/language/<%= language-id %>.langium` - the grammar definition of your language. -* `src/language/main.ts` - the entry point of the language server process. -* `src/language/<%= language-id %>-module.ts` - the dependency injection module of your language implementation. Use this to register overridden and added services. -* `src/language/<%= language-id %>-validator.ts` - an example validator. You should change it to reflect the semantics of your language. -* `src/cli/main.ts` - the entry point of the command line interface (CLI) of your language. -* `src/cli/generator.ts` - the code generator used by the CLI to write output files from DSL documents. -* `src/cli/util.ts` - utility code for the CLI. - -## Get up and running straight away - -* Run `npm run langium:generate` to generate TypeScript code from the grammar definition. -* Run `npm run build` to compile all TypeScript code. -* Press `F5` to open a new window with your extension loaded. -* Create a new file with a file name suffix matching your language. -* Verify that syntax highlighting, validation, completion etc. are working as expected. -* Run `node ./bin/cli` to see options for the CLI; `node ./bin/cli generate ` generates code for a given DSL file. - -## Make changes - -* Run `npm run watch` to have the TypeScript compiler run automatically after every change of the source files. -* Run `npm run langium:watch` to have the Langium generator run automatically after every change of the grammar declaration. -* You can relaunch the extension from the debug toolbar after making changes to the files listed above. -* You can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes. - -## Install your extension - -* To start using your extension with VS Code, copy it into the `/.vscode/extensions` folder and restart Code. -* To share your extension with the world, read the [VS Code documentation](https://code.visualstudio.com/api/working-with-extensions/publishing-extension) about publishing an extension. - -## To Go Further - -Documentation about the Langium framework is available at https://langium.org diff --git a/packages/generator-langium/templates/packages/language/package.json b/packages/generator-langium/templates/packages/language/package.json index fb672a899..b34aaaff7 100644 --- a/packages/generator-langium/templates/packages/language/package.json +++ b/packages/generator-langium/templates/packages/language/package.json @@ -26,12 +26,14 @@ } }, "scripts": { + "clean": "shx rm -fr *.tsbuildinfo out", "build": "echo 'No build step'", + "build:clean": "npm run clean && npm run build", "langium:generate": "langium generate", "langium:watch": "langium generate --watch" }, "dependencies": { - "langium": "~3.0.0" + "langium": "~3.0.0" }, "devDependencies": { "langium-cli": "~3.0.3" diff --git a/packages/generator-langium/templates/packages/web/README.md b/packages/generator-langium/templates/packages/web/README.md new file mode 100644 index 000000000..d5d325140 --- /dev/null +++ b/packages/generator-langium/templates/packages/web/README.md @@ -0,0 +1,35 @@ +# Web-based editor and language server + +How the web based editor works is well defined [here](https://langium.org/docs/learn/minilogo/langium_and_monaco). + +## What's in the folder? + +- [index.html](index.html) - Entry page that let's you decide which web editor version is used. +- [language-configuration.json](language-configuration.json) - the language configuration used in the web editor, defining the tokens that are used for comments and brackets. +- [package.json](./package.json) - The manifest file of your web editor package. +- [src/main-browser.ts](src/main-browser.ts) - The the language server running in a web worker. +- [src/setupClassic.ts](src/setupClassic.ts) - Create monaco-editor with classic configuration (monarch sytax highlighting) +- [src/setupCommon.ts](src/setupCommon.ts) - Common settings for monaco-editor +- [src/setupExtended.ts](src/setupExtended.ts) - Create monaco-editor with extended configuration (textmate sytax highlighting) +- [static/monacoClassic.html](static/monacoClassic.html) - Page for classic monaco-editor +- [static/monacoExtended.html](static/monacoExtended.html) - Page for extended monaco-editor +- [static/styles.css](static/styles.css) - Stylesheets used by the HTML pages +- [tsconfig.json](./tsconfig.json) - The packages specific TypeScript compiler configuration extending the [base config](../../tsconfig.json) +- [vite.config.ts](vite.config.ts) - Vite/rollup production build instructions + +## Run the web application + +The generation post-step ensure that the whole project is built. +You can run chose to run the application either in development mode (code changes are directly available in the application) or production mode (bundled). + +For development: + +```shell +npm run dev +``` + +For production: + +```shell +npm run serve +``` diff --git a/packages/generator-langium/templates/packages/web/package.json b/packages/generator-langium/templates/packages/web/package.json index 1986a7862..849b414b9 100644 --- a/packages/generator-langium/templates/packages/web/package.json +++ b/packages/generator-langium/templates/packages/web/package.json @@ -11,7 +11,9 @@ "src" ], "scripts": { + "clean": "shx rm -fr *.tsbuildinfo out dist", "build": "vite build", + "build:clean": "npm run clean && npm run build", "dev": "vite", "dev:debug": "vite --debug --force", "serve": "vite preview" diff --git a/packages/generator-langium/test/yeoman-generator.test.ts b/packages/generator-langium/test/yeoman-generator.test.ts index 6cf1c54fe..bae0ffe30 100644 --- a/packages/generator-langium/test/yeoman-generator.test.ts +++ b/packages/generator-langium/test/yeoman-generator.test.ts @@ -33,16 +33,19 @@ describe('Check yeoman generator works', () => { targetRoot + '/tsconfig.build.json', targetRoot + '/tsconfig.json', targetRoot + '/package.json', + targetRoot + '/README.md', targetRoot + '/.vscode/extensions.json', targetRoot + '/.vscode/launch.json', targetRoot + '/.vscode/tasks.json', + targetRoot + '/packages/language/README.md', targetRoot + '/packages/language/src/hello-world-module.ts', targetRoot + '/packages/language/src/hello-world-validator.ts', targetRoot + '/packages/language/src/hello-world.langium', targetRoot + '/packages/language/src/syntaxes/hello-world.monarch.ts', targetRoot + '/packages/language/src/generated/ast.ts', targetRoot + '/packages/language/src/generated/grammar.ts', - targetRoot + '/packages/language/src/generated/module.ts' + targetRoot + '/packages/language/src/generated/module.ts', + targetRoot + '/packages/language/syntaxes/hello-world.tmLanguage.json' ]; const filesTest = (targetRoot: string) => [ @@ -57,6 +60,7 @@ describe('Check yeoman generator works', () => { targetRoot + '/packages/cli/src/util.ts', targetRoot + '/packages/cli/src/generator.ts', targetRoot + '/packages/cli/src/main.ts', + targetRoot + '/packages/cli/README.md', targetRoot + '/packages/cli/package.json', targetRoot + '/packages/cli/tsconfig.json' ]; @@ -73,7 +77,8 @@ describe('Check yeoman generator works', () => { targetRoot + '/packages/web/language-configuration.json', targetRoot + '/packages/web/package.json', targetRoot + '/packages/web/tsconfig.json', - targetRoot + '/packages/web/vite.config.ts' + targetRoot + '/packages/web/vite.config.ts', + targetRoot + '/packages/web/README.md', ]; const filesExtension = (targetRoot: string) => [ @@ -81,6 +86,7 @@ describe('Check yeoman generator works', () => { targetRoot + '/packages/extension/src/language/main.ts', targetRoot + '/packages/extension/.vscodeignore', targetRoot + '/packages/extension/esbuild.mjs', + targetRoot + '/packages/extension/langium-quickstart.md', targetRoot + '/packages/extension/language-configuration.json', targetRoot + '/packages/extension/package.json', targetRoot + '/packages/extension/tsconfig.json' @@ -238,8 +244,10 @@ const PACKAGE_JSON_EXPECTATION: Record = { type: 'module', private: true, scripts: { + 'clean': 'npm run clean --workspaces', 'watch': 'tsc -b tsconfig.build.json --watch', 'build': 'tsc -b tsconfig.build.json && npm run build --workspaces', + 'build:clean': 'npm run clean && npm run build', 'lint': 'eslint src --ext ts', 'langium:generate': 'npm run --workspace packages/language langium:generate', 'langium:watch': 'npm run --workspace packages/language langium:watch' @@ -249,6 +257,7 @@ const PACKAGE_JSON_EXPECTATION: Record = { '@typescript-eslint/eslint-plugin': '~7.13.0', '@typescript-eslint/parser': '~7.13.0', 'eslint': '~8.57.0', + 'shx': '~0.3.4', 'typescript': '~5.4.5' }, volta: { @@ -274,7 +283,9 @@ const PACKAGE_JSON_EXPECTATION_CLI: Record = { 'hello-world-cli': './bin/cli.js' }, scripts: { - 'build': "echo 'No build step'" + 'clean': 'shx rm -fr *.tsbuildinfo out', + 'build': "echo 'No build step'", + 'build:clean': 'npm run clean && npm run build' }, dependencies: { 'hello-world-language': '0.0.1', @@ -298,7 +309,9 @@ const PACKAGE_JSON_EXPECTATION_WEB: Record = { }, files: ['out', 'src'], scripts: { + 'clean': 'shx rm -fr *.tsbuildinfo out dist', 'build': 'vite build', + 'build:clean': 'npm run clean && npm run build', 'dev': 'vite', 'dev:debug': 'vite --debug --force', 'serve': 'vite preview' @@ -351,8 +364,10 @@ const PACKAGE_JSON_EXPECTATION_EXTENSION: Record = { ], main: './out/extension/main.cjs', scripts: { + 'clean': 'shx rm -fr *.tsbuildinfo out', 'vscode:prepublish': 'npm run build && npm run lint', 'build': 'tsc -b tsconfig.json && node esbuild.mjs', + 'build:clean': 'npm run clean && npm run build', 'watch': 'concurrently -n tsc,esbuild -c blue,yellow "tsc -b tsconfig.json --watch" "node esbuild.mjs --watch"' }, dependencies: {