MicroCS is plain C99 with no dependencies. Wherever your C compiles, MicroCS compiles. This page explains how to add it to a project (any build system), which port to use, and how to support a new chip.

Flash numbers are Cortex-M, -Os, including newlib + libm (~49 KB). Details: PERFORMANCE.md · small parts: LOW_RESOURCE.md.

Sources: src/*.c (core) + modules/*/*.c (optional: fs, hal, sched, shell, runtime) + ports/<port>/mcs_port_<port>.c (optional). Include paths: include/ and ports/<port>/. Modules that cannot build on a target compile to nothing (e.g. the POSIX filesystem on an MCU).

MICROCS_DIR  := third_party/MicroCS
MICROCS_PORT := stm32                 # optional
include $(MICROCS_DIR)/microcs.mk
C_SOURCES    += $(MICROCS_SRCS)
C_INCLUDES   += $(MICROCS_INCS)
C_DEFS       += $(MICROCS_DEFS)       # set MICROCS_PROFILE := lowram to use a profile

Put mcs_user_config.h in one of your C_INCLUDES folders (it is found automatically), or name it with MICROCS_CONFIG := app/my_config.h. MICROCS_CORE_ONLY := 1 builds only the language core.

set(MICROCS_PORT stm32)               # stm32 | rp2 | esp32 | template | "" (none)
set(MICROCS_PROFILE embedded)         # auto | min | tiny | mcu | embedded | lowram | linux | full | "" (default)
add_subdirectory(third_party/MicroCS)
target_link_libraries(${PROJECT_NAME} microcs)

With MICROCS_PORT stm32 the library links the generated stm32cubemx target, so it sees your HAL configuration; with rp2 it links the hardware_* libraries of the pico-sdk. A mcs_user_config.h next to your top-level CMakeLists.txt (or in its include/, src/ or main/ folder) is found automatically; MICROCS_CONFIG=path/to/my_config.h names another file, MICROCS_CONFIG=NONE ignores it. MICROCS_MODULES=OFF builds only the core. On the host it also builds the mcs CLI.

Clone into components/MicroCS (or add it with the IDF component manager — idf_component.yml is included). The same CMakeLists.txt detects ESP-IDF and registers a component with the ESP32 port. In your main/CMakeLists.txt nothing is needed (IDF links all components) — see ports/esp32/example. Options: idf.py menuconfig → MicroCS (profile, filesystem, ws2812) and a mcs_user_config.h in the project folder or main/ (or Project config header in menuconfig) for everything else.

Add the repo as a module (west.yml project or -DZEPHYR_EXTRA_MODULES=path/to/MicroCS) and enable it in prj.conf:

CONFIG_MICROCS=y

zephyr/module.yml, zephyr/CMakeLists.txt and zephyr/Kconfig do the rest. See ports/zephyr/example. A mcs_user_config.h in the application folder (or its include/ / src/) is used automatically; CONFIG_MICROCS_USER_CONFIG_FILE names another one.

[env:board]
lib_deps = https://github.com/amir1387aht/MicroCS

library.json + tools/pio_build.py select the port from the framework: espidf → ESP32 port, arduino → Arduino port, stm32cube → STM32 port, zephyr → Zephyr port. Put mcs_user_config.h in the project's include/ folder; build_flags = -D… still work.

python3 tools/make_arduino.py          # → dist/arduino/MicroCS/ and dist/arduino/MicroCS-1.14.0.zip

Sketch → Include Library → Add .ZIP Library, then open File → Examples → MicroCS. The Arduino IDE has no per-library -D flags, so options live in the packaged src/mcs_user_config.h: edit it there, or build the package with --config my_config.h, --profile lowram, --define MCS_ENABLE_LINQ=0.

Add the folders src, modules, ports/<port> as source folders and include, ports/<port> as include paths, plus the folder with your mcs_user_config.h. No special compiler flags, no extensions; GCC, Clang, ARMCC 6, IAR and MSVC (host) are fine. Recommended: -Os (or -O2 for speed).

All options are #defines with defaults in include/mcs_config.h. Set them in a project header mcs_user_config.h — copy the template config/mcs_user_config.h, which sets every option, including the port options, to its default value, and edit what you change — or with -D…, which wins over the header. Ready-made profiles in include/profiles/: auto, min, tiny, mcu, lowram, embedded, linux; python3 tools/gen_config.py --profile embedded -o mcs_user_config.h writes the header with that profile's values (or, without a header, -DMCS_PROFILE=MCS_PROFILE_EMBEDDED). Where the header goes for each build system and the precedence rules: CONFIGURATION.md.

