From 4f3d9f8115b38569efac5331d333c13f0ebaa37f Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Thu, 20 Feb 2025 13:27:59 -0400 Subject: [PATCH] update --- .../compute_special_remote_interface.mdwn | 26 +++++++++++-------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/doc/design/compute_special_remote_interface.mdwn b/doc/design/compute_special_remote_interface.mdwn index f82fdc22c5..8b1a732e7a 100644 --- a/doc/design/compute_special_remote_interface.mdwn +++ b/doc/design/compute_special_remote_interface.mdwn @@ -51,12 +51,16 @@ In the example above, the program is expected to output something like: If possible, the program should write the content of the file it is computing directly to the file listed in COMPUTING, rather than writing to -somewhere else and renaming it at the end. If git-annex sees that the file -corresponding to the key it requested be computed is growing, it will use -its file size when displaying progress to the user. +somewhere else and renaming it at the end. Except, when the program writes +the file it computes out of order, it should write to a file somewhere else +and rename it at the end. + +If git-annex sees that the file corresponding to the key it requested be +computed is growing, it will use its file size when displaying progress to +the user. The program can also output lines to stdout to indicate its current -progress. +progress: PROGRESS 50% @@ -67,23 +71,23 @@ output, but not for progress displays. If the program exits nonzero, nothing it computed will be stored in the git-annex repository. -The program must also support listing the inputs and outputs that it +When run with the "interface" parameter, the program must describe its +interface. This is a list of the inputs and outputs that it supports. This allows `git-annex addcomputed` and `git-annex initremote` to list inputs and outputs, and also lets them reject invalid inputs and outputs. -In this mode, the program is run with a "list" parameter. -It should output lines, in the form: +The output is lines, in the form: - INPUT[?] Name Description - VALUE[?] Name Description + INPUT[?] Id Description + VALUE[?] Id Description OUTPUT Id Description Use "INPUT" when a file is an input to the computation, and "VALUE" for all other input values. Use "INPUT?" and "VALUE?" for optional inputs and values. -The program can also optionally output a "REPRODUCIBLE" line. +The interface can also optionally include a "REPRODUCIBLE" line. That indicates that the results of its computations are expected to be bit-for-bit reproducible. That makes `git-annex addcomputed` behave as if the `--reproducible` @@ -93,7 +97,7 @@ An example `git-annex-compute-foo` shell script follows: #!/bin/sh set -e - if [ "$1" = list ]; then + if [ "$1" = interface ]; then echo "INPUT raw A photo in RAW format" echo "VALUE? passes Number of passes" echo "OUTPUT photo Computed JPEG"