action.yml

name: Python Binary Build Action
description: Build Python applications into standalone executables for multiple architectures

inputs:
  scripts:
    description: Space-separated list of Python scripts to build
    required: true
  output-dir:
    description: Output directory for built executables
    required: true
  include-data-dirs:
    description: 'JSON object mapping script names to data directories to include.
      Supports wildcards (*) and exact matches. Format: {"script.py": ["./data"],
      "*": ["./common"]}'
    required: false
    default: '[]'
  script-name:
    description: Space-separated list of output names for executables. Must match
      the length of `scripts` variable. If not provided, the script name will be used.
    required: false
    default: ''
  icon-file:
    description: Path to icon file (Windows only)
    required: false
    default: ''
  target-platform:
    description: 'Target platform: windows-amd64, linux-amd64, macos-amd64, macos-arm64,
      linux-armv7, linux-aarch64'
    required: true
  python-version:
    description: Python version to use for building. Make sure that the version is
      available on all runners.
    required: false
    default: '3.13'
  pyinstaller-version:
    description: PyInstaller version to install. Default is 6.11.1 because it has
      the lowest false positive rate with antivirus. For latest version, use empty
      string.
    required: false
    default: 6.11.1
  additional-args:
    description: Additional PyInstaller arguments
    required: false
    default: ''
  pip-extra-index-url:
    description: Extra Python Package Index URL
    required: false
    default: https://dl.espressif.com/pypi
  install-deps-command:
    description: Command to install project dependencies. Command will be executed
      like `uv pip install {install-deps-command}`
    required: false
    default: uv pip install -e .
  additional-arm-packages:
    description: 'ARMv7 ONLY: Optional extra apt packages (space-separated). The Espressif
      idf-python-wheels-armv7l image already includes build tools, libffi-dev, libssl-dev,
      patchelf, etc.; omit this unless you need more.'
    required: false
    default: ''
  test-command-args:
    description: Command arguments to test binaries (e.g. "--help")
    required: false
    default: --help
  azure-client-id:
    description: Azure client ID for espressif/release-sign action
    required: false
    default: ''
  azure-client-secret:
    description: Azure client secret for espressif/release-sign action
    required: false
    default: ''
  azure-tenant-id:
    description: Azure tenant ID for espressif/release-sign action
    required: false
    default: ''
  azure-keyvault-uri:
    description: Azure key vault URI for espressif/release-sign action
    required: false
    default: ''
  azure-keyvault-cert-name:
    description: Azure key vault certificate name for espressif/release-sign action
    required: false
    default: ''

outputs:
  executable-extension:
    description: File extension of built executables
    value: ${{ steps.setup-platform.outputs.exe-extension }}
  build-success:
    description: Whether the build was successful
    value: ${{ steps.build.outputs.success }}

