Skip to content

QUICKSTART.md

Latest commit

 

History

History
136 lines (107 loc) · 3.17 KB

QUICKSTART.md

File metadata and controls

136 lines (107 loc) · 3.17 KB
Raw

Quick Start Guide

Step 1: Install Prerequisites

Automated installation (recommended):

Linux/macOS

./scripts/prerequisites.sh

Windows (as Administrator)

.\scripts\prerequisites.ps1

What gets installed:

  • Clang 18+ (Linux/macOS) or Visual Studio 2022 Build Tools (Windows)
  • CMake 3.20+
  • Python 3.12+ with virtual environment
  • SBOM tools: reuse, spdx-tools, ntia-conformance-checker
  • Build essentials and platform-specific libraries

Manual installation: If you prefer manual setup, see README.md for detailed instructions.

Step 2: Activate Python Environment

Linux/macOS

source .venv/bin/activate

Windows

.\.venv\Scripts\Activate.ps1

Step 3: Build and Test

Linux/macOS

./scripts/configure.sh --release
./scripts/build.sh
./scripts/test.sh

Windows

.\scripts\configure.ps1 -Release
.\scripts\build.ps1
.\scripts\test.ps1

Step 4: Generate SBOM (Optional)

Software Bill of Materials (SBOM) for supply chain security:

Linux/macOS

cmake --install build/linux-release

Windows

cmake --install build\windows-msvc-release

This generates:

  • wshell-sbom.spdx (SPDX tag-value format)
  • wshell-sbom.spdx.json (JSON format, NTIA-compliant)

What Happens During Build

  1. Prerequisites Check: Verifies compiler, CMake, Python environment
  2. Configure: CMake sets up build with security hardening flags
  3. Auto-fetch: Downloads Google Test v1.14.0 and cmake-sbom if needed
  4. Build: Compiles with full security hardening (ASLR, DEP, CFG, etc.)
  5. Test: Runs 31+ unit tests
  6. SBOM: Generates software bill of materials (on install)

Dependencies Downloaded Automatically

The project uses CMake FetchContent to automatically download:

  • ✅ Google Test v1.14.0 - Unit testing framework
  • ✅ cmake-sbom - SBOM generation tool
  • ✅ Works out of the box
  • ✅ No manual dependency installation
  • ✅ Consistent test environment

Run the Executable

# Linux/macOS
./build/linux-release/src/main/wshell

# Windows
.\build\windows-msvc-release\src\main\Release\wshell.exe

Pre-Push Validation

Before pushing to GitHub, run all validation steps:

# Linux/macOS - Complete validation
./scripts/clean.sh
./scripts/configure.sh --release
./scripts/build.sh
./scripts/test.sh
./scripts/fuzz.sh          # Fuzz testing
./scripts/benchmark.sh     # Performance benchmarks
cmake --install build/linux-release  # SBOM generation
# Windows - Complete validation
.\scripts\clean.ps1
.\scripts\configure.ps1 -Release
.\scripts\build.ps1
.\scripts\test.ps1
.\scripts\benchmark.ps1
cmake --install build\windows-msvc-release

Why? This ensures:

  • No build failures in CI/CD
  • All tests pass
  • No performance regressions
  • SBOM is valid
  • Security checks complete

Next Steps