Metadata-Version: 2.5
Name: beebium-server
Version: 0.1.8
Summary: Prebuilt Beebium BBC Micro emulator server binaries
Project-URL: Homepage, https://github.com/rob-smallshire/beebium
Project-URL: Repository, https://github.com/rob-smallshire/beebium
Author-email: Robert Smallshire <robert@smallshire.org.uk>
License-Expression: GPL-3.0-or-later
License-File: COPYING.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<!-- Generated by scripts/generate_readme.py from readme/README.md.j2 and
     the tested snippets in readme/snippets/. Do not edit this file directly:
     edit the template or a snippet and run scripts/generate_readme.py.
     See CONTRIBUTING.md. -->
# beebium-server

## What is Beebium?

[Beebium](https://github.com/rob-smallshire/beebium) is a headless,
cycle-accurate BBC Micro emulator with a client-server architecture. The
emulator runs as a server process -- one per machine variant (Model B, B+, B+
128K, B with ROM/RAM board) -- and is driven over gRPC, so front-ends and
automation talk to it across a well-defined protocol rather than being wired
into the emulation core.

## What is this package?

`beebium-server` is that emulator, shipped as platform wheels. Each wheel
carries the built server binaries, the ROMs, the presets and the bundled
extensions, so a complete, working BBC Micro emulator installs straight from
PyPI -- no system package manager, no compiler, no ROM files to locate by hand:

```bash
pip install beebium-server
```

Installing it also puts the four server binaries on `PATH`
(`beebium-model-b` and its variants), so the package is useful on its own.

### Relationship to `beebium`

[`beebium`](https://pypi.org/project/beebium/) is the Python client that drives
a server over gRPC. The two are independent packages -- neither depends on the
other -- but they complement each other: with both installed, the client finds
this wheel automatically and `Beebium.launch()` needs no arguments.

```bash
pip install beebium beebium-server
```

### Supported platforms

A wheel is published for each of these; `pip` selects the one matching your
machine.

| Platform | Wheel tag |
|----------|-----------|
| Linux x86-64 (glibc 2.36+) | `manylinux_2_36_x86_64` |
| Linux ARM64 / aarch64 (glibc 2.36+) | `manylinux_2_36_aarch64` |
| macOS Apple Silicon (arm64, macOS 11+) | `macosx_11_0_arm64` |
| macOS Intel (x86-64, macOS 12+) | `macosx_12_0_x86_64` |
| Windows x64 | `win_amd64` |

## Installation

With [uv](https://docs.astral.sh/uv/):

```bash
uv add beebium-server            # add to your project
# or, into a plain virtualenv:
uv pip install beebium-server
```

With pip:

```bash
pip install beebium-server
```

Usually you install it alongside the client, `pip install beebium beebium-server`.

## Usage

### Run a server from the command line

Installing the wheel puts one console script per machine variant on `PATH`.
Each starts a headless server that listens for gRPC clients:

```sh
# Run a BBC Model B server. Variants: beebium-model-b, beebium-model-b-plus,
# beebium-model-b-plus-128k, beebium-model-b-romram.
beebium-model-b --port 48875
# Initializing BBC Model B...
# Listening on port 48875
# BBC Model B ready. Press Ctrl+C to stop.
```

With no `--port` the server picks its default port. Run `beebium-model-b --help`
for the other subcommands (listing extensions, describing presets, capturing a
screenshot, and more).

### Locate the binaries and data from Python

A tiny, dependency-free API reports where the bundled binaries and data live --
useful for launching a server yourself or pointing other tooling at the ROMs:

```python
import beebium.server

# Where the bundled server binary lives (ensured executable), and its kin.
executable = beebium.server.executable_filepath()        # the model-b binary
print(executable)
print(beebium.server.variants())                         # the four variants
print(beebium.server.rom_dirpath())                      # the bundled ROMs
print(beebium.server.preset_dirpath())                   # the bundled presets
print(beebium.server.__version__)
```

### Drive a server from Python

To control a server programmatically -- type at the keyboard, read the screen,
inspect memory, drive the debugger -- install the
[`beebium`](https://pypi.org/project/beebium/) client and see its documentation.
With both packages installed, `Beebium.launch()` starts one of these servers
with no arguments.

## Contributing

Development happens in the
[Beebium repository](https://github.com/rob-smallshire/beebium). This wheel is
not built from source here: `build_wheel.py` repackages a release bundle that
the monorepo already builds and validates, so the server binaries are
byte-identical to those on the GitHub Release.

This README is **generated** -- do not edit `README.md` directly. See
[CONTRIBUTING.md](CONTRIBUTING.md).

## License

GPL-3.0-or-later. See [COPYING.txt](COPYING.txt).
