Updated python and sphinx-needs

.github/workflows/ci.yml

@@ -20,6 +20,12 @@ on:
                 required: false
                 default: "rc"
 
+permissions:
+    checks: write # publish test report as PR check
+    pull-requests: write
+    contents: read
+
+
 concurrency:
     group: ${{ github.head_ref || github.run_id }}
     cancel-in-progress: true
@@ -29,10 +35,9 @@ jobs:
         name: Check (Lint) Commit Messages and Files
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
               with:
                   fetch-depth: 0
-                  ref: ${{ github.event.inputs.target_branch || github.head_ref || github.ref_name }}
 
             - uses: actions/setup-python@v5
               with:
@@ -51,10 +56,9 @@ jobs:
             - lint
         timeout-minutes: 15
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
               with:
                   fetch-depth: 0
-                  ref: ${{ github.event.inputs.target_branch || github.head_ref || github.ref_name }}
 
             - name: install tools, build and test
               env:
@@ -64,49 +68,60 @@ jobs:
                   .\build.ps1
               shell: powershell
 
-            - name: Publish Test Results
-              uses: EnricoMi/publish-unit-test-result-action/windows@v2
+            - name: Publish Test Report
               if: always()
+              uses: mikepenz/action-junit-report@v6
               with:
-                  files: |
-                      out/test-report.xml
+               report_paths: "./out/test-report.xml"
+               detailed_summary: true
+               include_passed: true
+               fail_on_failure: true
+               fail_on_parse_error: true
+               require_tests: true
+               check_name: "Test Results (Windows)"
 
     test-on-linux:
         name: Build and Test on Linux
-        runs-on: ubuntu-22.04
+        runs-on: ubuntu-24.04
         needs:
             - lint
         timeout-minutes: 15
         steps:
-            - uses: actions/checkout@v4
+            - uses: actions/checkout@v6
               with:
                   fetch-depth: 0
-                  ref: ${{ github.event.inputs.target_branch || github.head_ref || github.ref_name }}
-
-            - name: Install build system
-              run: sudo apt-get update && sudo apt-get install cmake ninja-build
 
             - name: Install latest release of llvm (includes clang)
+              if: False
               run: wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 20 all && sudo ln -s /usr/bin/llvm-nm-20 /usr/bin/llvm-nm && sudo apt list --installed | grep llvm
 
             - name: Setup Python
-              uses: actions/setup-python@v2
+              uses: actions/setup-python@v5
               with:
-                  python-version: "3.x"
+                  python-version: "3.13"
 
             - name: Install poetry
               run: |
                 python -m pip install --upgrade poetry
 
-            - name: Install dependencies
+            - name: install tools, build and test
               run: |
-                poetry install
+                ./build.sh
 
-            - name: Run test suite
-              run: |
-                poetry run python -m pytest --verbose --capture=tee-sys
+            - name: Publish Test Report
+              if: always()
+              uses: mikepenz/action-junit-report@v6
+              with:
+               report_paths: "./out/test-report.xml"
+               detailed_summary: true
+               include_passed: true
+               fail_on_failure: true
+               fail_on_parse_error: true
+               require_tests: true
+               check_name: "Test Results (Linux)"
 
     release:
+        if: ${{ github.repository == 'avengineers/hammocking' }}
         needs:
             - lint
             - test-on-windows

.gitignore

@@ -1,6 +1,9 @@
 # Output directory of tests
 /out
 
