### Installation Methods

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/CONFIGURATION_REFERENCE.md

Commands for installing packages via pip, pipx, or uv.

```bash
pip install package-name
# Binary goes to: $VENV/bin/binary-name (Unix) or $VENV\Scripts\binary-name.exe (Windows)
```

```bash
pipx install package-name
# Binary isolated in separate virtual environment
# Accessible from PATH without activation
```

```bash
uv tool install package-name
# Similar to pipx, managed by uv
```

--------------------------------

### Install Make Utility

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/README.md

Command to install build essentials for micro-editor.

```bash
apt-get install build-essential
```

--------------------------------

### Install go-task-bin with pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/task/README.md

Use this command to install the go-task-bin package. Ensure you have pip installed and configured.

```sh
pip install go-task-bin
```

--------------------------------

### Install Make Utility

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Commands to install the Make utility for building micro-editor components.

```bash
# macOS
xcode-select --install

# Ubuntu/Debian
apt-get install build-essential

# Verify
make --version
```

--------------------------------

### Install rustup-init-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the rustup-init-bin package using uv.

```bash
uv tool install rustup-init-bin
```

--------------------------------

### Install xh-bin using pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/xh/README.md

Use this command to install the xh-bin tool. Ensure you have pip installed.

```sh
pip install xh-bin
```

--------------------------------

### Install jaq-bin

Source: https://github.com/bing-su/pip-binary-factory/blob/main/jaq/README.md

Install the jaq-bin package using pip to get precompiled binaries of the jaq tool.

```sh
pip install jaq-bin
```

--------------------------------

### Install rustup-init-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the rustup-init-bin package using pipx.

```bash
pipx install rustup-init-bin
```

--------------------------------

### Install jaq-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the jaq-bin package using uv.

```bash
uv tool install jaq-bin
```

--------------------------------

### Install brush-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the brush-bin package using uv.

```bash
uv tool install brush-bin
```

--------------------------------

### Install brush-bin with pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/brush/README.md

Use this command to install the brush-bin package. Ensure you have pip installed and configured.

```sh
pip install brush-bin
```

--------------------------------

### Install Rust Compiler

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/README.md

Standard installation script for the Rust toolchain.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Go build() Example Calls

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/API_FUNCTIONS_REFERENCE.md

Demonstrates various ways to invoke the build function for different projects.

```python
build(Path(context.build_dir, "bin", "eget"))
# -> /tmp/build/bin/eget
```

```python
args = [
    go,
    "build",
    "-o",
    output,
    "-trimpath",
    "-ldflags",
    f"-s -w -X github.com/pocketbase/pocketbase.Version=0.39.6",
    ".",
]
```

```python
version_file = cwd.joinpath("VERSION")
version_file.write_text(VERSION, encoding="utf-8")
# ... build ...
version_file.unlink()  # cleanup
```

--------------------------------

### Install and Test Locally

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Set up a virtual environment and install the built wheel to verify functionality.

```bash
# Create virtual environment
python -m venv test_env
source test_env/bin/activate  # or test_env\Scripts\activate on Windows

# Install built wheel
pip install dist/package_name-X.Y.Z-py3-none-{platform}.whl

# Test binary
binary-name --version
```

--------------------------------

### Install Rust Compiler

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Standard installation script for the Rust toolchain via rustup.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
cargo --version
```

--------------------------------

### Install micro-py

Source: https://github.com/bing-su/pip-binary-factory/blob/main/micro/README.md

Install the micro-py Python wrapper using pip.

```sh
pip install micro-editor
```

--------------------------------

### Install go-task-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the go-task-bin package using uv.

```bash
uv tool install go-task-bin
```

--------------------------------

### Install xh-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the xh-bin package using uv.

```bash
uv tool install xh-bin
```

--------------------------------

### Install pocketbase-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the pocketbase-bin package using uv.

```bash
uv tool install pocketbase-bin
```

--------------------------------

### Example Project URL Configurations

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/CONFIGURATION_REFERENCE.md

Specific examples showing how to map upstream project URLs alongside the repository link.

```toml
# eget/pyproject.toml
[project.urls]
eget = "https://github.com/zyedidia/eget"
repository = "https://github.com/Bing-su/pip-binary-factory"

