📝 Doc updates #216

Workflow file for this run

	# =========================================================================
	# Ceedling - Test-Centered Build System for C
	# ThrowTheSwitch.org
	# Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
	# SPDX-License-Identifier: MIT
	# =========================================================================

	# -----------------------------------------------------------------------
	# Continuous Integration Workflow
	#
	# Purpose:
	# Run the full test suite and verify a clean gem build on every push.
	# No releases are created here — publishing is handled by prerelease.yml
	# and release.yml, which trigger only on intentional Git tags.
	#
	# Triggers:
	# - Push to any branch
	# - Pull request targeting master
	# - Manual dispatch (workflow_dispatch)
	#
	# Skip-CI:
	# Add any of the following to your commit message to skip this workflow:
	# [skip ci] [ci skip] [no ci] [skip actions] [actions skip]
	# Note: skip keywords have no effect on workflow_dispatch runs.
	#
	# Branch exclusions:
	# To permanently exclude a branch pattern from CI, add a branches-ignore
	# list under the push: trigger below (e.g. docs/, wip/).
	# -----------------------------------------------------------------------

	---
	name: CI

	# Triggers the workflow on push to any branch (tag pushes excluded — handled by
	# prerelease.yml and release.yml), pull requests targeting master, or manual dispatch
	on:
	push:
	branches:
	- '' # All branches; branches: [''] scopes push to refs/heads/ only,
	# excluding refs/tags/ pushes — see Skip-CI above
	pull_request:
	branches: [master]
	workflow_dispatch:


	# Cancel any in-progress run on the same ref when a new push arrives,
	# preventing stale run pile-up on active branches
	concurrency:
	group: ci-${{ github.ref }}
	cancel-in-progress: true


	permissions:
	contents: read


	jobs:
	# Job: Build MkDocs HTML documentation bundle for gem inclusion
	generate-docs:
	name: "Generate Local Docs Bundle for Gem Inclusion"
	uses: ./.github/workflows/_generate-docs.yml


	# Job: Linux test suite
	tests-linux:
	name: "Linux Test Suite"
	needs: generate-docs
	runs-on: ubuntu-latest
	strategy:
	fail-fast: false
	matrix:
	ruby: ['3.0', '3.1', '3.2', '3.3', '3.4', '3.5']
	steps:
	# Checks out repository under $GITHUB_WORKSPACE — must come first to enable local action access
	- name: Checkout Latest Repo
	uses: actions/checkout@v4
	with:
	submodules: recursive

	# Common set up steps
	- name: Set Up Ruby Test Environment
	uses: ./.github/actions/setup
	with:
	ruby: ${{ matrix.ruby }}

	# Workaround: Fix Ruby toolcache Gem directory permissions (Bundler exit 38)
	# This is an environmental Ruby/toolcache issue, not a Bundler issue; the fix must
	# run after setup-ruby (which populates the toolcache) but before bundle install.
	# Issue: https://github.com/rubygems/rubygems/issues/7983
	- name: Apply Workaround for Ruby toolcache Gem Directory Permissions
	run: \|
	sudo chmod -R go-w /opt/hostedtoolcache/Ruby///lib/ruby/gems/**/gems \|\| true

	# Install Gem Dependencies
	- name: Install Gem Dependencies
	# Ensure local installation to prevent system directory permission problems
	run: \|
	bundle install

	# Run unit tests immediately after gem install — before the slower external tool
	# installation steps — so unit failures surface as quickly as possible.
	# Unit tests have no dependency on gdb, valgrind, cppcheck, gcovr, or ReportGenerator.
	- name: Run Unit Tests
	env:
	CI_RSPEC_PROGRESS_FORMAT: true
	run: rake specs:units

	# Install gdb for backtrace feature testing
	- name: Install gdb for Backtrace Feature Testing
	run: \|
	sudo apt-get update -qq
	sudo apt-get install --assume-yes --quiet gdb

	# Install valgrind for Valgrind plugin testing
	- name: Install valgrind for Valgrind Feature Testing
	run: \|
	sudo apt-get update -qq
	sudo apt-get install --assume-yes --quiet valgrind

	# Build cppcheck from source at a pinned version so all plugin options
	# (including SARIF, which requires 2.16+) are available for testing.
	# The installed binary is cached by version to avoid rebuilding on every run.
	- name: Cache cppcheck binary and data files
	id: cache-cppcheck
	uses: actions/cache@v4
	with:
	path: \|
	/usr/local/bin/cppcheck
	/usr/local/share/cppcheck
	key: cppcheck-${{ env.CPPCHECK_VERSION }}-linux
	env:
	CPPCHECK_VERSION: '2.16.0'

	- name: "Build and Install cppcheck for Tests of Ceedling Plugin: Cppcheck"
	if: steps.cache-cppcheck.outputs.cache-hit != 'true'
	env:
	CPPCHECK_VERSION: '2.16.0'
	run: \|
	sudo apt-get install --assume-yes --quiet cmake
	wget -q https://github.com/danmar/cppcheck/archive/refs/tags/${CPPCHECK_VERSION}.tar.gz -O cppcheck.tar.gz
	tar xzf cppcheck.tar.gz
	cmake -S cppcheck-${CPPCHECK_VERSION} -B cppcheck-build -DCMAKE_BUILD_TYPE=Release -DUSE_MATCHCOMPILER=ON -DFILESDIR=/usr/local/share/cppcheck
	cmake --build cppcheck-build --parallel $(nproc)
	sudo cmake --install cppcheck-build

	# --break-system-packages is required on Ubuntu 24.04+
	# (PEP 668 prevents pip from installing to the system Python environment without explicit opt-in)
	- name: "Install GCovr for Tests of Ceedling Plugin: Gcov"
	run: \|
	pip install --break-system-packages gcovr

	# Install ReportGenerator for Gcov plugin
	# Fix PATH before tool installation
	# https://stackoverflow.com/questions/59010890/github-action-how-to-restart-the-session
	- name: "Install ReportGenerator for Tests of Ceedling Plugin: Gcov"
	run: \|
	mkdir --parents $HOME/.dotnet/tools
	echo "$HOME/.dotnet/tools" >> $GITHUB_PATH
	dotnet tool install --global dotnet-reportgenerator-globaltool

	# Run system tests via the run-system-tests action (CI batch debug mode: failures only preserved)
	- name: Run System Tests
	uses: ./.github/actions/run-system-tests
	with:
	ruby: ${{ matrix.ruby }}

	# Common plugin test steps
	- name: Run Plugin Tests
	uses: ./.github/actions/run-plugin-tests


	# Job: Windows test suite
	tests-windows:
	name: "Windows Test Suite"
	needs: generate-docs
	runs-on: windows-latest
	strategy:
	fail-fast: false
	matrix:
	# Ruby 3.5 not available on Windows runners [July 2026]
	ruby: ['3.0', '3.1', '3.2', '3.3', '3.4']
	steps:
	# Checks out repository under $GITHUB_WORKSPACE — must come first to enable local action access
	- name: Checkout Latest Repo
	uses: actions/checkout@v4
	with:
	submodules: recursive

	# Windows Defender real-time monitoring scans every file touched during gem installation
	# and C compilation, adding 5–15 minutes of overhead per run. Disable it for CI performance.
	- name: Disable Windows Defender real-time monitoring
	shell: powershell
	run: Set-MpPreference -DisableRealtimeMonitoring $true

	# Common set up steps
	- name: Set Up Ruby Test Environment
	uses: ./.github/actions/setup
	with:
	ruby: ${{ matrix.ruby }}

	# Install Gem Dependencies
	- name: Install Gem Dependencies
	# Ensure local installation to prevent system directory permission problems
	run: \|
	bundle install

	# Run unit tests immediately after gem install — before the slower external tool
	# installation steps — so unit failures surface as quickly as possible.
	# Unit tests have no dependency on gcovr, ReportGenerator, or cppcheck.
	- name: Run Unit Tests
	env:
	CI_RSPEC_PROGRESS_FORMAT: true
	run: rake specs:units

	# Install GCovr for Gcov plugin test
	- name: "Install GCovr for Tests of Ceedling Plugin: Gcov"
	run: \|
	pip install gcovr

	# Install ReportGenerator for Gcov plugin test
	- name: "Install ReportGenerator for Tests of Ceedling Plugin: Gcov"
	run: \|
	dotnet tool install --global dotnet-reportgenerator-globaltool

	# Install cppcheck via Chocolatey (installs the MSI to C:\Program Files\Cppcheck\).
	# Add the real install directory to PATH ahead of the Chocolatey shim so that
	# cppcheck can locate its cfg/ directory (needed for std.cfg library lookups).
	- name: "Install cppcheck for Tests of Ceedling Plugin: Cppcheck"
	run: \|
	choco upgrade cppcheck -y
	echo "C:\Program Files\Cppcheck" >> $env:GITHUB_PATH

	# Run system tests via the run-system-tests action (CI batch debug mode: failures only preserved)
	- name: Run System Tests
	uses: ./.github/actions/run-system-tests
	with:
	ruby: ${{ matrix.ruby }}

	# Common plugin test steps
	- name: Run Plugin Tests
	uses: ./.github/actions/run-plugin-tests


	# Job: macOS test suite
	# Targets Apple Clang (the gcc alias on macOS resolves to Xcode's LLVM-based Clang).
	# Homebrew GCC is effectively covered by the Linux job, so no compiler matrix is needed.
	# Ruby matrix starts at 3.1: macos-latest runs on Apple Silicon (ARM64), and ruby/setup-ruby
	# has no pre-built binary for Ruby 3.0 on ARM64.
	# Note for the future: Ruby 3.1 will itself be dropped starting with macOS 26.
	tests-macos:
	name: "macOS Test Suite"
	needs: generate-docs
	runs-on: macos-latest
	strategy:
	fail-fast: false
	matrix:
	ruby: ['3.1', '3.2', '3.3', '3.4', '3.5']
	steps:
	# Checks out repository under $GITHUB_WORKSPACE — must come first to enable local action access
	- name: Checkout Latest Repo
	uses: actions/checkout@v4
	with:
	submodules: recursive

	# Common set up steps
	- name: Set Up Ruby Test Environment
	uses: ./.github/actions/setup
	with:
	ruby: ${{ matrix.ruby }}

	# No toolcache permissions workaround — that step targets /opt/hostedtoolcache (Linux-specific path)

	# Install Gem Dependencies
	# force_ruby_platform bypasses Bundler's multi-platform gem resolution, which fails on
	# macOS ARM64 due to mixed versioned/generic platform strings in the lockfile.
	# All Ceedling gem dependencies are pure Ruby, so this has no functional effect.
	- name: Install Gem Dependencies
	run: \|
	bundle config set --local force_ruby_platform true
	bundle install

	# Run unit tests immediately after gem install — before the slower external tool
	# installation steps — so unit failures surface as quickly as possible.
	# Unit tests have no dependency on cppcheck, gcovr, or ReportGenerator.
	- name: Run Unit Tests
	env:
	CI_RSPEC_PROGRESS_FORMAT: true
	run: rake specs:units

	# gdb is not installed on macOS runners — backtrace specs detect absence and skip
	# valgrind is unavailable on macOS — valgrind specs already skip via @valgrind_available guard

	# Install cppcheck via Homebrew
	- name: "Install cppcheck for Tests of Ceedling Plugin: Cppcheck"
	run: \|
	brew install cppcheck

	# --break-system-packages required on macOS 14+ (PEP 668 prevents pip from installing
	# to the system Python environment without explicit opt-in, same as Ubuntu 24.04+)
	- name: "Install GCovr for Tests of Ceedling Plugin: Gcov"
	run: \|
	pip install --break-system-packages gcovr

	# Install ReportGenerator for Gcov plugin
	# Fix PATH before tool installation
	# https://stackoverflow.com/questions/59010890/github-action-how-to-restart-the-session
	- name: "Install ReportGenerator for Tests of Ceedling Plugin: Gcov"
	run: \|
	mkdir -p $HOME/.dotnet/tools
	echo "$HOME/.dotnet/tools" >> $GITHUB_PATH
	dotnet tool install --global dotnet-reportgenerator-globaltool

	# Run system tests via the run-system-tests action (CI batch debug mode: failures only preserved)
	- name: Run System Tests
	uses: ./.github/actions/run-system-tests
	with:
	ruby: ${{ matrix.ruby }}

	# Common plugin test steps
	- name: Run Plugin Tests
	uses: ./.github/actions/run-plugin-tests


	# Job: Preprocessing locale encoding regression test
	# Installs ja_JP.UTF-8 locale and runs the locale encoding spec under it.
	# This replicates issue #1160's root cause: GCC under a non-C locale outputs
	# localized preprocessor markers (e.g. <組み込み> for <built-in>) that Ceedling
	# must handle without raising encoding errors.
	# Note: No generate-docs dependency or docs download needed — system tests use
	# a path-based Bundler deployment (deploy_gem) that does not require a gem build.
	tests-linux-locale:
	name: "Linux Test Suite (ja_JP.UTF-8 Locale)"
	runs-on: ubuntu-latest
	steps:
	- uses: actions/cache@v4
	with:
	path: vendor/bundle
	key: bundle-use-ruby-${{ runner.os }}-3.3-${{ hashFiles('**/Gemfile.lock') }}
	restore-keys: \|
	bundle-use-ruby-${{ runner.os }}-3.3-

	- name: Checkout Latest Repo
	uses: actions/checkout@v4
	with:
	submodules: recursive

	- name: Set Up Ruby
	uses: ruby/setup-ruby@v1
	with:
	ruby-version: '3.3'

	- name: Apply Workaround for Ruby toolcache Gem Directory Permissions
	run: \|
	sudo chmod -R go-w /opt/hostedtoolcache/Ruby///lib/ruby/gems/**/gems \|\| true

	- name: Install Gem Dependencies
	run: \|
	bundle install

	- name: Install ja_JP.UTF-8 Locale
	run: \|
	sudo locale-gen ja_JP.UTF-8
	sudo update-locale
	locale -a

	- name: Run Preprocessing Locale Spec under ja_JP.UTF-8
	env:
	LC_ALL: ja_JP.UTF-8
	LANG: ja_JP.UTF-8
	CI_RSPEC_PROGRESS_FORMAT: true
	run: \|
	rake spec:system:debug:preprocessing_locale

	# Passing project directories are deleted immediately by done!; passing logs are never written.
	# This step is retained as a safety net in case of any leftover pass artifacts.
	- name: Remove passing system test artifacts before upload
	if: failure()
	shell: bash
	run: \|
	rm -rf systests/proj/pass \|\| true
	rm -f systests/systest.pass.*.log \|\| true

	# Upload system test failure logs and temp project directories on test job failure
	- name: Upload system test failure artifacts
	if: failure()
	uses: actions/upload-artifact@v4
	with:
	name: systest-failures-locale-ruby-3.3
	path: systests/
	if-no-files-found: ignore


	# Job: Default-encoding stress test against example projects
	# Forces Ruby's default external encoding to US-ASCII (via LC_ALL=C) and exports +
	# fully tests example projects with differing preprocessing configurations, catching
	# regressions in Ceedling's handling of non-ASCII source content under a non-UTF-8
	# platform default encoding.
	# Note: No generate-docs dependency needed — system tests use a path-based Bundler
	# deployment (deploy_gem) that does not require a gem build.
	tests-linux-encoding-stress:
	name: "Linux Encoding Stress Test (C/POSIX)"
	runs-on: ubuntu-latest
	steps:
	- uses: actions/cache@v4
	with:
	path: vendor/bundle
	key: bundle-use-ruby-${{ runner.os }}-3.3-${{ hashFiles('**/Gemfile.lock') }}
	restore-keys: \|
	bundle-use-ruby-${{ runner.os }}-3.3-

	- name: Checkout Latest Repo
	uses: actions/checkout@v4
	with:
	submodules: recursive

	- name: Set Up Ruby
	uses: ruby/setup-ruby@v1
	with:
	ruby-version: '3.3'

	- name: Apply Workaround for Ruby toolcache Gem Directory Permissions
	run: \|
	sudo chmod -R go-w /opt/hostedtoolcache/Ruby///lib/ruby/gems/**/gems \|\| true

	- name: Install Gem Dependencies
	run: \|
	bundle install

	# LC_ALL/LANG=C (POSIX) is the stress pick: it's always available (no locale-gen
	# needed, unlike the ja_JP.UTF-8 job above) and it's the locale under which Ruby's
	# Encoding.default_external resolves to US-ASCII rather than UTF-8 on Linux. That's
	# the actual condition under test — source files here are UTF-8, but the platform
	# default encoding is 7-bit ASCII, which is what surfaces bugs in code that reads
	# or scans file content without accounting for the platform's default encoding.
	# These env vars set the job-level default before RSpec boots; the spec itself
	# additionally re-asserts them per-invocation since SystemContext#with_context
	# otherwise forces en_US.UTF-8 ahead of each nested Ceedling call.
	- name: Run Example Projects Under C/POSIX Default Encoding Stress
	env:
	LC_ALL: C
	LANG: C
	CI_RSPEC_PROGRESS_FORMAT: true
	run: \|
	rake spec:system:debug:encoding_stress

	# Passing project directories are deleted immediately by done!; passing logs are never written.
	# This step is retained as a safety net in case of any leftover pass artifacts.
	- name: Remove passing system test artifacts before upload
	if: failure()
	shell: bash
	run: \|
	rm -rf systests/proj/pass \|\| true
	rm -f systests/systest.pass.*.log \|\| true

	# Upload system test failure logs and temp project directories on test job failure
	- name: Upload system test failure artifacts
	if: failure()
	uses: actions/upload-artifact@v4
	with:
	name: systest-failures-encoding-stress-ruby-3.3
	path: systests/
	if-no-files-found: ignore


	# Job: Build the Ceedling gem once all tests pass
	# Verifies a clean gem build is possible; the built gem is uploaded as a
	# downloadable workflow artifact. No release is created here.
	build-gem:
	name: "Validate Ceedling Gem Build"
	needs:
	- tests-linux
	- tests-windows
	- tests-macos
	- tests-linux-locale
	- tests-linux-encoding-stress
	runs-on: ubuntu-latest

	steps:
	# Use a cache for our tools to speed up builds
	# No matrix here; Ruby version is hardcoded to match the cache key format used by test jobs
	- uses: actions/cache@v4
	with:
	path: vendor/bundle
	key: bundle-use-ruby-${{ runner.os }}-3.3-${{ hashFiles('**/Gemfile.lock') }}
	restore-keys: \|
	bundle-use-ruby-${{ runner.os }}-3.3-

	- name: Checkout Latest Repo
	uses: actions/checkout@v4
	with:
	submodules: recursive

	- name: Set Up Ruby
	uses: ruby/setup-ruby@v1
	with:
	ruby-version: '3.3'

	- name: Install Gem Dependencies
	run: \|
	bundle install

	# Download HTML docs bundle built by generate-docs job to validate docs ingestion in gem build
	- name: Download HTML Documentation Bundle
	uses: actions/download-artifact@v4
	with:
	name: gem-docs-site-local
	path: site-local/

	- name: Build Ceedling Gem
	run: \|
	gem build ceedling.gemspec

	# Upload the built gem as a workflow artifact (downloadable from the Actions UI)
	- name: Upload Built Gem Artifact
	uses: actions/upload-artifact@v4
	with:
	name: ceedling-gem
	path: ceedling-*.gem
	if-no-files-found: error

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

📝 Doc updates #216

Workflow file

📝 Doc updates #216

Uh oh!

Workflow file for this run