ptprnt/README.md

# ptprnt

A command-line label printer driver for Brother P-touch printers on Linux. Prints text labels directly from your terminal.

## Example

Too print a label, provide your text and optionally a font and a font size. This command will print the label below on a Brother P-Touch P700:

```bash
ptprnt --font "NotoMono Nerd Font" --fontsize 32 --text "🖶 ptprnt v0.2.0 🥰"
```

![Printed label that proudly reads 🖶 ptprnt v0.2.0 🥰](docs/assets/label_print_v0_2_0.jpg)

## Quick Start

## Quick Start

**Binary dependencies**

Arch Linux:
```bash
pacman -S pango cairo libusb 
```

Debian/Ubuntu:
```bash
apt install libpangocairo-1.0-0 libusb-1.0-0
```

**Build dependencies:**

Arch Linux:
```bash
pacman -S libusb spdlog pango cairo meson
```

Debian/Ubuntu:
```bash
apt install libusb-1.0-0-dev libspdlog-dev libfmt-dev libpango1.0-dev libcairo2-dev meson
```

Note: spdlog is built as a subproject and statically linked, so it's not required as a system dependency.

**Build and run:**
Clone this repository first and enter the directory. Then build:
```bash
# Using the build script (recommended)
./scripts/build.sh release
builddir/ptprnt --help

# Or manually with meson
meson setup builddir
ninja -C builddir
builddir/ptprnt --help
```

## Usage

### Basic Text Printing

Print a simple label with text:
```bash
ptprnt --text "Hello World"
```

### Formatting Options

Control the appearance of your labels with these options:

- `--font FONT_NAME` - Set the font (e.g., "NotoMono Nerd Font", "DejaVu Sans")
- `--fontsize SIZE` - Set font size in points (default: 24)
- `--halign ALIGNMENT` - Horizontal alignment: `left`, `center`, `right` (default: center)
- `--valign ALIGNMENT` - Vertical alignment: `top`, `center`, `bottom` (default: center)

**Example with formatting:**
```bash
ptprnt --font "DejaVu Sans Mono" --fontsize 28 --halign left --text "Left aligned text"
```

### Multiple Text Elements

You can add multiple text elements to a single label. Formatting options apply to all subsequent `--text` arguments until changed:

```bash
ptprnt \
  --font "DejaVu Sans" --fontsize 32 --text "Large Title" \
  --fontsize 18 --text "Smaller subtitle"
```

### Multiple Labels (Stitching)

Create multiple labels that will be stitched together horizontally using the `--new` flag:

```bash
ptprnt \
  --text "Label 1" \
  --new \
  --text "Label 2" \
  --new \
  --text "Label 3"
```

Each `--new` starts a fresh label. The labels are automatically stitched together with 60 pixels of spacing.

**Example - Creating a series of address labels:**
```bash
ptprnt \
  --font "DejaVu Sans" --fontsize 20 \
  --text "Peter Lustig" --text "Am Bauwagen 1" \
  --new \
  --text "Donald Duck" --text "Blumenstraße 13" \
  --new \
  --text "Homer Simpson" --text "742 Evergreen Terrace"
```

**Example - Mixed formatting across labels:**
```bash
ptprnt \
  --fontsize 32 --text "BIG" \
  --new \
  --fontsize 16 --text "small" \
  --new \
  --fontsize 24 --text "medium"
```

### Printer Selection

By default, ptprnt auto-detects your printer. You can explicitly select a printer:

```bash
ptprnt --printer P700 --text "Hello"
```

List all available printer drivers:
```bash
ptprnt --list-all-drivers
```

### Testing with Fake Printer

Before printing to your real printer, you can test your label output using the built-in fake printer. This generates a PNG image file instead of printing:

```bash
ptprnt --printer FakePrinter --text "Test Label"
```

This will create a file named `fakelabel_YYYYMMDD_HHMMSS.png` in your current directory with a preview of your label. Use this to:
- Verify text formatting and layout
- Test multi-label stitching
- Preview before wasting label tape

**Example workflow:**
```bash
# First, test your label design
ptprnt --printer FakePrinter \
  --font "DejaVu Sans" --fontsize 28 \
  --text "Test Design" --text "Check Layout"

# View the generated PNG file to verify
# If satisfied, print to real printer
ptprnt --printer P700 \
  --font "DejaVu Sans" --fontsize 28 \
  --text "Test Design" --text "Check Layout"
```

### Verbose Output

Enable detailed logging for debugging:

```bash
ptprnt --verbose --text "Debug mode"
```

Enable USB trace to see raw USB communication:
```bash
ptprnt --trace --text "USB trace mode"
```

### Complete Example

An example using a mixed bag of features:

```bash
ptprnt \
  --verbose \
  --printer P700 \
  --font "NotoMono Nerd Font" \
  --fontsize 28 --halign center --text "Product Label" \
  --fontsize 20 --text "SKU: 12345" \
  --new \
  --fontsize 24 --text "Backup Label" \
  --fontsize 18 --text "Date: 2025-10-16"
```

## Supported Printers
(I need more printers for verification 😉)

- Brother P-touch P700 series

## Developer info

This is a modern C++20 rewrite of [ptouch-print](https://git.familie-radermacher.ch/linux/ptouch-print.git). Credits to Dominic Rademacher for reverse engineering the USB protocol.

**Build script:**
```bash
# Release build (tests disabled for faster builds)
./scripts/build.sh release

# Debug build (tests enabled)
./scripts/build.sh debug

# Debug with tests
./scripts/build.sh debug --test

# Debug with coverage
./scripts/build.sh debug --coverage

# Clean all build directories
./scripts/build.sh clean

# Show all options
./scripts/build.sh --help
```

**Note:** Tests are only built in debug mode to keep release builds fast and small. Release builds do not include test binaries or link against gtest/gmock.

**Running tests:**
```bash
# Using build script
./scripts/build.sh --test

# Or manually
ninja -C builddir test
```

**Coverage reports:**
```bash
# 1. Build with coverage enabled and run tests
./scripts/build.sh debug --coverage --test

# 2. Generate coverage reports
./scripts/generate_coverage.sh              # All formats (html, xml, text)
./scripts/generate_coverage.sh --html       # HTML only
./scripts/generate_coverage.sh --text       # Text only
./scripts/generate_coverage.sh --xml        # XML only (for CI/CD)
./scripts/generate_coverage.sh --html --xml # HTML and XML

```

## License

GPLv3, see [LICENSE](./LICENSE)

## Author
Moritz Martinius <moritz@admiralackbar.de>