# chips-test: sample emulators and a test harness for the chips project > chips-test is the test and sample repository for the chips chip emulator project, and it is where the actual emulators live, with a CPC emulator, other machines and a set of ROMs, all built through a Deno-driven build script called fibs that handles CMake, Ninja, Xcode, Visual Studio, VS Code and the Emscripten WebAssembly build. It suits a developer who wants to run one of these emulators or contribute a new machine, and the detail to understand first is that fibs is the whole developer interface, not just a convenience wrapper. **floooh/chips-test** — Tests and sample code for https://github.com/floooh/chips - Repository: https://github.com/floooh/chips-test - Stars: 547 · Forks: 58 - Language: C - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/floooh-chips-test ## Where the emulators actually live chips-test is described as tests and sample code for the chips project, and the distinction it draws is worth stating up front. The chips repository holds the core chip emulation library, and this repository holds everything built on top of it: the emulators, the test suite, the ROM images and the build machinery. The directory listing shows the split. There is an `examples/` directory with four subdirectories, `ascii/`, `common/`, `emus/` and `roms/`. The `emus/` directory is where the emulated machines live, and the `roms/` directory holds the ROM images they need. The `ascii/` directory is for the terminal-flavoured rendering, and `common/` holds what the emulators share. There is also a `tests/` directory at the root, which is the test suite proper, and a `webpage/` directory for the browser-hosted demos. The live demos are published at floooh.github.io/tiny8bit, and the README refers to them as live demos of the example emulators. So the emulators here are real programs that run, not illustrations in a README. The primary language is C, the licence is MIT, the default branch is master, the last push was on 2026-10-04, and there are no GitHub releases. The project acknowledges utest.h from sheredom, the single-header testing library, in a many thanks section at the end of the README, which tells you the test suite is built on a header-only framework rather than on a heavyweight one. The examples/cpc emulator is the one the README builds first, and the CPC, the Amstrad home computer, is the machine the project uses to demonstrate the setup. The naming convention of the build targets, `cpc` as the run target, suggests the other emulators are configured the same way. ## fibs, the build script that is really the developer interface Every command in the README goes through one executable, fibs, and understanding what it does explains the whole project layout. The top level of the repository contains a `fibs` file, a `fibs.cmd` for Windows, a `fibs.ts` written in TypeScript, and a `fibs-scripts/` directory. So fibs is a TypeScript program that runs on Deno, which is why Deno is listed first among the prerequisites along with CMake at least version 3.21 and the system's own C or C++ toolchain, whether that is Clang, GCC or MSVC. The basic build is three commands: ```bash git clone https://github.com/floooh/chips-test cd chips-test ./fibs build ./fibs run cpc ``` The README notes that exact versions of tools shouldn't matter, which is a claim about the build being reasonably portable rather than pinned. Then the configuration step, which is where the naming scheme becomes visible. On Linux or macOS with Ninja installed, you would want to use that instead: ```bash # on Linux ./fibs config linux-ninja-release ./fibs build # on macOS ./fibs config macos-ninja-release ./fibs build ``` So a configuration is named by platform, by build tool and by build type. The combinations named in the README are linux-ninja-release, macos-ninja-release, emsc-ninja-release, macos-xcode-debug, macos-vscode-debug, linux-vscode-debug, win-vstudio-debug and win-vscode-debug. That is a small set, but the naming shows the axes the project cares about: which machine, which generator, and whether you want a debug or a release build. The IDE targets use the same mechanism, which is a neat trick: ```bash # on macOS with Xcode ./fibs config macos-xcode-debug ./fibs open # on macOS with VSCOde: ./fibs config macos-vscode-debug ./fibs open ``` Configuring a configuration and then opening it is all it takes to get an IDE session going, because the configuration is a build directory and the IDE generators write their project files into it. To see everything runnable, the command is: ```bash ./fibs list targets --exe ``` That is worth knowing, because it is how you find the names of the other emulators rather than guessing them from the directory listing. ## The WebAssembly build, and its separate toolchain Building the browser demos is the part of the workflow that needs an extra toolchain, and the README is upfront about the uncertainty in it. To build the WebAssembly demos, Linux or OSX is recommended, Windows might work too, but this is not well tested. The steps are: ```bash # check if required tools are installed (ninja and maybe http-server) ./fibs diag tools # install the Emscripten SDK ./fibs emsdk install # configure, build and run ./fibs config emsc-ninja-release ./fibs build ./fibs run cpc # or to open the project in VSCode: ./fibs config emsc-vscode-debug ./fibs open ``` The `diag tools` subcommand is the diagnostic step and it reports which tools are missing, so the workflow is check, install, configure, build. The `emsdk install` step fetches the Emscripten SDK, which is the compiler toolchain that turns C into WebAssembly, and it is a separate download from the rest of the build. The naming of the configuration, `emsc-ninja-release`, follows the same convention as the native ones, so the Emscripten build is not a special case bolted on afterwards. It is one more platform axis in the same scheme. Once the Emscripten build works, the whole samples page can be built and served: ```bash ./fibs webpage build ./fibs webpage serve ``` So there are two separate outputs. The emulator itself builds to WebAssembly, and the webpage is the harness that hosts those builds, which is what the live demos at floooh.github.io/tiny8bit are. The `webpage/` directory at the repository root is that harness. Having it in the repository rather than in a separate deployment project means the demos and the emulators are versioned together, so a demo page always matches the code it is demonstrating. The honest caveat is the one the README states. Windows might work for the Emscripten path, but it is not well tested, and the recommendation is Linux or OSX. Anyone planning to build the browser demos as part of a Windows release pipeline should verify that early rather than discovering it at the end. ## Linux dependencies and the escape hatch Two practical details are easy to miss and both cost time if you do not know them in advance. The first is the Linux dependency note: on Linux, additional dev packages need to be present for X11, GL, ALSA and ncurses development. Those are the four subsystems an emulator with a window, a display, sound and a terminal interface touches, and each needs its development headers rather than just its runtime library. This is a classic Linux build failure that produces link errors naming functions you have never heard of, and the README names the four packages rather than making you guess. The second is the reset command. If fibs gets stuck in an error situation, try `./fibs reset` to start over from scratch: ```bash ./fibs reset ``` The existence of that command is a tell about the build system. fibs is generating build directories and running generators inside them, and a generator that has written a half-broken cache can leave the build in a state where every subsequent invocation fails the same way. A reset that discards the generated state and starts again is the standard answer for that class of problem, and having it as a single command rather than a manual sequence of deletions matters when the state includes several directories. There is also a `tools/` directory at the repository root, which is presumably where the ROM and asset handling lives, and a `.github/` directory with the build workflow whose badge sits at the top of the README. The README points at the build workflow badge as the indicator of whether the current state of the repository builds, which for a project with this many platform and toolchain combinations is the honest thing to check. The one thing fibs does not do, on this evidence, is install the system dependencies for you. The prerequisites are listed, the tools can be diagnosed, and the Linux package note tells you which headers are needed, but the actual package installation is left to you. ## What this repository is for It is worth being clear about the division of labour, because a repository named with a test suffix can be mistaken for something narrower than it is. The chips project is the core: the chip emulation library itself. This repository is the layer above it, where the emulated machines are defined, where the ROMs that give those machines something to run live, where the test suite sits, and where the build system that ties CMake, Ninja, the Emscripten SDK and the IDE generators together is written. That division is a normal arrangement for an emulator project. The library should not contain a CPC machine definition, because the library is about chips and a machine is a wiring of chips plus ROMs plus a video and keyboard interface. Keeping the machines in a separate repository means the library's users who are not interested in whole computers do not carry them. It also means the emulators are the test surface. An emulator that boots a ROM and produces a screen is a test of the library, and running it against a corpus of ROM images in `examples/roms/` is how the library's behaviour gets checked against real behaviour rather than against assertions written alongside the code. For a contributor, the practical entry points are visible in the README's structure. The `examples/` tree tells you where to add a machine, the `tests/` directory is where to add a test, and `utest.h` tells you the framework is a single header you can drop in. The `fibs list targets --exe` command tells you the names you need to build and run each thing, which is the kind of detail that is usually buried in a wiki page and here is one command away. The whole project is MIT licensed, and the live demos make it easy to see what the emulators do before deciding whether to build anything, which is the right order of operations for a repository whose purpose is partly to show what the underlying library is capable of. ## Conclusion Adopt chips-test if you want to run or study the chip emulators in the chips project, since this repository holds the emulator code, the ROMs and the test suite rather than just the core library. Do not expect a single command to build every configuration, because fibs selects a named configuration per platform and toolchain, and check first that the tools you intend to use are present, because the script can tell you which are missing and the Emscripten path in particular needs the SDK installed separately. ## FAQ ### What is chips-test? It is the repository holding the tests and sample code for the chips chip emulator project. It contains the sample emulators under examples/emus/, the ROM images under examples/roms/, the test suite, the browser demo harness in webpage/ and the fibs build script. The licence is MIT and the primary language is C. ### How do I build the CPC emulator in chips-test? Clone the repository, cd into it, then run `./fibs build` and `./fibs run cpc`. The prerequisites are deno, CMake at least version 3.21 and your system's C or C++ toolchain, and on Linux you also need the development packages for X11, GL, ALSA and ncurses. ### What does the fibs build script do? It is a TypeScript program run by Deno that drives the build, with the source in fibs.ts and the helper scripts in fibs-scripts/. Configurations are named by platform, generator and build type, such as linux-ninja-release, macos-xcode-debug, win-vstudio-debug and emsc-ninja-release, and after `./fibs config ` the same script can build with `./fibs build`, open an IDE with `./fibs open`, or list what exists with `./fibs list targets --exe`. ### How do I build the WebAssembly demos in chips-test? Check the tools with `./fibs diag tools`, install the Emscripten SDK with `./fibs emsdk install`, then configure with `./fibs config emsc-ninja-release`, build and run with `./fibs build` and `./fibs run cpc`. The README notes that Linux or OSX is recommended, Windows might work but is not well tested, and the samples page can then be built with `./fibs webpage build` and served with `./fibs webpage serve`. ### What happens if the fibs build gets stuck? Run `./fibs reset` to start over from scratch. The command exists because the build generates state in its build directories, and a broken generator can leave the build failing the same way on every subsequent run. ### Is chips-test still being maintained? The repository is not archived and the last push was on 2026-10-04, with no GitHub releases. The build is checked by a GitHub Actions workflow whose badge sits at the top of the README, the test suite uses the header-only utest.h framework, and the live demos of the example emulators are published at floooh.github.io/tiny8bit. ## Sources - [floooh/chips-test on GitHub](https://github.com/floooh/chips-test) - [Issues](https://github.com/floooh/chips-test/issues) - [License: MIT](https://github.com/floooh/chips-test/blob/master/LICENSE) - [README](https://github.com/floooh/chips-test/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/floooh-chips-test