CToy: Interactive C99 Prototyping with TCC and Persistent Memory

CToy targets rapid C99 experiments

CToy solves a narrow problem: changing a C program and seeing the result immediately without repeatedly managing a compiler and a separate build directory. The README describes it as an interactive C99 environment based on TCC, with downloadable packages for Windows, macOS, and Linux. Its intended users are people prototyping small interactive programs, learning C through immediate feedback, or teaching code whose output changes while it is edited.

The workflow is not tied to a built-in code editor. A developer launches CToy, opens `src/main.c` in a favorite text editor, edits the project, and saves. CToy notices changes to the main file or any file connected to it through direct or recursive inclusion, then recompiles and restarts the program. This makes the save action the primary feedback event. It is a different development model from editing and manually invoking a compiler after every change.

CToy is not limited to terminal output. The documented API covers window management, input, persistent memory, image processing through MaratisTCL, OpenGLES-2, and OpenAL. The README also mentions pen-tablet support for devices such as Wacom. These capabilities place the project closer to an interactive C learning and graphics prototyping workbench than to a conventional command-line C compiler wrapper. The repository description and README support that interpretation, but they do not claim that it is a general-purpose replacement for a full production toolchain.

How save-triggered recompilation works

CToy expects a project entry file at `src/main.c`. Instead of the standard C `main` function, the example uses `ctoy_begin`, `ctoy_main_loop`, and `ctoy_end`. The first runs when the program starts, the second runs at every main-loop update, and the third runs at program end. That lifecycle makes it possible to put initialization, per-frame work, and cleanup in explicit stages.

The central source file includes the CToy API through `ctoy.h`, which the README describes as including frequently used ANSI C libraries. Saving `src/main.c`, or an included dependency, causes a dynamic recompilation and restart. The documentation does not describe a separate process manager, build cache, or incremental dependency database beyond this file-change behavior, so those details should not be assumed.

CToy also changes one ordinary C lifecycle assumption. A registered memory block can survive recompilation, allowing state to remain available when the program is rebuilt. The mechanism is explicit: allocate memory, register it during the first run, and retrieve it after later rebuilds. The documentation warns against storing function pointers because function addresses may change after recompilation. This is an important boundary for interactive programs because persistent data can outlive the code that originally allocated or referenced it.

Installing CToy and running the first program

The README provides prebuilt downloads rather than a package-manager installation command. It says that no compiler is required for those packages and lists CToy 1.06 for Win64, CToy 1.05 for macOS, and CToy 1.05 for Linux64. The package names and links below are copied from the project documentation. The Linux section separately states that OpenAL is required.

After downloading the appropriate archive, unzip it and run the CToy application. The documented first use is:

1. Launch CToy. 2. Open `src/main.c` in a text editor. 3. Replace or edit the entry functions with a program such as the following. 4. Save the file and inspect the running result.

#include <ctoy.h>

void ctoy_begin()
{
   printf("Hello, World!\n");
}

void ctoy_main_loop()
{}

void ctoy_end()
{}

The three functions are the CToy-specific entry points. The README says that CToy recompiles and restarts whenever the main file or a connected file changes. The visible result for this example is the `Hello, World!` line printed by `ctoy_begin`.

For a first persistent-state experiment, the README provides this pattern. The initial run allocates and registers 256 zeroed bytes; later runs retrieve the same registered block and increment a counter.

#include <ctoy.h>

void *persistent_memory = NULL;

void ctoy_begin()
{
   if (ctoy_t() == 0) {
      persistent_memory = calloc(256, 1);
      ctoy_register_memory(persistent_memory);
   }
   else {
      persistent_memory = ctoy_retrieve_memory();
   }
}

void ctoy_main_loop()
{
   int *persistent_counter = (int *)persistent_memory;
   (*persistent_counter)++;
   printf("persistent_counter = %d\n", (*persistent_counter));
}

void ctoy_end()
{}

The README does not document rollback, crash recovery, or a command for selecting a different main entry file.

Persistent memory changes the recompilation model

Persistent memory is CToy's most distinctive documented feature. A normal C program starts from its process state each time it launches, but CToy can retain a manually allocated block across recompilations. That is useful for experiments involving counters, scene state, or other values that should not reset whenever a source file is saved.