# pocketbase/pyproject.toml
[project.urls]
pocketbase = "https://pocketbase.io"
repository = "https://github.com/Bing-su/pip-binary-factory"
```

--------------------------------

### Install pocketbase-bin with pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/pocketbase/README.md

Install the pocketbase-bin package using pip. This command fetches and installs the package from the Python Package Index.

```sh
pip install pocketbase-bin
```

--------------------------------

### Install Go Compiler

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Commands to install the Go compiler on macOS and Ubuntu/Debian systems.

```bash
# macOS
brew install go

# Ubuntu/Debian
apt-get install golang-go

# Verify installation
go version
```

--------------------------------

### Install nats-server-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the nats-server-bin package using uv.

```bash
uv tool install nats-server-bin
```

--------------------------------

### Install act-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the act-bin package using uv.

```bash
uv tool install act-bin
```

--------------------------------

### Install juicefs-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the juicefs-bin package using uv.

```bash
uv tool install juicefs-bin
```

--------------------------------

### Install zig-bin Package

Source: https://github.com/bing-su/pip-binary-factory/blob/main/zig/README.md

Use this command to install the zig-bin package from PyPI.

```sh
pip install zig-bin
```

--------------------------------

### Install eget-py

Source: https://github.com/bing-su/pip-binary-factory/blob/main/eget/README.md

Install the eget-py library using pip.

```sh
pip install eget-py
```

--------------------------------

### Install fzf-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the fzf-bin package using uv.

```bash
uv tool install fzf-bin
```

--------------------------------

### Install zig-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the zig-bin package using uv.

```bash
uv tool install zig-bin
```

--------------------------------

### Install Yazi using pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/yazi/README.md

Install the yazi-bin package using pip. This is the primary method for installing Yazi.

```sh
pip install yazi-bin
```

--------------------------------

### Install Package via Pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Command to install the newly created package.

```bash
pip install new-package-bin
```

--------------------------------

### Install SeaweedFS Binaries

Source: https://github.com/bing-su/pip-binary-factory/blob/main/seaweedfs/README.md

Install the seaweedfs-bin package using pip.

```sh
pip install seaweedfs-bin
```

--------------------------------

### Install go-task-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the go-task-bin package using pipx.

```bash
pipx install go-task-bin
```

--------------------------------

### Install yazi-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the yazi-bin package using uv.

```bash
uv tool install yazi-bin
```

--------------------------------

### Install seaweedfs-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the seaweedfs-bin package using uv.

```bash
uv tool install seaweedfs-bin
```

--------------------------------

### Go build examples for specific projects

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/BUILD_SYSTEM.md

Variations of the Go build process for different project structures including simple builds, pyproject versioning, and temporary version file injection.

```python
# eget/pdm_build.py
args = [
    go,
    "build",
    "-o",
    output,
    "-trimpath",
    "-ldflags",
    f"-s -w -X main.Version={VERSION}",
    ".",
]
subprocess.run(args, check=True, cwd=Path(__file__).parent.joinpath("eget"))
```

```python
# pocketbase/pdm_build.py
pwd = Path(__file__).parent
with pwd.joinpath("pyproject.toml").open("rb") as f:
    pyproject = tomllib.load(f)
VERSION: str = pyproject["project"]["version"]

args = [
    go,
    "build",
    "-o",
    output,
    "-trimpath",
    "-ldflags",
    f"-s -w -X github.com/pocketbase/pocketbase.Version={VERSION}",
    ".",
]
```

```python
# act/pdm_build.py
version_file = cwd.joinpath("VERSION")
version_file.write_text(VERSION, encoding="utf-8")