+# Apple
+.DS_Store
+
 # Any log directory
 **/[Ll][Oo][Gg]/*
 

.readthedocs.yml

@@ -6,9 +6,9 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-    os: ubuntu-20.04
+    os: ubuntu-22.04
     tools:
-        python: "3.10"
+        python: "3.13"
     jobs:
         post_create_environment:
             # Install poetry

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
     "files.insertFinalNewline": true,
+    "files.trimTrailingWhitespace": true,
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true,
     "python.formatting.provider": "black",

LINUX_QUICKSTART.md

@@ -0,0 +1,109 @@
+# Linux Quickstart Guide
+
+This guide helps you get started with **hammocking** on Linux.
+
+## Prerequisites
+
+### Required
+- Python 3.10 or higher (3.13 recommended)
+- Git
+
+### Optional (for integration tests)
+- clang/llvm
+- ninja-build
+
+### Installing Prerequisites on Ubuntu/Debian
+
+```bash
+# Install Python 3.13
+sudo apt update
+sudo apt install python3.13 python3.13-venv python3-pip
+
+# Optional: Install build tools for integration tests
+sudo apt install clang ninja-build llvm
+```
+
+## Installation
+
+### Using the build script
+
+```bash
+# Clone the repository
+git clone https://github.com/avengineers/hammocking
+cd hammocking
+
+# Install dependencies
+./build.sh --install
+
+# Run full build (includes lint, test, docs)
+./build.sh
+```
+
+## Common Tasks
+
+The common tasks are separated as functions within `./build.sh`.
+
+## Setup Development Environment
+
+```bash
+# Complete setup with pre-commit hooks
+./build.sh --setup
+
+# Or manually
+poetry install
+poetry run pre-commit install
+```
+
+## build.sh Targets Reference
+
+Run `./build.sh --help` to see all available targets.
+
+## Troubleshooting
+
+### Poetry Not Found
+If `poetry` command is not found after installation:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+Add this to your `~/.bashrc` or `~/.zshrc` to make it permanent.
+
+### Python Version Issues
+Check your Python version:
+```bash
+python3 --version
+```
+
+If you need to use a specific Python version with poetry:
+```bash
+poetry env use python3.13
+```
+
+### Integration Test Failures
+If integration tests fail due to missing clang:
+```bash
+# Skip integration tests
+poetry run pytest -v -m "not integration"
+
+# Or install clang
+sudo apt install clang
+```
+
+### Lock File Issues
+If you see "poetry.lock changed" errors:
+```bash
+poetry lock
+poetry install
+```
+
+## Getting Help
+
+- Documentation: Built docs at `out/docs/html/index.html` after running `./build.sh`
+- Issues: https://github.com/avengineers/hammocking/issues
+- Main command help: `poetry run python -m hammocking --help`
+
+## Next Steps
+
+1. Read the full documentation: `./build.sh && firefox out/docs/html/index.html`
+2. Explore the examples in `docs/usage/examples/`
+3. Check out the test files in `tests/` to see how to use the API

README.md

@@ -32,18 +32,37 @@
 
 Automatic mocking tool for C
 
-## Installation of Dependencies
+## Installation and Building
 
+### On Windows
+
+#### Install Dependencies
 ```powershell
 .\build.ps1 -install
 ```
 
-## Building
+#### Build
+```powershell
+.\build.ps1
+```
 
+### On Linux/macOS
+
+#### Quick Start
+```bash
+
+# Using build script
+./build.sh          # Normal build
+./build.sh --clean  # Clean build
+./build.sh --install # Install only
+```
+
+#### Prerequisites
+- Python 3.10+ (Python 3.13 recommended)
+- Poetry (will be auto-installed)
+- For running integration tests: clang/llvm, cmake, ninja-build
+
+#### What the Build Does
 -   Pre-Commit checks and linting
 -   Execution of all tests
 -   Building documentation
-
-```powershell
-.\build.ps1
-```

build.ps1

@@ -43,7 +43,7 @@ function Invoke-CommandLine {
 
 function Invoke-Bootstrap {
     # Download bootstrap scripts from external repository
-    Invoke-RestMethod https://raw.githubusercontent.com/avengineers/bootstrap-installer/v1.17.1/install.ps1 | Invoke-Expression
+    Invoke-RestMethod https://raw.githubusercontent.com/avengineers/bootstrap-installer/v1.19.0/install.ps1 | Invoke-Expression
     # Execute bootstrap script
     . .\.bootstrap\bootstrap.ps1
 }