builder2ibek#
A tool suite for converting DLS XMLbuilder IOC projects to epics-containers ibek.
Source |
|
|---|---|
PyPI |
|
Documentation |
|
Releases |
What is builder2ibek for?#
DLS has hundreds of EPICS IOCs defined using the
XMLbuilder format — XML files
that describe which support modules to load and how to configure them.
builder2ibek is the bridge between that legacy world and
epics-containers, the modern approach
to running EPICS IOCs in containers under Kubernetes.
In epics-containers, each IOC instance is expressed as an ibek ioc.yaml file
and support modules are described by ibek.support.yaml entity models.
builder2ibek converts the former, and this documentation covers how to author the latter.
Philosophy of conversion#
The goal is not to produce a one-off translation that is immediately edited
by hand. The goal is to make xml2yaml produce correct output directly,
so that:
The original builder XML remains the source of truth. While a beamline is being converted it may still occasionally require updates to its traditional builder XML, then you can re-run
xml2yamland get a correctioc.yamlwithout manual patching.Every IOC that uses the same support module benefits from the same fix. Improvements to a converter or support YAML are shared automatically.
The conversion is reproducible and testable — sample XML/YAML pairs in
tests/samples/catch regressions in CI.
When xml2yaml output needs correcting, the right response is almost always
to improve the converter (src/builder2ibek/converters/) or the ibek
support YAML (ibek-support-dls/ or ibek-support/), not to edit the
generated ioc.yaml by hand.
Two levels of conversion work#
Converting IOC instances (xml2yaml) is the common case and should be
straightforward. For many IOCs the converters and support YAML already exist;
you run the command, review the output, and verify with db-compare.
Creating or updating ibek support YAML for a module is needed less
frequently — but requires deeper
knowledge of the module’s builder.py, its DB templates, and the ibek YAML
schema. It is a good candidate for AI assistance.
Claude AI has been used successfully to create ibek support YAML and install.yml from scratch
for support modules. For example, the hidenRGA support YAML was generated with
Claude and is available as a reference at
ibek-support-dls hidenRGA-CLAUDE.
This repository contains a CLAUDE.md that describes the full context and skills needed for an AI agent to repeat that process for other modules.
Where to start#
Do you already have a Generic IOC that contains the support modules you need?
If not, you need to build that first:
Write the
ibek.support.yamlandinstall.ymlfor each support module — start with Creating ibek support YAML from a builder.py module for the straightforward case, or ibek support YAML for a complex builder.py if needed.Create the Generic IOC container project that bundles those modules — see Create a Generic IOC repository.
If any support modules use autosave, generate the required
.reqfiles — see Generating autosave req files from DB templates.
Once you have a Generic IOC
Start with Converting a builder XML IOC to ibek ioc.yaml for a quick walkthrough, or Convert a builder XML IOC instance to ibek YAML for the full guide including edge cases.
If there are issues with the conversion then the fix belongs in a converter — see Create a builder2ibek converter for a support module. Or you may need to go back to
ibek.support.yaml, make adjustments and rebuild the generic IOC.After conversion, use Verify a converted IOC using db-compare to check the output record-for-record against the original builder database.
If you encounter old vacuum or interlock modules, see dlsPLC migration reference.
How the documentation is structured#
Documentation is split into four categories, also accessible from links in the top bar.