runs:
  using: composite
  steps:
    - name: Setup platform variables
      id: setup-platform
      shell: bash
      run: |
        case "${{ inputs.target-platform }}" in
          windows-amd64)
            echo "exe-extension=.exe" >> $GITHUB_OUTPUT
            echo "data-separator=;" >> $GITHUB_OUTPUT
            echo "needs-docker=false" >> $GITHUB_OUTPUT
            echo "needs-arm-emulation=false" >> $GITHUB_OUTPUT
            ;;
          linux-amd64|linux-aarch64)
            echo "exe-extension=" >> $GITHUB_OUTPUT
            echo "data-separator=:" >> $GITHUB_OUTPUT
            echo "needs-docker=true" >> $GITHUB_OUTPUT
            echo "needs-arm-emulation=false" >> $GITHUB_OUTPUT
            ;;
          macos-amd64|macos-arm64)
            echo "exe-extension=" >> $GITHUB_OUTPUT
            echo "data-separator=:" >> $GITHUB_OUTPUT
            echo "needs-docker=false" >> $GITHUB_OUTPUT
            echo "needs-arm-emulation=false" >> $GITHUB_OUTPUT
            ;;
          linux-armv7)
            echo "exe-extension=" >> $GITHUB_OUTPUT
            echo "data-separator=:" >> $GITHUB_OUTPUT
            echo "needs-docker=false" >> $GITHUB_OUTPUT
            echo "needs-arm-emulation=true" >> $GITHUB_OUTPUT
            ;;
        esac

    - name: Prepare build environment
      shell: bash
      run: |
        # Create output directory
        mkdir -p "${{ inputs.output-dir }}"

        # Write include-data-dirs to a temporary file to avoid shell escaping issues
        echo '${{ inputs.include-data-dirs }}' > ${GITHUB_ACTION_PATH}/include_data_dirs.json

    - name: Set up QEMU for ARMv7 Docker
      if: inputs.target-platform == 'linux-armv7'
      uses: docker/setup-qemu-action@v3

    - name: Build for ARMv7 architecture
      if: inputs.target-platform == 'linux-armv7'
      shell: bash
      run: |
        docker run --rm \
          --platform linux/arm/v7 \
          -v "${PWD}/${{ inputs.output-dir }}:/${{ inputs.output-dir }}" \
          -v "${GITHUB_ACTION_PATH}:/github/action" \
          -v "${GITHUB_WORKSPACE}:/${GITHUB_WORKSPACE}" \
          -w ${GITHUB_WORKSPACE} \
          ghcr.io/espressif/github-esp-dockerfiles/idf-python-wheels-armv7l:v1 \
          bash -c "
          export DEBIAN_FRONTEND=noninteractive &&
          export TZ=UTC &&
          if [ -n '${{ inputs.additional-arm-packages }}' ]; then
            apt-get update -y &&
            apt-get install -y ${{ inputs.additional-arm-packages }}
          fi &&
          curl -LsSf https://astral.sh/uv/install.sh | sh &&
          source /root/.local/bin/env &&
          uv python install ${{ inputs.python-version }} &&
          uv venv &&
          source .venv/bin/activate &&
          uv pip install --upgrade setuptools wheel &&

          export GITHUB_ACTION_PATH=/github/action &&
          /github/action/setup_environment.sh \
            '${{ inputs.pyinstaller-version }}' \
            '${{ inputs.pip-extra-index-url }}' \
            '${{ inputs.install-deps-command }}' &&

          /github/action/build_with_pyinstaller.sh '${{ inputs.target-platform }}' '${{ inputs.output-dir }}' '${{ inputs.scripts }}' '${{ inputs.script-name }}' '${{ inputs.icon-file }}' '/github/action/include_data_dirs.json' '${{ steps.setup-platform.outputs.data-separator }}' '${{ inputs.additional-args }}' &&

          /github/action/test_executables.sh \
            '${{ inputs.scripts }}' \
            '${{ inputs.script-name }}' \
            '${{ inputs.output-dir }}' \
            '${{ steps.setup-platform.outputs.exe-extension }}' \
            '${{ inputs.test-command-args }}'
          "

    - name: Build for Linux (Docker)
      # Running in Docker to link older versions of GLIBC, because the GitHub runners don't offer ubuntu 20.04 anymore
      if: steps.setup-platform.outputs.needs-docker == 'true'
      shell: bash
      run: |
        docker run --rm \
          -v "${PWD}/${{ inputs.output-dir }}:/${{ inputs.output-dir }}" \
          -v "${GITHUB_ACTION_PATH}:/github/action" \
          -v "${GITHUB_WORKSPACE}:/${GITHUB_WORKSPACE}" \
          -w ${GITHUB_WORKSPACE} \
          ubuntu:20.04 \
          bash -c "
          export DEBIAN_FRONTEND=noninteractive &&
          export TZ=UTC &&
          apt-get update -y &&
          apt-get install -y curl git build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev pkg-config gcc g++ patchelf binutils &&
          curl -LsSf https://astral.sh/uv/install.sh | sh &&
          source /root/.local/bin/env &&
          # Install Python version using uv
          uv python install ${{ inputs.python-version }} &&
          # Create and activate virtual environment
          uv venv &&
          source .venv/bin/activate &&
          # Install UV and upgrade tools
          uv pip install --upgrade setuptools wheel &&

          export GITHUB_ACTION_PATH=/github/action &&
          /github/action/setup_environment.sh \
            '${{ inputs.pyinstaller-version }}' \
            '${{ inputs.pip-extra-index-url }}' \
            '${{ inputs.install-deps-command }}' &&

          # Execute the build script
          /github/action/build_with_pyinstaller.sh '${{ inputs.target-platform }}' '${{ inputs.output-dir }}' '${{ inputs.scripts }}' '${{ inputs.script-name }}' '${{ inputs.icon-file }}' '/github/action/include_data_dirs.json' '${{ steps.setup-platform.outputs.data-separator }}' '${{ inputs.additional-args }}'
          "

    - name: Install UV
      if: |
        steps.setup-platform.outputs.needs-docker == 'false' && steps.setup-platform.outputs.needs-arm-emulation == 'false'
      uses: astral-sh/setup-uv@v6
      with:
        enable-cache: true

    - name: Setup environment (Native platforms)
      if: |
        steps.setup-platform.outputs.needs-docker == 'false' && steps.setup-platform.outputs.needs-arm-emulation == 'false'
      shell: bash
      run: |
        # Create and activate virtual environment
        uv venv
        if [ "${{ inputs.target-platform }}" == 'windows-amd64' ]; then
          source .venv\\Scripts\\activate
        else
          source .venv/bin/activate
        fi

        $GITHUB_ACTION_PATH/setup_environment.sh \
          '${{ inputs.pyinstaller-version }}' \
          '${{ inputs.pip-extra-index-url }}' \
          '${{ inputs.install-deps-command }}'

    - name: Build with PyInstaller (Native platforms)
      if: |
        steps.setup-platform.outputs.needs-docker == 'false' && steps.setup-platform.outputs.needs-arm-emulation == 'false'
      id: build
      shell: bash
      run: |
        $GITHUB_ACTION_PATH/build_with_pyinstaller.sh '${{ inputs.target-platform }}' '${{ inputs.output-dir }}' '${{ inputs.scripts }}' '${{ inputs.script-name }}' '${{ inputs.icon-file }}' '${{ inputs.include-data-dirs }}' '${{ steps.setup-platform.outputs.data-separator }}' '${{ inputs.additional-args }}'

        echo "success=true" >> $GITHUB_OUTPUT

    - name: Verify builds
      if: steps.setup-platform.outputs.needs-arm-emulation == 'false'
      shell: bash
      run: |-
        $GITHUB_ACTION_PATH/test_executables.sh \
          "${{ inputs.scripts }}" \
          "${{ inputs.script-name }}" \
          "${{ inputs.output-dir }}" \
          "${{ steps.setup-platform.outputs.exe-extension }}" \
          "${{ inputs.test-command-args }}"

    - name: Check signing certificate
      if: |
        inputs.target-platform == 'windows-amd64' && inputs.azure-client-secret == ''
      shell: pwsh
      run: |
        Write-Host "::warning title=Signing::Azure client secret is not set, skipping signing"

    - name: Sign binaries
      if: |
        inputs.target-platform == 'windows-amd64' && inputs.azure-client-secret != ''
      uses: espressif/release-sign@master
      with:
        path: ${{ inputs.output-dir }}
        azure-client-id: ${{ inputs.azure-client-id }}
        azure-client-secret: ${{ inputs.azure-client-secret }}
        azure-tenant-id: ${{ inputs.azure-tenant-id }}
        azure-keyvault-uri: ${{ inputs.azure-keyvault-uri }}
        azure-keyvault-cert-name: ${{ inputs.azure-keyvault-cert-name }}

    - name: Remove leftover signature files
      if: |
        inputs.target-platform == 'windows-amd64' && inputs.azure-client-secret != ''
      shell: bash
      run: find ./${{ inputs.output-dir }} -name "*.sig" -type f -delete