Developer Guide

A comprehensive guide for new developers joining the wiRedPanda project. This document provides an overview of the codebase, a learning path, and practical tips.

For build instructions, see the Development Setup. For contribution workflow (PRs, code style, translations), see CONTRIBUTING.md. For Git workflows, see the Git Guide.

Tech Stack

Component	Technology
Language	C++20
UI Framework	Qt 6.2+
Build System	CMake 3.16+ with Ninja
Tests	Qt Test Framework + CTest
CI/CD	GitHub Actions
Crash Reporting	Sentry (Crashpad/Breakpad)
Dependencies	nlohmann/json, json-schema-validator
i18n	Qt Linguist / Weblate

---

Developer Documentation

Codebase Internals

• Architecture Overview — Project structure, layer diagram, module dependencies, core types
• Element System — Class hierarchy, factory, registration, element catalog, code anatomy
• Simulation Engine Internals — Four-state logic, simulation loop, topological sorting, feedback
• Scene and UI — Ports, connections, undo/redo, workspace, MainWindow
• File Format and Code Generation — .panda format, Arduino, SystemVerilog, BeWavedDolphin, i18n
• Testing and CI — Test framework, writing tests, coverage, sanitizers, GitHub Actions

Guides

• Development Setup — Environment setup for all platforms
• Element Creation Guide — Step-by-step walkthrough for adding new elements
• Simulation Guide — Conceptual overview of the simulation model
• Translation Guide — How to contribute translations via Weblate
• Git Guide — Git workflows, branching, conflict resolution

---

Suggested Learning Path

Week 1: Orientation

1. Build the project and run the application.
2. Open example circuits from Examples/ — try counter.panda, decoder.panda, mux_demux.panda.
3. Play with the UI: drag gates, wire them, flip switches, watch LEDs.
4. Run the tests: ctest --preset debug — see them all pass.

Week 2: Read the Code

5. Read one gate end-to-end: Start with And.h → And.cpp → the ElementInfo<And> specialization → StatusOps::statusAndAll().
6. Compare with other gates: Not.cpp, Or.cpp, Xor.cpp — notice the pattern.
7. Read a sequential element: DFlipFlop.cpp — understand edge detection and state storage.
8. Read a test: TestLogicGates.cpp — see how CircuitBuilder and TestUtils work.
9. Trace the simulation loop: Read Simulation::update() to see the five phases.

Week 3: Make a Change

10. Write a test for an existing element — add a truth-table test for Xnor or test a flip-flop's async reset.
11. Break something on purpose: change an AND gate to OR behavior, run the tests, see what fails.
12. Fix a small issue or improve a tooltip string.

Week 4: Build Something

13. Implement a new element following the Element Creation Guide.
14. Add tests for your new element.
15. Open a PR and go through the review process.

---

Starter Tasks

Ordered by difficulty:

Beginner

Task	Skills Practiced
Add a missing truth-table test for an existing gate	Test framework, element API
Add Doxygen comments to GraphicElement.h public methods	Code reading, documentation
Create a new example circuit (.panda file)	Understanding the UI
Fix a typo or improve a UI string	Build system, PR workflow

Intermediate

Task	Skills Practiced
Implement a simple new gate (e.g., 3-input majority)	Full element lifecycle
Add a test for async preset/clear on a flip-flop	Sequential logic testing
Trace and document how an IC loads its internal circuit	Serialization, hierarchical design
Improve an error message in the code generator	CodeGen architecture

Advanced

Task	Skills Practiced
Add a new display variant (e.g., dot matrix)	Qt painting, element rendering
Add export to a new HDL format	Code generation, visitor pattern
Optimize the simulation loop for large circuits	Profiling, performance
Add a new waveform analysis feature to BeWavedDolphin	Signal visualization

---

Tips and Common Pitfalls

Do

• Always build in build/ — never generate artifacts in the source tree
• Use CMake presets — ensures consistent configuration
• Run tests before opening a PR — ctest --preset debug
• Keep CMakeSources.cmake alphabetically sorted — source lists must stay sorted
• Use python3 on Linux/macOS — python may not exist
• End files with a trailing newline — project requirement
• Trim trailing whitespace — no spaces/tabs at line ends
• Use /// for Doxygen docs — never //!

