Skip to content

Canonical Source

Content auto-synced from README.Files/DevTools.README.md. Edit the source file to make changes.

SmrtHub Dev Tools & Build Scripts

Overview

SmrtHub provides a robust set of development and maintenance tools to ensure a clean, reliable, and efficient build environment for all components. This document explains the available scripts and their locations, as well as their intended usage.

Per-App Clean/Build Scripts

  • Every C# app in CSApps/ has its own dedicated clean and build scripts. Use these for targeted cleaning or building of individual applications.

Per-project ownership and staging parity

  • Some C# apps/libraries under SmrtApps/src/ and some Python modules under SmrtApps/PythonApp/ include per-project scripts (for example: SmrtApps/PythonApp/BuildPythonApp.ps1).
  • These scripts are owned and versioned alongside their project/module and are intended for focused, local workflows.
  • Per-project build scripts stage outputs using the same central layout as the master scripts:
  • Staging root: Apps/<Configuration>/<RuntimeIdentifier>/
  • Per-app folder: Apps/<Configuration>/<RuntimeIdentifier>/<AppName>/
  • Executable path: Apps/<Configuration>/<RuntimeIdentifier>/<AppName>/<AppName>.exe
  • This keeps developer tooling (e.g., Supervisor, launchers) consistent whether you build via the master Tools/Clean-Build/BuildApps.ps1 or a per-project script.

Goal: We aim to include a concise README.md in every C# project and Python module. As you touch a component and it makes sense, add or update its README to cover purpose, how to build/run, and staging conventions.

Centralized Clean/Build Scripts

  • The directory SmrtHub.App/Tools/Clean-Build/ contains scripts for:
  • Cleaning all C# apps (CSApps/), all libraries/apps in src/, or both.
  • Cleaning all log files from %APPDATA%/SmrtHub/Logs.
  • Cleaning all config files from %APPDATA%/SmrtHub/Config.
  • Cleaning the SQLite database (SmrtDB) from %APPDATA%/SmrtHub/SmrtDB.
  • These scripts are designed for comprehensive maintenance and are safe to run as part of regular development or before/after major changes.

Central Apps Staging (for local runs)

We now stage all runnable app outputs into a single, predictable folder so tools (and humans) can find them without chasing project-specific bin paths.

  • Staging root: Apps/<Configuration>/<RuntimeIdentifier>/
  • Per-app layout: Apps/<Configuration>/<RuntimeIdentifier>/<AppName>/<AppName>.exe

Examples (Windows x64, Debug): - Apps/Debug/win-x64/HubWindow/HubWindow.exe

This layout is populated by Tools/Clean-Build/BuildApps.ps1 and by any per-project build scripts that follow the same convention. The SmrtHub Supervisor and other tooling resolve executables using this central location first, falling back to conventional bin/<Configuration>/<RID>/ locations if needed.

BuildApps.ps1 — Build, Stage, and Package Python Core

  • Path: Tools/Clean-Build/BuildApps.ps1

  • Purpose: Builds C# apps (CSApps and src) and stages outputs into the central Apps/ layout. It can also package the Python Core app (SmrtApps/PythonApp) into a Windows EXE via PyInstaller and stage it alongside C# apps.

  • Interactive menu options:

  • 1) CSApps Only
  • 2) SRC Only
  • 3) CSApps + SRC
  • 4) Python Core (package only)

  • 5) CSApps + SRC + Python Core (combined build + package)

  • Key parameters (subset):

  • -Scope: CSApps, SRC, Full Solution, or PythonApp
    • -Scope PythonApp packages Python Core only and exits
  • -Configuration: e.g., Debug, Release
  • -RuntimeIdentifier: e.g., win-x64
  • -Exclude / -ExcludeFile: filter projects by name/pattern

