Hi everyone.
Command line scripts. All command line scripts need to be accessible from IRIS. If you are not creating command line scripts for your module, we need to know this and why. Tom will talk on the devel con call today what is required for integration into IRIS.
In order for us to accomplish this, module owners will need to ensure the following:
Script Documentation
1) that all commands return zero when invoked with the -h and the --help options.
2) that all commands print to standard out a help message when invoked with the -h and --help options.
3) that the output contains the following information (see template below)
a description of what the script does
a description of the parameters
a description of the inputs and outputs
We'll harvest this text as part of the release process (see below)
Naming Convention
We will be cleaning up the namespace soon as a single, comprehensive effort in the near future. To help, you can start now by following this simple guidance:
1) commands are named lowercase with a consistent use of underscores (or dashes).
2) the kb prefix will be dropped in future releases
3) prefix with a module identifier
examples are :
Auxiliary Store:
as_create_index as_list_nodes as_resources
as_create_node as_list_users as_view_node
as_create_user as_modify_node as_view_user
Workspace Service (drop the kb):
kbws-createws kbws-load kbws-types.pl
kbws-delete kbws-login kbws-url
kbws-deletews kbws-logout kbws-whoami
kbws-exists kbws-meta kbws-workspace
Testing
The use of the test-scripts target will become a mandatory requirement for scripts that will be executed within IRIS. Because we will have hundreds of commands, we need an automated way to at a minimum verify that the script will run (this verifies the deployment was done correctly and all runtime dependancies are in place). As a minimal start, you should write a shell script that.
1) invokes the script using pre-staged test data
2) verifies correct output.
3) verifies the correct exit code
4) one directory per test
5) this directory contains the input data and output to be compared against by way of a diff or something of your choice.
6) these test directories are located under the top level script-tests directory as per the standard laid out in the module.Makefile template.
Complex Commands
Commands with complex interfaces, such as jnomics and the assembly service needs to be wrapped into simpler scripts for the user that set preset parameter values and turn the command/subcommand style interface into just a command interface.
Commands running on the IRIS host
Those commands that themselves are not clients in a client-server architecture, that is commands that will execute on the IRIS host (matR comes to mind), need to have communicated to the release engineering team cpu, memory and storage requirements.
Release Process
What I will do is modify the release process so that all commands are checked for the -h and --help options. The process will go something like first check to see if the -h and --help options exist and the command returns 0, for those that pass this check we'll have someone take a look at the output to see if it addresses the items in #3. The output will be saved as plain text, moved to the webroot directory under the deployment target, and from there be brought into the
kbase.us/developer_zone site as html docs.
Here is the template: