Metadata-Version: 2.4
Name: bat2pe
Version: 1.5.5
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
License-File: LICENSE
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

- **Drag-and-drop conversion** — drop a `.bat` / `.cmd` file onto `Bat2PE.exe` in Windows Explorer and the conversion runs instantly, no command needed
- **`%~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** — drop `run.bat` onto `Bat2PE.exe` in Windows Explorer, or run from command line:

```powershell
bat2pe run.bat
```

**Or drag and drop** — drag `run.bat` onto `Bat2PE.exe` in Windows Explorer; no command needed:

```
[drag run.bat onto Bat2PE.exe]  →  run.exe created beside run.bat
```

**Specify output path and icon**:

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

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

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

**Add UAC admin elevation**:

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

**Write full version metadata**:

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

> 💡 Run `bat2pe --help` for the full list of options.

### 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, 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 flow
- CLI drag-and-drop conversion
- 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


## Completed Features

| 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.