Notes: - The script skips staging if a target app is currently running (safety). - It filters candidates by RID to avoid mixing incompatible outputs. - When packaging Python Core, the EXE is staged to Apps/<Configuration>/<RID>/PythonApp/PythonApp.exe.

See SmrtApps/PythonApp/BuildPythonApp.ps1 and SmrtApps/PythonApp/pyinstaller/README.md for details on the PyInstaller packaging flow.

Python packaging deltas (recent): - Requirements split: requirements.txt now includes requirements.runtime.txt to keep runtime lean; heavy deps (NumPy/OpenCV) were removed. - PyInstaller spec trimmed hiddenimports to only what’s needed (magika, onnxruntime). - The prior Python payload_check.py path was removed; image text-likelihood hints now run in C# (Clipboard utils) using a late-bound Windows OCR quick-check with heuristic fallback.

CleanApps.ps1 — Clean build outputs, staging, and Python Core caches

  • Path: Tools/Clean-Build/CleanApps.ps1
  • Scopes (interactive menu):
  • 1) CSApps
  • 2) SRC
  • 3) All C# Apps (CSApps + SRC)
  • 4) Staging (Apps/Debug + Apps/Release)
  • 5) All C# Apps + Staging
  • 6) Python Core (cleans __pycache__ and .pyc under SmrtApps/PythonApp/python_core)

  • 7) All C# Apps + Staging + Python Core

  • Modes: Basic or Aggressive (quiesce build servers, optional IDE kill; multi-pass).

  • Includes safety checks and long-path handling.

Documentation tasks

  • Use Tools/MKDocs-Creation/BuildMkDocs.ps1 to build or serve the MkDocs site.
  • -Serve to run the dev server (add -Open to auto-open; -Port to change port)
  • Without switches to build a clean static site (outputs to Documentation/site)

VS Code cleaner tasks (matrix)

The workspace defines standardized cleaner tasks so you can pick scope and mode quickly:

  • 1-1: CSApps (Basic) | 1-2-N: CSApps (Aggressive, No Kill)
  • 2-1: SRC (Basic) | 2-2-N: SRC (Aggressive, No Kill)
  • 3-1: Both (Basic) | 3-2-N: Both (Aggressive, No Kill)
  • 4-1: Staging (Basic)| 4-2-N: Staging (Aggressive, No Kill)
  • 5-1: All (Basic) | 5-2-N: All (Aggressive, No Kill)

Each task invokes CleanApps.ps1 with -TargetScope and adds -Aggressive for the *-2-N variants.

VS Code packaging task (Python Core)

  • A convenience task is available to package Python Core without navigating menus:
  • Task: 🐍 Package PythonApp (PyInstaller)
  • Runs: SmrtApps/PythonApp/BuildPythonApp.ps1 -Configuration Debug -RuntimeIdentifier win-x64
  • Staging output: Apps/Debug/win-x64/PythonApp/PythonApp.exe

Use “Tasks: Run Task” in VS Code and select the task to build the EXE and stage it.

Test runners (Tools/Run-Tests)

To make test execution deterministic and easier to debug outside the VS Code Test Explorer aggregation, a small set of PowerShell wrappers lives in Tools/Run-Tests:

  • All-Tests.ps1 — Runs the PythonApp tests first (activates .venv) then runs all discovered C# test projects.
  • Run-PythonApp-Tests.ps1 — Activates the PythonApp virtual environment, sets PYTHONPATH so local packages (for example python_core) are importable, and runs pytest. Supports -CollectOnly and -VerboseOutput switches.
  • Run-CSharp-Tests.ps1 — Discovers *.Tests.csproj under SmrtApps/ and runs dotnet test for each project. Supports -Filter and -NoBuild.

