chore(deps): update sphinx-needs to version 6.3 in pyproject.toml

Author: danwos

.github/workflows/ci.yml

@@ -29,10 +29,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 +50,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:
@@ -73,40 +71,42 @@ jobs:
 
     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 Results
+              uses: actions/upload-artifact@v6
+              if: always()
+              with:
+                name: test-results-linux
+                path: |
+                  ./out/
 
     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
-```