Developer & Contributing Hub

Welcome to the fsmc Developer & Contributing Hub. Whether you are extending the compiler with new frontend parsers, implementing middle-end optimization passes, adding target code emitters, or optimizing the zero-heap C++ runtime, this section provides the resources and guidelines you need.

---

Contributing Resources

Resource	Focus Area	Description	Link
Developer Guide & Recipes	Extensibility & Workflows	Step-by-step developer recipes for adding parsers, middle-end passes, serializers, and runtime features.	Developer Guide
Test Suite Catalog	Quality & Verification	Comprehensive catalog of all 89 CTest targets with test scenarios and intents.	Test Suite Catalog
CMake Integration Reference	Build System Automation	Documentation of fsmc_target_sources macro and imported CMake interface libraries.	CMake Reference
Compiler Architecture	Pipeline & Drivers	Detailed design of compiler stages, data flow, and Intermediate Representation.	Compiler Architecture
Canonical IR AST Specification	Data Model	Formal specification of FsmIr, StateNode, TransitionEdge, and port definitions.	IR Specification
Release Changelog	Version History	Comprehensive log of all additions, architectural improvements, and breaking changes per release.	Changelog (GitHub)

---

Fast-Track Contribution Workflow

1. Fork and Clone the Repository:

   git clone https://github.com/simoneCavalleri/fsmc.git
   cd fsmc
   

2. Configure and Build C++ Targets:

   cmake -B build -DCMAKE_BUILD_TYPE=Debug -DFSMC_ENABLE_TESTING=ON
   cmake --build build -j$(nproc)
   

3. (Optional) Setup Documentation Environment:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements-docs.txt
   

4. Run the Full Verification Pipeline:

   # Step A: Ensure standalone runtime headers are synchronized
   python3 scripts/generate_standalone_runtime.py --check
   
   # Step B: Run all 89 CTest targets (100% must pass)
   ctest --test-dir build --output-on-failure
   
   # Step C: Verify documentation builds with zero errors
   mkdocs build
   
   # Step D: (Optional) Live preview local documentation server
   mkdocs serve
   

5. Submit a Pull Request:

6. Ensure all code compiles cleanly without warnings under -Wall -Wextra -Wpedantic -Werror.
7. Write unit tests following the Arrange-Act-Assert (AAA) pattern with standard Doxygen documentation blocks.