mirror of
https://github.com/blw1138/cross-py-builder.git
synced 2026-09-07 21:41:09 -05:00
Brett Williams
6f38beaf92
Replace the retired CLI usage docs with the current flow: install the setuptools package (editable) on each host, then run cross-py-agent on the workers and cross-py-controller on the UI host with a CROSS_PY_WORKERS list.
124 lines
3.6 KiB
Markdown
124 lines
3.6 KiB
Markdown
# Cross-Py-Builder
|
|
|
|
Cross-Py-Builder is a remote build tool for compiling Python projects with PyInstaller on
|
|
different platforms (Linux, macOS, Windows) across a local network.
|
|
|
|
It has two parts:
|
|
|
|
- **Controller** — a small web service with a browser UI for submitting builds (upload a zip
|
|
or point at a git repo), tracking live progress, and downloading the resulting binaries.
|
|
- **Agent** (worker) — one per target OS/CPU. Runs the actual PyInstaller builds and exposes
|
|
them over HTTP; the controller dispatches builds to an agent matching the requested
|
|
OS + CPU.
|
|
|
|
## System Requirements
|
|
- **Ubuntu/Debian & macOS:** 2GB+ RAM
|
|
- **Windows:** 4GB+ RAM
|
|
- **Python 3.10 or later** installed on each host
|
|
- **Local network** between the controller and the agents
|
|
|
|
---
|
|
|
|
## How it's packaged
|
|
|
|
This is a Python package installed with `setuptools` (`setup.py`). Installing it (editable, for
|
|
development) makes two commands available on your PATH:
|
|
|
|
| Command | Runs | Purpose |
|
|
|---|---|---|
|
|
| `cross-py-controller` | `ctrl.app:main` | Web UI + scheduler (the machine you browse to) |
|
|
| `cross-py-agent` | `agent.build_agent:main` | Worker agent (one per target OS/CPU) |
|
|
|
|
Start by installing the package into a virtualenv on **every** machine that will act as a
|
|
controller or agent:
|
|
|
|
```sh
|
|
cd cross-py-builder
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
|
|
pip install -e . # editable install: installs deps + links to your working dir
|
|
```
|
|
|
|
`-e` (editable) links the install to your checkout, so code changes take effect without
|
|
reinstalling. On the LXC workers you can alternatively copy the source and just run the `.py`
|
|
files (see below).
|
|
|
|
---
|
|
|
|
## Running a worker (agent)
|
|
|
|
On each target OS/CPU machine (e.g. each Ubuntu LXC):
|
|
|
|
```sh
|
|
cd cross-py-builder
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -e .
|
|
|
|
cross-py-agent
|
|
```
|
|
|
|
The agent binds on port `9001` and announces itself on the local network. To run it
|
|
directly without the package command:
|
|
|
|
```sh
|
|
pip install -r requirements.txt
|
|
python agent/build_agent.py
|
|
```
|
|
|
|
---
|
|
|
|
## Running the controller
|
|
|
|
On the machine that will serve the browser UI:
|
|
|
|
```sh
|
|
cd cross-py-builder
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -e .
|
|
```
|
|
|
|
Set the static worker list (JSON array of `host:port`, matching where your agents are
|
|
listening) and start it:
|
|
|
|
```sh
|
|
CROSS_PY_WORKERS='["192.168.1.40:9001","192.168.1.41:9001"]' \
|
|
cross-py-controller
|
|
```
|
|
|
|
Then open `http://<controller-ip>:8080` in a browser.
|
|
|
|
### Controller environment variables
|
|
|
|
| Variable | Default | Purpose |
|
|
|---|---|---|
|
|
| `CROSS_PY_WORKERS` | (none) | JSON array of agent `host:port` strings |
|
|
| `CROSS_PY_PORT` | `8080` | HTTP port the controller UI listens on |
|
|
| `CROSS_PY_MAX_CONCURRENT` | `1` | Max simultaneous builds (across distinct agents) |
|
|
| `CROSS_PY_DATA` | `<repo>/data` | Data dir (jobs DB, uploaded sources) |
|
|
| `CROSS_PY_BUILDS` | `<data>/builds` | Dir where finished build artifacts are saved |
|
|
| `CROSS_PY_DEBUG` | off | Use Flask dev server instead of waitress |
|
|
|
|
---
|
|
|
|
## Using the UI
|
|
|
|
1. Open the controller in a browser.
|
|
2. Pick the target **OS** and **CPU** (or "any").
|
|
3. Either upload a `.zip` of your project (PyInstaller spec + source) or paste a git
|
|
`repo_url`.
|
|
4. Submit. The job is queued → dispatched to a matching agent → built → artifacts fetched.
|
|
5. Watch live per-step progress, then download the built binaries from the job detail.
|
|
|
|
A submitted project only needs the source plus at least one `*.spec` file; each spec file in
|
|
the archive produces a build.
|
|
|
|
---
|
|
|
|
## Retired CLI
|
|
|
|
The original single-command CLI (`./cross-py-builder.py --build ...`, `agent_manager.py`) has been
|
|
removed and replaced by the controller + agent model above.
|