4.2 KiB
Platform detection
8bitworkshop can tell the platform of existing code from clues in it, and it always shows you the clue it used.
When it runs
- Set as Main File, or Build or Run on a file with no project. You asked, so a clear answer applies at once: "Using NES (game.c:3 includes "neslib.h"). [Change]". If the answer isn't clear, a list shows the likely platforms first, each with its clue.
- Opening a folder that has no 8bitworkshop settings. A notification appears only when the clues are strong and point at one platform: "This looks like an NES project (...). [Use It] [Choose...] [Not Now] [Don't Ask]". Nothing changes until you choose Use It, which opens the main file, builds it, and offers Run. A large folder with projects scattered through it, such as a big codebase with a few examples inside, brings up no notification.
- Opening a source file in a folder with no project. If its folder has strong clues, you get the same notification. After Not Now, 8bitworkshop doesn't ask again until you reopen the window. Weaker clues show only in the status bar, such as NES?; click it to choose a platform.
- 8bitworkshop: Detect Projects scans the folder again, even after Don't Ask. It also lists folders with weaker clues as potential projects, unchecked.
If a folder holds several projects, such as nes/ and c64/
subfolders or a folder of cloned repos, the notification says how many
it found. A project's own subfolders count as part of it. Click Review
and check the ones to use; each gets its own entry in
8bitworkshop.folders.
The clues
Strongest first:
| Clue | Example |
|---|---|
The 8bitworkshop link in README.md |
8bitworkshop.com/...?platform=vcs&file=game.dasm |
| A ROM file | game.nes, game.a26, game.gb |
| A platform's header or include file | #include "neslib.h", include "nesdefs.dasm" |
| Hardware registers | WSYNC, COLUBK (VCS); PPUCTRL (NES); $D020 (C64) |
| A cc65 target in a Makefile, or a cc65 linker config | cl65 -t c64, nes.cfg |
| A file extension few platforms use | .cc2600, .bb |
| A folder named after a platform | nes/, c64/ |
Plain C or assembly with none of these never brings up a notification,
so other projects you open aren't interrupted. Neither do ROM files,
linker configs, headers, or folder names alone: a notification needs a
clue in a program's own source. A C program needs a main(), and
startup code such as crt0.s is never the main file.
Hardware registers and function names in a header only declare a library, so a folder of nothing but headers and library sources isn't offered as a project. When a folder holds several programs, its review entry shows the count (Game Boy · 26 programs). Accepting it makes the folder a directory of small programs, so Run builds whichever program is open.
Some platforms share everything detection can see. For example, the
ColecoVision, MSX and Sega platforms all use cv.h. Then the list shows
them all and you choose.
Assembler syntax
A file extension can mean different assemblers: .asm builds with DASM
on the 6502 platforms. When you set a main file that's written for
another assembler, 8bitworkshop says so:
This looks like ca65 code; .asm builds with dasm. [Use ca65] [Keep dasm]
Choosing Use ca65 saves 8bitworkshop.tool for the project. When
you accept a project found on opening a folder, the right tool is saved
without asking.
Fix a wrong guess
Click the status bar, then choose one of these:
- Change Platform... to pick another platform.
- Detect Again to look at the clues again.
- Remove Project... to clear its settings, so it isn't a project at all. See Remove a project.
From the command line
8bws detect prints the same guesses and clues:
8bws detect game.c
8bws detect path/to/folder
8bws build and 8bws run use detection when you leave out
--platform. Give them a source file, or a folder: for a folder they
build the main file detection picks. If no platform clearly wins, or no
main file stands out, they list the candidates and ask for --platform
or a source file.
8bws build --check path/to/folder
8bws run path/to/folder --frames 60