Writing DNAnexus Apps in bash

If you have not already, you should install the DNAnexus SDK and walk through the Intro to Building Apps tutorial.

Hello, <your name here>!

Run the App Wizard

The DNAnexus App Wizard (dx-app-wizard) supports the creation of bash templates for bash apps. Let's walk through the process to make a simple applet which takes in a string input and returns a string output.

$ dx-app-wizard [...] App Name: greeting [...] (<ENTER> to accept defaults) Input Specification You will now be prompted for each input parameter to your app. Each parameter should have a unique name that uses only the underscore "_" and alphanumeric characters, and does not start with a number. 1st input name (<ENTER> to finish): name Label (optional human-readable name) []: Your name Your input parameter must be of one of the following classes: applet array:file array:record file int array:applet array:float array:string float record array:boolean array:int boolean hash string Choose a class (<TAB> twice for choices): string This is an optional parameter [y/n]: n 2nd input name (<ENTER> to finish): <ENTER> Output Specification You will now be prompted for each output parameter of your app. Each parameter should have a unique name that uses only the underscore "_" and alphanumeric characters, and does not start with a number. 1st output name (<ENTER> to finish): greeting Label (optional human-readable name) []: A greeting Choose a class (<TAB> twice for choices): string 2nd output name (<ENTER> to finish): <ENTER> Template Options You can write your app in any programming language, but we provide templates for the following supported languages: Python, bash Programming language [Python]: bash ... Execution pattern [basic]: <ENTER> ...

Take a look at the generated files

The following files should be created for you:

greeting ├── dxapp.json ├── Makefile ├── Readme.developer.md ├── Readme.md ├── resources ├── src │ └── greeting.sh └── test

Let's open up the source file greeting/src/greeting.sh and take a look at what has been automatically generated. Note that input variables are automatically loaded as bash variables, and that each output is reported one at a time using the command-line utility dx-jobutil-add-output, which is available in the SDK. You can run the command yourself; it will simply directly edit the file ~/job_output.json which is used in the Execution Environment to report the output of the job.

main() {

    echo "Value of name: '$name'"

    # Fill in your application code here.
    # To report any recognized errors in the correct format in
    # $HOME/job_error.json and exit this script, you can use the
    # dx-jobutil-report-error utility as follows:
    #   dx-jobutil-report-error "My error message"
    # Note however that this entire bash script is executed with -e
    # when running in the cloud, so any line which returns a nonzero
    # exit code will prematurely exit the script; if no error was
    # reported in the job_error.json file, then the failure reason
    # will be AppInternalError with a generic error message.

    # The following line(s) use the utility dx-jobutil-add-output to format and
    # add output variables to your job's output as appropriate for the output
    # class.  Run "dx-jobutil-add-output -h" for more information on what it
    # does.

    dx-jobutil-add-output greeting "$greeting" --class=string

Fill in application code

Let's set the variable greeting before it is used to report the output. Insert the following line right before the line that runs dx-jobutil-add-output.

  greeting='Hello, '"$name"'!'

Build and run it as an applet

You are now ready to build it as an applet. If you haven't already, log in using the dx login command and navigate to the project to which you would like to upload your applet.

$ dx build greeting

Now try running the applet!

$ dx run greeting -iname="George" -y

Once the job is done, describe it to see its output (replace job-xxxx below with the job ID of your job).

$ dx wait job-xxxx && dx describe job-xxxx Waiting for job-xxxx to finish running... Done Result 1: ID job-B447Jg2qqBk7fgZ16G7Q0023 Job name greeting ... Input name = "George" Output greeting = "Hello, George!" ...

Other examples

You may find the collection of bash sample code snippets to be useful.

Last edited by Thanh-Ha Nguyen, 2016-06-24 23:25:08