DEV Community

CrabPascal
CrabPascal

Posted on

How We Ship the VS Code Extension | Como publicamos a extensão VS Code

#pascal #vscode #opensource #devops

Bilingual post · Post bilíngue

Jump to: English · Português

English {#english}

How We Ship the VS Code Extension

Post 034 showed how check, tasks, and problem matchers feel inside VS Code. This article pulls back the curtain on how the extension gets to the Marketplace — and a structural lesson that confused early contributors.

Read the full playbooks: guia-publicacao-vscode-marketplace and resposta-extensao-vscode.

The packaging mistake we fixed

Early on, .vscode/tasks.json lived at the compiler repo root. That worked for people building CrabPascal itself — but Marketplace users never received those files. Installing crabpascal.crabpascal downloaded syntax highlighting only; tasks and keybindings were missing.

The fix documented in resposta-extensao-vscode:

crabpascal/                    # Compiler (Rust)
├── src/
├── Cargo.toml
└── vscode-extension/          # ← Separate extension package
    ├── package.json           # tasks, commands, contributes
    ├── extension.js
    ├── syntaxes/
    └── README.md
Enter fullscreen mode Exit fullscreen mode

When you vsce package, everything under vscode-extension/ ships. Users get tasks on first .pas open — no manual JSON editing.

Extension folder essentials

Minimum layout for publish:

vscode-extension/
├── package.json
├── extension.js
├── language-configuration.json
├── syntaxes/pascal.tmLanguage.json
├── images/icon.png          # 128×128
├── README.md
├── CHANGELOG.md
└── LICENSE
Enter fullscreen mode Exit fullscreen mode

Critical package.json fields:

{
  "name": "crabpascal",
  "displayName": "CrabPascal",
  "publisher": "crabpascal",
  "version": "2.22.0",
  "engines": { "vscode": "^1.80.0" },
  "categories": ["Programming Languages"],
  "repository": {
    "type": "git",
    "url": "https://bitbucket.org/alphatecnologia/crabpascal.git"
  }
}
Enter fullscreen mode Exit fullscreen mode

Commands and task definitions live in contributes — not in the user's workspace.

Marketplace publishing pipeline

Publishing is free on the Visual Studio Marketplace. Prerequisites from guia-publicacao-vscode-marketplace:

  1. Microsoft/Azure DevOps account
  2. Personal Access Token with Marketplace (Manage) scope
  3. npm install -g vsce

Release loop:

cd vscode-extension
vsce login crabpascal          # paste PAT once
vsce package                   # produces .vsix for local test
code --install-extension crabpascal-2.22.0.vsix
vsce publish                   # push to Marketplace
Enter fullscreen mode Exit fullscreen mode

Local .vsix install validates tasks and compiler path resolution before public users see a broken build.

Version coupling with the compiler

The extension version should track minimum compiler features users expect. When Sprint 1 shipped real diagnostic spans (v2.9.9), the extension's bundled auto-install URL pointed at matching release artifacts.

Mismatch symptoms:

  • Extension invokes stale crab-pascal.exe → errors still at 1:1
  • README claims features the downloaded binary lacks

We align package.json version, CHANGELOG.md, and Git tag in the same PR that bumps Cargo.toml.

What users get vs what contributors edit

Audience Gets tasks from…
Marketplace install vscode-extension/package.json
Compiler hacker Optional local .vscode/ for Rust work

Never put Pascal user tasks only in repo-root .vscode/ — they'll never reach end users.

Security and trust notes

  • PAT tokens expire — calendar reminder before vsce publish fails mid-release.
  • Extension can download compiler binary — verify checksum or HTTPS source in extension.js.
  • Marketplace listing is public README — keep honest parity statements (Sprint 13 policy applies).

Contributing to extension releases

Open vscode-extension/CHANGELOG.md before every publish. Summarize all user-visible changes: new tasks, compiler auto-install URL bumps, syntax scope fixes. Cross-link guia-publicacao-vscode-marketplace from the PR so reviewers verify PAT scope and version alignment.

Smoke test checklist after .vsix install:

code --install-extension crabpascal-2.22.0.vsix
# Open examples/hello.dpr → Ctrl+Shift+B → Problems panel shows real spans
Enter fullscreen mode Exit fullscreen mode

If syntax highlighting regressed, diff syntaxes/pascal.tmLanguage.json against the previous tag — TM scopes break silently when string delimiters change in the lexer.

Next in series

Post 036 — Testing Horse APIs with Postman moves from IDE comfort to HTTP verification — collections, cURL, and the CRUD example that stress-tests real Delphi-style server code.

Português {#portugus}

Como publicamos a extensão VS Code

O post 034 mostrou como check, tasks e problem matchers funcionam no VS Code. Este artigo abre o capô de como a extensão chega ao Marketplace — e uma lição estrutural que confundiu contribuidores no início.

Leia os guias completos: guia-publicacao-vscode-marketplace e resposta-extensao-vscode.

O erro de empacotamento que corrigimos

No início, .vscode/tasks.json ficava na raiz do repo do compilador. Funcionava para quem compilava o CrabPascal — mas usuários do Marketplace nunca recebiam esses arquivos. Instalar crabpascal.crabpascal baixava syntax highlighting; tasks e atalhos sumiam.

A correção documentada em resposta-extensao-vscode:

crabpascal/                    # Compilador (Rust)
├── src/
├── Cargo.toml
└── vscode-extension/          # ← Pacote separado da extensão
    ├── package.json           # tasks, commands, contributes
    ├── extension.js
    ├── syntaxes/
    └── README.md
Enter fullscreen mode Exit fullscreen mode

Ao rodar vsce package, tudo em vscode-extension/ vai no pacote. Usuários recebem tasks ao abrir o primeiro .pas — sem editar JSON manualmente.

Estrutura mínima da extensão

Layout para publicar:

vscode-extension/
├── package.json
├── extension.js
├── language-configuration.json
├── syntaxes/pascal.tmLanguage.json
├── images/icon.png          # 128×128
├── README.md
├── CHANGELOG.md
└── LICENSE
Enter fullscreen mode Exit fullscreen mode

Campos críticos do package.json:

{
  "name": "crabpascal",
  "displayName": "CrabPascal",
  "publisher": "crabpascal",
  "version": "2.22.0",
  "engines": { "vscode": "^1.80.0" },
  "categories": ["Programming Languages"],
  "repository": {
    "type": "git",
    "url": "https://bitbucket.org/alphatecnologia/crabpascal.git"
  }
}
Enter fullscreen mode Exit fullscreen mode

Comandos e tasks ficam em contributes — não no workspace do usuário.

Pipeline de publicação no Marketplace

Publicar é grátis no Visual Studio Marketplace. Pré-requisitos de guia-publicacao-vscode-marketplace:

  1. Conta Microsoft/Azure DevOps
  2. Personal Access Token com escopo Marketplace (Manage)
  3. npm install -g vsce

Ciclo de release:

cd vscode-extension
vsce login crabpascal          # colar PAT uma vez
vsce package                   # gera .vsix para teste local
code --install-extension crabpascal-2.22.0.vsix
vsce publish                   # envia ao Marketplace
Enter fullscreen mode Exit fullscreen mode

Instalar .vsix local valida tasks e resolução de path do compilador antes do usuário público ver build quebrado.

Acoplamento de versão com o compilador

A versão da extensão deve acompanhar features mínimas que o usuário espera. Quando o Sprint 1 entregou spans reais (v2.9.9), a URL de auto-instalação apontava para artefatos da mesma release.

Sintomas de desalinhamento:

  • Extensão chama crab-pascal.exe velho → erros ainda em 1:1
  • README promete o que o binário baixado não tem

Alinhamos versão do package.json, CHANGELOG.md e tag Git no mesmo PR que sobe Cargo.toml.

O que usuários recebem vs o que contribuidores editam

Público Tasks vêm de…
Instalação Marketplace vscode-extension/package.json
Hacker do compilador .vscode/ local opcional para Rust

Nunca coloque tasks Pascal só em .vscode/ na raiz — usuários finais não recebem.

Notas de segurança e confiança

  • PAT expira — lembrete no calendário antes de vsce publish falhar.
  • Extensão pode baixar binário — verifique checksum ou HTTPS em extension.js.
  • Listing público é o README — mantenha paridade honesta (política do Sprint 13).

Contribuindo com releases da extensão

Abra vscode-extension/CHANGELOG.md antes de cada publish. Resuma mudanças visíveis: tasks novas, bumps de URL de auto-instalação, correções de syntax scope. Linke guia-publicacao-vscode-marketplace no PR para revisores validarem escopo PAT e alinhamento de versão.

Checklist smoke após instalar .vsix:

code --install-extension crabpascal-2.22.0.vsix
# Abra examples/hello.dpr → Ctrl+Shift+B → Problems com spans reais
Enter fullscreen mode Exit fullscreen mode

Se syntax highlighting regrediu, diff syntaxes/pascal.tmLanguage.json contra tag anterior — scopes TM quebram silenciosamente quando delimitadores mudam no lexer.

Próximo da série

Post 036 — Testando APIs Horse com Postman sai do conforto da IDE para verificação HTTP — collections, cURL e o exemplo CRUD que estressa código servidor estilo Delphi de verdade.

Published on dev.to/@crabpascal · Código em CrabPascal

Top comments (0)