Git Dependency

View full source code on GitHub

What does this applet do?

This applet performs a basic SAMtools count of alignments present in an input BAM.

Prerequisites

The app must have network access to the hostname where the git repository is located. In this example, access.network is set to:

"access": {
  "network": ["github.com"]
}

To learn more about access and network fields see Execution Environment Reference.

How is the SAMtools dependency added?

SAMtools is cloned and built from the SAMtools GitHub repository. Let's take a closer look at the dxapp.json file's runSpec.execDepends property:

  "runSpec": {
 ...
    "execDepends": [
        {
        "name": "htslib",
        "package_manager": "git",
        "url": "https://github.com/samtools/htslib.git",
        "tag": "1.3.1",
        "destdir": "/home/dnanexus"
        },
        {"name": "samtools",
        "package_manager": "git",
        "url": "https://github.com/samtools/samtools.git",
        "tag": "1.3.1",
        "destdir": "/home/dnanexus",
        "build_commands": "make samtools"
        }
    ],
...
  }

The execDepends value is a JSON array of dependencies to resolve before the applet source code is run. In this applet, we specify the following git fetch dependency for htslib and SAMtools. Dependencies are resolved in the order they're specified. Here we must specify htslib first, before SAMtools build_commands, due to newer versions of SAMtools depending on htslib. An overview of the each property in the git dependency:

• package_manager - Details the type of dependency and how to resolve. supplementary details.

• url - Must point to the server containing the repository. In this case, a GitHub URL.

• tag/branch - Git tag/branch to fetch.

• destdir - Directory on worker to which the git repository is cloned.

• build_commands - If needed, build commands to execute. We know our first dependency, htslib, is built when we build SAMtools. As a result, we only specify build_commands for the SAMtools dependency.

The build_commands are executed from the destdir. Use cd when appropriate.

How is SAMtools called in our src script?

Because we set "destdir": "/home/dnanexus" in our dxapp.json, we know the git repository is cloned to the same directory from which our script will execute. Our example directory's structure:

├── home
│   ├── dnanexus
│       ├── < app script >
│       ├── htslib
│       ├── samtools
│           ├── < samtools binary >

Our SAMtools command from the app script is samtools/samtools.

Applet Script

main() {
  set -e -x -o pipefail

  dx download "$mappings_bam"

  count_filename="${mappings_bam_prefix}.txt"
  readcount=$(samtools/samtools view -c "${mappings_bam_name}")
  echo "Total reads: ${readcount}" > "${count_filename}"

  counts_txt=$(dx upload "${count_filename}" --brief)
  dx-jobutil-add-output counts_txt "${counts_txt}" --class=file
}

We could have built SAMtools in a destination within our $PATH or added the binary directory to our $PATH. Keep this in mind for your app(let) development.