chore(bindings): add tooling to generate docsrs_bindings.rs

Refs: #443

Author: Xenira

.dockerignore

@@ -0,0 +1,2 @@
+/target
+/guide

.github/workflows/build.yml

@@ -11,6 +11,10 @@ env:
   # increment this manually to force cache eviction
   RUST_CACHE_PREFIX: "v0-rust"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
+
 jobs:
   lint:
     name: Lint

.github/workflows/docsrs_bindings.yml

@@ -0,0 +1,28 @@
+name: docsrs bindings
+on:
+  pull_request:
+    paths:
+      - 'allowed-bindings.rs'
+      - 'docsrs_bindings.rs'
+      - 'Cargo.toml'
+      - 'build.rs'
+      - 'Dockerfile'
+      - '.dockerignore'
+      - 'tools/update_bindings.sh'
+      - '.github/workflows/docsrs_bindings.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-bindings:
+    name: Lint bindings
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check docsrs_bindings.rs
+        run: tools/update_bindings.sh && git diff --exit-code docsrs_bindings.rs

Dockerfile

@@ -0,0 +1,39 @@
+FROM rust:latest AS base
+ARG PHP_VERSION=8.4
+WORKDIR /tmp
+RUN <<EOF
+set -e
+
+apt update -y
+apt install -y \
+  libclang-dev \
+  bison \
+  re2c
+
+# Build PHP
+git clone --depth 1 -b PHP-${PHP_VERSION} https://github.com/php/php-src.git
+cd php-src
+# by default you will be on the master branch, which is the current
+# development version. You can check out a stable branch instead:
+./buildconf
+./configure \
+    --enable-debug \
+    --disable-all --disable-cgi
+make -j "$(nproc)"
+make install
+EOF
+
+FROM base AS docsrs_bindings_builder
+WORKDIR /src
+RUN rustup component add rustfmt
+RUN --mount=type=bind,target=/src,rw <<EOF
+set -e
+cargo clean
+cargo build
+cp target/debug/build/ext-php-rs-*/out/bindings.rs /docsrs_bindings.rs
+rustfmt /docsrs_bindings.rs
+EOF
+ENTRYPOINT ["/generate.sh"]
+
+FROM scratch AS docsrs_bindings
+COPY --from=docsrs_bindings_builder /docsrs_bindings.rs /

README.md

@@ -201,6 +201,26 @@ Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.
 
+## Development
+
+### `allowed_bindings.rs`
+This file contains the list of allowed bindings for the Zend API. It is acting
+as a whitelist for the bindings that can be used in the library.
+
+When updating this file you need to also update the `docsrs_bindings.rs` file.
+To do this, run the following command from the root of the project:
+
+```bash
+tools/update_bindings.sh
+```
+
+This will build the bindings using docker, and then copy the `docsrs_bindings.rs`
+file to the root of the repository.
+This will ensure that the file is always built in the same environment.
+
+Docker and buildx are required to run the script, so make sure you have
+those [installed](https://docs.docker.com/engine/install/).
+
 ## Resources
 
 - [PHP Internals Book](https://www.phpinternalsbook.com/)

allowed_bindings.rs

@@ -7,17 +7,19 @@
 //
 // NOTE TO EDITORS:
 //   When updating this file, you must re-generate the `docsrs_bindings.rs`
-//   file used by docs.rs to build documentation. To perform this:
+//   file used by docs.rs to build documentation. To perform this from
+//   within the repository root:
 //
-//     $ cargo clean
-//     $ cargo build
-//     $ cp target/debug/build/ext-php-rs-e2cb315d27898d01/out/bindings.rs
-//       docsrs_bindings.rs
+//     $ tools/update_bindings.sh
 //     $ git add . && git commit -m "update docs.rs bindings"
 //
-//   The hash after `ext-php-rs-` in the bindings path may change. There should
-//   be two folders beginning with `ext-php-rs-` in `target/debug/build`, so
-//   check both for the presence of the bindings file.
+//   This will build the bindings using docker, and then copy the
+//   `docsrs_bindings.rs` file to the root of the repository.
+//   This will ensure that the file is always built in the same environment.
+//
+//   Docker and buildx are required to run the script, so make sure you have
+//   those installed. For more information, see:
+//   https://docs.docker.com/engine/install/
 
 bind! {
     HashTable,

docsrs_bindings.rs

@@ -270,7 +270,7 @@ pub struct _IO_FILE {
     pub _wide_data: *mut _IO_wide_data,
     pub _freeres_list: *mut _IO_FILE,
     pub _freeres_buf: *mut ::std::os::raw::c_void,
-    pub _prevchain: *mut *mut _IO_FILE,
+    pub __pad5: usize,
     pub _mode: ::std::os::raw::c_int,
     pub _unused2: [::std::os::raw::c_char; 20usize],
 }

tools/update_bindings.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# This script updates the bindings for the docs.rs documentation.
+# It should be run from the root of the repository.
+#
+# This script requires docker to be installed and running.
+set -e
+
+docker buildx build \
+  --target docsrs_bindings \
+  -o type=local,dest=. \
+  --build-arg PHP_VERSION=8.3 \
+  .