args = [
    go,
    "build",
    "-o",
    output,
    "-trimpath",
    "-ldflags",
    f"-s -w -X main.version={VERSION}",
    ".",
]
subprocess.run(args, check=True, cwd=cwd)
version_file.unlink()  # cleanup
```

--------------------------------

### Install jaq-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the jaq-bin package using pipx.

```bash
pipx install jaq-bin
```

--------------------------------

### Verify Installation Path

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Check the location of the installed binary on Unix or Windows systems.

```bash
which binary-name  # Unix
where binary-name  # Windows (PowerShell)
```

--------------------------------

### Install fzf-bin with pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/fzf/README.md

Use this command to install the fzf-bin Python package.

```sh
pip install fzf-bin
```

--------------------------------

### Install brush-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the brush-bin package using pipx.

```bash
pipx install brush-bin
```

--------------------------------

### Install pocketbase-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the pocketbase-bin package using pipx.

```bash
pipx install pocketbase-bin
```

--------------------------------

### Install ripgrep-bin with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the ripgrep-bin package using uv.

```bash
uv tool install ripgrep-bin
```

--------------------------------

### Install act-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the act-bin package using pipx.

```bash
pipx install act-bin
```

--------------------------------

### Install rustup-init-bin

Source: https://github.com/bing-su/pip-binary-factory/blob/main/rustup-init/README.md

Installs the rustup-init binary using pip. This is the primary method for adding the tool to your Python environment.

```shell
pip install rustup-init-bin
```

--------------------------------

### Install lazygit-py with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the lazygit-py package using uv.

```bash
uv tool install lazygit-py
```

--------------------------------

### Install xh-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the xh-bin package using pipx.

```bash
pipx install xh-bin
```

--------------------------------

### build(output: str, plugins: list[str] | None = None) -> None

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/API_FUNCTIONS_REFERENCE.md

Compiles a Caddy binary with optional plugins using xcaddy. This function handles the installation of xcaddy, the compilation process, and sets the appropriate file permissions on the resulting binary.

```APIDOC
## build(output: str, plugins: list[str] | None = None) -> None

### Description
Compiles Caddy with optional plugins using xcaddy. This function requires Go to be installed and available in the system PATH.

### Parameters
- **output** (str) - Required - Full path where the compiled binary should be written.
- **plugins** (list[str] | None) - Optional - List of plugin GitHub module paths to include in the build.

### Returns
- **None**

### Side Effects
- Downloads xcaddy binary via eget.
- Compiles Caddy with specified plugins.
- Sets file permissions on the output binary to 0o777.
```

--------------------------------

### Configure custom Caddy plugins

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/BUILD_SYSTEM.md

Example command for passing custom plugins during the build process via configuration settings.

```bash
uv build --config-setting="--caddy-plugins=github.com/plugin1,github.com/plugin2"
```

--------------------------------

### Install fzf-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the fzf-bin package using pipx.

```bash
pipx install fzf-bin
```

--------------------------------

### Install ripgrep-bin with pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/ripgrep/README.md

Use this command to install the ripgrep-bin package from PyPI.

```shell
pip install ripgrep-bin
```

--------------------------------

### Install zig-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the zig-bin package using pipx.

```bash
pipx install zig-bin
```

--------------------------------

### Install juicefs-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the juicefs-bin package using pipx.

```bash
pipx install juicefs-bin
```

--------------------------------

### Install eget-py with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the eget-py package using uv.

```bash
uv tool install eget-py
```

--------------------------------

### Install nats-server-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the nats-server-bin package using pipx.

```bash
pipx install nats-server-bin
```

--------------------------------

### Install yazi-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the yazi-bin package using pipx.

```bash
pipx install yazi-bin
```

--------------------------------

### Install seaweedfs-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the seaweedfs-bin package using pipx.

```bash
pipx install seaweedfs-bin
```

--------------------------------

### Implement Caddy plugin build function

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/BUILD_SYSTEM.md

Automates the installation of xcaddy and the subsequent build process with optional plugins.

```python
# caddyserver/pdm_build.py
def build(output: str, plugins: list[str] | None = None) -> None:
    # 1. Install xcaddy
    args = ["eget", "https://github.com/caddyserver/xcaddy", "--asset=^deb"]
    xcaddy = Path.cwd().joinpath("xcaddy").with_suffix(sysconfig.get_config_var("EXE"))
    subprocess.run(args, check=True)

    # 2. Build caddy with plugins
    args = [
        str(xcaddy),
        "build",
        f"v{VERSION}",
        "--output",
        output,
    ]
    for plugin in plugins:
        args.extend(["--with", plugin])

    subprocess.run(args, check=True)
