# Runtime Support (ibek-runtime-support)

Runtime support lets you add DB templates ibek entity definitions to one or more
IOC instances **without recompiling** the generic IOCs that they use.

Note that the ibek entity definitions can add to the startup script entires of
the IOC instance as well as to its expanded database.

This can be used for
facility-wide shared definitions (like AreaDetector plugin sets) as well as
beamline-specific templates — anything that is purely declarative (DB
templates, entity models with `sub_entities`) rather than compiled code.

## Why use runtime support?

In epics-containers, Generic IOC images are shared across beamlines. Compiling
every DB template and entity definition into the image would either bloat it
or force you to create many near-identical one-off containers. Runtime support
solves this by letting you supply `.ibek.support.yaml` files (and their
associated DB templates) from outside the container. ibek picks them up at
boot time and treats them exactly like built-in support definitions.

This works for both facility-wide definitions (shared across all beamlines via
a git submodule) and beamline-specific templates (committed directly to your
services repo). The principle is the same as referencing a DB template via the
`databases` entry in a genric IOC's support YAML — the only difference is that the
files come from the services repo at runtime instead of from inside the
container filesystem.

There are two levels of sharing:

| Level | Where it lives | Example |
|---|---|---|
| **Facility-wide** | A shared submodule under `ibek-runtime-support/` | `ibek-runtime-support-dls` (contains `detectorPlugins`) |
| **Beamline-specific** | A folder directly in `ibek-runtime-support/` | `ibek-runtime-support/bl21i-support/` |

Anything that requires **compilation** (e.g. aSub record C code) cannot use
this mechanism — it must live in a compiled support module inside a Generic
IOC image.

## How it works

At IOC boot time, ibek's `runtime generate` command looks for entity model
definitions in two places:

1. **Built-in definitions** — the `.ibek.support.yaml` files compiled into the
   Generic IOC image under `/epics/ibek-defs/`.
2. **Config folder definitions** — any `.ibek.support.yaml` files found in the
   IOC instance's `config/` folder, **including symlinks** (ibek follows
   symlinks when globbing).

It then loads instance YAML files in order:

1. `ioc.yaml` — the main IOC definition (entities from the Generic IOC's
   built-in support).
2. `runtime.yaml` — additional entities that use runtime support definitions.

The entities from `runtime.yaml` are appended after those from `ioc.yaml`, so
runtime entities appear at the end of the startup script.

## Directory structure

A typical services repo with runtime support looks like this:

```
my-beamline-services/
  ibek-runtime-support/
    my-beamline-support/                  # beamline-specific (committed directly)
      my-beamline-support.ibek.support.yaml
      myCustom.template                   # optional DB templates
    ibek-runtime-support-dls/             # facility-wide (git submodule)
      detectorPlugins.ibek.support.yaml
    runtime.schema.json                   # auto-generated by pre-commit
  services/
    bl21i-di-dcam-01/
      config/
        ioc.yaml
        runtime.yaml
        detectorPlugins.ibek.support.yaml -> ../../../ibek-runtime-support/ibek-runtime-support-dls/detectorPlugins.ibek.support.yaml
```

The key detail is the **symlink** in the IOC's `config/` folder. ibek only
looks inside `config/` for support definitions, so you must symlink in each
`.ibek.support.yaml` file that the IOC needs. This is deliberate — it means
each IOC explicitly declares which runtime support it uses.

## Setting up runtime support in your services repo

### 1. Update your services repo template

Make sure your services repo is on template version 5.2.0 or later:

```bash
uvx copier update -A
# fix any merge conflicts
git commit -am "update services repo to latest template"
git push
```

### 2. Add the facility-wide submodule (if needed)

If your IOCs use AreaDetector and you want the standard `detectorPlugins`
entities, add the shared submodule:

```bash
cd ibek-runtime-support
git submodule add https://gitlab.diamond.ac.uk/controls/containers/utils/ibek-runtime-support-dls.git
```

### 3. Create a beamline-specific support folder (if needed)

For DB templates or entity models specific to your beamline, create a folder
directly under `ibek-runtime-support/`:

```bash
mkdir ibek-runtime-support/bl21i-support
```

Add a support YAML file — for example, a custom template that loads a DB file:

```yaml
# ibek-runtime-support/bl21i-support/bl21i-support.ibek.support.yaml
# yaml-language-server: $schema=https://github.com/epics-containers/ibek/releases/download/3.0.1/ibek.support.schema.json

module: bl21i-support

entity_models:
  - name: myCustomDevice
    description: A beamline-specific device template
    parameters:
      P:
        type: str
        description: PV prefix
      PORT:
        type: str
        description: Asyn port name
    databases:
      - file: myCustom.template
        args:
          P:
          PORT:
```

