Build script to build liboqs

.github/workflows/build-script-test.yml

@@ -0,0 +1,271 @@
+name: Build Script Test
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [ main,charishma_build_script ]
+    paths:
+      - 'build_liboqs.sh'
+      - 'requirements.txt'
+      - 'CMakeLists.txt'
+      - 'src/**/CMakeLists.txt'
+      - '.github/workflows/build-script-test.yml'
+  pull_request:
+    paths:
+      - 'build_liboqs.sh'
+      - 'requirements.txt'
+      - 'CMakeLists.txt'
+      - 'src/**/CMakeLists.txt'
+      - '.github/workflows/build-script-test.yml'
+  workflow_dispatch:
+
+jobs:
+  test-build-script:
+    name: Test build script on ${{ matrix.os }} - ${{ matrix.test-name }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Essential Ubuntu tests - covers core functionality
+          - os: ubuntu-latest
+            test-name: default-build
+            script-args: ""
+            description: "Default configuration (most common use case)"
+
+          - os: ubuntu-latest
+            test-name: minimal-build
+            script-args: '--minimal-build "KEM_ml_kem_768;SIG_ml_dsa_44"'
+            description: "Minimal build with specific algorithms"
+            test-kem-alg: "ML-KEM-768"
+            test-sig-alg: "ML-DSA-44"
+
+          - os: ubuntu-latest
+            test-name: shared-no-openssl
+            script-args: "--shared --no-openssl"
+            description: "Shared library without OpenSSL"
+
+          # Cross-platform verification - macOS tests
+          - os: macos-latest
+            test-name: default-build
+            script-args: ""
+            description: "Verify script works on macOS"
+
+          - os: macos-latest
+            test-name: minimal-build-multi-alg
+            script-args: '--minimal-build "KEM_ml_kem_512;KEM_ml_kem_768;KEM_ml_kem_1024;SIG_ml_dsa_44;SIG_ml_dsa_65;SIG_falcon_512"'
+            description: "Minimal build with multiple algorithms on macOS"
+            test-kem-alg: "ML-KEM-768"
+            test-sig-alg: "ML-DSA-44"
+
+          # NixOS test - verify Nix flake integration
+          - os: ubuntu-latest
+            test-name: nixos-flake
+            script-args: ""
+            description: "Test NixOS/Nix flake integration"
+            use-nix: true
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # pin@v4.2.2
+
+      - name: Install Nix (for NixOS tests)
+        if: matrix.use-nix == true
+        uses: nixbuild/nix-quick-install-action@v28
+        with:
+          nix_conf: |
+            experimental-features = nix-command flakes
+
+      - name: Make build script executable
+        run: chmod +x build_liboqs.sh
+
+      - name: Run build script - ${{ matrix.test-name }} (NixOS)
+        if: matrix.use-nix == true
+        env:
+          SKIP_STALENESS_CHECK: 1
+        run: |
+          # Simulate NixOS by unsetting IN_NIX_SHELL to test auto-detection
+          unset IN_NIX_SHELL
+          # The script should automatically re-execute itself with 'nix develop -c'
+          ./build_liboqs.sh ${{ matrix.script-args }}
+
+      - name: Run build script - ${{ matrix.test-name }} (non-NixOS)
+        if: matrix.use-nix != true
+        env:
+          SKIP_STALENESS_CHECK: 1
+        run: ./build_liboqs.sh ${{ matrix.script-args }}
+
+      - name: Verify build artifacts exist
+        run: |
+          if [ ! -d "build" ]; then
+            echo "Error: build directory not created"
+            exit 1
+          fi
+          if [ ! -f "build/lib/liboqs.a" ] && [ ! -f "build/lib/liboqs.dylib" ] && [ ! -f "build/lib/liboqs.so" ]; then
+            echo "Error: liboqs library not found"
+            exit 1
+          fi
+          echo "✓ Build artifacts verified"
+
+      - name: Run basic library test
+        run: |
+          cd build
+          # Check if test executables exist and run a quick test
+          if [ -f "tests/test_kem" ]; then
+            echo "Running KEM test..."
+            # Use specified algorithm if provided, otherwise auto-detect
+            if [ -n "${{ matrix.test-kem-alg }}" ]; then
+              KEM_ALG="${{ matrix.test-kem-alg }}"
+              echo "Testing with specified algorithm: $KEM_ALG"
+            else
+              # Get list of available algorithms and pick the first one
+              KEM_ALG=$(./tests/test_kem 2>&1 | grep "algname:" | sed 's/.*algname: //' | cut -d',' -f1 | tr -d ' ')
+              echo "Testing with first available algorithm: $KEM_ALG"
+            fi
+
+            if [ -n "$KEM_ALG" ]; then
+              ./tests/test_kem "$KEM_ALG"
+              echo "✓ KEM test passed with $KEM_ALG"
+            else
+              echo "⚠ Could not determine available KEM algorithms"
+            fi
+          else
+            echo "KEM test executable not found (may be disabled in minimal build)"
+          fi
+
+          if [ -f "tests/test_sig" ]; then
+            echo "Running SIG test..."
+            # Use specified algorithm if provided, otherwise auto-detect
+            if [ -n "${{ matrix.test-sig-alg }}" ]; then
+              SIG_ALG="${{ matrix.test-sig-alg }}"
+              echo "Testing with specified algorithm: $SIG_ALG"
+            else
+              # Get list of available algorithms and pick the first one
+              SIG_ALG=$(./tests/test_sig 2>&1 | grep "algname:" | sed 's/.*algname: //' | cut -d',' -f1 | tr -d ' ')
+              echo "Testing with first available algorithm: $SIG_ALG"
+            fi
+
+            if [ -n "$SIG_ALG" ]; then
+              ./tests/test_sig "$SIG_ALG"
+              echo "✓ SIG test passed with $SIG_ALG"
+            else
+              echo "⚠ Could not determine available SIG algorithms"
+            fi
+          else
+            echo "SIG test executable not found (may be disabled in minimal build)"
+          fi
+
+  test-script-options-coverage:
+    name: Verify script covers all CMake options
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # pin@v4.2.2
+
+      - name: Extract CMake options from CONFIGURE.md
+        run: |
+          # Extract OQS_ prefixed options from CONFIGURE.md
+          grep -oE 'OQS_[A-Z_]+' CONFIGURE.md | sort -u > cmake_options.txt || true
+          echo "CMake options found in CONFIGURE.md:"
+          cat cmake_options.txt
+
+      - name: Extract options from build script
+        run: |
+          # Extract OQS_ prefixed options from build_liboqs.sh
+          grep -oE 'OQS_[A-Z_]+' build_liboqs.sh | sort -u > script_options.txt || true
+          echo "Options found in build_liboqs.sh:"
+          cat script_options.txt
+
+      - name: Compare coverage
+        shell: bash
+        run: |
+          echo "Checking if build script covers major CMake options..."
+          # Check for key options that should be in the script (using word boundaries to avoid partial matches)
+          echo "Checking for OQS_USE_OPENSSL..."
+          if grep -qE '\bOQS_USE_OPENSSL\b' build_liboqs.sh; then
+            echo "✓ Found: OQS_USE_OPENSSL"
+          else
+            echo "❌ Missing: OQS_USE_OPENSSL"
+          fi
+
+          echo "Checking for OQS_DIST_BUILD..."
+          if grep -qE '\bOQS_DIST_BUILD\b' build_liboqs.sh; then
+            echo "✓ Found: OQS_DIST_BUILD"
+          else
+            echo "❌ Missing: OQS_DIST_BUILD"
+          fi
+
+          echo "Checking for OQS_MINIMAL_BUILD..."
+          if grep -qE '\bOQS_MINIMAL_BUILD\b' build_liboqs.sh; then
+            echo "✓ Found: OQS_MINIMAL_BUILD"
+          else
+            echo "❌ Missing: OQS_MINIMAL_BUILD"
+          fi
+
+          echo "Checking for OQS_BUILD_ONLY_LIB..."
+          if grep -qE '\bOQS_BUILD_ONLY_LIB\b' build_liboqs.sh; then
+            echo "✓ Found: OQS_BUILD_ONLY_LIB"
+          else
+            echo "❌ Missing: OQS_BUILD_ONLY_LIB"
+          fi
+
+          echo "Checking for OQS_ALGS_ENABLED..."
+          if grep -qE '\bOQS_ALGS_ENABLED\b' build_liboqs.sh; then
+            echo "✓ Found: OQS_ALGS_ENABLED"
+          else
+            echo "❌ Missing: OQS_ALGS_ENABLED"
+          fi
+
+          echo "✓ Coverage check complete"
+
+  test-script-help:
+    name: Verify script help and usage
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # pin@v4.2.2
+
+      - name: Make build script executable
+        run: chmod +x build_liboqs.sh
+
+      - name: Test help flag
+        run: |
+          ./build_liboqs.sh --help > help_output.txt 2>&1
+          if [ ! -s help_output.txt ]; then
+            echo "Error: Help output is empty"
+            exit 1
+          fi
+          echo "✓ Help flag works"
+          cat help_output.txt
+
+      - name: Test invalid option handling
+        run: |
+          if ./build_liboqs.sh --invalid-option 2>&1 | grep -q "Unknown option"; then
+            echo "✓ Invalid option handling works"
+          else
+            echo "Error: Script should reject invalid options"
+            exit 1
+          fi
+
+  test-script-syntax:
+    name: Verify script syntax and shellcheck
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # pin@v4.2.2
+
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+      - name: Check bash syntax
+        run: bash -n build_liboqs.sh
+
+      - name: Run shellcheck
+        run: |
+          shellcheck build_liboqs.sh || echo "Shellcheck warnings found (non-blocking)"

README.md

@@ -19,6 +19,7 @@ liboqs is an open source C library for quantum-safe cryptographic algorithms.
 			- [Support limitations](#support-limitations)
 	- [Quickstart](#quickstart)
 		- [Linux and Mac](#linux-and-mac)
+		- [Using the build script](#using-the-build-script)
 		- [Windows](#windows)
 		- [Cross compilation](#cross-compilation)
 	- [Documentation](#documentation)
@@ -173,6 +174,69 @@ The following instructions assume we are in `build`.
 5. `ninja uninstall` can be run to remove all installation files.
 
 
+### Using the build script
+
+`build_liboqs.sh` is a convenience wrapper around the standard CMake + Ninja build that handles OS detection, dependency installation, and exposes the most common [CMake options](CONFIGURE.md) as named flags.
+
+**Basic usage**
+
+```sh
+# Default build (installs deps, static library, all algorithms, Release mode)
+./build_liboqs.sh
+
+# Shared library, Debug build
+./build_liboqs.sh --shared --build-type Debug
+
+# Minimal build — only the algorithms you need (quote the list to protect `;`)
+./build_liboqs.sh --minimal-build "KEM_ml_kem_768;SIG_ml_dsa_44"
+
+# Skip OpenSSL dependency
+./build_liboqs.sh --no-openssl
+
+# Show all available flags
+./build_liboqs.sh --help
+```
+
+**Script internals, step by step**
+
+1. **Detects the OS** (macOS, Ubuntu/Debian, NixOS) and installs missing build dependencies automatically — Homebrew on macOS, `apt` on Debian/Ubuntu, `nix develop` on NixOS.
+2. **Checks for build-directory conflicts** — if an existing `build/` was created with a different CMake generator it is removed before proceeding.
+3. **Runs `cmake -GNinja`** inside `./build/` with any flags you provided, plus these defaults when none are given:
+   - `CMAKE_BUILD_TYPE=Release`
+   - `OQS_DIST_BUILD=ON` (portable across CPUs)
+   - `OQS_USE_OPENSSL=ON`
+   - `OQS_ALGS_ENABLED=All`
+4. **Runs `ninja`** to compile the library and (unless `--build-only-lib`) the test harnesses under `build/tests/`.
+5. **Prints next-step hints** — how to run `ninja install`, `ninja run_tests`, and install Python test dependencies.
+
+**Dependency-check-only mode**
+
+Pass `--build-only` to verify all required tools are present without installing or building anything:
+
+```sh
+./build_liboqs.sh --build-only
+```
+
+**Key flags reference**
+
+| Flag | CMake equivalent | Description |
+|------|-----------------|-------------|
+| `--shared` | `-DBUILD_SHARED_LIBS=ON` | Build a shared library instead of static |
+| `--build-type TYPE` | `-DCMAKE_BUILD_TYPE=TYPE` | `Debug`, `Release`, `RelWithDebInfo`, `MinSizeRel` |
+| `--minimal-build "A;B"` | `-DOQS_MINIMAL_BUILD="A;B"` | Build only the listed algorithms |
+| `--algs-enabled SET` | `-DOQS_ALGS_ENABLED=SET` | `STD`, `NIST_R4`, `NIST_SIG_ONRAMP`, `All` |
+| `--no-openssl` | `-DOQS_USE_OPENSSL=OFF` | Disable OpenSSL dependency |
+| `--build-only-lib` | `-DOQS_BUILD_ONLY_LIB=ON` | Skip tests and docs |
+| `--no-dist-build` | `-DOQS_DIST_BUILD=OFF` | Optimise for the current machine only |
+| `--install-prefix PATH` | `-DCMAKE_INSTALL_PREFIX=PATH` | Where `ninja install` puts files |
+| `-D KEY=VALUE` | `-DKEY=VALUE` | Pass any CMake option directly |
+
+Any CMake option not listed above can still be passed with `-D`, e.g.:
+
+```sh
+./build_liboqs.sh -DOQS_SPEED_USE_ARM_PMU=ON
+```
+
 ### Windows
 
 Binaries can be generated using Visual Studio 2019 with the [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) extension installed. The same options as explained above for Linux/macOS can be used and build artifacts are generated in the specified `build` folders.