```

--------------------------------

### Install Go Compiler

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/README.md

Commands to resolve missing Go compiler dependencies.

```bash
brew install go
```

```bash
apt-get install golang-go
```

--------------------------------

### Build Caddy with Plugins

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/API_FUNCTIONS_REFERENCE.md

Compiles Caddy using xcaddy. Requires Go to be installed and available in the system PATH.

```python
def build(output: str, plugins: list[str] | None = None) -> None:
    go = shutil.which("go")
    if go is None:
        msg = "golang is required and 'go' should be in $PATH"
        raise RuntimeError(msg)

    # 1. Install xcaddy
    args = ["eget", "https://github.com/caddyserver/xcaddy", "--asset=^deb"]
    xcaddy = Path.cwd().joinpath("xcaddy").with_suffix(sysconfig.get_config_var("EXE"))
    subprocess.run(args, check=True)

    # 2. Build caddy with plugins
    os.environ.setdefault("CGO_ENABLED", "0")
    if not plugins:
        plugins = []

    args = [
        str(xcaddy),
        "build",
        f"v{VERSION}",
        "--output",
        output,
    ]

    for plugin in plugins:
        args.extend(["--with", plugin])

    subprocess.run(args, check=True)
    Path(output).chmod(0o777)
```

--------------------------------

### Install Binary Packages

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PROJECT_OVERVIEW.md

Commands to install binary packages using standard Python package managers.

```bash
# Via pip
pip install micro-editor

# Via pipx (recommended for CLI tools)
pipx install micro-editor