A port maps the C# peripheral API to the vendor's own SDK. It includes the SDK's headers from your project — CubeMX handles, ESP-IDF drivers, pico-sdk hardware_*, Zephyr device drivers — so it follows your chip variant, pin muxing and clocks. MicroCS never pokes registers behind the SDK's back.

Every port provides mcs_<port>_hal_init(&hal, &cfg), mcs_<port>_ticks, mcs_<port>_delay and a console transport, which is all mcs_runtime needs.

Run each VM in one task/thread — a VM is not thread-safe, but several VMs can run in different tasks. mcs_request_abort(vm) may be called from an ISR or another task to stop a script at the next safe point. Peripheral events from ISRs go through mcs_hal_post().

1. Copy ports/template/mcs_port_template.c.
2. Fill the console (read/write), ticks, delay and the mcs_hal_t members your chip has (GPIO first — everything else is optional; see HAL.md).
3. Post interrupts with mcs_hal_post(MCS_HAL_EV_GPIO, pin, level) and timer ticks with MCS_HAL_EV_TIMER.
4. Optional (HAL API v3): gpio_configure, spi_configure … so scripts can set pins, pulls, drive strength and filters with configuration objects, and an options table for settings only your chip has (PERIPHERALS.md). Return MCS_HAL_ENOTSUP after mcs_hal_error("why") for anything the hardware cannot do — never ignore a field. Background transfers: dma_alloc, dma_copy, spi_transfer_async … posting MCS_HAL_EV_DMA when done; return MCS_HAL_ENOTSUP for one request and the library runs it synchronously (DMA.md). A bus opened with three_wire gets exactly one of tx / rx per spi_transfer.
5. Optional: persistent files — fill the template's flash port (mcs_flash_port_t: region size, erase unit, program unit and read / write / erase of the chip's flash; mcs_intflash_init() makes the mcs_flash_t) and build with MICROCS_FS=tinyfs (built in, a few KB of internal flash is enough), littlefs or yaffs2 (FILESYSTEM.md). STM32, RP2040/RP2350, ESP32 and Zephyr already have theirs. Drivers — fill the template's ws2812_write backend for LedStrip (Servo uses the HAL PWM, nothing to add), or add your own driver (DRIVERS.md).
6. Optional: networking — fill an mcs_net_t (include/mcs_net.h: Wi-Fi, ESP-NOW, SNTP, mDNS, ping, TLS; leave the rest NULL) and call mcs_net_set() before the HAL library opens; with lwIP / BSD sockets TcpClient, UdpClient and Http work as they are (NETWORK.md). Bluetooth LE — fill an mcs_ble_t (include/mcs_ble.h), call mcs_ble_set() the same way and build with MCS_ENABLE_BLE=1 (BLE.md).
7. Run examples/hardware/*.cs on the board — they are the acceptance tests for a port.
8. Send a pull request: add a tools/check_ports.sh-style compile check if the SDK headers are freely downloadable.

A minimal firmware without any SDK: startup.c (vector table, .data/.bss, stack painting, FPU enable), cm.ld, board.c (UART + tick drivers for a minimal SoC + newlib stubs) and main.c (pool heap, VM, RAM FS, scheduler, demo image, optional shell). Targets (make cm): m0-runtime, m0-lowram, m0-node (48 KB RAM), m4-full, m33-full, m33-shell. make cm-check executes them instruction by instruction and requires the output to be byte-identical to the host interpreter — this is how the code generation, ABI, alignment, soft/hard float paths and the memory budgets are checked for each core. To use it on a real chip, replace board.c with your UART/SysTick code and adapt cm.ld (or use one of the vendor ports above, which already do this).

tools/check_ports.sh compiles a port against the real vendor headers without hardware:

tools/check_ports.sh stm32 f4 STM32F446xx cortex-m4     # downloads the Cube HAL headers into build/sdk
tools/check_ports.sh stm32 h7 STM32H743xx cortex-m7

Each run compiles the port in 8 configurations in parallel (default, without the ws2812 / servo drivers, without drivers, the auto profile, and the internal flash with LittleFS, YAFFS2 and TinyFS). CI runs it for 18 popular STM32 boards across 12 families (Blue Pill, Black Pill F401/F411, F4 Discovery, Nucleo F0/F4/F7/G0/G4/H5/H7/L0/L4/U5/WB) as parallel jobs with the ST headers cached, builds the RP2 example for pico and pico2, and builds the ESP-IDF example for ESP32, S3, C3 and C6 (.github/workflows/ci.yml).