The cost is that application code must cooperate with the persistence model. The developer has to check `ctoy_t()`, allocate with `calloc` or another manual allocation method, register the block with `ctoy_register_memory`, and retrieve it with `ctoy_retrieve_memory`. The storage must be treated as application data, not as a permanent reference to executable code. The README specifically warns that function pointers may become invalid after recompiles and should either be avoided or refreshed after retrieval.

The documented memory size in the example is 256 bytes, but the project does not state limits, ownership rules, or the behavior when multiple blocks are registered. For that reason, persistence should be introduced deliberately. A project that expects a fresh process for every restart may find that retained state changes debugging assumptions, especially when a saved edit leaves the program in a state that the new source does not expect.

CToy_player separates running from publishing

The repository README lists `CToy_player` as a companion component for publishing a project with dynamic update disabled. That distinction is useful when comparing the development environment with the runtime intended for a stable presentation. The editor-facing CToy application responds to source changes, while the publishing path is documented as a way to run the project without dynamic updates.

The project also documents use with dynamic libraries by copying `.dll` files into `your_ctoy_path/lib/`. It mentions pre-built Dear-Imgui support and a CMake script for GCC, Visual Studio, and MinGW. Those features indicate that the environment is not restricted to the small console example. However, the README does not provide a complete deployment guide for `CToy_player`, platform-specific library loading instructions, or a release checklist. Those omissions matter when moving from experimentation to distribution.

Emscripten compatibility is also stated in the README. The README does not describe the required Emscripten command, generated browser artifacts, or limitations of the browser build. It is therefore reasonable to treat compatibility as a documented capability, but not as a fully specified publishing pipeline from the README alone.

Building from CMake is a separate path

Although the README emphasizes prebuilt archives, it also documents a source build with CMake. On Unix, the documented sequence creates a `Build` directory, configures CMake with the Unix Makefiles generator, builds, and installs into `../bin` with a Release configuration.

mkdir Build
cd Build
cmake -G "Unix Makefiles" ../ -DCMAKE_INSTALL_PREFIX=../bin -DCMAKE_BUILD_TYPE=Release
make
make install

The Windows instructions configure the project with the Visual Studio 11 Win64 generator.

mkdir Build
cd Build
cmake -G "Visual Studio 11 Win64" ../ -DCMAKE_INSTALL_PREFIX=../bin

The README states that the bundled `libtcc.dll` and `libtcc.dylib` were prebuilt from a fork of TCC. The repository layout also includes CMake files and shell or batch build scripts, but the README does not document the compiler versions, install dependencies, or the exact result of running the scripts. The source build is consequently less self-contained than the README's prebuilt-package instructions.

For Linux users, the requirement is stated simply as OpenAL. The README does not name a distribution package or installation command, so this article does not invent one. This is a real setup constraint for a supposedly no-compiler download workflow.

License and maintenance boundaries

The README states that CToy is licensed under the zlib/libpng License, while the repository metadata classifies the top-level license as Other because GitHub cannot classify the custom terms. The repository includes `LICENSE.txt`, and the README identifies the zlib/libpng License. That distinction matters for adoption review: a user should read the actual `LICENSE.txt` rather than infer terms solely from the repository's license classification. This is a licensing note, not legal advice.

The repository is not archived, and its last push was on 2026-10-06. No GitHub releases are listed. The README links to versioned archives for CToy 1.06 on Windows and CToy 1.05 on macOS and Linux, but it does not provide a release history, upgrade policy, migration notes, or compatibility matrix for TCC and the included libraries. The absence of GitHub releases also means the linked binaries, rather than a documented release workflow, are the clearest installation route.

Compared with a conventional C project, CToy has lower apparent setup cost because it provides small cross-platform archives and reacts to saves. It also introduces project-specific concepts that an adoption team must account for: `ctoy_begin`, `ctoy_main_loop`, `ctoy_end`, registered memory, and the distinction between the live editor and `CToy_player`. The trade-off is clear. CToy is well matched to short interactive experiments, while conventional CMake or compiler-based workflows provide more explicit control over builds, dependencies, and release artifacts.

Editorial conclusion

Adopt CToy when you want a small, editor-driven workflow for experimenting with C99 graphics, audio, and interactive programs. Do not adopt it as a general production toolchain when you need a conventional build system, formal release packaging, or a documented compiler-selection workflow without checking the included CMake files. Verify first that the platform download runs, that the project layout matches `src/main.c`, and that your Linux environment provides the documented OpenAL requirement.

Frequently asked questions

Official sources

1. anael-seghezzi/CToy on GitHub
2. Issues
3. README