From 0bb4ea4676bca26c4b27906611256c8d908706e9 Mon Sep 17 00:00:00 2001 From: Yaroslav Halchenko Date: Fri, 20 Oct 2017 13:42:17 -0400 Subject: [PATCH 1/2] minor typos --- spec/manifest.schema.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/manifest.schema.json b/spec/manifest.schema.json index 4cd30e4..143303f 100644 --- a/spec/manifest.schema.json +++ b/spec/manifest.schema.json @@ -39,7 +39,7 @@ "additionalProperties": { "$ref": "#/definitions/directive" }, - "description": "Schema snippets desribing the options this gear consumes. Not currently processed." + "description": "Schema snippets describing the options this gear consumes. Not currently processed." }, "custom": { "type": "object", @@ -48,7 +48,7 @@ "description": { "type": "string", "maxLength": 5000, - "description": "A brief description of the gear's purpose. Ideally 1-4 sentances." + "description": "A brief description of the gear's purpose. Ideally 1-4 sentences." }, "environment": { "type": "object", From f32879c406e520154980b0bb9348ed0ec09b3985 Mon Sep 17 00:00:00 2001 From: Yaroslav Halchenko Date: Fri, 20 Oct 2017 13:42:44 -0400 Subject: [PATCH 2/2] ENH: removed forgotten html
from .md, and adjusted some wording --- spec/readme.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/spec/readme.md b/spec/readme.md index b46d858..8a9b84e 100644 --- a/spec/readme.md +++ b/spec/readme.md @@ -10,7 +10,8 @@ This tar file can be created from most common container tools (e.g., Docker). ## The base folder -To be a Flywheel gear, the container in the tar file must include a folder named: `/flywheel/v0`.
+To be a Flywheel gear, the container in the tar file must include a folder named: `/flywheel/v0`. + All following references to folders are relative to this folder. The `/flywheel/v0` folder contains two specific files: @@ -24,7 +25,8 @@ The contents of these files are described here. Here's an example manifest.json that specifies a Flywheel gear which reads one dicom file as input and specifies one configuration parameter. The keys listed in this example are all required, unless marked otherwise. -For other restrictions and required fields, you can view our [manifest schema](manifest.schema.json).
+For other restrictions and required fields, you can view our [manifest schema](manifest.schema.json). + This document is a [JSON schema](http://json-schema.org), which allows for automatic validation of structured documents. Note, the `// comments` shown below are not JSON syntax and cannot be included in a real manifest file. @@ -114,7 +116,8 @@ Note, the `// comments` shown below are not JSON syntax and cannot be included i ### Manifest inputs -Each key of `inputs` specifies an input to the gear.
+Each key of `inputs` specifies an input to the gear. + At this point, the inputs are always files and the `"base": "file"` is part of the specification. Further constraints are an advanced feature, so feel free to leave this off until you want to pursue it. When present, they will be used to guide the user to give them hints as to which files are probably the right choice. In the example above, we add a constraint describing the `type` of file. File types will be matched against our [file data model](https://github.com/scitran/core/wiki/Data-Model,-v2#file-subdocument-only). @@ -215,20 +218,20 @@ As you might expect, gears cannot produce "normal" files called `.metadata.json` ## The run target and environment -By default, the gear is invoked by running is `/flywheel/v0/run`. The file must be executable (`chmod +x run`). It can be a bash script, a python function, or any other executable. +By default, the gear is invoked by running is `/flywheel/v0/run`. The file must be executable (`chmod +x run`). It can be a bash or a Python script, or any other executable. If it is a script, please make sure to include appropriate shebang (`#!`) leading line. You can change this by setting the `command` key of the manifest. -Whatever your run script, it is the only entry point used for the gear and must accomplish everything the gear sets out to do. On success, exit zero. If the algorithm encounters a failure, exit non-zero. Ideally, print something out before exiting non-zero, so that your users can check the logs to see why things did not work. +Your run script is the only entry point used for the gear and must accomplish everything the gear sets out to do. On success, exit zero. If the algorithm encounters a failure, exit non-zero. Ideally, print something out before exiting non-zero, so that your users can check the logs to see why things did not work. ### The environment for the run script -An important consideration is the environment when the `run` command is executed. +An important consideration is the environment where the `run` command is executed. The command will be executed in the folder containing it (`/flywheel/v0`), and with no environment variables save the `PATH`: -```` +``` /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin -```` +``` Any required environment and path variables should be specified within the script. This can be important if, for example, you're producing a gear from a Dockerfile, as the variables there will not transfer over. We typically specify the path and environment variables in a `.bashrc` file, and source that file at the beginning of the `run` script. @@ -238,7 +241,8 @@ The file is also executed with no arguments. You must specify the inputs to the At the current time, basic outbound networking may be available to the gear. This is not necessarily guaranteed, and may vary depending on your installation's setup. It is likely that this feature will become opt-in in a future version of the spec. -Be sure to get in touch with us regarding your networking needs - Matlab license checks, for example.
+Be sure to get in touch with us regarding your networking needs - Matlab license checks, for example. + There are no current plans to allow inbound networking. ## Contact