# Via uv (faster alternative)
uv tool install micro-editor
```

--------------------------------

### Install nats-server-bin with pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/nats-server/README.md

Use this command to install the nats-server-bin package. This package provides a pre-compiled binary of the NATS server.

```sh
pip install nats-server-bin
```

--------------------------------

### Install lazygit-py with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the lazygit-py package using pipx.

```bash
pipx install lazygit-py
```

--------------------------------

### Test a Single Package

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/README.md

Commands to build a wheel for a specific package and verify the installed binary version.

```bash
cd package-name
uv build --wheel
pip install dist/*.whl
binary-name --version
```

--------------------------------

### Publish distributions to PyPI manually

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Install build tools and use twine to upload distributions to PyPI.

```bash
pip install build twine

# Build distributions
python -m build dist/

# Upload to PyPI
twine upload dist/*
```

--------------------------------

### Display Help Information

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

View the command-line help documentation for the binary.

```bash
binary-name --help
```

--------------------------------

### Install eget-py with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the eget-py package using pipx.

```bash
pipx install eget-py
```

--------------------------------

### Set GOOS for Linux Build

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/CONFIGURATION_REFERENCE.md

Example of setting the target operating system and architecture for a wheel build using environment variables.

```bash
GOOS=linux GOARCH=amd64 uv build --wheel
```

--------------------------------

### Install lazygit-py with pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/lazygit/README.md

Install the lazygit-py package using pip. This command fetches and installs the latest stable version from the Python Package Index.

```sh
pip install lazygit-py
```

--------------------------------

### Set GOOS for macOS Build

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/CONFIGURATION_REFERENCE.md

Example of setting the target operating system and architecture for a macOS ARM64 build.

```bash
GOOS=darwin GOARCH=arm64 uv build --wheel
```

--------------------------------

### Test Packages with Docker

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Commands to verify package installation and functionality within isolated Linux containers.

```bash
# Test on Linux
docker run -it python:3.11 bash
pip install dist/package_name-X.Y.Z-py3-none-manylinux_2_28_x86_64.whl
binary-name --version

# Test on different architecture
docker run --platform linux/arm64 -it python:3.11 bash
```

--------------------------------

### Configure PDM build for pocketbase-bin

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the build settings for the pocketbase-bin package, specifying necessary Go source files and script installation paths.

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["go.mod", "go.sum", "*.go", "download.nu"]
excludes = ["bin/*", ".gitignore", "pdm_build.py", "build_wheel.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Configure PDM build for juicefs-bin

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the build settings for the juicefs-bin package, specifying the source directory and script installation path.

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["juicefs/"]
excludes = ["bin/*", ".gitignore", "*.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Install ripgrep-bin with pipx

Source: https://github.com/bing-su/pip-binary-factory/blob/main/README.md

Use this command to install the ripgrep-bin package using pipx.

```bash
pipx install ripgrep-bin
```

--------------------------------

### main()

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/API_FUNCTIONS_REFERENCE.md

Orchestrates the build process for all supported platforms defined in the build matrix.

```APIDOC
## main()

### Description
Builds wheels for all supported platforms by iterating through a predefined matrix of OS, architecture, and platform combinations.

### Signature
`def main() -> None:`

### Returns
- **None**
```

--------------------------------

### Build a Package Locally

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/README.md

Builds a wheel for the specified package directory using uv.

```bash
cd micro-editor
uv build --wheel
# Output: dist/micro_editor-2.0.15-py3-none-{platform}.whl
```

--------------------------------

### Initialize build process

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/API_FUNCTIONS_REFERENCE.md

Compiles binaries and prepares build artifacts. Must be called after the hook is enabled and before wheel assembly.

```python
def pdm_build_initialize(context: Context) -> None:
    # Configure wheel metadata
    add = {"--python-tag": "py3", "--py-limited-api": "none"}
    context.builder.config_settings = {**add, **context.builder.config_settings}

    # Ensure build directory exists
    context.ensure_build_dir()

    # Determine output path (handle Windows .exe extension)
    output_path = Path(context.build_dir, "bin", NAME)
    if is_windows():
        output_path = output_path.with_suffix(".exe")

    # Compile binary
    build(str(output_path))
```

--------------------------------

### Create Package Directory

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Initializes the directory structure for a new package.

```bash
mkdir -p /path/to/new-package-bin
cd new-package-bin
```

--------------------------------

### Enable Caddy Plugins

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Build Caddy with specific plugins using configuration settings.

```bash
cd caddyserver
uv build --config-setting="--caddy-plugins=github.com/plugin1,github.com/plugin2"
```

--------------------------------

### pdm_build_initialize

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/API_FUNCTIONS_REFERENCE.md

Compiles binary and prepares build artifacts before wheel assembly.

```APIDOC
## pdm_build_initialize

### Description
Compiles binary and prepares build artifacts before wheel assembly. This function handles directory creation, binary compilation, and configuration of builder settings.

### Signature
`def pdm_build_initialize(context: Context) -> None:`

### Parameters
- **context** (pdm.backend.hooks.Context) - Required - Build context with builder config and methods

### Returns
- **None**

### Side Effects
- Creates build directory via context.ensure_build_dir()
- Compiles binary via build() function
- Produces binary at ${context.build_dir}/bin/{NAME}
- Modifies context.builder.config_settings
```

--------------------------------

### Customize Go build environment

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/BUILD_SYSTEM.md

Configures cross-compilation, CGO settings, and platform-specific wheel targets.

```bash
# Force cross-compilation to specific platform
GOOS=linux GOARCH=arm64 uv build --wheel

# Disable C bindings (required for most packages)
CGO_ENABLED=0 uv build --wheel

# Target specific wheel platform tag
uv build --wheel --config-setting=--plat-name=win_amd64
```

--------------------------------

### Initialize Caddy Build Context

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/API_FUNCTIONS_REFERENCE.md

Configures the build environment and triggers the build process. Supports custom plugin lists via configuration settings.

```python
def pdm_build_initialize(context: Context) -> None:
    plugins = context.builder.config_settings.get("--caddy-plugins", "")
    if plugins:
        plugins = [p.strip() for p in plugins.split(",") if p.strip()]
    else:
        plugins = [
            "github.com/greenpau/caddy-security",
            "github.com/sjtug/caddy2-filter",
            "github.com/mholt/caddy-webdav",
            "github.com/abiosoft/caddy-exec",
            "github.com/aksdb/caddy-cgi/v2",
            "github.com/ggicci/caddy-jwt",
        ]

    context.ensure_build_dir()
    output_path = Path(context.build_dir, "bin", "caddy")
    if is_windows():
        output_path = output_path.with_suffix(".exe")
    build(str(output_path), plugins)
```

--------------------------------

### Configure Platform Tags

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/CONFIGURATION_REFERENCE.md

Set the platform name for wheel builds via command-line or Python script.

```bash
uv build --wheel --config-setting=--plat-name=win_amd64
```

```python
args = [
    "uv",
    "build",
    "--wheel",
    f"--config-setting=--plat-name={platform}",
]
```

--------------------------------

### Install JuiceFS with Pip

Source: https://github.com/bing-su/pip-binary-factory/blob/main/juicefs/README.md

Install the JuiceFS client package using pip. This command is used to add JuiceFS to your Python environment.

```shell
pip install juicefs-bin
```

--------------------------------

### Build Matrix for All Platforms

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Execute the build script to generate wheels for all supported OS and architecture combinations.

```bash
cd package-name
python build_wheel.py
```

--------------------------------

### Implement pdm_build_initialize

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/BUILD_SYSTEM.md

Compiles binaries before wheel assembly. Ensures the build directory exists and invokes the language-specific build process.

```python
def pdm_build_initialize(context: Context) -> None:
    context.builder.config_settings = {**add, **context.builder.config_settings}
    context.ensure_build_dir()
    output_path = Path(context.build_dir, "bin", NAME)
    build(str(output_path))
```

--------------------------------

### Define Standard Project Metadata

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/CONFIGURATION_REFERENCE.md

Configure the [project] section to define package identity, versioning, and metadata. Ensure dependencies are set to an empty list for standalone binary packages.

```toml
[project]
name = "package-name-bin"
version = "X.Y.Z"
description = "Package description"
readme = "README.md"
requires-python = ">=3.7"
license = { text = "MIT" }
authors = [{ name = "Author Name", email = "email@example.com" }]
keywords = ["keyword1", "keyword2"]
classifiers = [
  "Programming Language :: Go",
  "Topic :: Category",
]
dependencies = []
```

--------------------------------

### Platform Tags Reference

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/README.md

Examples of wheel platform tags used to determine compatibility with specific Python environments.

```text
win_amd64                         # Windows x86_64 (any Python)
macosx_12_0_arm64               # macOS 12+ ARM64
manylinux_2_28_x86_64.musllinux_1_2_x86_64  # Linux glibc 2.28 + musl
```

--------------------------------

### Test on Docker

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/README.md

Run a container with a specific architecture to verify binary compatibility.

```bash
docker run --platform linux/arm64 python:3.11 pip install dist/*.whl
```

--------------------------------

### Configure PDM build for nats-server-bin

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the build settings for the nats-server-bin package, including source inclusion and script installation paths.

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["nats-server/"]
excludes = ["bin/*", ".gitignore", "*.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Configure PDM build for micro-editor

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the build settings for the micro-editor package, specifying the source directory and script installation path.

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["micro/"]
excludes = ["bin/*", ".gitignore", "*.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Configure PDM build for lazygit-py

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the build settings for the lazygit-py package, specifying the source directory and script installation path.

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["lazygit/"]
excludes = ["bin/*", ".gitignore", "*.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Configure eget-py build settings

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the PDM build configuration for eget-py, specifying source includes and script installation paths.

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["eget/"]
excludes = ["bin/*", ".gitignore"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Configure PDM Wheel Data Scripts

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PROJECT_OVERVIEW.md

Defines the location of executable scripts within the wheel package for installation into the system path.

```toml
[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Build All Platforms (Matrix)

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/README.md

Executes a custom build script to generate wheels for multiple OS and architecture combinations.

```bash
cd lazygit-py
python build_wheel.py
# Creates 9 wheels for all OS/arch combinations
```

--------------------------------

### Rebuild Package with uv

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Build the wheel for the specified package.

```bash
cd package-name
uv build --wheel
```

--------------------------------

### Configure PDM build for Go binaries

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Use this configuration in pyproject.toml for packages like fzf-bin and go-task-bin to include binary assets and define wheel data scripts.

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["fzf/"]
excludes = ["bin/*", ".gitignore", "*.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["task/"]
excludes = ["bin/*", ".gitignore", "*.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Implement Python wrapper for Zig

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Locates the Zig binary in the system PATH and executes it with provided arguments.

```python
import shutil
import subprocess
import sys

if __name__ == "__main__":
    zig = shutil.which("zig")
    if zig is None:
        msg = "Not found 'zig' in $PATH"
        raise RuntimeError(msg)

    subprocess.run([zig, *sys.argv[1:]])
```

--------------------------------

### Configure PDM build and wheel metadata

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/BUILD_SYSTEM.md

Defines build settings and wheel data in pyproject.toml for platform-specific binary packages.

```toml
[tool.pdm.build]
is-purelib = false              # Contains platform-specific binary
source-includes = ["eget/"]     # Include submodule source
excludes = ["bin/*", ".gitignore"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]  # Install binary as script
```

--------------------------------

### Configure rustup-init-bin build system

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the maturin build backend and manifest path for the rustup-init binary package.

```toml
[build-system]
requires = ["maturin>=1.10,<2.0"]
build-backend = "maturin"

[tool.maturin]
auditwheel = "repair"
bindings = "bin"
manifest-path = "rustup-init/rustup/Cargo.toml"
profile = "release"
strip = true
```

--------------------------------

### Configure Build System Backend

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/CONFIGURATION_REFERENCE.md

Defines the build backend and required dependencies for PDM or Maturin projects.

```toml
[build-system]
requires = ["pdm-backend", "tomli; python_version < '3.11'"]
build-backend = "pdm.backend"
```

```toml
[build-system]
requires = ["maturin>=1.10,<2.0"]
build-backend = "maturin"
```

--------------------------------

### Define build matrix and execute builds

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/BUILD_SYSTEM.md

Iterates through a predefined list of OS, architecture, and platform tuples to trigger the build process.

```python
matrix = [
    ("windows", "amd64", "win_amd64"),
    ("windows", "arm64", "win_arm64"),
    ("darwin", "amd64", "macosx_12_0_x86_64"),
    ("darwin", "arm64", "macosx_12_0_arm64"),
    ("linux", "amd64", "manylinux_2_28_x86_64"),
    ("linux", "arm64", "manylinux_2_28_aarch64"),
    ("linux", "s390x", "manylinux_2_28_s390x"),
    ("linux", "ppc64le", "manylinux_2_28_ppc64le"),
    ("linux", "riscv64", "manylinux_2_28_riscv64"),
]

for os_, arch, platform in matrix:
    build(os_, arch, platform)
```

--------------------------------

### Orchestrate multi-platform wheel builds in Python

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/BUILD_SYSTEM.md

Uses subprocess to invoke uv build and adjust platform tags for Linux musl compatibility.

```python
def build(os_: str, arch: str, platform: str):
    os.environ["GOOS"] = os_
    os.environ["GOARCH"] = arch
    os.environ["CGO_ENABLED"] = "0"

    args = [
        "uv",
        "build",
        "--wheel",
        f"--config-setting=--plat-name={platform}",
    ]
    subprocess.run(args, check=True)

    if os_ != "linux":
        return

    # Fix Linux platform tag for musl compatibility
    platform_tag = linux_platform_map.get(platform, platform)
    whl = next(Path("dist").glob(f"*{platform}*"))

    args = [
        sys.executable,
        "-m",
        "wheel",
        "tags",
        "--remove",
        "--platform-tag",
        platform_tag,
        str(whl),
    ]
    subprocess.run(args, check=True)
```

--------------------------------

### Configure caddyserver-bin build settings

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the PDM build configuration for caddyserver-bin, including wheel data and project dependencies.

```toml
[tool.pdm.build]
is-purelib = false
excludes = ["bin/*", ".gitignore", "*.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]

[project]
requires = ["eget-py", "pdm-backend", "tomli; python_version < '3.11'"]
```

--------------------------------

### PDM Wheel Build Flow

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/API_FUNCTIONS_REFERENCE.md

Visual representation of the PDM build lifecycle, including hook initialization and cleanup.

```text
uv build --wheel
  ↓
pdm backend called
  ↓
pdm_build_hook_enabled() → True (not sdist)
  ↓
pdm_build_initialize()
  ├─ context.ensure_build_dir()
  ├─ build()  # compile binary
  └─ returns
  ↓
PDM assembles wheel from:
  ├─ Binary at ${BUILD_DIR}/bin/*
  ├─ pyproject.toml metadata
  └─ source includes
  ↓
pdm_build_finalize()
  └─ shutil.rmtree(context.build_dir)
  ↓
dist/package-version-py3-none-{platform}.whl
```

--------------------------------

### Define default caddyserver-bin plugins

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

List of default Go modules included during the caddyserver-bin build process.

```python
[
    "github.com/greenpau/caddy-security",
    "github.com/sjtug/caddy2-filter",
    "github.com/mholt/caddy-webdav",
    "github.com/abiosoft/caddy-exec",
    "github.com/aksdb/caddy-cgi/v2",
    "github.com/ggicci/caddy-jwt",
]
```

--------------------------------

### Configure act-bin build settings

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines PDM build settings for the act-bin package, including source includes and wheel data scripts.

```toml
[tool.pdm.build]
is-purelib = false
source-includes = ["*.go", "go.mod", "go.sum"]
excludes = ["bin/*", ".gitignore", "*.py"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
```

--------------------------------

### Build Package Distributions

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Commands to build wheels or source distributions for a specific package.

```bash
cd package-name
uv build --wheel
```

```bash
cd package-name
uv build --sdist
```

--------------------------------

### GitHub Actions Workflow for Building Wheels

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/DEVELOPMENT_GUIDE.md

Automate the build and upload process for wheels using GitHub Actions.

```yaml
name: Build Wheels

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true

      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install uv
          sudo apt-get install -y go-1.21

      - name: Build all platforms
        run: |
          cd package-name
          python build_wheel.py

      - name: Upload to PyPI
        run: |
          pip install twine
          twine upload dist/*
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
```

--------------------------------

### Configure PDM build for zig-bin

Source: https://github.com/bing-su/pip-binary-factory/blob/main/_autodocs/PACKAGE_REFERENCE.md

Defines the PDM build settings to include the wrapper script and distribute necessary library files.

```toml
[tool.pdm.build]
is-purelib = false
includes = ["zig.py"]
excludes = ["bin/*", "lib/*", ".gitignore"]

[tool.pdm.build.wheel-data]
scripts = ["${BUILD_DIR}/bin/*"]
data = [{ path = "${BUILD_DIR}/lib/**/*", relative-to = ".pdm-build" }]
```