Metadata-Version: 2.4
Name: python2binary
Version: 0.2.1
Summary: Bundle a Python project into a native launcher for a host Python environment, Update Include jetson Deployment systemd
Author-email: FauzanAriyatmoko <fauzan.ariyatmoko@gmail.com>
Project-URL: Homepage, https://github.com/FauzanAriyatmoko/python2binary
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# python2binary

`python2binary` adalah CLI untuk membungkus source proyek Python menjadi executable launcher native. Interpreter dan dependency tetap berasal dari environment Python pada mesin target, misalnya virtual environment aplikasi.

Untuk deployment Linux edge seperti Jetson Orin Nano, tool ini juga bisa menyiapkan deployment bundle berisi binary, `config`, `models`, `env`, dan skrip install/systemd agar artefaknya lebih dekat ke paket deploy yang benar-benar dipasang di device.

## Cara Kerja

Program ini bekerja melalui empat tahap:

1. **Pack**: Membungkus file `.py` proyek menjadi arsip `.pyz`.
2. **Convert**: Mengubah file `.pyz` menjadi header C (`.h`) menggunakan `xxd`.
3. **Compile**: Menghasilkan launcher C yang menyematkan data Python tersebut lalu mengompilasinya dengan `gcc` menjadi binary native.
4. **Deploy** (opsional): Menyalin aset tambahan dan membuat bundle deployment untuk instalasi Linux atau systemd.

Saat dijalankan, launcher menulis payload ke file temporer yang unik, menjalankannya dengan interpreter yang dipilih, meneruskan argumen dan sinyal, lalu menghapus payload tersebut.

## Prasyarat

Pada mesin build:

- Python 3.8+
- GCC
- XXD

Pada mesin target:

- Python yang kompatibel, biasanya dari venv aplikasi
- Semua dependency aplikasi sudah terinstal pada environment tersebut

GCC dan XXD hanya diperlukan saat build, bukan saat menjalankan binary.

```bash
sudo apt-get update
sudo apt-get install build-essential xxd
```

## Instalasi

```bash
source .binary/bin/activate
pip install -e .
```

## Penggunaan Dasar

```bash
python2binary \
  --project <direktori_proyek> \
  --entry <file_utama> \
  --output <folder_hasil> \
  [--name <nama_binary>] \
  [--python <path_interpreter>] \
  [--runtime-workdir <dir>] \
  [--include <src[:dest]> ...] \
  [--bundle-name <nama_bundle>] \
  [--service-name <nama_service>] \
  [--service-user <user>] \
  [--install-dir <target_dir>] \
  [--emit-install-scripts]
```

### Parameter

- `--project`, `-p`: Direktori root proyek Python.
- `--entry`, `-e`: Entry point relatif terhadap root, termasuk path bertingkat seperti `app/main.py`.
- `--output`, `-o`: Direktori artefak build.
- `--name`, `-n`: Nama binary. Default-nya memakai nama folder proyek.
- `--python`: Interpreter fallback yang disimpan di launcher. Bisa berupa executable di `PATH`, path absolut, atau path relatif terhadap lokasi binary seperti `env/bin/python3`.
- `--runtime-workdir`: Ubah `cwd` sebelum Python dijalankan. Path relatif di-resolve dari direktori binary.
- `--include`: Tambahkan file atau folder ke deployment bundle. Formatnya `SRC` atau `SRC:DEST`, dan dapat diulang.
- `--bundle-name`: Nama folder deployment bundle.
- `--service-name`: Nama file unit systemd yang digenerate ke deployment bundle.
- `--service-user`: Nilai `User=` untuk unit systemd.
- `--install-dir`: Target instalasi absolut yang dipakai oleh service dan script deploy.
- `--emit-install-scripts`: Generate `install.sh`, `uninstall.sh`, dan `monitor.sh` jika service juga diminta.

Interpreter saat runtime dipilih dengan urutan berikut:

1. Environment variable `PYTHON2BINARY_PYTHON`.
2. Nilai `--python` saat build.
3. `python3` dari `PATH` jika `--python` tidak diberikan.

Jika `PYTHON2BINARY_PYTHON` atau `--python` berisi path relatif seperti `env/bin/python3`, path tersebut akan di-resolve relatif terhadap lokasi binary. Ini memudahkan deployment bundle yang relocatable.

### Contoh Binary Sederhana

```bash
python2binary \
  -p ./my_script_folder \
  -e app/main.py \
  -o ./dist \
  -n my_application.bin \
  --python /opt/my_application/.venv/bin/python

./dist/my_application.bin --port 8080
```

## Deployment Bundle untuk Jetson Orin Nano

Untuk aplikasi seperti `snc-computer-vision`, binary saja belum cukup karena runtime masih membutuhkan folder `config`, `models`, dan sering kali `env`. Contoh build bundle yang cocok untuk pola deploy Jetson:

```bash
python2binary \
  -p ./snc-computer-vision \
  -e backend/app/main.py \
  -o ./dist \
  -n snc_bin \
  --python env/bin/python3 \
  --runtime-workdir . \
  --include config \
  --include models \
  --include .tested:env \
  --bundle-name snc-jetson-bundle \
  --service-name snc-cv.service \
  --service-user root \
  --install-dir /usr/local/bin/snc \
  --emit-install-scripts
```

Hasil bundle berisi:

- binary launcher native Linux
- folder `config/`, `models/`, dan `env/`
- `bundle_manifest.json`
- `snc-cv.service`
- `install.sh`, `uninstall.sh`, dan `monitor.sh`

Catatan penting untuk Jetson:

- Binary yang dihasilkan mengikuti arsitektur mesin build. Untuk Jetson Orin Nano ARM64, build sebaiknya dijalankan langsung di device Jetson atau di environment cross-compile yang memang menargetkan `aarch64`.
- `python2binary` tidak membekukan dependency Python menjadi satu ELF mandiri. Dependency tetap berasal dari interpreter atau venv yang Anda sertakan atau siapkan pada device.
- Jika aplikasi membaca file dengan path relatif seperti `config/config.json`, gunakan `--runtime-workdir .` atau `WorkingDirectory` systemd agar path tetap konsisten saat service berjalan.

## Menjalankan lewat systemd

Contoh unit file yang digenerate tool ini akan memakai pola seperti berikut:

```ini
[Unit]
Description=my_application service
After=network.target

[Service]
Type=simple
User=myapp
WorkingDirectory=/opt/my_application
ExecStart=/opt/my_application/my_application.bin
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

Aktivasi venv dengan `source` tidak diperlukan karena binary bisa memakai interpreter absolut atau relatif terhadap bundle.

## Struktur Proyek

- `main.py`: Entry point CLI.
- `pipeline.py`: Orkestrasi pipeline build.
- `infrastructure/`: Implementasi teknis untuk packing, konversi, kompilasi, dan deployment bundle.
- `interfaces/`: Definisi abstraksi setiap tahapan pipeline.
- `schemas/`: Struktur data untuk konfigurasi dan hasil build.

## Lisensi

MIT