Place the corresponding `myCustom.template` file in the same folder. ibek
will find it via the symlink (see below).

### 4. Generate the runtime schema

The runtime schema provides auto-completion and validation for `runtime.yaml`
files. It is generated automatically by a pre-commit hook:

```bash
uvx pre-commit run --all-files
```

This runs `ibek ioc generate-schema` over all `.ibek.support.yaml` files
in `ibek-runtime-support/` and writes `runtime.schema.json`. Commit the
generated schema alongside your support YAML.

## Using runtime support in an IOC instance

### 1. Symlink the support YAML into config

For each runtime support YAML your IOC needs, create a symlink in its
`config/` folder:

```bash
cd services/bl21i-di-dcam-01/config

# facility-wide detector plugins
ln -s ../../../ibek-runtime-support/ibek-runtime-support-dls/detectorPlugins.ibek.support.yaml .

# beamline-specific support (if you have one)
ln -s ../../../ibek-runtime-support/bl21i-support/bl21i-support.ibek.support.yaml .
```

Only symlink what the IOC actually uses — don't symlink everything.

::: {tip}
Don't forget to also symlink DB Templates if your runtime support yaml uses them
:::

### 2. Create runtime.yaml

Add a `runtime.yaml` to the IOC's `config/` folder. The schema reference at
the top gives you auto-completion in VS Code (with the Red Hat YAML extension):

```yaml
# yaml-language-server: $schema=../../../ibek-runtime-support/runtime.schema.json
ioc_name: "{{ _global.get_env('IOC_NAME') }}"
description: additional entities from the services repo

entities:
  - type: detectorPlugins.detectorPlugins
    P: BL21I-DI-DCAM-01
    CAM: D1.CAM
    PORTPREFIX: D1
```

The `type` field uses the format `module.entityName`, where `module` matches
the `module:` field in the support YAML and `entityName` matches the entity
model's `name:`.

### 3. Commit and deploy

```bash
git add -A
git commit -m "add runtime support for bl21i-di-dcam-01"
git push
```

Deploy with `ec` as usual. ibek will load both `ioc.yaml` and `runtime.yaml`
at boot time.

## Example: using detectorPlugins for an AreaDetector IOC

The `detectorPlugins` support YAML (in `ibek-runtime-support-dls`) is a
facility-wide shared definition for AreaDetector IOCs. It provides two entity
models:

| Entity | Description |
|---|---|
| `detectorPlugins.detectorPlugins` | Lean set of AreaDetector plugins for **Bluesky/Ophyd** (PVA, Stats, ROIStat, HDF5) |
| `detectorPlugins.gdaPlugins` | Full legacy plugin set for **GDA** (ROIs, StdArrays, Stats, Process, Overlay, TIFF, HDF5, PVA, ROIStat, MJPG) |

Both are composed entirely of `sub_entities` referencing `ADCore` types, so
they work with any Generic IOC that includes `ADCore` — no extra compilation
needed.

### Typical setup

Your `ioc.yaml` defines the camera and basic infrastructure:

```yaml
entities:
  - type: ADAravis.aravisCamera
    P: BL21I-DI-DCAM-01
    PORT: D1.CAM
    # ... other camera params
```

Your `runtime.yaml` adds the plugins:

```yaml
entities:
  - type: detectorPlugins.detectorPlugins
    P: BL21I-DI-DCAM-01
    CAM: D1.CAM
    PORTPREFIX: D1
```

This wires up PVA, Stats, ROIStat, and HDF5 plugins — everything
Bluesky/Ophyd needs for standard data collection. Use `gdaPlugins` instead if
you need the full legacy GDA plugin set.

## Tips

- **Schema validation catches errors early.** Always reference the runtime
  schema at the top of `runtime.yaml`. VS Code will underline invalid entity
  types or missing parameters immediately.

- **Keep runtime support lean.** If a support module is used by many beamlines
  and requires compilation, it belongs in a Generic IOC image, not in runtime
  support.

- **DB templates go next to their support YAML.** When ibek follows the
  symlink to load the `.ibek.support.yaml`, it also searches that directory
  for `.template` files referenced in `databases:` entries.

- **One symlink per support YAML.** Don't symlink the entire
  `ibek-runtime-support/` folder — symlink individual `.ibek.support.yaml`
  files so each IOC explicitly declares its dependencies.

- **Regenerate the schema when support YAML changes.** Run
  `uvx pre-commit run --all-files` after editing any `.ibek.support.yaml`
  under `ibek-runtime-support/` to keep the schema up to date.