Skip to content

← Connect an app

Protocol reference

The contract between a host plugin (napari, Fiji, QuPath) and an app's tools: the schema a host reads, the registry where it finds apps, and the messages it exchanges with the worker. This is protocol version 1. Every field marked additive below was added within version 1: a host that does not know it can ignore it. A change that is not additive would be protocol 2.

Schema (what hosts read)

<registry>/<name>.schema.json, generated by labconstrictor-tools describe without running any tool:

{ "protocol": 1, "application": str, "version": str, "tools_version"?: str, "features"?: [str],
  "tools": [ { "id", "label", "description"?,
               "inputs":  [ { "name", "label", "type", "required", "default"?, "description"?, "choices"?,
                              "minimum"?, "maximum"?, "unit"?, "axes"?, "pixel_size_of"?, "nullable"?, "group"?, "advanced"?, "enabled_when"?, "group_collapsed"?, "clear_after_run"?, "choices_from"?, "pick_channel"? } ],
               "outputs": [ { "name", "type", "axes"?, "display"?: {"apply_to", "relative_to"?}, "replace"? } ] } ] }

A host must skip, and report, a schema whose protocol it does not support.

Input type: string integer float boolean choice image labels table file folder. Output type: image labels table values affine file message points shapes.

Inputs

  • description: optional but recommended; the input's help, which hosts show on hover with an ⓘ after the label. check and test warn when it is missing.
  • nullable: true (additive): the parameter is optional and has no default (= None or Optional[...]). A host lets the person leave it unset and then omits it from the request; the tool receives None. Showing 0 or an empty string instead is a bug.
  • folder: a directory path; the worker checks that it exists. Hosts show a folder chooser.
  • axes (an input, or an image/labels output): a string of distinct labels from T C Z Y X S, one per array dimension. Anything else is a DeclarationError.

Presentation and interaction hints (all additive). A host that ignores them shows a plain form, so a tool must accept every parameter whether or not it is "enabled":

  • group: a heading, shown where the group first appears. advanced: true: listed under a collapsed "Advanced settings". group_collapsed: true (with group): the group is an accordion section that starts folded.
  • enabled_when: {"param", "equals"?}: the parameter applies only when param is set or true, or equals one of the listed values.
  • clear_after_run: true: after a successful run, a host that keeps form values between runs puts the parameter back to its default (or unset).
  • choices_from: {"tool", "depends", "field"} (string parameters): the host runs tool with the current values of the parameters named in depends, reads the list under field of its values result and shows a dropdown. When the call cannot be answered it falls back to a text field. The value stays a free string for the tool. A host that builds its form before the person types anything (Fiji) asks with the values of the previous run of the same app, kept in <LC_HOME>/state, and shows the text field the first time.
  • pick_channel: true (image inputs whose axes are YX or absent): the host lets the person choose a channel of the chosen image (by name where the host has names, by number otherwise) and sends only that channel, as a 2D image. A host that cannot list channels sends the image as it is.
  • output replace: true (image, labels, table, affine overlay): a new run replaces the previous result of the same output (same layer or window name) instead of adding "name [1]".

Value rules (enforced by the worker)

