Metadata-Version: 2.4
Name: bat2pe
Version: 1.4.8
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Rust
Summary: Windows Bat/Cmd to Exe converter with Rust CLI and Python API.
Author: Bat2PE Contributors
License: MPL-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Bat2PE

<div align="center">

![Bat2PE](https://socialify.git.ci/271374667/Bat2PE/image?description=1&language=1&name=1&owner=1&pattern=Plus&theme=Auto)

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](#quick-start)
[![Rust](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](#quick-start)
[![Platform](https://img.shields.io/badge/platform-Windows%2010%2F11-success.svg)](#highlights)
[![License](https://img.shields.io/badge/license-MPL--2.0-green.svg)](LICENSE)

[English README](README.md) | [中文说明](README_CN.md) | [Python API](docs/python-api.md) 

**Convert `.bat` / `.cmd` scripts to standalone `.exe` via CLI or Python module**  
**Fully compatible runtime behavior, custom icon & metadata, UAC elevation, passes Kaspersky and common AV scans, zero runtime dependencies**

</div>

> Existing solutions like Bat To Exe Converter fall short for professionals who need to integrate the conversion step into automated workflows. Bat2PE offers no GUI — instead it provides a CLI and a directly callable Python module, letting you convert batch scripts to executables in one command and fold distribution into your pipeline.

Executables generated by Bat2PE behave identically to the original batch script, preserving `%~dp0` and other special variables. You can embed a custom icon, set version info, company name, and other file metadata. One flag adds UAC elevation. The output passes Kaspersky (free edition) and common antivirus scans. The generated `.exe` runs standalone with zero extra dependencies.

## Highlights

- **`build → inspect → verify` pipeline** — generate, examine, and validate without switching tools
- **`%~dp0` semantics preserved** — temp script is written beside the `.exe`, not in `%TEMP%`, minimizing broken relative paths
- **Window mode** — defaults to `hidden` (silent background); add `--visible` for a foreground console
- **Multi-encoding support** — `UTF-8` · `UTF-8 BOM` · `UTF-16 LE BOM` · `ANSI/GBK` auto-detected
- **Dual entry points** — CLI for terminals and CI/CD, Python API for scripting and automation workflows
- **Native Windows resource writing** — icon, version number, company name, and other metadata written to PE resource sections, visible in Explorer
- **UAC elevation** — a single `--uac` or `uac=True` makes the generated `.exe` request admin privileges
- **AV-friendly** — generated executables pass Kaspersky Free and common antivirus scans
- **Zero extra dependencies** — generated `.exe` runs standalone, no runtime installation required

## Installation

### Python Users

```bash
pip install bat2pe
```

After installation, call `from bat2pe import build` directly in your Python code.

### CLI Users

Download `bat2pe.exe` from [GitHub Releases](https://github.com/271374667/Bat2PE/releases) and you're ready to go.

### System Requirements

| Dependency | Minimum Version |
|------------|----------------|
| OS | Windows 10 / 11 (x64) |
| Python (only for Python API) | 3.10+ |
| Rust (only for building from source) | 1.85+ |

## Quick Start

### CLI Usage

**Simplest conversion** — one command, generates a same-name `.exe` beside the script:

```powershell
bat2pe build run.bat
```

**Specify output path and icon**:

```powershell
bat2pe build run.bat --output-exe-path dist\run.exe --icon-path app.ico
```

**Show console window** (for interactive foreground tools):

```powershell
bat2pe build run.bat --visible
```

**Add UAC admin elevation**:

```powershell
bat2pe build admin.cmd --uac
```

**Write full version metadata**:

```powershell
bat2pe build run.bat ^
  --company "Acme Corp" ^
  --product "My Tool" ^
  --description "Launcher" ^
  --file-version 1.2.3 ^
  --product-version 1.2.3
```

> 💡 Besides `build`, there are also `inspect` (view exe metadata) and `verify` (check behavioral consistency) subcommands. Run `bat2pe <command> --help` for full details.

### Python Usage

#### Functional API (recommended for quick use)

```python
from bat2pe import build

result = build(input_bat_path="run.bat")
print(result.output_exe_path)  # run.exe
```

#### Object-Oriented API (recommended for complex scenarios)

```python
from bat2pe import Builder

builder = Builder(
    input_bat_path="run.bat",
    output_exe_path="dist/run.exe",
    # visible defaults to False (hidden); set True for console window
    icon_path="app.ico",
    company_name="Acme Corp",
    product_name="My Tool",
    file_version="1.2.3",
)
result = builder.build()
```

#### UAC Elevation

```python
from bat2pe import build

result = build(
    input_bat_path="admin_task.bat",
    uac=True,
)
```

#### Error Handling

```python
from bat2pe import build, BuildError, ERR_UNSUPPORTED_INPUT

try:
    build(input_bat_path="readme.txt")
except BuildError as e:
    if e.code == ERR_UNSUPPORTED_INPUT:
        print("Only .bat or .cmd files are supported")
    print(e.code, e.path, e.details)
```

For the full Python API reference (including `inspect`, `verify`, and other advanced usage), see [docs/python-api.md](docs/python-api.md).

## How It Works

Bat2PE embeds a batch script into a native Windows PE executable. At runtime, the generated `.exe`:

1. Reads the embedded script content from its own PE resources
2. Writes a temporary `.cmd` file (with hidden attribute) in the `.exe`'s directory
3. Executes the temp script via `cmd.exe /d /c`, forwarding all command-line arguments
4. Automatically deletes the temp file after execution, with orphan cleanup on abnormal termination

**Why not write to `%TEMP%`?** Because many batch scripts rely on `%~dp0` to locate adjacent config files or resource directories. Placing the temp script beside the `.exe` preserves this semantic as much as possible, keeping behavior consistent with the original script.

### Architecture Overview

```
┌──────────────┐    ┌──────────────┐    ┌──────────────────┐
│  CLI Users   │    │ Python Users │    │  CI/CD Pipelines │
└──────┬───────┘    └──────┬───────┘    └────────┬─────────┘
       │                   │                     │
       ▼                   ▼                     ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────────┐
│  bat2pe.exe  │    │bat2pe._native│    │  bat2pe (Python)  │
│  (Rust CLI)  │    │(PyO3 Extension)│  │   pip install     │
└──────┬───────┘    └──────┬───────┘    └────────┬─────────┘
       │                   │                     │
       └───────────────────┴─────────────────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │   bat2pe-core   │
                  │  (Rust Core Lib)│
                  └─────────────────┘
```


## Building from Source (Developers)

If you want to build from source or contribute:

### Setup

```powershell
# Install dependencies
uv sync
```

### Build All Artifacts

```powershell
# Recommended (one-step build for CLI + Python extension)
uv run python scripts/compile.py

# For debug builds
uv run python scripts/compile.py --debug
```

Build outputs:

| Artifact | Description |
|----------|-------------|
| `target/release/bat2pe.exe` | Standalone CLI program |
| `python/bat2pe/_native.pyd` | Python native extension module |

### Manual Build

```powershell
cargo build --release -p bat2pe -p bat2pe-py
uv run maturin develop
```

### Running Tests

```powershell
# Rust unit tests
cargo test --workspace

# Python integration tests (CLI, Python API, runtime behavior, etc.)
uv run pytest
```

Test coverage includes:

- CLI help output, argument validation, full build/inspect/verify flow
- Python API functional + object-oriented dual interfaces
- Encoding detection and unsupported encoding rejection
- Typed exception mapping
- UAC manifest writing
- Native Windows version resource writing
- Runtime `%~dp0` behavior and working directory preservation
- Hidden window exit codes
- Temp file cleanup and forced termination cleanup
- Python 3.10 syntax compatibility checks


## Current Stage & Known Limitations

Bat2PE is ready for **single-script, launcher-style batch projects**. The `build → inspect → verify` workflow is fully operational.


| Item | Status |
|------|--------|
| Single `.bat` / `.cmd` script conversion | ✅ Fully supported |
| Icon & version metadata | ✅ Written to native Windows PE resources |
| UAC admin elevation | ✅ Supported |
| Hidden window mode | ✅ Supported |
| Multi-encoding auto-detection | ✅ UTF-8 / UTF-8 BOM / UTF-16 LE BOM / ANSI/GBK |


## License

This project is licensed under the [MPL-2.0](LICENSE) license.

