Add macOS (Apple Silicon / arm64) build, packaging, and CI support

.github/workflows/ci-nightly-build-test.yaml

@@ -108,6 +108,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python ${{inputs.py_version || env.py_version}}
+        id: python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: ${{inputs.py_version || env.py_version}}
@@ -118,16 +119,22 @@ jobs:
           bazelrc: ${{env.bazelrc_additions}}
 
       - name: Build wheel
+        env:
+          PYTHON_BIN_PATH: ${{steps.python.outputs.python-path}}
         run: |
           pip install --upgrade pip setuptools wheel
           # The next script does a pip install, configure, & bazel build.
           ./scripts/build_pip_package_test.sh
 
       - name: Test wheel
+        env:
+          PYTHON_BIN_PATH: ${{steps.python.outputs.python-path}}
         run: |
           ./scripts/run_example.sh
 
       - name: Test rest of TFQ
+        env:
+          PYTHON_BIN_PATH: ${{steps.python.outputs.python-path}}
         run: |
           set -o pipefail
           ./scripts/test_all.sh 2>&1 | tee test_all.log
@@ -160,3 +167,55 @@ jobs:
             !/home/runner/.bazel/execroot/__main__/bazel-out/**/*.o
             !/home/runner/.bazel/execroot/__main__/bazel-out/**/_objs
             !/home/runner/.bazel/execroot/__main__/bazel-out/**/_solib_k8
+
+  Nightly-macOS:
+    if: needs.Decision.outputs.run == 'true'
+    name: Build and test (macOS)
+    needs: Decision
+    runs-on: macos-15
+    steps:
+      - name: Check out a copy of the TFQ git repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python ${{inputs.py_version || env.py_version}}
+        id: python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{inputs.py_version || env.py_version}}
+
+      - name: Set up Bazel
+        uses: bazel-contrib/setup-bazel@c5acdfb288317d0b5c0bbd7a396a3dc868bb0f86 # 0.19.0
+        with:
+          bazelrc: ${{env.bazelrc_additions}}
+
+      - name: Build wheel
+        env:
+          PYTHON_BIN_PATH: ${{steps.python.outputs.python-path}}
+        run: |
+          pip install --upgrade pip setuptools wheel
+          ./scripts/build_pip_package_test.sh
+
+      - name: Test wheel
+        env:
+          PYTHON_BIN_PATH: ${{steps.python.outputs.python-path}}
+        run: |
+          ./scripts/run_example.sh
+
+      - name: Test rest of TFQ
+        env:
+          PYTHON_BIN_PATH: ${{steps.python.outputs.python-path}}
+        run: |
+          set -o pipefail
+          ./scripts/test_all.sh 2>&1 | tee test_all.log
+
+      - if: failure() || inputs.save_artifacts == 'true'
+        name: Make artifacts downloadable
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: test-artifacts-macos
+          retention-days: 7
+          include-hidden-files: true
+          path: |
+            test_all.log

.github/workflows/ci.yaml

@@ -68,8 +68,12 @@ jobs:
         run: ./scripts/lint_all.sh
 
   wheel-build:
-    name: Wheel test
-    runs-on: ubuntu-22.04
+    name: Wheel test (${{matrix.os}})
+    runs-on: ${{matrix.os}}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-15]
     timeout-minutes: 60
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
@@ -116,7 +120,30 @@ jobs:
         run: ./scripts/ci_install.sh
 
       - name: Configure CI TF
-        run: echo "Y\n" | ./configure.sh
+        run: printf "Y\n" | ./configure.sh
+
+      - name: Full Library Test
+        run: ./scripts/test_all.sh
+
+  bazel-tests-macos:
+    name: Library tests (macOS)
+    runs-on: macos-15
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{env.python-version}}
+          cache: pip
+          cache-dependency-path: requirements.txt
+
+      - name: Install Bazel on CI
+        run: ./scripts/ci_install.sh
+
+      - name: Configure CI TF
+        run: printf "Y\n" | ./configure.sh
 
       - name: Full Library Test
         run: ./scripts/test_all.sh

README.md

