🚀 Trilha Básica
Bem-vindo(a) à Trilha de Desenvolvimento com DSLs com Langium! Esta trilha foi cuidadosamente estruturada para oferecer um caminho completo de aprendizado, desde os conceitos básicos de DSLs (Domain-Specific Languages).
Além do conhecimento técnico, você aprenderá a criar sua própria DSL de forma eficiente, garantindo sintaxe expressiva, validações robustas e ferramentas modernas para facilitar o desenvolvimento.
🔎 O que você vai aprender?
✅ Configuração do ambiente e estrutura de um projeto Langium
⏳ Carga horária total: 10h
📌 Formato: Vídeos, artigos, leituras complementares e desafios práticos
🎯 Pré-requisitos
Para um melhor aproveitamento da trilha, é recomendado possuir conhecimentos básicos de:
- TypeScript: Documentação Oficial
- Node.js: Guia de Introdução
Tutoriais em Vídeo
Para obter orientação prática sobre o desenvolvimento com Langium, confira esta playlist de tutoriais em vídeo da TypeFox, que aborda os fundamentos do Langium e exemplos úteis:
1. Pré-requisitos
Certifique-se de ter os seguintes itens instalados:
- Node.js (a versão LTS mais recente é recomendada)
- npm (incluído com o Node.js)
- Ubuntu 22.4
2. Instalando o Yeoman e o Gerador Langium
Para configurar o ambiente, instale globalmente o Yeoman e o gerador Langium com o seguinte comando:
npm install -g yo @langium/generator
Este comando instala tanto o Yeoman quanto o gerador específico do Langium, permitindo que você crie projetos Langium de forma rápida e eficiente.
3. Gerando um Projeto Langium
Após a instalação, você pode criar um novo projeto Langium com o seguinte comando:
yo langium
4. Configuração do Projeto
Ao executar este comando, o Yeoman solicitará algumas preferências do projeto. As principais opções de configuração incluem:
> yo langium
┌─────┐ ─┐
┌───┐ │ ╶─╮ ┌─╮ ╭─╮ ╷ ╷ ╷ ┌─┬─╮
│ ,´ │ ╭─┤ │ │ │ │ │ │ │ │ │ │
│╱ ╰─ ╰─┘ ╵ ╵ ╰─┤ ╵ ╰─╯ ╵ ╵ ╵
` ╶─╯
Welcome to Langium! This tool generates a VS Code extension with a "Hello World" language
to get started quickly. The extension name is an identifier used in the extension
marketplace or package registry.
❓ Your extension name: hello-world
The language name is used to identify your language in VS Code. Please provide a name to
be shown in the UI. CamelCase and kebab-case variants will be created and used in
different parts of the extension and language server.
❓ Your language name: Hello World
Source files of your language are identified by their file name extension. You can
specify multiple file extensions separated by commas.
❓ File extensions: .hello
Your language can be run inside of a VSCode extension.
❓ Include VSCode extension? Yes
You can add CLI to your language.
❓ Include CLI? Yes
You can run the language server in your web browser.
❓ Include Web worker? No
You can add the setup for language tests using Vitest.
❓ Include language tests? Yes
- Your language name: define qual o nome da linguagem que irá criar.
- File extensions: define qual a extensão da sua linguagem.
- Include VSCode extension?: define se será gerado uma extensão do VScode.
- Include CLI?: define se será gerado um CLI para o projeto.
- Include Web worker?: define se será criado uma versão web da linguagem. Para o nosso exemplo, colocamos não.
- Include language tests?: define se será gerado classes de teste para a linguagem criada.
5. Estrutura do Projeto
Após a geração, seu projeto terá uma estrutura semelhante a esta:
├── HelloWorld
│ ├── esbuild.mjs
│ ├── langium-config.json
│ ├── langium-quickstart.md
│ ├── language-configuration.json
│ ├── package-lock.json
│ ├── package.json
│ ├── src
│ │ ├── cli
│ │ │ ├── cli-util.js
│ │ │ ├── generator.js
│ │ │ └── main.js
│ │ ├── extension
│ │ │ └── main.ts
│ │ └── language
│ │ ├── generated
│ │ │ ├── ast.ts
│ │ │ ├── grammar.ts
│ │ │ └── module.ts
│ │ ├── hello-world-module.ts
│ │ ├── hello-world-validator.ts
│ │ ├── hello-world.langium
│ │ └── main.ts
│ ├── syntaxes
│ │ └── hello-world.tmLanguage.json
│ └── tsconfig.json
| Arquivo | Descrição |
|---|---|
| esbuild.mjs | Configuração do esbuild, ferramenta de bundling e transpile dos arquivos TypeScript para JavaScript. Usado na build do projeto. |
| langium-config.json | Configuração do Langium, define o caminho dos arquivos de entrada e saída, além das regras da gramática. |
| langium-quickstart.md | Documentação de início rápido para o projeto gerado, explicando como usar e estender. |
| language-configuration.json | Configurações adicionais da linguagem, como comentários, brackets e auto fechamento de pares. |
| package-lock.json | Registro das versões exatas das dependências instaladas, garantindo builds reproduzíveis. |
| package.json | Gerenciador de dependências e scripts do projeto Node.js. Contém metadados, dependências e comandos úteis como build, start, etc. |
| tsconfig.json | Configuração do compilador TypeScript, definindo como os arquivos serão transpilados para JavaScript. |
📂 src/ — Código fonte principal
| Arquivo | Descrição |
|---|---|
| main.ts | Ponto de entrada para integração com editores (VS Code, por exemplo). Responsável por registrar o servidor da linguagem (Language Server). |
📂 language/
| Arquivo | Descrição |
|---|---|
| hello-world.langium | Arquivo da gramática da sua linguagem personalizada! Aqui você define as regras da linguagem (tokens, sintaxe, etc). |
| hello-world-module.ts | Configuração de injeção de dependências para os serviços da linguagem, como parser, validator e code generator. |
| hello-world-validator.ts | Validações customizadas da linguagem. Exemplo: regras semânticas adicionais que vão além da gramática. |
| main.ts | Entrada principal para inicializar a linguagem fora da extensão, por exemplo para testes ou CLI. |
📂 language/generated/
⚙️ Arquivos gerados automaticamente pelo Langium a partir da gramática. Evite mexer manualmente.
| Arquivo | Descrição |
|---|---|
| ast.ts | Define as interfaces e tipos da Abstract Syntax Tree (AST) da linguagem, ou seja, a representação em árvore dos elementos da sua gramática. |
| grammar.ts | Representação da gramática definida no .langium em forma de código para uso interno da engine. |
| module.ts | Módulo gerado automaticamente que conecta os serviços básicos da linguagem. |
📂 syntaxes/
| Arquivo | Descrição |
|---|---|
| hello-world.tmLanguage.json | Definição de tokens para syntax highlighting no VS Code. Esse arquivo determina como as palavras-chave e símbolos da sua linguagem serão coloridos no editor. |
💡 Resumo Visual:
📦 Configuração e dependências
├── package.json / package-lock.json
├── tsconfig.json
├── langium-config.json
📝 Documentação
├── langium-quickstart.md
⚙️ Build
├── esbuild.mjs
💻 Código fonte
├── src/
│ ├── extension/ → Extensão do VSCode
│ └── language/ → Implementação da linguagem
│ ├── hello-world.langium → Gramática
│ ├── validator e module → Serviços e validação
│ └─ ─ generated/ → Arquivos automáticos (AST, grammar)
🎨 Syntax Highlighting
├── syntaxes/
│ └── hello-world.tmLanguage.json
6. Gerando Código para a Gramática
Após criar o projeto, temos que executar o comando abaixo, dentro da pasta do projeto, para instalar a bibliotecas necessárias:
npm install
Observe que o uma grmatica de exemplo foi criada em src/language/hello-world.langium.
grammar HelloWorld
entry Model:
(persons+=Person | greetings+=Greeting)*;
Person:
'person' name=ID;
Greeting:
'Hello' person=[Person:ID] '!';
hidden terminal WS: /\s+/;
terminal ID: /[_a-zA-Z][\w_]*/;
terminal INT returns number: /[0-9]+/;
terminal STRING: /"(\\.|[^"\\])*"|'(\\.|[^'\\])*'/;
hidden terminal ML_COMMENT: /\/\*[\s\S]*?\*\//;
hidden terminal SL_COMMENT: /\/\/[^\n\r]*/;
A gramatica apresentada permite que o usuário crie um um aquivo .hello com o seguinte conteúdo:
person Paulo
Hello Paulo!
Para o Langium processar a gramática e gerar os arquivos necessários para interpretar e validar sua linguagem é necessário executar o seguinte comando:
npm run langium:generate
7. Compilando o Projeto
Após a geração do código, compile o projeto com TypeScript:
npm run build
Este comando garante que todos os arquivos TypeScript sejam compilados e que o projeto esteja pronto para uso.
8. Executando e Testando a nossa linguagem
Para testar a nossa linguagem, vá no menu e clique em run--> Start Debugging, ou clique F5. Isso irá abrir o nova janela do Vscode.
Crie um novo arquivo chamado teste.hello e depois digite:
person Paulo
Hello Paulo!
Perceba que cada elemento da linguagem "Hello" e "Person" aparecem de cores diferentes do que as variáveis da linguagem "Paulo".
Parabéns você conseguiu criar a sua primeira linguagem com langium. No nível intermediário iremos fazer uma linguagem básica que permita criar funções em diferentes linguagens de programação.