Don't

• Don't cd build/ to run tests — always stay at the project root
• Don't modify CMakeLists.txt to add sources — use CMakeSources.cmake
• Don't add backward-compatibility code for features that haven't been released yet
• Don't change tests to accept incorrect behavior — fix the code instead
• Don't commit build files — the build/ directory is in .gitignore

Slow Builds?

1. Check that ccache is enabled: ccache -s
2. Check that mold is being used: look for mold in CMake output
3. Use Unity Build for faster full compilations
4. The first build will always be slow — subsequent builds are incremental

Common Errors

Error	Likely Cause	Solution
Qt6 not found	Qt not installed or not in PATH	Install Qt 6.2+ and set CMAKE_PREFIX_PATH
Ninja not found	Ninja not installed	apt install ninja-build
undefined reference to ...	.cpp file not listed in CMakeSources.cmake	Add the file to the source list
Tests crash with segfault	Accessing destroyed object	Use ASAN: cmake --preset asan
Tests pass locally but fail in CI	Platform-dependent behavior	Test with the same Qt versions as CI

---

Key Files Reference

File	Purpose
App/Core/Enums.h	All enums: ElementType, ElementGroup, Status
App/Core/StatusOps.h	Four-state logic operations (AND, OR, NOT, XOR)
App/Core/Application.h	Custom QApplication with theme and i18n setup
App/Core/Settings.h	Persistent settings management
App/Core/ThemeManager.h	Theme system (light/dark/system)
App/Core/Priorities.h	Topological sorting and feedback detection
App/Element/GraphicElement.h	Base class for all elements
App/Element/GraphicElementInput.h	Base class for interactive input elements (switches, buttons, clocks)
App/Element/ElementInfo.h	Self-registration template and constraints
App/Element/ElementFactory.h	Factory for creating elements by type
App/Element/ElementMetadata.h	Element metadata (icons, names, capabilities)
App/Element/IC.h	Integrated circuit element
App/Element/ICRegistry.h	Central IC registry with file monitoring
App/Simulation/Simulation.h	Simulation engine and update loop
App/Scene/Scene.h	Main graphics scene
App/Scene/Commands.h	All undo/redo command classes
App/Scene/Workspace.h	File and workspace management
App/Nodes/QNEPort.h	Port base class
App/Nodes/QNEConnection.h	Wire connection class
App/IO/Serialization.h	File format save/load
App/IO/VersionInfo.h	Named predicates for file-format compatibility checks
Tests/Common/TestUtils.h	CircuitBuilder and test helpers
CMakeSources.cmake	Source file lists (add new files here)
CMakePresets.json	Build presets (debug, release, asan, etc.)

---

Glossary

Term	Description
Combinational Circuit	Circuit whose output depends only on current inputs
Sequential Circuit	Circuit with memory elements (flip-flops, latches)
Clock	Periodic signal that synchronizes sequential elements
Rising Edge	Transition from 0 to 1 on the clock signal
Feedback Loop	Path where an output feeds back to an input
Grid Snapping	Automatic alignment of elements to the 16px grid
IC	Integrated Circuit — sub-circuit encapsulated as a component
Latch	Level-sensitive memory element
Flip-Flop	Edge-sensitive memory element
Mux/Demux	Multiplexer/Demultiplexer — signal routing
PCH	Precompiled Header — precompiled header for faster builds
QGraphicsScene	Qt class that manages 2D graphic items
QDataStream	Qt class for binary serialization
Scene	The main scene containing the circuit
Appearance	The SVG used to render an element; user-replaceable via canChangeAppearance
Status	4-value logic state (Unknown, Inactive, Active, Error)
Topological Sort	Ordering that respects dependencies between elements
Tx/Rx	Transmitter/Receiver — wireless mode of the Node element
Unity Build	Compilation technique that groups .cpp files to reduce overhead
Workspace	Working context (open file, modification state)

---

Additional Resources

• Repository: github.com/GIBIS-UNIFESP/wiRedPanda
• Roadmap: GitHub Project
• Translations: Weblate
• Wiki: GitHub Wiki
• Issues: GitHub Issues (look for good first issue)
• Coverage: Codecov