Document Copilot build setup (incl. PyCDE/ESI) and align integration image defaults (#9314)

Implements Teach copilot how to compile CIRCT #9313

Author: Copilot

.github/copilot-instructions.md

@@ -0,0 +1,20 @@
+# Copilot build & test guidance
+
+- Default to the integration docker image in `CIRCT_INTEGRATION_IMAGE` (set by the Copilot setup workflow and the `utils/run-docker.sh` default; currently `ghcr.io/circt/images/circt-integration-test:v19.2`) when compiling or testing.
+- Run inside that image via `./utils/run-docker.sh ./utils/run-tests-docker.sh "$CIRCT_INTEGRATION_IMAGE"` or `docker run` with the repo root bind-mounted.
+- When cloning or checking out, ensure submodules are present (`git submodule update --init --recursive` if needed).
+- Configure builds from the repo root with Ninja, matching the README:
+  ```
+  cmake -G Ninja llvm/llvm -B build \
+    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+    -DLLVM_ENABLE_ASSERTIONS=ON \
+    -DLLVM_TARGETS_TO_BUILD=host \
+    -DLLVM_ENABLE_PROJECTS=mlir \
+    -DLLVM_EXTERNAL_PROJECTS=circt \
+    -DLLVM_EXTERNAL_CIRCT_SOURCE_DIR=$PWD \
+    -DLLVM_ENABLE_LLD=ON
+  ```
+- Build everything with `ninja -C build check-circt`; use `ninja -C build bin/circt-opt` or `ninja -C build bin/firtool` for tool-only builds.
+- Keep Python bindings enabled when needed via `-DMLIR_ENABLE_BINDINGS_PYTHON=ON -DCIRCT_BINDINGS_PYTHON_ENABLED=ON`.
+- For PyCDE and the ESI runtime, add `-DCIRCT_ENABLE_FRONTENDS=PyCDE -DESI_RUNTIME=ON` (keep Python bindings on). Test with `ninja -C build check-pycde` and `ninja -C build check-pycde-integration` (the integration tests exercise both PyCDE and the ESI runtime and are the only ESIRuntime tests).
+- Prefer the integration image and the setup steps workflow for reliable dependencies; only fall back to host builds when explicitly requested.

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,28 @@
+name: Copilot setup steps
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+permissions:
+  contents: read
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pre-pull integration docker image
+        env:
+          CIRCT_INTEGRATION_IMAGE: ghcr.io/circt/images/circt-integration-test:v19.2
+        run: |
+          echo "CIRCT_INTEGRATION_IMAGE=$CIRCT_INTEGRATION_IMAGE" >> $GITHUB_ENV
+          docker pull "$CIRCT_INTEGRATION_IMAGE"
+      - name: Summarize defaults
+        run: |
+          {
+            echo "### CIRCT Copilot setup"
+            echo "- Integration image: $CIRCT_INTEGRATION_IMAGE"
+            echo "- Default build directory: build"
+          } >> "$GITHUB_STEP_SUMMARY"

utils/run-docker.sh

@@ -20,7 +20,7 @@
 ##===----------------------------------------------------------------------===##
 
 CMD=${1:-"./utils/run-tests-docker.sh"}
-VER=${2:-"v5"}
+VER=${2:-"v19.2"}
 REPO_ROOT=$(cd "$(dirname "$BASH_SOURCE[0]")/.." && pwd)
 
 cd $REPO_ROOT