Solves #194 - Root module runtime

The commit proposes a solution for issue #194, which underlines how root module has common name, which may imply name clashes with other existing modules in python ecosystem. The actual implementation: * renames `runtime` module in `qc_framework` module. `runtime` is a submodule for `qc_framework`. The approach allows to introduce other required applications for successful execution of runtime directly, without maintaining multiple module. * `qc_runtime` script is preserved * `runtime` remains the principal executable of the package, and can be launched also with `python -m qc_framework` (for users that do not have python scripts on PATH - in particular Windows users) * Documentation for the framework has been updated in order to reflect the changes * License banner are included for all source file * Github builders definition has been updated to reflect the changes * Dockerfiles have been updated to reflect the changes * All public methods have been documented * Wrong type hinting for model field validation has been corrected Signed-off-by: Matteo Ragni <[email protected]>
asam-ev · Oct 4, 2024 · 4426dd4 · 4426dd4
1 parent 06148f0
commit 4426dd4
Show file tree

Hide file tree

Showing 31 changed files with 143 additions and 91 deletions.
diff --git a/.github/workflows/build-on-change-linux-bare.yaml b/.github/workflows/build-on-change-linux-bare.yaml
@@ -13,7 +13,7 @@ on:
       - test/**
       - .github/workflows/**
       - doc/**
-      - runtime/**
+      - qc_framework/**
       - docker/**
 
   # execute on every push made targeting the branches bellow
@@ -28,7 +28,7 @@ on:
       - test/**
       - .github/workflows/**
       - doc/**
-      - runtime/**
+      - qc_framework/**
       - docker/**
 
   workflow_dispatch: # Allows manual triggering of the workflow
@@ -111,33 +111,33 @@ jobs:
           name: unit-test-report-ubuntu
           path: ${{ github.workspace }}/build/Testing/Temporary/LastTest.log
 
-      - name: Runtime test execution
+      - name: Framework test execution
         run: |
           mv build out_build
           cp -r /home/$(whoami)/qc-build/bin bin
           cp out_build/examples/checker_bundle_example/DemoCheckerBundle bin/
-          cd runtime
+          cd qc_framework
           curl -sSL https://install.python-poetry.org | python3 -
           poetry install --with dev
           poetry run pytest -rA > runtime_test.log
 
-      - name: Archive runtime test results
+      - name: Archive Framework test results
         uses: actions/upload-artifact@v4
         with:
-          name: runtime-test-report-ubuntu
-          path: ${{ github.workspace }}/runtime/runtime_test.log
+          name: framework-test-report-ubuntu
+          path: ${{ github.workspace }}/qc_framework/runtime_test.log
 
       - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
           python-version: '3.10'
 
-      - name: Execute checker bundles runtime
+      - name: Execute checker bundles
         run: |
           export ASAM_QC_FRAMEWORK_MANIFEST_DIR=${{ github.workspace }}/.github/workflows/linux-manifest
           export ASAM_QC_FRAMEWORK_INSTALLATION_DIR=/home/$(whoami)/qc-build/bin
 
-          pip install -e ${{ github.workspace }}/runtime
+          pip install -e ${{ github.workspace }}/qc_framework
 
           mkdir "/home/$(whoami)/odr_out"
           pip install asam-qc-opendrive@git+https://github.com/asam-ev/qc-opendrive@develop

diff --git a/.github/workflows/build-on-change-linux-docker.yaml b/.github/workflows/build-on-change-linux-docker.yaml
@@ -13,7 +13,7 @@ on:
       - test/**
       - .github/workflows/**
       - doc/**
-      - runtime/**
+      - qc_framework/**
       - docker/**
 
   # execute on every push made targeting the branches bellow
@@ -28,7 +28,7 @@ on:
       - test/**
       - .github/workflows/**
       - doc/**
-      - runtime/**
+      - qc_framework/**
       - docker/**
 
 jobs:
@@ -41,7 +41,7 @@ jobs:
       - name: Docker Build
         run: |
           docker build -f docker/Dockerfile.linux --target unit_test -t unit_test .
-          docker build -f docker/Dockerfile.linux --target runtime_test -t runtime_test .
+          docker build -f docker/Dockerfile.linux --target framework_test -t framework_test .
 
       - name: Unit test execution
         if: github.event_name == 'pull_request'
@@ -55,14 +55,14 @@ jobs:
           name: unit-test-report
           path: ${{ github.workspace }}/LastTest.log
 
-      - name: Runtime test execution
+      - name: Framework test execution
         if: github.event_name == 'pull_request'
         run: |
-          docker run -v ${{ github.workspace }}:/out --rm --name runtime_test runtime_test
+          docker run -v ${{ github.workspace }}:/out --rm --name framework_test framework_test
 
-      - name: Archive runtime test results
+      - name: Archive framework test results
         if: github.event_name == 'pull_request' && (success() || failure())
         uses: actions/upload-artifact@v4
         with:
-          name: runtime-test-report
+          name: framework-test-report
           path: ${{ github.workspace }}/runtime_test.log
diff --git a/.github/workflows/build-on-change-windows.yaml b/.github/workflows/build-on-change-windows.yaml
@@ -13,7 +13,7 @@ on:
       - test/**
       - .github/workflows/**
       - doc/**
-      - runtime/**
+      - qc_framework/**
       - docker/**
 
   # execute on every push made targeting the branches bellow
@@ -28,7 +28,7 @@ on:
       - test/**
       - .github/workflows/**
       - doc/**
-      - runtime/**
+      - qc_framework/**
       - docker/**
 
   workflow_dispatch: # Allows manual triggering of the workflow
@@ -147,34 +147,34 @@ jobs:
           name: test-report
           path: ${{ github.workspace }}\build\Testing\Temporary\LastTest.log
 
-      - name: Runtime test execution
+      - name: Framework test execution
         run: |
-          Write-Output "Starting runtime tests..."
+          Write-Output "Starting framework tests..."
 
           Rename-Item -path "$env:WORKING_PATH\qc-framework\qc-framework\build" -NewName "$env:WORKING_PATH\qc-framework\qc-framework\out_build"
           Copy-Item -Path "$env:WORKING_PATH\QC-Framework-Out\bin" -Destination "$env:WORKING_PATH\qc-framework\qc-framework\bin" -Recurse
           Copy-Item -Path "$env:WORKING_PATH\qc-framework\qc-framework\out_build\examples\checker_bundle_example\Release\DemoCheckerBundle.exe" -Destination "$env:WORKING_PATH\qc-framework\qc-framework\bin"
 
-          cd "$env:WORKING_PATH\qc-framework\qc-framework\runtime"
+          cd "$env:WORKING_PATH\qc-framework\qc-framework\qc_framework"
           python3 -m pip install poetry
           python3 -m poetry install
           python3 -m poetry run pytest
-          Write-Output "All runtime tests done."
+          Write-Output "All framework tests done."
         shell: pwsh
 
       - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
           python-version: '3.10'
 
-      - name: Execute checker bundles runtime
+      - name: Execute checker bundles
         run: |
           $env:ASAM_QC_FRAMEWORK_MANIFEST_DIR="$env:WORKING_PATH\qc-framework\qc-framework\.github\workflows\windows-manifest"
           $env:ASAM_QC_FRAMEWORK_INSTALLATION_DIR="$env:WORKING_PATH\QC-Framework-Out\bin"
 
           git config --system core.longpaths true
 
-          pip install -e $env:WORKING_PATH\qc-framework\qc-framework\runtime
+          pip install -e $env:WORKING_PATH\qc-framework\qc-framework\qc_framework
 
           mkdir "$env:WORKING_PATH\odr_out"
           pip install asam-qc-opendrive@git+https://github.com/asam-ev/qc-opendrive@develop

diff --git a/INSTALL.md b/INSTALL.md
@@ -145,29 +145,29 @@ We recommend installing Python modules in a virtual environment. Virtual environ
 Using Virtualenv:
 
 ```bash
-python3 -m venv runtime-venv
-source runtime-venv/bin/activate
+python3 -m venv .venv
+source .venv/bin/activate
 ```
 
 Using Conda:
 
 ```bash
-conda create -y -n runtime-venv python=3.10
-conda activate runtime-venv
+conda create -y -n .venv python=3.10
+conda activate .venv
 ```
 
 ## Install Python Modules
 
 Python modules can be installed using `pip`.
 
 ```bash
-pip install asam-qc-runtime@git+https://github.com/asam-ev/qc-framework@develop#subdirectory=runtime
+pip install asam-qc-framework@git+https://github.com/asam-ev/qc-framework@develop#subdirectory=qc_framework
 ```
 
-**Note:** The above command will install `asam-qc-runtime` from the `develop` branch. If you want to install `asam-qc-runtime` from another branch or tag, replace `@develop` with the desired branch or tag. It is also possible to install from a local directory.
+**Note:** The above command will install `asam-qc-framework` from the `develop` branch. If you want to install `asam-qc-framework` from another branch or tag, replace `@develop` with the desired branch or tag. It is also possible to install from a local directory.
 
 ```bash
-pip install /home/user/qc-framework/runtime
+pip install /home/user/qc-framework/qc_framework
 ```
 
 ## Install ASAM Checker Bundles

diff --git a/doc/manual/demo_pipeline.md b/doc/manual/demo_pipeline.md
@@ -125,7 +125,7 @@ docker run \
 The docker image will automatically:
 - Detect the type of file passed as input.
 - Create the specific config according to [config schema](../doc/schema/config_format.xsd).
-- Execute the runtime with specific checker, result pooling and text result application.
+- Execute the framework with specific checker, result pooling and text result application.
 
 Currently the demo_pipeline will install and execute:
 

diff --git a/doc/manual/file_formats.md b/doc/manual/file_formats.md
@@ -10,7 +10,7 @@ with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 ## Configuration File (`*.xml`)
 
-The runtime configuration settings are stored in a configuration file. This
+The framework configuration settings are stored in a configuration file. This
 file defines which Checker Bundles and what checkers are used, how they are
 parameterized and whether the issues are warnings or errors. If a CheckerBundle
 outputs errors that are not configured in this file, the result pooling removes
@@ -63,7 +63,7 @@ The name `Result.xqar` is reserved for the output of the Result Pooling module.
 * The name `Result.xqar` **MUST NOT** be used as the name of the result `.xqar` file for any Checker Bundle.
 * The file `Result.xqar` can be used as the input file for Report Modules.
 * The result file of each checker bundle must have the postfix `.xqar`. It must be a file name (e.g., `my-bundle-result.xqar`) and must not contain any path (both asolute path and relative path are not allowed).
-* All the result files and the automatically generated `Result.xqar` will be stored in the in the output folder `qc-output-YYYY-MM-DD-HH-MM-SS-*`. It is also possible to configure the output folder path. For more details see the [Runtime Module documentation](runtime_module.md).
+* All the result files and the automatically generated `Result.xqar` will be stored in the in the output folder `qc-output-YYYY-MM-DD-HH-MM-SS-*`. It is also possible to configure the output folder path. For more details see the [Framework Module documentation](python_qc_framework.md).
 
 ## Result File (`*.xqar`)
 

diff --git a/doc/manual/manifest_file.md b/doc/manual/manifest_file.md
@@ -11,8 +11,8 @@ There are two types of manifest files in the framework: **Framework manifest fil
 ## Framework Manifest File
 
 A framework manifest file is a JSON file containing a list of module manifest file paths.
-The [runtime module](runtime_module.md) uses the framework manifest file to discover
-and execute Checker Bundles and Report Modules.
+The [framework executable](python_framework_module.md) uses manifest files to discover
+and execute Checker Bundles, Result Poolers and Report Modules.
 
 The framework manifest file must follow the JSON format as in the example below.
 
@@ -164,7 +164,7 @@ On Linux, environment variables of the form `$name` and `${name}` are supported.
 To register a Checker Bundle or Report Module with the framework:
 * First, a module manifest file must be provided.
 * Second, the path to the module manifest file must be included in the framework manifest file.
-* Last, the framework manifest file can be provided to the [runtime module](runtime_module.md) when triggering a framework execution.
+* Last, the framework manifest file can be provided to the [framework executable](python_qc_framework.md):
   ```bash
   qc_runtime --config=$PATH_TO_CONFIG_FILE --manifest=$PATH_TO_MANIFEST_FILE
   ```
diff --git a/doc/manual/runtime_module.md → doc/manual/python_qc_framework.md b/doc/manual/runtime_module.md → doc/manual/python_qc_framework.md
@@ -1,6 +1,7 @@
-# Runtime module
+# Framework module
 
-The runtime module is responsible of executing the qc-framework modules specified in an input configuration file.
+The Framework module is responsible for the execution of checker bundles, result poolers and result reporters, based 
+upon a defined configuration file. The main executable is implemented in the `runtime` submodule.
 
 Input configuration file need to respect the [config xsd schema](../doc/schema/config_format.xsd)
 
@@ -13,16 +14,17 @@ The runtime module execute the following steps:
 
 ## Installation & Usage
 
-The runtime module can be installed using pip.
+The ASAM QC Framework can be installed using pip.
 
 ```bash
-pip install asam-qc-runtime@git+https://github.com/asam-ev/qc-framework@develop#subdirectory=runtime
+pip install asam-qc-framework@git+https://github.com/asam-ev/qc-framework@develop#subdirectory=qc_framework
 ```
 
-**Note:** The above command will install `asam-qc-runtime` from the `develop` branch. If you want to install `asam-qc-runtime` from another branch or tag, replace `@develop` with the desired branch or tag. It is also possible to install from a local directory.
+**Note:** The above command will install `asam-qc-framework` from the `develop` branch. If you want to install `asam-qc-framework` from another branch or tag, replace `@develop` with the desired branch or tag. It is also possible to install from a local directory.
 
 ```bash
-pip install /home/user/qc-framework/runtime
+# From reporsitory root
+pip install ./qc_framework
 ```
 
 Then, it can be executed as follows.

diff --git a/doc/manual/using_the_framework.md b/doc/manual/using_the_framework.md
@@ -16,13 +16,13 @@ Example configuration files for running the official Checker Bundles for ASAM Op
 
 ## Run the Checker Bundles
 
-The Checker Bundles can be run using the [runtime module](runtime_module.md).
+The Checker Bundles are run by the [quality checker framework](python_qc_framework.md).
 
 ```bash
 qc_runtime --config "PATH_TO_CONFIG_FILE" --manifest "PATH_TO_MANIFEST_FILE"
 ```
 
-The output of the runtime modules are the `.xqar` [result files](file_formats.md) and any other output files from the specified report modules in the configuration file, such as `.txt` files for the text report module. If the ReportGUI is specified, the Report GUI will open.
+The output of the framework are the `.xqar` [result files](file_formats.md) and any other output files from the specified report modules in the configuration file, such as `.txt` files for the text report module. If the ReportGUI is specified, the Report GUI will open.
 
 ## Reporting
 

diff --git a/docker/Dockerfile.linux b/docker/Dockerfile.linux
@@ -36,7 +36,7 @@ COPY doc /app/framework/doc
 COPY CMakeLists.txt /app/framework/CMakeLists.txt
 COPY version /app/framework/version
 COPY licenses /app/framework/licenses
-COPY runtime /app/framework/runtime
+COPY qc_framework /app/framework/qc_framework
 COPY demo_pipeline /app/demo_pipeline
 
 RUN echo "Building framework..." && \
@@ -51,14 +51,14 @@ RUN echo "Building framework..." && \
     echo "Done."
 
 RUN python3 -m pip install --no-cache-dir -r /app/demo_pipeline/requirements.txt && \
-    python3 -m pip install --no-cache-dir /app/framework/runtime && \
+    python3 -m pip install --no-cache-dir /app/framework/qc_framework && \
     python3 -m pip install asam-qc-opendrive@git+https://github.com/asam-ev/qc-opendrive@develop && \
     python3 -m pip install asam-qc-openscenarioxml@git+https://github.com/asam-ev/qc-openscenarioxml@develop && \
     python3 -m pip install asam-qc-otx@git+https://github.com/asam-ev/qc-otx@develop
 
 
-# Runtime test stage
-FROM ubuntu:22.04 as runtime_test
+# Framework test stage
+FROM ubuntu:22.04 as framework_test
 
 # Dependancies installation currently required by ResultPooling and TextReport modules
 RUN echo "Installing Qt..." && \
@@ -74,13 +74,13 @@ RUN  mkdir -p /app
 
 # For testing files
 COPY --from=framework_builder /app/framework /app/framework
-# Copy install directory in runtime image
+# Copy install directory in framework image
 COPY --from=framework_builder /home/root/qc-build/bin /app/framework/bin
 COPY --from=framework_builder /app/framework/build/test /app/framework/test
 # @NOTE this is just because DemoCheckerBundle is not installed by default
 COPY --from=framework_builder /app/framework/build/examples/checker_bundle_example/DemoCheckerBundle /app/framework/bin/
 
-WORKDIR /app/framework/runtime/
+WORKDIR /app/framework/qc_framework/
 
 SHELL ["/bin/bash", "-c"]
 
@@ -89,9 +89,9 @@ COPY --from=framework_builder /usr/local/bin /usr/local/bin
 
 RUN python3 -m pip install poetry==1.8.3
 RUN poetry install --with dev
-CMD poetry run pytest -rA > runtime_test.log && cp /app/framework/runtime/runtime_test.log /out/runtime_test.log
+CMD poetry run pytest -rA > runtime_test.log && cp /app/framework/qc_framework/runtime_test.log /out/runtime_test.log
 
-# Runtime stage
+# Unit Test stage
 FROM framework_builder as unit_test
 CMD ctest --test-dir /app/framework/build -C Release && cp /app/framework/build/Testing/Temporary/LastTest.log /out/
 
@@ -113,7 +113,7 @@ RUN  mkdir -p /app
 # Framework components
 COPY --from=framework_builder /home/root/qc-build/bin /app/framework/bin
 COPY --from=framework_builder /app/demo_pipeline /app/demo_pipeline
-COPY --from=framework_builder /app/framework/runtime /app/framework/runtime
+COPY --from=framework_builder /app/framework/qc_framework /app/framework/qc_framework
 
 # Framework schemas
 COPY --from=framework_builder /app/framework/doc/schema /app/framework/doc/schema

diff --git a/docker/test_runtime.sh b/docker/test_runtime.sh
@@ -10,8 +10,8 @@ cd ..
 DOCKER_BUILDKIT=1 \
   docker build \
   -f docker/Dockerfile.linux \
-  --target runtime_test \
-  -t runtime_test .
+  --target framework_test \
+  -t framework_test .
 
 DOCKER_BUILDKIT=1 \
   docker build \
@@ -21,7 +21,7 @@ DOCKER_BUILDKIT=1 \
 
 docker run \
   -v "$OUTPUT_DIR":/out \
- --rm --name runtime_test runtime_test 
+ --rm --name framework_test framework_test 
 
 docker run --rm \
   -v "$OUTPUT_DIR":/out \

diff --git a/runtime/poetry.lock → qc_framework/poetry.lock b/runtime/poetry.lock → qc_framework/poetry.lock