@@ -57,7 +57,8 @@ Please see the [installation
 instructions](https://www.tensorflow.org/quantum/install) in the documentation.
 
 _Compatibility_: At this time, TensorFlow Quantum is built and
-tested on Linux with the following systems and software:
+tested on Linux (`x86_64`) and macOS (Apple Silicon / `arm64`) with the
+following systems and software:
 
 * Python 3.10–3.12
 * TensorFlow 2.19.1

configure.sh

@@ -107,7 +107,15 @@ while [[ -z "${TF_NEED_CUDA}" ]]; do
   read -p "${y_for_cpu}" INPUT || true
   case "${INPUT:-Y}" in
     [Yy]* ) echo "CPU build selected."; TF_NEED_CUDA=0;;
-    [Nn]* ) echo "GPU build selected."; TF_NEED_CUDA=1;;
+    [Nn]* )
+      if is_macos; then
+        echo "GPU (CUDA) build is not supported on macOS; selecting CPU build."
+        TF_NEED_CUDA=0
+      else
+        echo "GPU build selected."
+        TF_NEED_CUDA=1
+      fi
+      ;;
     * ) echo "Please answer y or n.";;
   esac
 done
@@ -141,10 +149,17 @@ lib_path = sc.get_lib()
 lib_dir = lib_path if os.path.isdir(lib_path) else os.path.dirname(lib_path)
 print(lib_dir)
 
-cands = (glob.glob(os.path.join(lib_dir, 'libtensorflow_framework.so*')) or
-         glob.glob(os.path.join(lib_dir, 'libtensorflow.so*')) or
-         glob.glob(os.path.join(lib_dir, '_pywrap_tensorflow_internal.*')))
-print(os.path.basename(cands[0]) if cands else 'libtensorflow_framework.so.2')
+if sys.platform == 'darwin':
+    cands = (glob.glob(os.path.join(lib_dir, 'libtensorflow_framework*.dylib')) or
+             glob.glob(os.path.join(lib_dir, 'libtensorflow*.dylib')) or
+             glob.glob(os.path.join(lib_dir, '_pywrap_tensorflow_internal.*')))
+    default_lib = 'libtensorflow_framework.2.dylib'
+else:
+    cands = (glob.glob(os.path.join(lib_dir, 'libtensorflow_framework.so*')) or
+             glob.glob(os.path.join(lib_dir, 'libtensorflow.so*')) or
+             glob.glob(os.path.join(lib_dir, '_pywrap_tensorflow_internal.*')))
+    default_lib = 'libtensorflow_framework.so.2'
+print(os.path.basename(sorted(cands)[0]) if cands else default_lib)
 PY
 )
 
@@ -189,11 +204,26 @@ write_bazelrc "common --experimental_repo_remote_exec"
 write_bazelrc "build --spawn_strategy=standalone"
 write_bazelrc "build --strategy=Genrule=standalone"
 write_bazelrc "build -c opt"
-write_bazelrc "build --cxxopt=-D_GLIBCXX_USE_CXX11_ABI=1"
+if ! is_macos; then
+  write_bazelrc "build --cxxopt=-D_GLIBCXX_USE_CXX11_ABI=1"
+fi
 write_bazelrc "build --cxxopt=-std=c++17"
+write_bazelrc "build --host_cxxopt=-std=c++17"
 write_bazelrc "build --action_env=TF_USE_LEGACY_KERAS=1"
 write_bazelrc "build --action_env=PYTHON_BIN_PATH=${PYTHON_BIN_PATH}"
 
+if is_macos; then
+  write_bazelrc "build --macos_minimum_os=12.0"
+  write_bazelrc "build --host_macos_minimum_os=12.0"
+  write_bazelrc "build --copt=-DGRPC_BAZEL_BUILD"
+  write_bazelrc "build --host_copt=-DGRPC_BAZEL_BUILD"
+  write_bazelrc "build --features=archive_param_file"
+  write_bazelrc "build --linkopt=-Wl,-undefined,dynamic_lookup"
+  write_bazelrc "build --host_linkopt=-Wl,-undefined,dynamic_lookup"
+  write_bazelrc "build --linkopt=-Wl,-rpath,@loader_path/../../../tensorflow"
+  write_bazelrc "build --linkopt=-Wl,-rpath,@loader_path/../../../../tensorflow"
+fi
+
 # rpath so the dynamic linker finds TF’s shared lib
 if ! is_windows; then
   write_bazelrc "build --linkopt=-Wl,-rpath,${LIBDIR}"