Why: VS Code aggregates test providers (C#, Python, etc.). If one provider fails discovery (for example Python missing pytest or an interpreter issue), the aggregated Test Explorer run can appear to abort and show 0/0 completed. These scripts let contributors run the providers sequentially, capture output, and avoid the silent aggregated failure mode.

VS Code tasks were added that map to these scripts so you can run them from the Command Palette or the Tasks runner:

  • 🧪 Run: All Tests (Python + C#) — runs Tools/Run-Tests/All-Tests.ps1
  • 🧪 Run: PythonApp Tests — runs Tools/Run-Tests/Run-PythonApp-Tests.ps1
  • 🧪 Run: C# Tests (All) — runs Tools/Run-Tests/Run-CSharp-Tests.ps1

Recommended workflow:

  1. Use Run: PythonApp Tests to validate Python discovery and resolve any import/venv issues.
  2. Use Run: C# Tests (All) to run dotnet tests across projects.
  3. Use Run: All Tests to run both in sequence when you want a full verification.

Solution Management

  • In SmrtHub.App/Tools/ you will find UpdateSmrtHubSLN.ps1, a script that can generate three different Visual Studio solution files:
  • CSApps Only: Includes only the C# apps in CSApps/.
  • src/ Only: Includes only the apps and libraries in src/.
  • Full Solution: Includes all SmrtHub apps and libraries.
  • Use this tool to quickly reconfigure your solution for focused development or full builds.

Best Practices

  • Use per-app scripts for isolated work and debugging.
  • Use the centralized scripts for full clean/build cycles, especially before major refactors or releases.
  • Always ensure your environment is clean before running integration or end-to-end tests.

Supervisor Manifest Tokens (dev quality-of-life)

To make paths stable across machines and builds, the Supervisor supports tokenized paths in its component manifest. The most relevant tokens for dev builds are:

  • ${RepoRoot} — path to the repository root
  • ${AppsRoot} — ${RepoRoot}/Apps/${Configuration}/${RuntimeIdentifier}
  • ${Configuration} — e.g., Debug, Release
  • ${RuntimeIdentifier} — e.g., win-x64

Example manifest path: - ${AppsRoot}/HubWindow/HubWindow.exe

The resolver expands tokens and, if needed, falls back to searching conventional bin/<Configuration>/<RID>/ locations under the project.

For more details on individual scripts, see the comments within each script file in SmrtHub.App/Tools/Clean-Build/ and SmrtHub.App/Tools/.

Per-project script index (running list)

Discovered per-project Build/Clean scripts and README presence. ✅ = README present in the same project folder (or obvious subfolder), ❌ = missing.

C# apps (CSApps)

  • SmrtApps/CSApps/HubWindow — Build/Clean scripts: Yes; README: ✅
  • SmrtApps/CSApps/ClipboardMonitor — Build/Clean scripts: Yes; README: ✅
  • SmrtApps/CSApps/MouseHookPipe — Build/Clean scripts: Yes; README: ❌
  • SmrtApps/CSApps/TriggerManager — Build/Clean scripts: Yes; README: ❌

C# apps/libraries (src)

  • SmrtApps/src/Smrt.UI — Build/Clean scripts: Yes; README: ❌
  • SmrtApps/src/Smrt.Utils.Clipboard — Build/Clean scripts: Yes; README: ✅
  • SmrtApps/src/Smrt.Tools.CredentialManager — Build/Clean scripts: Yes; README: ❌

Python modules

  • SmrtApps/PythonApp — Build script: Yes (BuildPythonApp.ps1); README: ❌ (submodules have READMEs)
  • SmrtApps/PythonApp/python_core/utils/README.md — ✅
  • SmrtApps/PythonApp/python_core/smrtdetect/README.md — ✅
  • SmrtApps/PythonApp/pyinstaller/README.md — ✅

Tools (central scripts)

  • Tools/Clean-Build — Build/Clean scripts: Yes (central); README: ❌ (covered throughout this DevTools README)
  • Tools/Documentation Building — Build script: Yes (BuildMkDocs.ps1); README: ❌

If you add a new per-project script, please follow the central staging conventions and include/update the local README.md.