Each violation is a FAILURE with code invalid_parameter, unless another code is named, or a DeclarationError when the app is registered.

  • boolean must be JSON true or false, never text or a number. A choice value must match a choice in type and value. A float is never a boolean.
  • integer and float must be JSON numbers. Text (even "3"), lists, objects, NaN and infinity are refused: 'N' must be an integer, got text, 'N' must be a number, got a list, 'N' must be a finite number. An integer-valued float such as 3.0 is accepted for an integer. A number beyond the float range is refused for a float.
  • file, folder, image and labels values must be text paths: 'N' must be a path (text), got a list: the host must send the file or folder path as text. An image may also be a shared-memory descriptor (see Shared-memory images).
  • null means "not given": the parameter takes its default or, when nullable, the tool receives None. Optional[...] with a default other than None is refused at registration.
  • A default must be valid for its declared type (checked when the schema is generated).
  • A choice declared with an Enum reaches the tool as the Enum member.
  • An image or labels input with no pixels is refused with empty_image.
  • A table input is a UTF-8 CSV file with a header line. The tool gets a DataFrame exactly as written: floats keep every digit (float_precision="round_trip"); column names stay as written, duplicates and empty names included (address those by position); an empty cell is missing; NaN, nan and NAN are missing numbers, but a text column keeps them as text; the other words pandas calls missing (NA, None, null, ...) stay text, except in a column whose other cells are all numbers. A missing file is file_not_found; an empty file or one that is not a UTF-8 CSV is unreadable_table.
  • Integers of any size and floats up to the double range are carried. A value beyond a declared Min/Max (or the notebook form's ±(2**53 - 1), notebook.MAX_FORM_INTEGER) is refused, never clamped, with the sentence every host uses: 'L' must be <= 9007199254740991 or 'L' must be >= -9007199254740991.

Results and what the tool must return

A tool returns one value, or a tuple with one value per declared output (tool returned N values, declared M). A value that does not match its declaration fails the task with bad_return: the <type> output '<name>' must be <what>, got <what arrived>. The expected values are an array of numbers (image, labels), a DataFrame, dict of lists or list of dicts (table, points), a dict (values), a path (file), text (message) and a finite 3x3 matrix of numbers (affine).

Output names are file names (<name>.tif, .csv, .geojson in the result folder), so Name(...) must be one portable file name: no /, \, :, <>"|?*, control characters or NUL, not . or .., no leading space or trailing space or dot, and not a Windows device name (CON, NUL, COM1, ...). Anything else is a DeclarationError; the writers also refuse (bad_return) a path that would leave the result folder.

Images and labels

  • An empty array is bad_return (image is empty (shape ...)). Complex, object, text and bytes arrays are unsupported_dtype.
  • Integer values never change. Wide integers that fit 16 bits are stored as 16-bit; others must be exact as float32, otherwise unsupported_dtype (for example a uint64 of 2**64-1). Floats are stored as float32 (about 7 significant digits); values outside the float32 range fail.
  • A declared axes is a promise: an array with another number of dimensions is bad_return and nothing is written. Without axes, the host gets YX, ZYX or CZYX for 2, 3 or 4 dimensions, and no axes otherwise.
  • A tool whose output axes depend on the input returns WithAxes(array, "TZYX"); a declared axes must agree, otherwise bad_return. The result's axes are the returned ones.
  • Hyperstacks (feature result_axes_v1): a result with known axes (declared or returned) that are a subsequence of T Z C Y X ending in Y X, more than two dimensions and none of size 1, a pixel type ImageJ stores (uint8, uint16, int16, float32) and less than 4 GiB is written as an ImageJ hyperstack TIFF, which Fiji opens with its dimensions. The array is never reordered. Any other result is a plain TIFF.

Tables and points. Written as UTF-8 CSV. Line breaks, quotes and commas in cells and names are quoted and arrive unchanged. A NUL character in a column name or cell is refused with bad_return (the table output 'X' has a NUL character in a cell of column 'c': remove it); a lone surrogate or other text that is not UTF-8 is refused with bad_return (... cannot be written as a UTF-8 CSV ...). A points result is {path, n, columns, apply_to?}: a CSV whose first two columns are y and x, finite pixel coordinates in the frame of the image named by apply_to (else of the first image); other columns are properties of each point.

Shapes. {path, n, apply_to?}: a GeoJSON FeatureCollection file of Polygon and MultiPolygon features, [x, y] coordinates in the same frame, pixel centres at integers. Feature properties are kept; a label property links an outline to its label. A GeoJSON dict returned by a tool is checked before anything is written: a Polygon is a list of rings (outer boundary first, then holes), a MultiPolygon a non-empty list of polygons, every ring at least 4 [x, y] positions of two finite numbers, closed, with at least 3 distinct vertices. Anything else is bad_return naming the feature, polygon and ring. An empty result is a FeatureCollection with no features. A host that does not know shapes lists the file.

Message. {text}: short plain text.

Tools version and features

Two additive fields say what produced a schema:

  • tools_version: the labconstrictor-tools version that ran describe in the app's interpreter (labconstrictor_tools.__version__, for example 0.3.0a1 for tag v0.3.0-alpha.1; see OPERATIONS.md).
  • features: the sorted list of feature ids (labconstrictor_tools.features.FEATURES). An id means "this Tools implements that rule". It is added in the change that implements it and is never renamed or reused.

register copies both into the registry entry; describe and doctor print them. A missing field means unknown/old.

Id Meaning Since
reserved_inputs_v1 the worker accepts and ignores reserved underscore inputs it does not know (Reserved inputs) 0.2.0rc1
retention_prune the command labconstrictor-tools prune [--root results\|runs\|all] [--dry-run] [--json] and labconstrictor_tools.retention exist; only folders with a valid .lc-owner.json and .lc-done.json are removed (Result folders and run records) 0.2.0rc1
shm_order_v1 a shared-memory descriptor's order is honoured (Shared-memory images). A host that sends F blocks requires it 0.3.0a1; the one id added after its behaviour: older versions behave the same but cannot be told apart
app_hosts_v1 register records the app's hosts, and a host lists an app only if it is named there (App hosts) 0.3.0a1
host_requirements_v1 register --app-manifest records the app's host_requirements, and host_requirements.check gives every host the same verdict (Host requirements) 0.3.0a2
result_axes_v1 a result with known axes in ImageJ order is written as an ImageJ hyperstack TIFF (Images and labels). Hosts need nothing new 0.3.0a4

Some behaviour has a version but no id. Tools >= 0.3.0a1 maps big TIFF files (see TIFF files); a host can observe it only as speed, memory use and the Windows file lock. The run-record helpers of the runs module also need 0.3.0a1.

Compatibility rules for hosts

A host that needs a minimum states it as (min_tools_version, required_features) and applies these rules to every schema it loads, with labconstrictor_tools.compat.check_schema (Python hosts) or the same rules in its own language (Fiji and QuPath read the cases from conformance.json, section compat; see CONFORMANCE.md). The result is ok, warn or refuse, with one sentence for the person:

  1. protocol not supported: refuse.
  2. A required feature missing from features, or no features list: refuse, "needs ; update the app's labconstrictor-tools".
  3. tools_version missing (unknown/old): refuse when a minimum is set, otherwise warn, "Tools version unknown".
  4. tools_version below the minimum: refuse. Below the optional warn_below but not below the minimum: warn.
  5. Otherwise ok. A tools_version the host cannot parse is warn, never a crash.
  6. A host that starts prune after a run requires retention_prune, or checks for it before starting the subprocess. Without it the host starts nothing and never deletes a folder itself.
  7. A host that applies the per-host listing rule requires app_hosts_v1 (with min_tools_version 0.3.0a1). An app whose Tools lacks it is refused by rule 2 with "lacks app_hosts_v1: update it" (conformance.json, app_hosts.compat_cases).

Versions compare as PEP 440: 0.2.0a1 < 0.2.0b1 < 0.2.0rc1 < 0.2.0 < 0.2.1, and 0.2.0rc1 < 0.3.0a1 < 0.3.0. Tags v0.2.0-rc.1 and v0.2.0-rc.2 both report 0.2.0rc1 with different code, so a host that needs anything from 0.3.0a1 sets that as its minimum.

App hosts (which host lists an app)

An app declares which hosts may list it, and a host never lists an app whose declaration excludes it. Feature id app_hosts_v1; reference: labconstrictor_tools.app_hosts.listed_for; test vectors: conformance.json, section app_hosts.

Where the declaration comes from. The hosts: line of the app's labconstrictor-app.yaml (Tool markers), which the installer passes to register --app-manifest <file>; --hosts notebook,napari is the command-line equivalent (the two are exclusive). The reader accepts a quoted key, a flow or block list and a UTF-8 byte order mark; a form it does not understand is refused, never read as absent. register validates the list and writes it into the registry entry as hosts. A manifest with no hosts key still registers, and register prints the "declares no hosts" sentence below on stderr.

The rule. For each registered app, a host calls listed_for(entry, "<its own name>") (napari, fiji or qupath; Fiji and QuPath implement the same rule) and acts on (listed, sentence):

Entry hosts listed sentence (exact; {app} is the entry's name, the list is written as declared, separated by ,)
contains the host yes none
valid, does not contain the host no '{app}' is not listed in {host}: the app declares hosts: {hosts}
absent (older installers) yes, in every host '{app}' declares no hosts, so it is listed in every host; register it with --app-manifest (or --hosts) to choose
present but not valid: not a list, empty, a non-text item, an unknown or repeated name, a name in capitals no, in no host '{app}' is not listed in {host}: its hosts declaration is not valid ({problem}); register the app again with a valid one

The problems are: hosts must be a list of host names, hosts is empty; write at least notebook, hosts must contain only text, unknown host name 'x' (known: notebook, napari, fiji, qupath), host name 'x' appears twice. The manifest reader and --hosts also refuse hosts has an empty item (a trailing or doubled comma, or a bare '-'). An unknown name for the asking host is a bug in the host: listed_for raises ValueError.

A host writes every non-empty sentence to the Tools log, the absent case included, and shows the skip sentence wherever it reports apps it leaves out.

What is not filtered. The command line (labconstrictor-tools list|run|check|test), notebooks (%%lc_tool, run_once) and the worker. labconstrictor-tools list prints each app's declaration (hosts: notebook, fiji, not declared (listed in every host) or INVALID (...)); list --json adds "hosts": {app: [...] | null} (null: not declared, or not a list) and "hosts_status": {app: "declared" | "absent" | "invalid"}. An app that declares only notebook is registered, usable from the command line and hidden from all three hosts.

Host requirements (which plugin an app needs)

The compatibility rules let a host require a minimum Tools in the app. This is the other direction: an app says which host plugin it needs, so that a person with an old plugin is told to update. Feature id host_requirements_v1; reference: labconstrictor_tools.host_requirements.check; test vectors: conformance.json, section host_requirements.

Where the declaration comes from. The app's labconstrictor-app.yaml (Tool markers):

host_requirements:
  qupath:
    min_version: 0.1.0-alpha.6        # a release tag of the plugin, with or without "v"
    features: [shapes_owner_v1]       # optional: host feature ids (HOST_FEATURES.md)
    why: Replace keeps your own annotations   # optional, one line
    required: false                   # optional; true refuses instead of warning

register --app-manifest validates the block and copies it into the registry entry; an invalid block is refused and nothing is registered. Only napari, fiji and qupath can be named. The reader understands this block form only (two levels of key: value, a flow list on one line, quoted or plain text, true/false).

The rule. For each registered app, a host calls check(entry, "<its own name>", <its own version or None>, <its own feature ids>) and acts on (status, sentence):

Situation status sentence (exact; {app} is the entry's display_name, {why} is (<why>) or empty, {url} is https://github.com/CellMigrationLab/LabConstrictor-{plugin}/releases/latest)
nothing declared for this host, or new enough with every feature ok none
the host's version is below min_version warn (refuse with required: true) {app} needs LabConstrictor-{plugin} {min_version} or newer{why}; this is {host_version}. Update the plugin: {url}
a required host feature is missing warn (refuse with required: true) {app} needs LabConstrictor-{plugin} with {features}{why}; this plugin does not have it. Update the plugin: {url}
the host's version is unknown or unreadable (Fiji's loose script) while min_version is set always warn {app} needs LabConstrictor-{plugin} {min_version} or newer{why}; the version of this plugin is unknown. Update the plugin if the app misbehaves: {url}
the declaration is not valid (hand-edited entry) warn {app} has a host_requirements declaration that is not valid ({problem}); register the app again with a valid one

{plugin} is napari, Fiji or QuPath. Versions compare as PEP 440 after dropping a leading v (v0.1.0-alpha.6 = 0.1.0a6; 0.1.0a6.dev0 < 0.1.0a6 < 0.1.0rc1 < 0.1.0); version_order in the vectors pins the order. An unknown asking host raises an exception.

What a host does. ok: nothing. warn: the app stays listed; the sentence is shown where the person picks the app (a status line, a tooltip or one dialog per session) and written to the Tools log. refuse: the app's tools do not start. napari keeps the app listed and refuses Run with the sentence; Fiji and QuPath leave the app out of their list and show the sentence where they report skipped apps. A host without host_requirements_v1 ignores the field. The command line and notebooks are never checked.

Each host's version source and feature ids are in HOST_FEATURES.md.

Result folders and run records (retention)

Under <LC_HOME>, results/<YYYYMMDDTHHMMSS>_<6 hex>_<app>_<tool> holds the files of a run and runs/<time>_<app>_<tool> its record (run.json). Feature retention_prune. The reasons behind the policy are in SPEC_WRONG_SCIENCE.md.

  • Markers. Whoever creates the folder (a host, the CLI, runs.record) writes .lc-owner.json first: {"lc_marker": 1, "kind": "result|run", "name": "<folder name>", "host": "cli|napari|fiji|qupath|notebook", "pid": n, "created": "<UTC ISO-8601 with Z>", "token": "<uuid4>"}. It writes .lc-done.json last, atomically (temporary file, then rename): {"finished": "<UTC ISO-8601>", "status": "ok|failed|cancelled"}. labconstrictor_tools.retention.write_owner and write_done are the reference writers.
  • Hosts never delete anything under results/ or runs/. After writing the done marker, a host starts labconstrictor-tools prune in a subprocess and ignores its exit code.
  • What prune removes: the oldest eligible folders beyond the newest 20 (results) or 50 (runs). Eligible means: a real directory (not a symlink, junction or other reparse point), a direct child of the root, a name made of A-Za-z0-9_.-, a valid owner marker whose name is the folder's name and whose kind matches the root, and a done marker. Other folders (foreign, without markers, unfinished or crashed), links and files are never touched and do not count. Order: the marker's created, then the name.
  • How: prune takes a non-blocking lock on <LC_HOME>/.retention.lock; if it cannot, it exits 0 and deletes nothing. A folder is renamed to .lc-deleting-<token> inside the root, then removed without following links; the next prune finishes an interrupted removal. --dry-run lists what a real run would remove and changes nothing. Exit code 0, also when the lock is held; 1 when a folder could not be removed (the report says which and why). --out folders, state, logs and everything outside the two roots are never touched.

A Python host that writes its own run record (napari). runs.record is for the CLI and the Python client: it creates the folder when the run is over, writes the markers and run.json, and prunes. A host instead creates its folder when the run starts (owner marker first, so a crash leaves an owned, unfinished folder that nobody removes) and never prunes. It uses three functions that create, delete and prune nothing:

  • runs.build_record(app, tool_id, inputs, task, seconds, stderr="", *, run_id=None, started_utc=None, finished_utc=None) -> dict: the content of run.json, the same dict runs.record writes. The host-owned _job_dir and matrix_yx are left out, the stderr tail is cut to runs.STDERR_TAIL_CHARS, and finished_utc defaults to now. With run_id and started_utc the record carries them (run_id first, started_utc after tool); without them it has neither key, as the CLI writes it.
  • runs.record_json(content) -> str: the text of run.json (indented; anything that is not JSON is written as text).
  • runs.done_status(task_status, cancel_requested=False) -> str: the status for .lc-done.json. COMPLETE is ok, CANCELED is cancelled, FAILED is failed, and CRASHED is cancelled when the person pressed Cancel (Task.cancel_requested), failed otherwise.

The host writes the owner marker with retention.write_owner(folder, "run", "<host>"), run.json with the text above and the done marker with retention.write_done(folder, runs.done_status(...)), then starts labconstrictor-tools prune (compatibility rule 6). The three functions arrive in 0.3.0a1: a host that calls them requires min_tools_version 0.3.0a1 (compat.check_schema(schema, "0.3.0a1")) or, in Python, checks hasattr(runs, "build_record"). There is no features id for them: ids describe worker and CLI behaviour that any host can read in the schema, while these are functions only a Python host imports.

Reserved inputs

A request's inputs may carry fields that are not tool parameters. Their names start with an underscore and belong to the protocol; a tool cannot declare a parameter with such a name (declaration error). A worker accepts every name that starts with an underscore and ignores the ones it does not know, so a newer host never fails an older worker. Tools never see reserved inputs. The list is labconstrictor_tools.protocol.RESERVED_INPUTS, tested against this table:

Name Sent by Meaning
_job_dir every host the host-owned directory for outputs; the worker consumes it
_calibration hosts that send a PixelSizeOf value per-axis pixel or voxel size with its provenance (x, y)
_axes hosts that write a file without axes metadata {param: "TZCYX"}, the axes of the file just written; reserved, no worker reads it yet

A new name is added to RESERVED_INPUTS and to this table in the same change. The worker refuses exactly convert.undeclared_inputs(schema, inputs), the names that are neither declared nor reserved, with invalid_parameter.

Wire protocol (host <-> worker)

The worker (python -m labconstrictor_tools serve --module M) speaks the Appose worker protocol: one JSON object per line on stdin and stdout.

Host sends Worker answers
{"task": id, "requestType": "EXECUTE", "script": "lc:<tool_id>", "inputs": {...}} LAUNCH, then UPDATE {message, current, maximum}*, then exactly one of COMPLETION {outputs}, FAILURE {error, code, traceback?}, CANCELATION
{"task": id, "requestType": "CANCEL"} the task ends with CANCELATION if the tool calls check_cancel()

Requests

  • task must be a non-empty string, unique until the task's terminal answer. An EXECUTE that reuses the id of a running task is ignored.
  • script must be lc:<id> of a declared tool. Anything else, Python source included, is refused with unknown_tool. A script that is not text, or inputs that is not an object (or absent), is refused with bad_request.
  • inputs: image, labels, table, file and folder values are paths; an image may also be an Appose ndarray shared-memory object. Other values are JSON. _job_dir names the host-owned output directory.
  • A CANCEL for a task that is not running is ignored, and not remembered for a later EXECUTE. Unknown requestTypes, lines that are not JSON objects and lines longer than 16 MiB are ignored. Each of these is written to the worker's log and stderr.

Answers

  • UPDATE {message, current, maximum}: maximum is 100 and current is the whole percent nearest to the fraction the tool reported (progress(0.29) -> 29); a tie goes up (0.295 -> 30), as Java's Math.round does. A host that converts the fraction itself rounds the same way and never truncates.
  • COMPLETION.outputs = {results: [...], job_dir, timings, diagnostics}. A result is {type, name, ...}: image/labels {path, axes}, table {path}, values {values}, affine {matrix_yx, apply_to, relative_to}, file {path}, and message, points, shapes as described under Results.
  • NaN and infinity cannot be written in JSON and are sent as null. A host treats null in a numeric value as "not a finite number".
  • A tool that calls sys.exit() or is interrupted ends with FAILURE (code SystemExit or KeyboardInterrupt). A result that JSON cannot carry ends with FAILURE code unserializable_result.
  • A request written to a worker that has already exited ends as CRASHED with the worker's last output. In the Python client, WorkerProcess.task returns that task; it is not kept in worker.tasks and no exception reaches the host.

Shared-memory images

  • The descriptor is {"appose_type": "ndarray", "shm": {"name"}, "shape", "dtype"}, optionally with "order". The block must still exist, be large enough and have a numeric dtype. A stale or malformed descriptor gives unreadable_image: the shared-memory image for 'N' is gone or malformed (...): the host must keep the block alive until the task ends and send {...}.
  • The host creates the block and unlinks it when it is done. The worker only maps and copies it, never unlinks it, and does not register it with its resource tracker.
  • order (feature shm_order_v1): absent, "C" or "C_ORDER" is row-major (last axis fastest, what numpy and a [Y, X] shape mean); "F" or "F_ORDER" is column-major (first axis fastest, what an ImgLib2-style [X, Y] array has). The tool receives the same logical array either way (array[i, j] is the element the host calls [i, j]), as a C-ordered copy. Any other value ("A", "K", "f", a number, a list, null) is refused with unreadable_image and a message that says send 'C' or 'F', because a block read in the wrong order is the transposed image with no error. When in doubt, send a C-ordered block and [Y, X].

TIFF files

The worker memory-maps a TIFF input (copy-on-write) instead of reading it whole only when the file is at least 8 MiB and simple: one series with one pyramid level, uncompressed, untiled, all strips in one contiguous run in the machine's byte order, a generic, ImageJ or shaped TIFF (not OME, LSM or multi-file), not truncated. Any other file, or LC_TIFF_MEMMAP=0 in the worker's environment, is read the plain way. The tool cannot tell the difference: same shape, dtype and values, a writable numpy.ndarray. A tool that writes to its input changes only its private copy, never the file.

The worker releases every mapping before it sends the terminal answer, so the host can delete the input at once, also on Windows, where an open mapping locks the file (unless the tool keeps a reference to its input in a global). A host must not truncate or rewrite an input file while a task reads it: a mapped page beyond the end of a shortened file ends the worker.

Process lifetime

  • Tools run on the worker's main thread. stdin is read on a helper thread; on Windows by polling, never a blocking read, because native libraries touch the stdin handle while they load and a pending read would deadlock them.
  • Closing stdin means "the host is gone": running tools are asked to cancel and the worker exits within 10 s.
  • Nothing a tool starts outlives the worker. On Windows the worker puts them in a kill-on-close job object. On POSIX the worker makes itself the leader of its own process group at start (setsid, so no host has to) and, as its last act, sends SIGKILL to every other process of that group (found with ps; if that fails, it kills the whole group, itself included).

Registry

An entry <name>.json is {name, display_name, version, prefix, python, module, pythonpath, runtime_path, schema_path, tools_version?, features?, hosts?, host_requirements?}. tools_version and features are copied from the schema (Tools version and features); hosts is the app's declaration, absent meaning listed in every host (App hosts); host_requirements is described in Host requirements.

Search order, first wins: $LC_HOME/apps (default ~/.labconstrictor/apps), the directories in $LC_APPS_PATH, then the system directory (%ProgramData%\LabConstrictor\apps, /Library/Application Support/LabConstrictor/apps or /etc/labconstrictor/apps).

An entry is skipped and reported when its interpreter is missing or not inside prefix, when its file is not owned by the user or is group- or world-writable (POSIX only), or when its schema is unreadable or has an unsupported protocol.

Edit this page on GitHub