feat(llar): add install command wrapper

.github/actions/setup-demo-deps/action.yml

@@ -0,0 +1,61 @@
+name: "Setup Demo Dependencies"
+description: "Install dependencies required by the LLGo demo suite"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install cargs demo library
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        case "${RUNNER_OS}" in
+          Linux)
+            demo_pkg="cargs_linux_amd64.zip"
+            ;;
+          macOS)
+            case "$(uname -m)" in
+              x86_64)
+                demo_pkg="cargs_darwin_amd64.zip"
+                ;;
+              arm64)
+                demo_pkg="cargs_darwin_arm64.zip"
+                ;;
+              *)
+                echo "Unsupported macOS architecture: $(uname -m)" >&2
+                exit 1
+                ;;
+            esac
+            ;;
+          *)
+            echo "Unsupported runner OS: ${RUNNER_OS}" >&2
+            exit 1
+            ;;
+        esac
+
+        libs_dir="${GITHUB_WORKSPACE}/_demo/c/cargs/libs"
+        mkdir -p "${libs_dir}"
+        wget -P "${libs_dir}" "https://github.com/xgo-dev/llpkg/releases/download/cargs/v1.0.0/${demo_pkg}"
+        unzip -o "${libs_dir}/${demo_pkg}" -d "${libs_dir}"
+
+        for tmpl in "${libs_dir}"/lib/pkgconfig/*.pc.tmpl; do
+          pc_file="${tmpl%.tmpl}"
+          sed "s|{{.Prefix}}|${libs_dir}|g" "${tmpl}" > "${pc_file}"
+        done
+
+        echo "PKG_CONFIG_PATH=${libs_dir}/lib/pkgconfig:${PKG_CONFIG_PATH:-}" >> "${GITHUB_ENV}"
+
+    - name: Install Python demo dependencies
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        pip3.12 install --break-system-packages numpy torch
+
+        pcdir="${HOME}/pc"
+        mkdir -p "${pcdir}"
+        libdir="$(pkg-config --variable=libdir python-3.12-embed)"
+        ln -sf "${libdir}/pkgconfig/python-3.12-embed.pc" "${pcdir}/python3-embed.pc"
+
+        echo "PKG_CONFIG_PATH=${pcdir}:${PKG_CONFIG_PATH:-}" >> "${GITHUB_ENV}"
+        echo "LLGO_FULL_RPATH=true" >> "${GITHUB_ENV}"

.github/actions/setup-deps/action.yml

@@ -5,37 +5,261 @@ inputs:
     description: "LLVM version to install"
     required: true
     default: "19"
+  install-llvm:
+    description: "Whether to install LLVM"
+    required: false
+    default: "true"
 
 runs:
   using: "composite"
   steps:
+    - name: Set up Windows MSYS2
+      if: runner.os == 'Windows' && inputs.install-llvm == 'true'
+      id: msys2
+      # CLANG64 provides a native Windows LLVM build. It is only the host
+      # library used by github.com/xgo-dev/llvm; LLGo's target configuration
+      # independently selects the requested Go target ABI.
+      uses: msys2/setup-msys2@v2
+      with:
+        msystem: CLANG64
+        path-type: inherit
+        update: true
+
+    - name: Install Windows dependencies
+      if: runner.os == 'Windows' && inputs.install-llvm == 'true'
+      shell: msys2 {0}
+      run: |
+        set -euo pipefail
+
+        llvm_major="${{ inputs.llvm-version }}"
+        case "$llvm_major" in
+          19)
+            llvm_version=19.1.7
+            package_version=19.1.7-1
+            ;;
+          *)
+            echo "unsupported Windows LLVM version: $llvm_major" >&2
+            exit 1
+            ;;
+        esac
+
+        repo=https://repo.msys2.org/mingw/clang64
+        prefix=mingw-w64-clang-x86_64
+        packages=(
+          "clang-$package_version"
+          "clang-libs-$package_version"
+          "compiler-rt-$package_version"
+          "llvm-$package_version"
+          "llvm-libs-$package_version"
+          "lld-$package_version"
+          "libc++-$package_version"
+          "libunwind-$package_version"
+          "gettext-runtime-0.22.5-2"
+          "libffi-3.4.6-1"
+          "libiconv-1.17-4"
+          "libxml2-2.12.9-2"
+          "xz-5.6.3-3"
+          "zlib-1.3.1-1"
+          "zstd-1.5.6-2"
+        )
+        urls=()
+        for package in "${packages[@]}"; do
+          urls+=("$repo/$prefix-$package-any.pkg.tar.zst")
+        done
+
+        # LLVM 19 packages predate MSYS2's compiler-runtime dependency rename
+        # from gcc-libs to cc-libs. libc++ 19 already supplies the runtime, so
+        # satisfy only the renamed package metadata while installing the
+        # archived, mutually compatible package set.
+        assumed_cc_runtime="$prefix-cc-libs=$llvm_version"
+        pacman --noconfirm -U \
+          --assume-installed "$assumed_cc_runtime" \
+          "${urls[@]}"
+        pacman --noconfirm -S --needed \
+          --assume-installed "$assumed_cc_runtime" \
+          "$prefix-pkgconf"
+
+        for package in clang clang-libs compiler-rt llvm llvm-libs lld libc++ libunwind; do
+          installed="$(pacman -Q "$prefix-$package" | awk '{print $2}')"
+          if [[ "$installed" != "$package_version" ]]; then
+            echo "expected $package $package_version, got $installed" >&2
+            exit 1
+          fi
+        done
+
+        # The released LLVM binding discovers its host flags through
+        # versioned pkg-config metadata. MSYS2 does not ship llvm.pc, so derive
+        # it from the authoritative llvm-config installation instead of
+        # leaking global CGO flags into every package in the build.
+        cflags="$(llvm-config --cflags)"
+        ldflags="$(llvm-config --ldflags --libs all --system-libs)"
+        cflags="${cflags//$'\r'/}"
+        cflags="${cflags//$'\n'/ }"
+        ldflags="${ldflags//$'\r'/}"
+        ldflags="${ldflags//$'\n'/ }"
+        # Install the metadata in CLANG64's standard pkg-config tree. This
+        # keeps discovery stable for both MSYS2 shells and native Go/CGO
+        # subprocesses without passing shell-specific temporary paths between
+        # workflow steps.
+        pc_dir="$MINGW_PREFIX/lib/pkgconfig"
+        mkdir -p "$pc_dir"
+        printf '%s\n' \
+          "Name: LLVM $llvm_major" \
+          "Description: LLVM $llvm_major host compiler and linker flags" \
+          "Version: $llvm_version" \
+          "Cflags: $cflags" \
+          "Libs: $ldflags" \
+          > "$pc_dir/llvm-$llvm_major.pc"
+
+        {
+          echo "CC=clang"
+          echo "CXX=clang++"
+          echo "CGO_ENABLED=1"
+        } >> "$GITHUB_ENV"
+
+        if [[ "$(llvm-config --version)" != "$llvm_version" ]]; then
+          echo "expected LLVM $llvm_version, got $(llvm-config --version)" >&2
+          exit 1
+        fi
+        pkg-config --modversion "llvm-$llvm_major"
+
+    - name: Configure Windows SDK and MSVC tools
+      if: runner.os == 'Windows' && inputs.install-llvm == 'true'
+      shell: pwsh
+      env:
+        MSYS2_LOCATION: ${{ steps.msys2.outputs.msys2-location }}
+      run: |
+        $ErrorActionPreference = "Stop"
+
+        $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+        # LLVM 19 predates the Visual Studio 18 STL compatibility floor. Keep
+        # this pinned lane on VS 2022 instead of selecting a newer toolset
+        # merely because the runner image also happens to contain one.
+        $installPath = & $vswhere -latest -products * -version '[17.0,18.0)' `
+          -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 `
+          -property installationPath
+        if (-not $installPath) {
+          throw "Visual Studio 2022 C++ tools required by LLVM 19 were not found"
+        }
+        Import-Module "$installPath\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"
+        Enter-VsDevShell -VsInstallPath $installPath `
+          -SkipAutomaticLocation `
+          -DevCmdArguments "-arch=x64 -host_arch=x64"
+
+        # Clang emits the MSVC ABI but uses the SDK/UCRT selected by the
+        # Visual Studio developer environment. Persist only the target search
+        # variables and native tools needed by later composite-action callers.
+        foreach ($name in @(
+          "INCLUDE",
+          "LIB",
+          "LIBPATH",
+          "UCRTVersion",
+          "UniversalCRTSdkDir",
+          "VCINSTALLDIR",
+          "VCToolsInstallDir",
+          "WindowsSdkDir",
+          "WindowsSDKVersion"
+        )) {
+          $value = [Environment]::GetEnvironmentVariable($name)
+          if ($value) {
+            Add-Content -Encoding utf8 $env:GITHUB_ENV "$name=$value"
+          }
+        }
+        @("cl.exe", "lib.exe", "link.exe", "rc.exe", "mt.exe") |
+          ForEach-Object { Split-Path (Get-Command $_).Source } |
+          Select-Object -Unique |
+          ForEach-Object { Add-Content -Encoding utf8 $env:GITHUB_PATH $_ }
+
+        # MSYS2 stores compiler-rt under its GNU archive name. Clang's MSVC
+        # target searches the equivalent target-specific COFF layout, so make
+        # the same archive visible there without changing its ABI or contents.
+        $clang = Join-Path $env:MSYS2_LOCATION "clang64\bin\clang.exe"
+        if (-not (Test-Path $clang)) {
+          throw "LLVM 19 clang was not found at $clang"
+        }
+        $resourceDir = (& $clang -print-resource-dir).Trim()
+        $gnuBuiltins = Join-Path $resourceDir "lib\windows\libclang_rt.builtins-x86_64.a"
+        if (-not (Test-Path $gnuBuiltins)) {
+          throw "LLVM 19 compiler-rt archive was not found at $gnuBuiltins"
+        }
+        $msvcRuntimeDir = Join-Path $resourceDir "lib\x86_64-pc-windows-msvc"
+        New-Item -ItemType Directory -Force $msvcRuntimeDir | Out-Null
+        Copy-Item -Force $gnuBuiltins (Join-Path $msvcRuntimeDir "clang_rt.builtins.lib")
+
     - name: Install macOS dependencies
       if: runner.os == 'macOS'
       shell: bash
+      env:
+        HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: 1
       run: |
         brew update
-        brew install llvm@${{inputs.llvm-version}} lld@${{inputs.llvm-version}} bdw-gc openssl libffi libuv
-        brew link --overwrite llvm@${{inputs.llvm-version}} lld@${{inputs.llvm-version}} libffi
-        echo "$(brew --prefix llvm@${{inputs.llvm-version}})/bin" >> $GITHUB_PATH
+
+        # Install LLVM if requested
+        if [[ "${{ inputs.install-llvm }}" == "true" ]]; then
+          llvm_formula="llvm@${{inputs.llvm-version}}"
+          lld_formula="lld@${{inputs.llvm-version}}"
+
+          # GitHub macOS runners may pre-link another LLVM/LLD version (for example llvm@18),
+          # which makes lld@<target> fail during Homebrew's automatic link step.
+          while IFS= read -r formula; do
+            case "${formula}" in
+              llvm|llvm@*|lld|lld@*)
+                if [[ "${formula}" != "${llvm_formula}" && "${formula}" != "${lld_formula}" ]]; then
+                  brew unlink "${formula}" || true
+                fi
+                ;;
+            esac
+          done < <(brew list --formula)
+
+          brew install "${llvm_formula}" "${lld_formula}"
+          brew link --force --overwrite "${llvm_formula}" "${lld_formula}"
+          llvm_bin="$(brew --prefix "${llvm_formula}")/bin"
+          lld_bin="$(brew --prefix "${lld_formula}")/bin"
+          echo "${llvm_bin}" >> "$GITHUB_PATH"
+
+          # Print resolved toolchain versions for CI diagnostics.
+          echo "LLVM/LLD versions:"
+          brew list --versions "${llvm_formula}" "${lld_formula}"
+          clang_version="$("${llvm_bin}/clang" --version | head -n 1)"
+          lld_version="$("${lld_bin}/ld.lld" --version | head -n 1)"
+          echo "clang: ${clang_version}"
+          echo "ld.lld: ${lld_version}"
+          echo "linked ld.lld path: $(command -v ld.lld || true)"
+        fi
+
+        # Install common dependencies
+        brew install bdw-gc openssl libffi libuv
+        brew link --overwrite libffi
 
         # Install optional deps for demos.
         #
         # NOTE: Keep this list updated as new deps are introduced.
         opt_deps=(
           cjson       # for github.com/goplus/lib/c/cjson
           sqlite      # for github.com/goplus/lib/c/sqlite
-          python@3.12 # for github.com/goplus/lib/py
         )
         brew install "${opt_deps[@]}"
+
+        brew install python@3.12 || true # for github.com/goplus/lib/py
+        brew link --overwrite python@3.12
+
     - name: Install Ubuntu dependencies
       if: runner.os == 'Linux'
       shell: bash
       run: |
-        echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-${{inputs.llvm-version}} main" | sudo tee /etc/apt/sources.list.d/llvm.list
-        wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
-        sudo apt-get update
-        sudo apt-get install -y llvm-${{inputs.llvm-version}}-dev clang-${{inputs.llvm-version}} libclang-${{inputs.llvm-version}}-dev lld-${{inputs.llvm-version}} libunwind-${{inputs.llvm-version}}-dev libc++-${{inputs.llvm-version}}-dev pkg-config libgc-dev libssl-dev zlib1g-dev libffi-dev libcjson-dev libuv1-dev 
-        echo "PATH=/usr/lib/llvm-${{inputs.llvm-version}}/bin:$PATH" >> $GITHUB_ENV
+        # Install LLVM if requested
+        if [[ "${{ inputs.install-llvm }}" == "true" ]]; then
+          echo "deb http://apt.llvm.org/$(lsb_release -cs)/ llvm-toolchain-$(lsb_release -cs)-${{inputs.llvm-version}} main" | sudo tee /etc/apt/sources.list.d/llvm.list
+          wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+          sudo apt-get update
+          sudo apt-get install -y llvm-${{inputs.llvm-version}}-dev clang-${{inputs.llvm-version}} libclang-${{inputs.llvm-version}}-dev lld-${{inputs.llvm-version}} libunwind-${{inputs.llvm-version}}-dev libc++-${{inputs.llvm-version}}-dev
+          echo "PATH=/usr/lib/llvm-${{inputs.llvm-version}}/bin:$PATH" >> $GITHUB_ENV
+        else
+          sudo apt-get update
+        fi
+
+        # Install common dependencies
+        sudo apt-get install -y pkg-config libgc-dev libssl-dev zlib1g-dev libffi-dev libcjson-dev libuv1-dev
 
         # Install optional deps for demos.
         #

.github/actions/setup-embed-deps/action.yml

@@ -0,0 +1,37 @@
+name: "Setup Embedded Dependencies"
+description: "Install dependencies required for embedded QEMU tests"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install macOS embedded dependencies
+      if: runner.os == 'macOS'
+      shell: bash
+      env:
+        HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: 1
+      run: |
+        brew update
+        brew install sdl2
+
+    - name: Install Ubuntu embedded dependencies
+      if: runner.os == 'Linux'
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libsdl2-2.0-0 libslirp0
+
+    - name: Install ESP QEMU toolchains
+      shell: bash
+      run: |
+        chmod +x .github/workflows/install-esp-qemu.sh
+        QEMU_DIR=".cache/qemu"
+        .github/workflows/install-esp-qemu.sh "$QEMU_DIR"
+        echo "${PWD}/${QEMU_DIR}/bin" >> $GITHUB_PATH
+
+    - name: Verify ESP QEMU installation
+      shell: bash
+      run: |
+        which qemu-system-riscv32
+        which qemu-system-xtensa
+        qemu-system-riscv32 --version
+        qemu-system-xtensa --version