Contributing - amir1387aht/MicroCS GitHub Wiki

Contributing to MicroCS

Thanks for helping! MicroCS runs on devices where a crash means a bricked field unit, so the bar is "tested and honest" rather than "big".

Ground rules

  1. make check stays green โ€” tests, GC-stress run and all feature-flag builds with -Werror.
  2. Behaviour is defined by .out files. A new language feature needs a test; if it is plain C#, its output must be byte-identical to .NET (tools/verify_dotnet.sh).
  3. Docs describe the code, not the plan. Label anything unfinished as ๐Ÿงช experimental or ๐Ÿ—“๏ธ planned. Every number must come from a command in docs/PERFORMANCE.md.
  4. C99, no dependencies, no global state in the core (state lives in the VM; modules use extension slots).
  5. Public API is append-only (include/mcs.h); opcodes are append-only and a format change bumps IMG_VERSION.

Workflow

make check                               # must pass
make asan-test                           # sanitizers (then `make clean && make`)
python3 tools/fuzz.py ./mcs 1000 $RANDOM # for parser/compiler/VM changes
tools/verify_dotnet.sh                   # for language/library changes (needs dotnet 8)
make cm-check                            # for anything that could affect 32-bit targets
python3 tools/gen_stdlib_doc.py > docs/STDLIB.md   # after adding library members

Where things go

Change Code Docs / tests
New syntax src/mcs_lexer.c, src/mcs_parser.c (desugar if possible), src/mcs_compiler.c docs/LANGUAGE.md, tests/t*.cs
New library member src/mcs_lib*.c registration tables regenerate docs/STDLIB.md, add to a test
New opcode append to MCS_OPCODES in src/mcs_internal.h, VM case, disassembler, loader validation docs/BYTECODE.md
New module / peripheral modules/<name>/, public headers only, MCS_ENABLE_<NAME> flag docs/<NAME>.md, FLAG_SETS in the Makefile
New port ports/<target>/ docs/PORTING.md

Style

4-space indent, K&R braces, snake_case, mcs_ prefix for anything public, comments that explain why. Keep hot paths in src/mcs_vm.c allocation-free and remember that the GC only runs at safepoints โ€” new roots must be reachable from mark_roots.

Generated from the MicroCS repository - edit the files there, not in the wiki.

โš ๏ธ **GitHub.com Fallback** โš ๏ธ