@@ -210,10 +240,12 @@ write_bazelrc 'build --per_file_copt=external/.*[.]c$@-Wno-deprecated-non-protot
 write_bazelrc 'build --host_per_file_copt=external/.*[.]c$@-Wno-deprecated-non-prototype'
 write_bazelrc "build --per_file_copt=external/com_google_protobuf/.*@-Wno-unused-function"
 write_bazelrc "build --host_per_file_copt=external/com_google_protobuf/.*@-Wno-unused-function"
-write_bazelrc "build --per_file_copt=external/com_google_protobuf/.*@-Wno-stringop-overflow"
-write_bazelrc "build --host_per_file_copt=external/com_google_protobuf/.*@-Wno-stringop-overflow"
-write_bazelrc "build --per_file_copt=external/eigen/.*@-Wno-maybe-uninitialized"
-write_bazelrc "build --host_per_file_copt=external/eigen/.*@-Wno-maybe-uninitialized"
+if ! is_macos; then
+  write_bazelrc "build --per_file_copt=external/com_google_protobuf/.*@-Wno-stringop-overflow"
+  write_bazelrc "build --host_per_file_copt=external/com_google_protobuf/.*@-Wno-stringop-overflow"
+  write_bazelrc "build --per_file_copt=external/eigen/.*@-Wno-maybe-uninitialized"
+  write_bazelrc "build --host_per_file_copt=external/eigen/.*@-Wno-maybe-uninitialized"
+fi
 
 # The following warnings come from qsim.
 # TODO: fix the code in qsim & update TFQ to use the updated version.

docs/install.md

@@ -16,7 +16,7 @@ TensorFlow Quantum is supported on Python version 3.10 through 3.12 and depends
 
 ### Requirements
 
