Skip to content

Commit c623aaa

Browse files
peterdragunpeterdragun
committed
feat: Add a initial version of the action
1 parent 18da8b6 commit c623aaa

File tree

3 files changed

+550
-1
lines changed

3 files changed

+550
-1
lines changed

‎README.md‎

Lines changed: 175 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,175 @@
1-
# python-binary-action
1+
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/espressif/python-binary-action/master.svg)](https://results.pre-commit.ci/latest/github/espressif/python-binary-action/master)
2+
3+
# Python Binary Build Action
4+
5+
A GitHub Action for building Python applications into standalone executables using `PyInstaller` across multiple architectures and platforms.
6+
7+
## Overview
8+
9+
This action automates the process of creating standalone executables from Python applications using `PyInstaller`. It supports multiple target platforms including Windows, macOS, and Linux (both x86_64 and ARM architectures). The action handles platform-specific configurations, dependency installation, and binary verification automatically.
10+
11+
## Supported Platforms
12+
13+
- **Windows**: `windows-amd64`
14+
- **Linux**: `linux-amd64`, `linux-armv7`, `linux-aarch64`
15+
- **macOS**: `macos-amd64`, `macos-arm64`
16+
17+
## Inputs
18+
19+
### Required Inputs
20+
21+
| Input | Description | Example |
22+
|-------------------|-----------------------------------------------|----------------------------|
23+
| `python-files` | Space-separated list of Python files to build | `"main.py utils.py"` |
24+
| `output-dir` | Output directory for built executables | `"./dist-linux-amd64"` |
25+
| `target-platform` | Target platform for the build | `"linux-amd64"` |
26+
27+
### Optional Inputs
28+
29+
| Input | Description | Default | Example |
30+
|---------------------------|-------------------------------------------|---------------------------------------------|-----------------------------------------|
31+
| `include-data-dirs` | Mapping script names to data directories to include. Supports wildcards (*). | `[]` | `{"main.py": [{"src": "./data", "dest": "./data"}], "*": [{"src": "./common", "dest": "./common"}]}` |
32+
| `icon-file` | Path to icon file (Windows only) | `""` | `"./icon.ico"` |
33+
| `python-version` | Python version to use | `"3.11"` | `"3.12"` |
34+
| `pyinstaller-version` | PyInstaller version to install | `"latest"` | `"6.3.0"` |
35+
| `additional-args` | Additional PyInstaller arguments | `""` | `"--hidden-import=module"` |
36+
| `pip-extra-index-url` | Extra pip index URL | `"https://dl.espressif.com/pypi"` | `""` |
37+
| `install-deps-command` | Command to install project dependencies | `"pip install --user --prefer-binary -e ."` | `"pip install -r requirements.txt"` |
38+
| `additional-arm-packages` | ARMv7 ONLY: Additional system packages | `""` | `"openssl libffi-dev"` |
39+
| `test-command-args` | Command arguments to test binaries | `"-h"` | `"--version"` |
40+
41+
## Outputs
42+
43+
| Output | Description |
44+
|------------------------|----------------------------------------------------------------|
45+
| `executable-extension` | File extension of built executables (e.g., `.exe` for Windows) |
46+
| `build-success` | Whether the build was successful (`true`/`false`) |
47+
48+
## Features
49+
50+
- **Multi-architecture support**: Builds for x86_64 and ARM architectures
51+
- **Cross-platform compatibility**: Supports Windows, macOS, and Linux
52+
- **Automatic dependency handling**: Installs Python dependencies and system packages
53+
- **Flexible data file inclusion**: Supports per-script configuration with wildcard support
54+
- **Binary verification**: Tests built executables to ensure they run correctly
55+
- **Windows icon support**: Allows custom icons for Windows executables
56+
- **Flexible `PyInstaller` configuration**: Supports additional `PyInstaller` arguments
57+
- **ARM cross-compilation**: Uses Docker containers for ARMv7 architecture builds
58+
59+
## Usage Examples
60+
61+
### Basic Usage
62+
63+
```yaml
64+
- name: Build Python executable
65+
uses: ./.github/actions/pyinstaller-build-multiarch
66+
with:
67+
python-files: 'main.py'
68+
output-dir: './dist'
69+
target-platform: 'linux-amd64'
70+
```
71+
72+
### Multi-File Build with Data
73+
74+
```yaml
75+
- name: Build multiple executables
76+
uses: ./.github/actions/pyinstaller-build-multiarch
77+
with:
78+
python-files: 'app.py utils.py cli.py'
79+
output-dir: './binaries'
80+
target-platform: 'windows-amd64'
81+
include-data-dirs: |
82+
{
83+
"app.py": [{"src": "./assets", "dest": "./assets"}],
84+
"*": [{"src": "./config", "dest": "./config"}]
85+
}
86+
icon-file: './icon.ico'
87+
```
88+
89+
### ARM Architecture Build
90+
91+
```yaml
92+
- name: Build for ARMv7
93+
uses: ./.github/actions/pyinstaller-build-multiarch
94+
with:
95+
python-files: 'main.py'
96+
output-dir: './arm-binaries'
97+
target-platform: 'linux-armv7'
98+
additional-arm-packages: 'openssl libffi-dev libffi7 libssl-dev'
99+
python-version: '3.11'
100+
```
101+
102+
### Custom PyInstaller Configuration
103+
104+
```yaml
105+
- name: Build with custom options
106+
uses: ./.github/actions/pyinstaller-build-multiarch
107+
with:
108+
python-files: 'app.py'
109+
output-dir: './dist'
110+
target-platform: 'macos-arm64'
111+
additional-args: '--hidden-import=requests --hidden-import=urllib3 --strip'
112+
pyinstaller-version: '6.3.0'
113+
test-command-args: '--version'
114+
```
115+
116+
### Complete Workflow Example
117+
118+
```yaml
119+
name: Build Executables
120+
121+
on: [push, pull_request]
122+
123+
jobs:
124+
build:
125+
runs-on: ubuntu-latest
126+
strategy:
127+
fail-fast: false
128+
matrix:
129+
platform: [windows-amd64, linux-amd64, macos-arm64]
130+
131+
env:
132+
STUBS_DIR: ./esptool/targets/stub_flasher/
133+
134+
steps:
135+
- name: Checkout code
136+
uses: actions/checkout@v4
137+
138+
- name: Set up Python
139+
uses: actions/setup-python@v5
140+
with:
141+
python-version: '3.11'
142+
143+
- name: Build executable
144+
uses: ./.github/actions/pyinstaller-build-multiarch
145+
with:
146+
python-files: 'esptool.py'
147+
output-dir: './dist-${{ matrix.platform }}'
148+
target-platform: ${{ matrix.platform }}
149+
include-data-dirs: |
150+
{
151+
"epstool.py": [
152+
{"src": "${{ env.STUBS_DIR }}1", "dest": "${{ env.STUBS_DIR }}1"},
153+
{"src": "${{ env.STUBS_DIR }}2", "dest": "${{ env.STUBS_DIR }}2"},
154+
]
155+
}
156+
157+
- name: Add license and readme
158+
shell: bash
159+
run: mv LICENSE README.md ./dist-${{ matrix.platform }}
160+
161+
- name: Upload artifacts
162+
uses: actions/upload-artifact@v4
163+
with:
164+
name: executable-${{ matrix.platform }}
165+
path: ./dist-${{ matrix.platform }}
166+
```
167+
168+
## Notes
169+
170+
- For 32-bit ARM architecture (linux-armv7), the action uses Docker containers to provide the necessary build environment
171+
- For 64-bit ARM architecture please use the GitHub provided runners, e.g. `ubuntu-22.04-arm`. Please note that this is still in public preview so there might be some changes to images. For more details see [available runners](https://docs.github.com/en/actions/how-tos/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources).
172+
- Windows builds automatically include `.exe` extensions
173+
- The action automatically tests built executables using the specified test command arguments
174+
- System packages for ARMv7 builds can be customized using the `additional-arm-packages` input. For other systems this can be done before running this action.
175+
- It is recommended to add `fail-fast: false` to your matrix strategy to prevent one platform failure from stopping all builds

0 commit comments

Comments
 (0)