Merge branch 'main' into mcx_gidney_khattar

.azure/lint_docs-linux.yml

@@ -23,7 +23,13 @@ jobs:
       - bash: tools/install_ubuntu_docs_dependencies.sh
         displayName: 'Install docs dependencies'
 
-      - bash: tox run -e docs,lint
+      - bash: tools/install_ubuntu_c_dependencies.sh
+        displayName: 'Install C dependencies'
+
+      - bash: |
+          set -e
+          make cformat
+          tox run -e docs,lint
         displayName: 'Lint and docs'
 
       - bash: rm -rf docs/_build/html/{.doctrees,.buildinfo}

.clang-format

@@ -0,0 +1,7 @@
+---
+BasedOnStyle: LLVM
+ColumnLimit: '100'
+IndentWidth: '4'
+Language: Cpp
+TabWidth: '4'
+UseTab: Never

.github/workflows/ctests.yml

@@ -0,0 +1,20 @@
+---
+name: Tests
+on:
+  push:
+    branches: [ main, 'stable/*' ]
+  pull_request:
+    branches: [ main, 'stable/*' ]
+  merge_group:
+
+jobs:
+  tests:
+    if: github.repository_owner == 'Qiskit'
+    name: linux-tests-c
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: cargo install cbindgen
+      - name: Run tests
+        run: make ctest

CMakeLists.txt

@@ -0,0 +1,17 @@
+cmake_minimum_required (VERSION 3.27)
+project (Qiskit)
+
+# We are using CMake to build our C API test suite, and we leverage ctest to run
+# those tests.
+enable_testing ()
+
+# The C API is provided by the qiskit_cext Rust crate. Its header gets
+# generated by cbindgen (see `make cheader`). It is important that this done as
+# a Release-build for cbindgen to work properly.
+find_library (qiskit qiskit_cext PATHS target/release REQUIRED)
+
+# Generally include the directory for the ``qiskit.h`` file.
+include_directories (dist/c/include)
+
+# The remaining CMake configuration is done inside of the C API test suite.
+add_subdirectory (test/c)

CONTRIBUTING.md

@@ -684,9 +684,53 @@ GitHub Action file.  This same file may also include patches to dependencies to
 make them compatible with Miri, which you would need to temporarily apply as
 well.
 
+### Testing the C API
+
+The C API test suite is located at `test/c/`. It is built and run using `cmake`
+and `ctest` which can be triggered simply via:
+```bash
+make ctest
+```
+
+#### Writing C API tests
+
+The C API test suite automatically discovers any files inside `test/c/` matching
+the pattern `test_*.c`. Each one of these files should follow a template similar
+to the following.
+```c
+#include "common.h"
+
+// Individual tests may be implemented by custom functions. The return value
+// should be `Ok` (from `test/c/common.h`) when the test was successful or one
+// of the other error codes (`>0`) indicating the error type.
+int test_something()
+{
+    return Ok;
+}
+
+// One main function must exist, WHOSE FUNCTION NAME MATCHES THE FILENAME!
+int test_FILE_NAME()
+{
+    // Ideally, this function should track the number of failed subtests.
+    int num_failed = 0;
+
+    // The RUN_TEST macro will execute the provided test function and perform a
+    // minimal amount of logging to indicate the success/failure of this test.
+    num_failed += RUN_TEST(test_something);
+
+    // Finally, this test should report the number of failed subtests.
+    fprintf(stderr, "=== Number of failed subtests: %i\n", num_failed);
+    fflush(stderr);
+
+    // And return the number of failed subtests. If this is greater than 0,
+    // ctest will indicate the failure.
+    return num_failed;
+}
+```
+
 ## Style and lint
 
-Qiskit uses three tools for verify code formatting and lint checking. The
+Qiskit uses three tools for Python code formatting and lint checking. The
 first tool is [black](https://github.com/psf/black) which is a code formatting
 tool that will automatically update the code formatting to a consistent style.
 The second tool is [pylint](https://www.pylint.org/) which is a code linter
@@ -724,6 +768,13 @@ conform to the style guidelines. This is very similar to running `tox -eblack` f
 
 Rust lint and formatting checks are included in the the `tox -elint` command. For CI to pass you will need both checks to pass without any warnings or errors. Note that this command checks the code but won't apply any modifications, if you need to update formatting, you'll need to run `cargo fmt`.
 
+### C style and lint
+
+Qiskit uses [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to format C code.
+The style is based on LLVM, with some few Qiskit-specific adjustments. 
+To check whether the C code conforms to the style guide, you can run `make cformat`. This check
+will need to execute without any warnings or errors for CI to pass.
+Automatic formatting can be applied by `make fix_cformat`.
 
 ## Building API docs locally