{"id":31802104,"url":"https://github.com/matjam/vscode-acme-extension","last_synced_at":"2025-10-11T00:17:13.129Z","repository":{"id":316961551,"uuid":"1065482440","full_name":"matjam/vscode-acme-extension","owner":"matjam","description":"A vscode extension for the ACME 6502/4510/45GS02 Assembler","archived":false,"fork":false,"pushed_at":"2025-09-27T21:51:18.000Z","size":7843,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-27T22:17:38.122Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matjam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-27T20:21:54.000Z","updated_at":"2025-09-27T21:50:42.000Z","dependencies_parsed_at":"2025-09-27T22:27:43.839Z","dependency_job_id":null,"html_url":"https://github.com/matjam/vscode-acme-extension","commit_stats":null,"previous_names":["matjam/vscode-acme-extension"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/matjam/vscode-acme-extension","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fvscode-acme-extension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fvscode-acme-extension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fvscode-acme-extension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fvscode-acme-extension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matjam","download_url":"https://codeload.github.com/matjam/vscode-acme-extension/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fvscode-acme-extension/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005657,"owners_count":26083941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T00:17:11.666Z","updated_at":"2025-10-11T00:17:13.124Z","avatar_url":"https://github.com/matjam.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ACME Assembler VS Code Extension\n\nA comprehensive VS Code extension for ACME assembler development, providing syntax highlighting, code formatting, hover documentation, and seamless integration with the ACME assembler and MEGA65 development tools.\n\n## Features\n\n### 🎨 Syntax Highlighting\n- **Complete ACME directive support**: `!cpu`, `!to`, `!addr`, `!8`, `!16`, `!by`, `!pet`, `!src`, `!if`, `!macro`, and more\n- **Multi-processor instruction set**: Full highlighting for 6502, 4510, and 45GS02 instructions and addressing modes\n- **Smart number highlighting**: Hexadecimal (`$1234`), binary (`%1010`), decimal, and character literals\n- **Label support**: Global labels, local labels (`+`, `-`), and proper scoping\n- **Comment and string highlighting**: Line comments (`;`) and string literals with escape sequences\n\n### 📝 Code Formatting\n- **Automatic formatting**: Clean up whitespace, align instructions, and format directives\n- **Smart indentation**: Proper indentation for conditional blocks and macros\n- **Consistent spacing**: Aligns labels, instructions, and operands for readability\n- **Format on save**: Optional automatic formatting when saving files\n\n### 📚 Hover Documentation\n- **Multi-processor instruction reference**: Hover over any 6502, 4510, or 45GS02 instruction for detailed documentation\n- **Comprehensive details**: Operation descriptions, flag effects, addressing modes, and cycle counts\n- **Visual flag display**: Interactive flag status with reverse highlighting for set flags\n- **Addressing mode tables**: Complete addressing mode information with syntax and opcodes\n- **Side effects**: Detailed information about instruction side effects\n- **Processor-specific operations**: CPU-specific operation details for 6502, 4510, and 45GS02\n\n\u003cimg width=\"1502\" height=\"702\" alt=\"image\" src=\"https://github.com/user-attachments/assets/1a35c068-e265-493a-b286-61d104c771e1\" /\u003e\n\n### 🔧 ACME Integration\n- **Direct assembler integration**: Seamless integration with ACME assembler binary\n- **Multiple output formats**: Support for PRG, CBM, BIN, and D64 formats\n- **Error parsing**: Automatic error detection and display in Problems panel\n- **Auto-assemble**: Optional background assembly on file save\n- **Build commands**: Assemble individual files or entire projects\n\n### 🎮 MEGA65 Development\n- **MEGA65 emulator integration**: Run programs directly in [xmega65 emulator](https://github.com/lgblgblgb/xemu)\n- **45GS02 processor support**: Full support for MEGA65's 45GS02 processor with enhanced instruction set\n- **4510 processor support**: Complete support for the 4510 processor variant\n- **Hardware support**: Load programs to MEGA65 via etherload command\n- **Flexible execution**: Choose between emulator or hardware execution modes\n- **Automatic binary detection**: Finds emulator and etherload binaries in PATH\n\n### ⚙️ VS Code Integration\n- **Task provider**: VS Code task integration for automated builds\n- **Context menus**: Right-click support for ACME files\n- **Command palette**: Easy access to all ACME commands\n- **Output channel**: Dedicated ACME assembler output channel\n- **Problem matcher**: Automatic error parsing and display\n\n## Installation\n\n### From VSIX (Recommended)\n1. Download the `.vsix` from the [GitHub Releases](https://github.com/matjam/vscode-acme-extension/releases)\n2. Install via VS Code: `Ctrl+Shift+P` → \"Extensions: Install from VSIX\"\n3. Select the downloaded `.vsix` file\n\n### Install script (for development)\nUse the interactive installer to symlink this repo into VS Code and/or Cursor:\n\n```bash\nchmod +x install.sh\n./install.sh\n```\n\nFlags:\n- `--vscode` install for VS Code only\n- `--cursor` install for Cursor only\n- `--both` install for both\n- `-y`, `--yes` run non-interactively and overwrite existing links\n\nRestart the IDE(s) after installation.\n\n\n## Configuration\n\nThe extension provides several configuration options accessible through VS Code settings:\n\n| Setting | Type | Default | Description |\n|---------|------|---------|-------------|\n| `acme.binaryPath` | string | `\"acme\"` | Path to the ACME assembler binary |\n| `acme.outputDirectory` | string | `\"out\"` | Directory for output files |\n| `acme.defaultFormat` | string | `\"prg\"` | Default output format (prg, cbm, bin, d64) |\n| `acme.verboseOutput` | boolean | `false` | Enable verbose output from ACME |\n| `acme.autoAssemble` | boolean | `false` | Automatically assemble on save |\n| `acme.emulatorBinary` | string | `\"xmega65\"` | Path to MEGA65 emulator binary |\n| `acme.runMode` | string | `\"emulator\"` | Run mode: \"emulator\" or \"etherload\" |\n| `acme.etherloadCommand` | string | `\"etherload\"` | Command for MEGA65 etherload |\n| `acme.showTerminalOnRun` | boolean | `false` | Show terminal when running programs |\n\n## Usage\n\n### Basic Usage\nOpen any `.a` or `.asm` file and the extension will automatically provide:\n- Syntax highlighting\n- Code formatting support\n- Hover documentation for instructions\n- Context menu options\n\n### Assembling Files\n\n#### Via Context Menu\n- **Right-click** on an ACME file in the editor\n- Select from available ACME commands:\n  - \"Assemble File\" - Assemble the current file\n  - \"Assemble and Run\" - Assemble and run using configured mode\n  - \"Assemble and Run on Emulator\" - Run on MEGA65 emulator\n  - \"Assemble and Run on MEGA65\" - Run on MEGA65 hardware\n\n#### Via Command Palette\n- Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)\n- Search for \"ACME\" to see all available commands\n- Select the desired command\n\n#### Via Keyboard Shortcuts\n- `Ctrl+Shift+B` - Run default build task\n- `Shift+Alt+F` - Format current document\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `ACME: Assemble File` | Assemble the current file |\n| `ACME: Assemble and Run` | Assemble and run using configured run mode |\n| `ACME: Assemble and Run on Emulator` | Assemble and run on MEGA65 emulator |\n| `ACME: Assemble and Run on MEGA65` | Assemble and run on MEGA65 hardware |\n| `ACME: Build Project` | Assemble all ACME files in workspace |\n| `ACME: Show Output` | Show ACME assembler output channel |\n\n### Hover Documentation\n\nHover over any 6502, 4510, or 45GS02 instruction to see:\n- **Instruction name** and short description\n- **Operation** details and CPU-specific operations\n- **Flags affected** with visual status indicators\n- **Side effects** in a bulleted list\n- **Addressing modes** in a detailed table with:\n  - Mode name and assembly syntax\n  - Opcode and cycle count\n  - Processor compatibility\n  - Cycle modifier explanations\n\n### Auto-Assemble on Save\n\nWhen enabled, the extension automatically assembles ACME files when saved:\n- Runs silently in the background\n- Displays errors in Problems panel\n- Shows detailed output in ACME output channel\n- Clears errors when compilation succeeds\n\n## File Support\n\nThe extension recognizes these file types:\n- `.a` - Primary ACME assembler files\n- `.asm` - Generic assembly files\n\n## Supported Processors\n\nThe extension provides comprehensive support for three processor architectures:\n\n- **6502** - Classic 8-bit processor with full instruction set support\n- **4510** - Enhanced 6502 variant with additional instructions and addressing modes\n- **45GS02** - MEGA65's advanced processor with extended instruction set and enhanced capabilities\n\nEach processor is fully supported with:\n- Complete instruction set highlighting\n- Comprehensive hover documentation\n- Processor-specific operation details\n- Addressing mode support\n- Cycle count information\n\n## Error Handling\n\nComprehensive error handling includes:\n- **Problems panel integration** - Errors and warnings displayed with line numbers\n- **Error navigation** - Click errors to jump to problematic lines\n- **Auto-clear** - Errors cleared when compilation succeeds\n- **Multiple formats** - Supports both ACME error and warning formats\n\n## Development\n\n### Building\n```bash\nnpm install\nnpm run compile\n```\n\n### Watching for Changes\n```bash\nnpm run watch\n```\n\n### Testing\nPress `F5` in VS Code to launch Extension Development Host and test the extension.\n\n## Requirements\n\n- VS Code 1.74.0 or higher\n- Node.js 16.x or higher\n- TypeScript 4.9.4 or higher\n- ACME assembler binary (for assembly features)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Acknowledgments\n\n- ACME assembler by Marco Baye\n- MEGA65 project team\n- VS Code team for the excellent extension API\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatjam%2Fvscode-acme-extension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatjam%2Fvscode-acme-extension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatjam%2Fvscode-acme-extension/lists"}