Scripts & Code Quality
Relevant source files
The following files were used as context for generating this wiki page:
FlxOS employs a robust suite of automation scripts designed to maintain high code standards across the project. These scripts handle tasks ranging from static analysis and complexity monitoring to documentation coverage and API cataloging. The system is centralized under a master quality script that orchestrates various specialized checkers to generate unified reports for developers.
The primary goal of the "Scripts & Code Quality" infrastructure is to ensure that the codebase remains maintainable, follows consistent naming and formatting conventions, and avoids technical debt through early detection of complex or circular logic.
Sources: scripts/code_quality.sh:1-5, README.md:126-130
Code Quality Orchestration
The master orchestration is handled by scripts/code_quality.sh. This script serves as a unified interface for running all quality checks and aggregating their outputs into a single Markdown report located at reports/code_quality_report.md.
Execution Flow
The script follows a sequential execution pattern where it verifies the existence of specialized sub-scripts before execution. It uses a helper function, run_check, to manage individual tool execution, capture logs in the reports/ directory, and update the master report with pass/fail statuses.
The diagram shows the sequential flow of checks orchestrated by the master script.
Sources: scripts/code_quality.sh:22-108
Static Analysis and Linting
FlxOS utilizes professional-grade linting tools and custom Python scripts to enforce architectural constraints and style guidelines.
Formatting and Clang-Tidy
The project enforces code style using clang-format and deep static analysis via clang-tidy.
- Check Format:
scripts/check_format.shperforms a dry run usingclang-format --dry-run --Werrorto identify files that do not match the project's style without modifying them. - Auto-Formatting:
scripts/code_format.shprovides a one-command fix for all formatting issues in themain/directory. - Linter:
scripts/run_clang_tidy.shruns extensive checks based on a.clang-tidyconfiguration. It supports an--fixmode for safe auto-corrections and requires acompile_commands.jsontypically generated by the build system.
Sources: scripts/check_format.sh:14-25, scripts/code_format.sh:1-4, scripts/run_clang_tidy.sh:37-65
Naming Conventions
The scripts/check_naming.py script enforces specific casing for different C++ entities to ensure consistency across the project.
| Entity Type | Required Convention | Example |
|---|---|---|
| Classes/Structs | PascalCase | AppManager, WindowManager |
| Functions | camelCase | initSystem(), refreshScan() |
| Macros/Constants | UPPER_SNAKE_CASE | CONFIG_FLXOS_MODE, MAX_PARAMS |
| Filenames (.cpp/.hpp) | PascalCase | Desktop.cpp, ThemeManager.hpp |
Sources: scripts/check_naming.py:12-24, scripts/check_naming.py:73-77
Metric Monitoring
Code Complexity Analysis
The scripts/analyze_complexity.py script monitors the maintainability of the codebase by tracking four key metrics against defined thresholds.
| Metric | Max Threshold | Description |
|---|---|---|
| Function Lines | 80 Lines | Total lines of code in a single function body. |
| Parameter Count | 6 Parameters | Maximum number of arguments in a function signature. |
| Nesting Depth | 4 Levels | Deepest level of nested {} blocks (if/for/while). |
| Cyclomatic Complexity | 15 | Number of independent linear paths through the code. |
Sources: scripts/analyze_complexity.py:15-19, reports/complexity.txt:3-30
Dependency and Include Analysis
scripts/analyze_includes.py builds a dependency graph of the project's source files to prevent architectural degradation. It checks for:
- Circular Dependencies: Recursive include chains that can lead to compilation errors (e.g.,
A.h -> B.h -> A.h). - Include Order: Ensures system headers (
<...>) are included before local headers ("...") or follows a specific internal order. - Header Guards: Verifies the presence of
#pragma onceor standard#ifndefguards in every header file.
Sources: scripts/analyze_includes.py:32-60, scripts/analyze_includes.py:100-128
Documentation and API Management
The project uses automation to track documentation coverage and maintain an up-to-date list of available APIs.
Documentation Coverage
The scripts/check_docs.py script evaluates how well the codebase is documented. It scans for:
- File Headers: Ensuring every source file starts with a license/description comment block.
- Function Docs: Detecting undocumented public functions in header files (using
///or/**markers). - TODO Tracking: Identifying and listing all
TODO,FIXME, andHACKcomments to monitor outstanding technical debt. - Module READMEs: Verifying that every major directory in
main/contains aREADME.md.
Sources: scripts/check_docs.py:14-21, scripts/check_docs.py:23-33, scripts/check_docs.py:35-71
API List Generation
scripts/update_api_list.py is a specialized tool that parses LVGL components to generate LVGL_full_api_list.md. It uses regex to extract function signatures and groups them by prefix (e.g., lv_obj, lv_draw) to provide a searchable catalog of available graphics functions.
The sequence diagram illustrates how the API documentation is automatically harvested from the source components.
Sources: scripts/update_api_list.py:36-82
Summary
The Scripts & Code Quality system in FlxOS provides an automated, multi-layered defense against code rot. By combining standardized tools like clang-format with custom-tailored Python analyzers for complexity and naming, the project maintains a high degree of technical rigor suitable for complex embedded systems. The automated generation of reports ensures that quality metrics are visible and actionable for all contributors.
Sources: scripts/code_quality.sh:100-115, reports/code_quality_report.md:1-10