updated README, tool help links

2026-10-25 00:02:16 +00:00 · 2026-09-12 19:12:28 +02:00
1 parent 1604794f08
commit 87a0d5c400
@@ -1,110 +0,0 @@
-
-https://github.com/sehugg/dasm
-http://sdcc.sourceforge.net/
-
-GPLv2
-
---
-
-https://github.com/gasman/jsspeccy2
-Z80 emulator
-GPLv3
-
---
-
-https://github.com/sehugg/javatari.js
-
-GNU Affero General Public License v3.0
-
---
-
-https://www.veripool.org/wiki/verilator
-
-GNU Lesser Public License Version 3
-
---
-
-http://mcpp.sourceforge.net/
-
-/*-
- * Copyright (c) 1998, 2002-2008 Kiyoshi Matsui <kmatsui@t3.rim.or.jp>
- * All rights reserved.
- *
- * This software including the files in this directory is provided under
- * the following license.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- * 1. Redistributions of source code must retain the above copyright
- *    notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in the
- *    documentation and/or other materials provided with the distribution.
- *
- * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
- * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
- * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- */
-
---
-
-https://github.com/sehugg/cc65
-
-This software is provided 'as-is', without any express or implied warranty.
-In no event will the authors be held liable for any damages arising from
-the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-1. The origin of this software must not be misrepresented; you must not
-claim that you wrote the original software. If you use this software in
-a product, an acknowledgment in the product documentation would be
-appreciated but is not required.
-
-2. Altered source versions must be plainly marked as such, and must not
-be misrepresented as being the original software.
-
-3. This notice may not be removed or altered from any source distribution.
-
---
-
-https://github.com/datajerk/c2t/blob/master/LICENSE
-
-Copyright 2017 Egan Ford <datajerk@gmail.com>
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1.  Redistributions of source code must retain the above copyright notice,
-this list of conditions and the following disclaimer.
-
-2.  Redistributions in binary form must reproduce the above copyright
-notice, this list of conditions and the following disclaimer in the
-documentation and/or other materials provided with the distribution.
-
-3.  Neither the name of the copyright holder nor the names of its
-contributors may be used to endorse or promote products derived from this
-software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGE.
@@ -2,15 +2,47 @@

 ![Build Status](https://github.com/sehugg/8bitworkshop/actions/workflows/node.js.yml/badge.svg)

+8bitworkshop is a browser-based IDE for micro computers and consoles.
+It compiles or assembles your code as you type,
+then runs the result in a built-in emulator — all locally in your
+browser, with no server round-trip.
+
+It bundles toolchains and emulators for dozens of platforms, including the
+Atari 2600/7800/8-bit, Commodore 64/VIC-20, NES, Game Boy, ColecoVision,
+MSX, ZX Spectrum, Amstrad CPC, PC Engine, Vectrex, Apple II, and a
+number of arcade boards. See
+[Toolchains & Platforms](src/docs/toolchains.md) for the complete list.
+
+![8bitworkshop IDE](https://8bitworkshop.com/images/ide_screenshot1.png)

 ## Use Online

 Latest release:
- https://8bitworkshop.com/latest/ or
- https://sehugg.github.io/8bitworkshop/
+- https://8bitworkshop.com/latest/ (bleeding edge, built from main branch)
+
+## Features
+
+* In-browser compilers and assemblers (cc65, SDCC, Z80/6502/6809
+  assemblers, and more) — see [Tools](src/docs/toolchains.md)
+* Built-in emulators with keyboard and gamepad input
+* Debugger with breakpoints, stepping, memory browser, disassembly,
+  call stack, memory probes, and time-travel replay
+* Hardware simulation with Verilog
+* Asset editor for bitmaps and palettes
+* Export ROMs, save screenshots/videos, share playable links, and sync
+  projects to GitHub
+
+Read the [IDE documentation](src/docs/index.md) for a guided tour.

 ## Install Locally

+Requirements:
+
+* [Node.js](https://nodejs.org/) 24.x
+* [npm](https://www.npmjs.com/)
+* `make` and `git`
+* Python 3 (for the local dev server)
+
 To clone just the main branch:

 ```sh
@@ -25,11 +57,16 @@ To build the 8bitworkshop IDE:
 make
 ```

-To use GitHub integration locally, download the Firebase config file, e.g. https://8bitworkshop.com/v[version]/config.js
+`make` initializes git submodules, installs npm dependencies, builds the
+TypeScript and lezer grammars, and runs esbuild.
+
+To use GitHub integration locally, download the Firebase config file,
+e.g. https://8bitworkshop.com/v[version]/config.js

 ### Start Local Web Server

-Start a web server on http://localhost:8000/ while TypeScript compiles in the background:
+Start a web server on http://localhost:8000/ while TypeScript compiles
+in the background:

 ```sh
 make tsweb
@@ -45,21 +82,39 @@ export TEST8BIT_GITHUB_TOKEN="<github_personal_access_token>"
 npm test
 ```

-## License
+## Command-Line Tool

-Copyright © 2016-2026 [Steven E. Hugg](https://github.com/sehugg).
+The `8bws` CLI builds and runs projects headlessly, without a browser.
+It is useful for scripting, CI, and regression tests.

+```sh
+# Build a source file to a ROM
+npm run cli -- build --platform c64 hello.c -o hello.prg --symbols

-This project, unless specifically noted, is multi-licensed.
-You may choose to adhere to the terms of either the [GPL-3.0](https://github.com/sehugg/8bitworkshop/blob/master/LICENSE) License for the entire project or respect the individual licenses of its dependencies and included code samples, as applicable.
+# Run a ROM for 200 frames and take a screenshot
+npm run cli -- run --platform nes --frames 200 --png shot.png game.nes

-This project includes various dependencies, modules, and components that retain their original licenses.
-For detailed licensing information for each dependency, please refer to the respective files and documentation.
+# Run with a debugger script (symbolic addresses come from the build)
+npm run cli -- run --platform gb hello.c -e "break _main; pc 4"

-All included code samples located in the `presets/` directory are licensed under
-[CC0](https://creativecommons.org/publicdomain/zero/1.0/)
-unless a different license is explicitly stated within the specific code sample.
+npm run cli -- list-platforms
+npm run cli -- list-tools
+```

+Run scripts (`-e` or `--script <file>`) can `run`, `break`, `step`,
+`trace`, `hist`, `key`, `mem`, `screen`, `pc`, `info`, `reset`, and
+`echo`. Run `npm run cli -- help` for the full list.
+
+## Documentation
+
+The IDE manual lives in [`src/docs/`](src/docs/index.md):
+
+* [IDE Overview](src/docs/index.md)
+* [Managing Files](src/docs/managing-files.md) — export, share, GitHub sync
+* [Build Directives](src/docs/build-directives.md) — multi-file projects
+* [Toolchains & Platforms](src/docs/toolchains.md) — tools and file extensions
+* [Debugger](src/docs/breakpoints.md) — breakpoints and stepping
+* [Embedding the IDE](src/docs/embedding-ide.md) — iframe embeds

 ## Contributing

@@ -76,67 +131,125 @@ It likes:

 The code samples in `presets/` are intended to be studied by humans.
 LLM usage for generating code samples is discouraged, as they tend to hide subtle errors in code and in comments, and it diminishes the human achievement and human-to-human communication aspects of the project.
+Please thoroughly review and edit such code.

 Adapting third party sample code with permissive licenses and giving credit to the original author(s) is encouraged.

+## Credits
+
+8bitworkshop is created and maintained by
+[Steven E. Hugg](https://github.com/sehugg).
+
+Major contributors:
+* [Fred Sauer](https://github.com/fredsa) - CodeMirror 6 editor migration, Apple II enhancements, and general IDE work.
+* [Mike DX](https://github.com/MikeDX) - PC Engine / Game Boy / Williams 6809 enhancements, library code, and examples.
+* [Micah Cowan](https://github.com/micahcowan) - Apple II enhancements.
+
+The emulators, compilers, assemblers, and libraries that this project
+builds on are credited in [Dependencies](#dependencies) and retain their
+own licenses (see [License](#license)).
+
+For the complete list of contributors, see the
+[GitHub contributors graph](https://github.com/sehugg/8bitworkshop/graphs/contributors).
+
+## License
+
+The original source code in this repository is Copyright © 2016-2026
+[Steven E. Hugg](https://github.com/sehugg) and is licensed under the
+[GPL-3.0](https://github.com/sehugg/8bitworkshop/blob/master/LICENSE).
+
+This project also bundles and links against third-party components,
+including emulators, compilers, and libraries. These components are
+**not** covered by the GPL-3.0 license above; they remain under their
+own licenses, and you must comply with those terms when redistributing
+this project or a modified version of it. 
+See the individual dependencies' own license files for details.
+
+All included code samples located in the `presets/` directory are licensed under
+[CC0](https://creativecommons.org/publicdomain/zero/1.0/)
+unless a different license is explicitly stated within the specific code sample.

 ## Dependencies

 ### Emulators

-* https://javatari.org/
-* https://jsnes.org/
-* https://www.mamedev.org/
-* https://github.com/floooh/chips
-* https://github.com/DrGoldfire/Z80.js
+* https://javatari.org/ (AGPL-3.0)
+* https://jsnes.org/ (Apache 2.0)
+* https://www.mamedev.org/ (BSD-3-Clause)
+* https://github.com/floooh/chips (Zlib)
+* https://github.com/DrGoldfire/Z80.js (MIT)
 * http://www.twitchasylum.com/jsvecx/
-* https://github.com/curiousdannii/ifvms.js/
-* https://6502ts.github.io/typedoc/stellerator-embedded/
-* https://github.com/yhzmr442/jspce
+* https://github.com/curiousdannii/ifvms.js/ (MIT)
+* https://github.com/6502ts/6502.ts (MIT)
+* https://github.com/yhzmr442/jspce (MIT)
+* https://github.com/gasman/jsspeccy2 (GPL-3)

 ### Compilers

-* https://cc65.github.io/
-* http://sdcc.sourceforge.net/
-* http://perso.b2b2c.ca/~sarrazip/dev/cmoc.html
+* https://cc65.github.io/ (zlib)
+* http://sdcc.sourceforge.net/ (GPL-2)
+* https://github.com/stahta01/cmoc/ (GPL-3.0)
 * https://github.com/batari-Basic/batari-Basic
-* https://www.veripool.org/wiki/verilator
-* http://mcpp.sourceforge.net/
-* http://www.ifarchive.org/indexes/if-archiveXinfocomXcompilersXinform6.html
-* https://github.com/dmsc/fastbasic
-* https://github.com/wiz-lang/wiz
-* https://github.com/sylefeb/Silice
-* https://github.com/steux/cc7800
+* https://www.veripool.org/wiki/verilator (GNU Lesser Public License Version 3)
+* http://mcpp.sourceforge.net/ (BSD-2)
+* https://github.com/DavidKinder/Inform6
+* https://github.com/dmsc/fastbasic (GPL-2.0)
+* https://github.com/wiz-lang/wiz (MIT)
+* https://github.com/sylefeb/Silice (GPL-3.0)
+* https://github.com/steux/cc7800 (GPL-3.0)
 * https://bellard.org/tcc/
+* https://github.com/Dialog-IF/dialog
+* https://github.com/alexfru/SmallerC (BSD-2-Clause)
+* https://github.com/drmortalwombat/oscar64/ (GPL-3.0)

 ### Assemblers/Linkers

-* https://dasm-assembler.github.io/
+* https://dasm-assembler.github.io/ (GPL-2)
 * http://atjs.mbnet.fi/mc6809/Assembler/xasm-990104.tar.gz
-* http://48k.ca/zmac.html
+* http://48k.ca/zmac.html (public domain)
 * https://github.com/apple2accumulator/merlin32
 * https://github.com/camsaul/nesasm
+* https://www.floodgap.com/retrotech/xa/
+* https://github.com/mikeakohn/naken_asm (GPL-3)
+* https://github.com/yasm/yasm
+* https://github.com/mbitsnbites/vasm-mirror
+* https://github.com/sehugg/acme (GPL-2.0)

 ### Dev Kits / Libraries

 * https://shiru.untergrund.net/code.shtml
 * http://www.colecovision.eu/ColecoVision/development/libcv.shtml
-* https://github.com/toyoshim/tss
-* https://github.com/lronaldo/cpctelera
+* https://github.com/toyoshim/tss (BSD-3-Clause)
+* https://github.com/lronaldo/cpctelera (LGPL-3.0)
+* https://github.com/datajerk/c2t (BSD-3)
+* https://github.com/sehugg/6809tools
+* https://github.com/mbitsnbites/liblzg (Zlib)
+* https://github.com/sehugg/makewav
+* https://github.com/Kingcom/armips (MIT)
+* https://github.com/dmsc/mkatr (GPL-2.0)

 ### Firmware

+The emulator cores need system firmware to boot. Only freely
+distributable replacement images are included — see
+[`mame/roms/README.md`](mame/roms/README.md) for their provenance and
+licenses.
+
+To use your own firmware, add it to the project as a binary file named
+`<platform-id>.rom` (for example `c64.rom`); the IDE loads it as the
+BIOS at startup. Only freely distributable firmware should be shared.
+
 * http://www.virtualdub.org/altirra.html
-* https://github.com/MEGA65/open-roms
+* https://github.com/MEGA65/open-roms (LGPL-3.0)
 * https://sourceforge.net/projects/cbios/
 * https://www.pledgebank.com/opense

 ### Related Projects

 * https://github.com/sehugg/8bitworkshop-compilers
-* https://github.com/sehugg/8bit-tools
-* https://github.com/sehugg/awesome-8bitgamedev
-* https://github.com/sehugg?tab=repositories
+* https://github.com/sehugg/8bit-tools (CC0-1.0)
+* https://github.com/sehugg/awesome-8bitgamedev (Public Domain)
+* https://github.com/sehugg?tab=repositories (CC0-1.0)


 ## Tool Server (experimental)
@@ -0,0 +1,65 @@
+# ROM images in this directory
+
+These are **not** the original system ROMs. They are freely
+redistributable replacement BIOS/OS images, included so that the MAME
+builds of the Atari 8-bit and ColecoVision platforms can boot without
+requiring the user to supply copyrighted firmware.
+
+If you are looking to load the real firmware, or your own dump, add it
+to the IDE project as a binary file named `<platform-id>.rom` (for
+example `apple2.rom`); the IDE loads it as the BIOS at startup.
+See the emulator code for the layout of the ROM file.
+
+## Contents
+
+| File | System | Image | Origin | License |
+| --- | --- | --- | --- | --- |
+| `a5200/5200.rom` | Atari 5200 | AltirraOS 5200 SuperKernel | [Altirra](https://www.virtualdub.org/altirra.html) by Avery Lee | permissive, notice required (see below) |
+| `a800xl.zip` → `co61598b.rom` | Atari 800XL | AltirraOS XL/XE kernel | Altirra by Avery Lee | permissive, notice required |
+| `a800xl.zip` → `co60302a.rom` | Atari 800XL | Altirra BASIC | Altirra by Avery Lee | permissive, notice required |
+| `coleco/313 10031-4005 73108a.u2` | ColecoVision | `minbios` | built from [`meta/romsrc/coleco/minbios.asm`](../../meta/romsrc/coleco/minbios.asm) | unspecified in source (see below) |
+
+The filenames inside `a800xl.zip` (`co61598b.rom`, `co60302a.rom`) and
+the Coleco chip filename are the names MAME expects; the *contents* are
+the free replacements, not the chips those names refer to.
+
+The Atari images are byte-identical to the copies used by the native
+(non-MAME) emulator:
+
+* `a5200/5200.rom` = `res/altirra/superkernel.rom`
+* `a800xl.zip` → `co61598b.rom` = `res/altirra/kernelxl.rom`
+
+## Altirra license
+
+The AltirraOS and Altirra BASIC ROMs are Copyright © 2008-2020
+Avery Lee and are distributed under this notice (taken from the
+source listing, `res/altirra/*.lst`):
+
+> Copying and distribution of this file, with or without modification,
+> are permitted in any medium without royalty provided the copyright
+> notice and this notice are preserved. This file is offered as-is,
+> without any warranty.
+
+Keep this notice when redistributing the project or the ROM images.
+
+## Coleco minbios
+
+`coleco/313 10031-4005 73108a.u2` is an 8 KB alternative ColecoVision
+BIOS assembled from `meta/romsrc/coleco/minbios.asm` with
+[`naken_asm`](https://www.naken.cc/naken-asm/), then padded to 8192
+bytes:
+
+```sh
+cd meta/romsrc/coleco
+make            # runs naken_asm and copies to mame/roms/coleco/
+```
+
+## Regenerating / replacing
+
+The Atari images can be rebuilt from the Altirra source (MADS
+assembler), which is part of the Altirra emulator distribution. After
+building, copy the resulting kernel/BASIC ROMs over the files above
+(keeping the MAME-expected names and the zip layout).
+
+Do not check in the original Atari or Coleco ROM dumps — they are
+copyrighted and are not covered by this project's license.
@@ -282,6 +282,7 @@ export const TOOL_META: { [id: string]: ToolMeta } = {
    id: 'nesasm', name: 'NESASM', kind: 'assembler', arch: '6502',
    extensions: ['.nesasm'],
    editorStyle: '6502',
+    helpURL: 'https://github.com/camsaul/nesasm',
    wasmModule: 'nesasm',
    version: '3.1',
    includePatterns: SHARED_INCLUDE_PATTERNS,
@@ -292,6 +293,7 @@ export const TOOL_META: { [id: string]: ToolMeta } = {
    id: 'merlin32', name: 'Merlin 32', kind: 'assembler', arch: '6502',
    extensions: ['.lnk'],
    editorStyle: '6502',
+    helpURL: 'https://github.com/apple2accumulator/merlin32',
    wasmModule: 'merlin32',
    version: '1.1.10',
    includePatterns: [...SHARED_INCLUDE_PATTERNS, ...USE_ASM_INCLUDE_PATTERNS],
@@ -393,6 +395,7 @@ export const TOOL_META: { [id: string]: ToolMeta } = {
  naken: {
    id: 'naken', name: 'Naken', kind: 'assembler',
    extensions: ['.ns'],
+    helpURL: 'https://github.com/mikeakohn/naken_asm',
    noWorkerBuild: true,
  },

@@ -436,7 +439,7 @@ export const TOOL_META: { [id: string]: ToolMeta } = {
    // NOTE: no bundled filesystem -- the compiler passes -I/share/include but
    // never mounts one, so system headers can't be linked in the UI
    editorStyle: 'text/x-csrc',
-    helpURL: 'http://perso.b2b2c.ca/~sarrazip/dev/cmoc.html',
+    helpURL: 'https://github.com/stahta01/cmoc/',
    wasmModule: 'cmoc',
    version: '0.1.67',
    defineFlag: '-D', defineInline: false,
@@ -506,6 +509,7 @@ export const TOOL_META: { [id: string]: ToolMeta } = {
  smlrc: {
    id: 'smlrc', name: 'SmallerC', kind: 'compiler', arch: 'x86',
    extensions: ['.c'],
+    helpURL: 'https://github.com/alexfru/SmallerC/blob/master/v0100/doc/smlrc.md',
    // NOTE: no bundled filesystem and no -I arg -- no headers to link in the UI
    editorStyle: 'text/x-csrc',
    wasmModule: 'smlrc',
@@ -518,6 +522,7 @@ export const TOOL_META: { [id: string]: ToolMeta } = {
    id: 'yasm', name: 'YASM', kind: 'assembler', arch: 'x86',
    extensions: ['.asm'],
    editorStyle: 'gas',
+    helpURL: 'https://www.tortall.net/projects/yasm/manual/html/manual.html',
    wasmModule: 'yasm',
    version: '1.3.0',
    defineFlag: '-D', defineInline: false,
@@ -568,6 +573,7 @@ export const TOOL_META: { [id: string]: ToolMeta } = {
    id: 'cc2600', name: 'CC2600', kind: 'compiler', arch: '6502',
    extensions: ['.cc2600'],
    editorStyle: 'text/x-csrc',
+    helpURL: 'https://github.com/steux/cc2600',
    wasmModule: 'cc2600',
    version: '0.4.5',
    wasiFSZip: 'cc2600-fs.zip',
@@ -580,6 +586,7 @@ export const TOOL_META: { [id: string]: ToolMeta } = {
    id: 'cc7800', name: 'CC7800', kind: 'compiler', arch: '6502',
    extensions: ['.cc7800', '.c78'],
    editorStyle: 'text/x-csrc',
+    helpURL: 'https://github.com/steux/cc7800',
    wasmModule: 'cc7800',
    version: '0.2.28',
    wasiFSZip: 'cc7800-fs.zip',