diff --git a/extension/README.md b/extension/README.md index fed757bc..7a0f0c90 100644 --- a/extension/README.md +++ b/extension/README.md @@ -1,13 +1,13 @@ # 8bitworkshop for VS Code -![8bitworkshop running a program in VS Code](images/demo.gif) +![8bitworkshop running a program in VS Code](https://8bitworkshop.com/images/vscode_demo.gif) The original online 8-bit IDE, now in VS Code! Write programs for classic consoles and computers, then build and play them without leaving VS Code. -This extension uses the assemblers, +This extension bundles the assemblers, compilers, and emulators from [8bitworkshop.com](https://8bitworkshop.com). Supported platforms include 6502, Z80, and 6809 CPUs: @@ -52,24 +52,59 @@ To use code you already have, open its folder: the extension detects the appropr ## Settings +Project settings, saved in `.vscode/settings.json`: + | Setting | What it does | |---|---| | `8bitworkshop.platform` | The platform, such as `nes`, `c64`, or `vcs` | | `8bitworkshop.mainFile` | The file that runs. Empty: the file in the editor | +| `8bitworkshop.tool` | The build tool, when it isn't the usual one for the file | +| `8bitworkshop.folders` | Projects in subfolders | +| `8bitworkshop.exportRomPath` | Folder for exported ROMs, relative to the main file (`bin` by default) | + +Your local user settings: + +| Setting | What it does | +|---|---| | `8bitworkshop.autoBuild` | `onType` (default), `onSave`, or `off` | | `8bitworkshop.reloadOnBuild` | `always` (default), `onSave`, or `never` | +| `8bitworkshop.exportRom` | Write each successful build's ROM to the export folder | | `8bitworkshop.toolchainPath` | Use a local 8bitworkshop checkout instead of the included toolchains | +| `8bitworkshop.assetUrl` | Server or local directory to download toolchains from, tried before the default servers | -8bitworkshop saves your choices in `.vscode/settings.json`. Commit it so -people who clone your repo skip the questions. +## Commands + +Every command is under **8bitworkshop:** in the Command Palette; several +also appear in the editor title bar, the Explorer, or **Project Options**. + +| Command | What it does | +|---|---| +| **New Project...** | Create a project from an example or a blank program | +| **Open Example** | Open a bundled example without copying it | +| **Copy to Workspace** | Copy the open example into your workspace | +| **Set as Main File** | Make the active file the one that runs | +| **Change Main File...** | Pick the main file from the workspace | +| **Change Platform...** | Build the project for another platform | +| **Detect Projects** | Scan the folder for projects and platforms | +| **Add Launch Configuration** | Write a run configuration to `.vscode/launch.json` | +| **Project Options** | Open the project menu | +| **Build** | Build without running | +| **Run** | Build and run in the emulator | +| **Run This File** | Run the active file, without changing the project | +| **Run Main File** | Run the project's main file | +| **Follow Active Editor** | Run whichever program is in the editor | +| **Reset / Pause / Resume / Stop / Mute / Unmute Emulator** | Control the emulator panel | +| **Download All Toolchains** | Fetch every platform's toolchain for offline use | ## More -- [Projects and the file that runs](https://github.com/sehugg/8bitworkshop/blob/master/extension/docs/projects.md) -- [Platform detection](https://github.com/sehugg/8bitworkshop/blob/master/extension/docs/detection.md) +- [Projects](https://github.com/sehugg/8bitworkshop/blob/master/extension/docs/projects.md) - [Building](https://github.com/sehugg/8bitworkshop/blob/master/extension/docs/building.md) - [The emulator](https://github.com/sehugg/8bitworkshop/blob/master/extension/docs/emulator.md) +- [Platform detection](https://github.com/sehugg/8bitworkshop/blob/master/extension/docs/detection.md) +- [Changelog](https://github.com/sehugg/8bitworkshop/blob/master/extension/CHANGELOG.md) - [Report a problem](https://github.com/sehugg/8bitworkshop/issues) +- [Source code](https://github.com/sehugg/8bitworkshop) ## License diff --git a/extension/docs/QUICKSTART.md b/extension/docs/QUICKSTART.md index fab48988..6b0dcbff 100644 --- a/extension/docs/QUICKSTART.md +++ b/extension/docs/QUICKSTART.md @@ -107,22 +107,16 @@ If the game restarting while you type gets in the way, set Some compilers, such as llvm-mos, build on a server. Those always wait until you save. -## Other C and assembly extensions - -In an 8bitworkshop project, C files use the **8bitworkshop C** language -mode (shown at the right of the status bar) for compilers like cc65 and -SDCC. That keeps C/C++ extensions and clangd from reporting errors that -only apply to desktop C. 8bitworkshop provides hover, go to definition, -and completion instead. Files outside 8bitworkshop projects don't -change. - -To keep your usual C tools, set `8bitworkshop.cLanguage` to `c`. - ## Where your choices are saved 8bitworkshop saves the platform, main file, and build tool in `.vscode/settings.json`, whenever you choose or change one. Commit that -file so people who clone your repo skip these questions. +file to pin an ambiguous answer or a folder with several projects; +detection normally fills these in from your README and source. + +Your own settings stay in your user settings instead: `autoBuild` and +`reloadOnBuild` (window settings) and `toolchainPath` (a path on your +machine, which VS Code keeps out of the workspace file). **Run This File** is just for you: VS Code remembers it on this computer, and it never changes a file. **Add Launch Configuration** diff --git a/extension/docs/projects.md b/extension/docs/projects.md index 3008a47c..90e00c4f 100644 --- a/extension/docs/projects.md +++ b/extension/docs/projects.md @@ -102,21 +102,16 @@ also name another platform, so one program can run on `c64` and `vic20`: | Run This File, Follow Active Editor | VS Code, on this computer only | | Launch configurations | `.vscode/launch.json` | -Commit `.vscode/settings.json` so people who clone your repo skip these -questions. +Commit `.vscode/settings.json` to pin an ambiguous answer or a folder +with several projects; detection normally fills these in from your +README and source. Your own settings — `autoBuild`, `reloadOnBuild`, +`toolchainPath` — stay in your user settings and aren't committed. A file opened with no folder has nowhere to save, so its platform lasts until you close the window. Choose **Open Containing Folder** in the notification to keep it. -## Settings - -| Setting | Meaning | -|---|---| -| `8bitworkshop.platform` | The platform id, such as `nes` or `c64`. | -| `8bitworkshop.mainFile` | The main file, relative to the workspace folder. Leave it empty for a folder of small programs. | -| `8bitworkshop.tool` | The build tool, when it isn't the usual one for the file's extension (`ca65` for a `.asm` file, say). | -| `8bitworkshop.folders` | Projects in subfolders. The most specific folder wins. | +## Settings JSON For example, a repo with a game at the top and a C64 port in a subfolder: diff --git a/extension/images/demo.gif b/extension/images/demo.gif deleted file mode 100644 index 9187be8e..00000000 Binary files a/extension/images/demo.gif and /dev/null differ diff --git a/extension/package.json b/extension/package.json index cf89f32a..154d28a8 100644 --- a/extension/package.json +++ b/extension/package.json @@ -1,9 +1,10 @@ { "name": "8bitworkshop", - "displayName": "8bitworkshop — Retro 8-bit Dev (NES, Atari, C64, 6502)", - "description": "Build, run, and debug retro 8-bit programs — NES, Atari 2600/7800/8-bit, Commodore 64, and more — with 8bitworkshop's 6502/Z80/6809 assemblers, compilers, and emulators", + "displayName": "8bitworkshop — Retro 8-bit Dev", + "description": "Build, run, and debug 8-bit programs — NES, Atari, C-64, and more — with 8bitworkshop's 6502/Z80/6809 assemblers, compilers, and emulators", "keywords": [ "retro", + "vintage", "8-bit", "8bit", "6502", @@ -31,6 +32,9 @@ "dasm", "homebrew", "game development", + "Verilog", + "HDL", + "hardware design", "retrogaming" ], "version": "0.1.0", @@ -44,8 +48,13 @@ "license": "GPL-3.0", "repository": { "type": "git", - "url": "git+https://github.com/sehugg/8bitworkshop.git" + "url": "https://github.com/sehugg/8bitworkshop.git", + "directory": "extension" }, + "bugs": { + "url": "https://github.com/sehugg/8bitworkshop/issues" + }, + "homepage": "https://8bitworkshop.com", "engines": { "vscode": "^1.90.0" },