-* pip 19.0 or later (requires `manylinux2014` support)
+* pip 19.0 or later (requires `manylinux2014` support on Linux or macOS 12.0+ `arm64` on Apple Silicon)
 * [TensorFlow == 2.19.1](https://www.tensorflow.org/install/pip)
 
 See the [TensorFlow install guide](https://www.tensorflow.org/install/pip) to
@@ -53,11 +53,13 @@ Success: TensorFlow Quantum is now installed.
 
 ## Build from source
 
-The following steps are tested for Ubuntu-like systems.
+The following steps are tested for Ubuntu-like Linux systems and macOS (Apple Silicon / `arm64`).
 
 ### 1. Set up a Python 3 development environment
 
-We will use Python 3.10 as an example. First, we need the Python 3.10 development tools.
+We will use Python 3.10 as an example. First, install the Python 3.10 development tools for your operating system.
+
+**On Ubuntu/Debian Linux:**
 <!-- common_typos_disable -->
 <pre class="devsite-click-to-copy">
   <code class="devsite-terminal">sudo apt update</code>
@@ -67,6 +69,17 @@ We will use Python 3.10 as an example. First, we need the Python 3.10 developmen
 </pre>
 <!-- common_typos_enable -->
 
+**On macOS (Apple Silicon):**
+
+Install the Xcode Command Line Tools and Python 3.10 (for example, using <a href="https://brew.sh/" class="external">Homebrew</a>):
+<!-- common_typos_disable -->
+<pre class="devsite-click-to-copy">
+  <code class="devsite-terminal">xcode-select --install</code>
+  <code class="devsite-terminal">brew install python@3.10</code>
+  <code class="devsite-terminal">python3.10 -m pip install --upgrade pip</code>
+</pre>
+<!-- common_typos_enable -->
+
 ### 2. Create a virtual environment
 
 Go to your workspace directory and make a virtual environment for TFQ development.
@@ -88,28 +101,26 @@ guide, the <a href="https://bazel.build/" class="external">Bazel</a>
 build system will be required.
 
 Our latest source builds use TensorFlow 2.19.1. To ensure compatibility we use
-the same version of `bazel`, 6.5.0. To remove any existing version of Bazel:
-<!-- common_typos_disable -->
-<pre class="devsite-click-to-copy">
-  <code class="devsite-terminal">sudo apt-get remove bazel</code>
-</pre>
-<!-- common_typos_enable -->
+the same version of `bazel`, 6.5.0.
 
-Download and install `bazel` version 6.5.0:
+**On Ubuntu/Debian Linux:**
 
+Remove any existing version of Bazel, download and install `bazel` 6.5.0, and hold the package to prevent automatic updates to an incompatible version:
 <!-- common_typos_disable -->
 <pre class="devsite-click-to-copy">
-  <code class="devsite-terminal">wget https://github.com/bazelbuild/bazel/releases/download/6.5.0/bazel_6.5.0-linux-x86_64.deb
-</code>
+  <code class="devsite-terminal">sudo apt-get remove bazel</code>
+  <code class="devsite-terminal">wget https://github.com/bazelbuild/bazel/releases/download/6.5.0/bazel_6.5.0-linux-x86_64.deb</code>
   <code class="devsite-terminal">sudo dpkg -i bazel_6.5.0-linux-x86_64.deb</code>
+  <code class="devsite-terminal">sudo apt-mark hold bazel</code>
 </pre>
 <!-- common_typos_enable -->
 
-To prevent automatic updating of `bazel` to an incompatible version, run the following:
+**On macOS (Apple Silicon):**
 
+Install `bazelisk` via Homebrew (which automatically selects Bazel 6.5.0 from `.bazelversion`), or download the `bazel-6.5.0-darwin-arm64` binary directly from the Bazel releases page:
 <!-- common_typos_disable -->
 <pre class="devsite-click-to-copy">
-  <code class="devsite-terminal">sudo apt-mark hold bazel</code>
+  <code class="devsite-terminal">brew install bazelisk</code>
 </pre>
 <!-- common_typos_enable -->
 
@@ -124,7 +135,7 @@ Finally, confirm installation of the correct `bazel` version:
 
 ### 4. Build TensorFlow from source
 
-TensorFlow Quantum is compatible with TensorFlow version&nbsp;2.19.1. To build
+TensorFlow Quantum is compatible with TensorFlow version 2.19.1. To build
 TensorFlow from sources, download the <a
 href="https://github.com/tensorflow/tensorflow" class="external">TensorFlow
 source code</a> by cloning the git repository, then switch to the `r2.19`

release/README.md

@@ -10,7 +10,7 @@ documents the process used by the TensorFlow Quantum maintainers to build and
 release the packages for public TensorFlow Quantum distributions.
 
 At present, binary distributions in the form of Python wheel files are made
-available only for Linux systems.
+available for Linux (`x86_64`) and macOS (Apple Silicon / `arm64`) systems.
 
 ## Version numbering policy
 
@@ -33,7 +33,8 @@ on, including:
 
 *   The version of Python and the local Python environment.
 *   The version of TensorFlow.
-*   The TensorFlow build container used.
+*   The TensorFlow build container used (on Linux) or Xcode/Clang toolchain
+    used (on macOS).
 *   The Crosstool configuration used.
 *   The dependency requirements implied by Cirq, TF-Keras, NumPy, Protobuf, and
     other Python packages that TFQ and TF depend on.
@@ -61,8 +62,8 @@ into the upstream repository before proceeding further.
 
 ### Preliminary steps
 
-1.  Make sure you have `docker`, `pyenv`, `pip`, and `jq` installed on your
-    system.
+1.  Make sure you have `pyenv`, `pip`, and `jq` installed on your system, plus
+    `docker` on Linux or Xcode Command Line Tools and Bazel 6.5.0 on macOS.
 
 2.  Git clone the TensorFlow Quantum repo to a directory on your computer.
 
@@ -94,7 +95,7 @@ into the upstream repository before proceeding further.
 For each Python version _X.Y.Z_ that will be supported in the TFQ release, do
 the following:
 
-1.  Run `./release/build_release.sh X.Y.Z`.
+1.  Run `./release/build_release.sh -p X.Y.Z`.
 
 2.  If the previous step fails, resolve the error.