v0.23.0

mccode-antlr v0.23.0

This release removes the deprecated HDF5 instrument serialization, hardens how
registries restored from a serialized instrument are handled, and makes a
serialized instrument portable: the local files it needs now travel with it.

Two changes alter the generated C, so a byte comparison against 0.22 output will
differ. Neither changes what the compiled instrument does.

Upgrading

HDF5 instrument serialization has been removed. save_hdf5 and load_hdf5
are gone, and .h5 is no longer accepted as input by mcstas-antlr,
mcxtrace-antlr, mcc-antlr, mxc-antlr, mcrun-antlr or mxrun-antlr. It has
been deprecated since 0.20.2 in favor of the JSON serialization. Convert any
.h5 instrument you still need with mccode-antlr <= 0.22:

mccode-antlr convert --to json instrument.h5     # using 0.22 or earlier

mccode_antlr.io now re-exports the JSON and msgpack helpers in their place, so
from mccode_antlr.io import save_json, load_json works. Reading .h5
simulation output is a separate feature and is unaffected; the hdf5 extra
remains for it.

The working directory is searched top-level only. It used to be searched as a
whole tree, which disagreed with mcstas and let an unrelated checkout below the
working directory shadow the real component registries. Pass -I . if you want
the old recursive behavior.

Local search directories restored from a serialized instrument are ignored. A
LocalRegistry records a path on the machine that saved the instrument, which
means nothing elsewhere. Supply the directory yourself with -I/--search-dir, or
opt back in with --trust-local-registries or the
serialization.trust_local_registries setting. Without it, -I now also applies
to .json input, which it previously did not.

Two cosmetic changes to the generated C. Source locations in SIG_MESSAGE are
named relative to the registry that supplied them, and embedded runtime files are
named rather than quoted by absolute path:

before:  SETTING [/home/you/.cache/mccodeantlr/mcstas/v3.7.17/mcstas-comps/misc/Progress_bar.comp:58]
after:   SETTING [mcstas-comps/misc/Progress_bar.comp:58]

before:  /* embedding file "/home/you/.cache/mccodeantlr/libc/v3.7.17/mccode/nlib/share/mcstas-r.h" */
after:   /* embedding file "mcstas-r.h" */

Identical input now produces identical C on any machine, apart from the
#define MCSTAS data-search root, which has to stay an absolute path. Use the new
-g/--debug to restore the absolute paths when you want them.

--line-directives is deprecated in favor of -g/--debug, which emits the
same #line directives and additionally keeps the absolute source paths. The
line_directives= keyword on TargetVisitor and Simulation.to_c is deprecated
the same way. Both still work and warn.

mccode-antlr datafile fetch reports failures differently. It still raises
FileNotFoundError and still points at datafile list, but the message now says
why the fetch failed rather than always reporting the file as absent.

Security

Two fixes in this release harden how registries arriving in a serialized
instrument are handled (#289, #291). If you translate instruments you did not
write -- a language server, CI, a validation bot, a shared translation service --
you should upgrade. Running an instrument has always meant running arbitrary C
from its DECLARE and INITIALIZE blocks; these fixes concern consumers that
only translate.

New

Serialized instruments are portable. Component definitions already traveled
in a .json, but the files they %include did not, so an instrument saved on one
machine failed to translate on another with mylib.h not found in registries.
Those headers and libraries are now captured when the instrument is saved,
followed transitively, and data files named by a component parameter come along
too, deposited where the compiled binary will look for them. Only files from a
local search directory are embedded; anything from a remote registry is already
reachable by name.

Controlled by serialization.embed_local_files (default on) and
serialization.embed_size_limit_mb (default 32).

-g/--debug on mcstas-antlr and mcxtrace-antlr: emits #line directives
and keeps absolute source paths in SIG_MESSAGE.

--trust-local-registries on mcstas-antlr, mcxtrace-antlr, mcc-antlr,
mcrun-antlr and mccode-antlr convert, with their mx counterparts.

Saving warns about an unresolvable %include. Saving an instrument that does
not yet translate stays legal, but you are now told which file could not be found
rather than discovering it later, possibly on another machine.

Fixes

• A lookup no longer commits to the first registry that claims a name. known()
  is a claim, not a guarantee, and a registry that answered truthfully but could
  not deliver would abort a lookup a later registry would have satisfied.
• An ambiguous match is reported as an ambiguity, listing the candidates, instead
  of No match -- which stated the opposite of what happened.
• SerializableRegistry round-trips correctly: a typed decode of a registry no
  longer fails, hashing survives a nested payload, and the registry type is
  recorded by class name rather than by a module path baked into every artifact.
• InMemoryRegistry can be serialized and opened, so an instrument built with the
  assembler and carrying one can be saved at all, and exporting one to Python no
  longer raises NameError.
• mccode-antlr convert -I <relative path> works. It never did; the root was
  joined onto a name that already contained it.
• In-memory registry entries are no longer written to disk merely to be read, so
  translating a portable instrument writes nothing outside the output directory.

What's Changed

Breaking Changes 🛠

• Remove the deprecated HDF5 instrument serialization by @g5t in #288

Exciting New Features 🎉

• Fix working directory registry by @g5t in #287
• Ignore LocalRegistry entries restored from serialized instruments by @g5t in #289
• Fix registry issues by @g5t in #290
• Build remote registry indices on first use, not at construction by @g5t in #291
• Ref in memory skips disk by @g5t in #292
• Ref single lookup registries by @g5t in #293

Full Changelog: v0.22.0...v0.23.0