Developer Tutorials/App Build Process

This tutorial will walk you through important features of the DNAnexus app build infrastructure that will help you build your app:

  • The dxapp.json file, a central point for information about your app
  • The /resources directory, where you can include files to be loaded onto the workers which will execute your app
  • The option to build your app remotely, needed when building from a system not compatible with Ubuntu 12.04

For more information about the worker environment where your app will run, and on how to specify runtime dependencies for your app, see the Execution Environment Reference.

App Directory Structure

DNAnexus applets and apps are usually compiled using the dx build and dx build --create-app utilities in the DNAnexus SDK, which take code on your local workstation and upload it into an object on the platform. The SDK expects each program to reside in a directory with a specific structure, which looks like this:

MyApp
├── dxapp.json
├── Readme.md
├── Readme.developer.md
├── resources
│   └── ...
├── src
│   └── ...
└── test
    └── ...

dxapp.json (App metadata)

The file dxapp.json is a DNAnexus application metadata file. Its presence in a directory tells DNAnexus tools that it contains DNAnexus app source code (i.e., it's a project directory). See dxapp.json for a complete description of the app metadata format.

Readme files

The Readme.md file, if present, is inlined into the description field of the app or applet.

The Readme.developer.md file, if present, is inlined into the developerNotes

resources/ subdirectory

See the section "Building apps from source" below, which describes the relationship between the resources subdirectory of your project directory and the resulting app or applet.

Building an applet

You can use the following command to load your application into the DNAnexus Platform as an applet:

dx build MyApp

(assuming your applet's source code appears in a directory MyApp underneath the current directory)

Before uploading your program to DNAnexus, dx build performs the following build steps.

  • ./configure (if a configure script exists)
  • make && make install (if a Makefile is present)

You can put arbitrary steps in your Makefile to prepare any resources that might be needed by your app at runtime. For example, one module of your app might be written in C++ and therefore would need to be compiled to a library or executable.

The resources/ directory and its use

Anything that is present in the resources/ subdirectory of your app directory will be archived after the build step and then unarchived into the root of your execution environment's filesystem at runtime. (You can either check files directly into your source repository in the resources/ subdirectory, or have your build step generate files there, or a combination of the two.)

By default, the PATH in the environment is the following (it is inherited from Ubuntu's defaults):

/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

As an example, if your Makefile produces a binary and puts it in resources/usr/bin/bwa in your source tree, that file is available to your app as /usr/bin/bwa at runtime (and you can therefore easily call it as a subprocess from your entry point method).

While the resources/ subdirectory is unpacked into the root of the virtual filesystem, your app starts in in /home/dnanexus as its current working directory. You may therefore wish to put files or data in resources/home/dnanexus in order to have them available in the current working directory when your applet starts.

Cross-compiling to Ubuntu: Build your app remotely

If your app will package any architecture-dependent resources (such as executables compiled from C or C++) you will need to ensure that you can produce resources targeting Ubuntu 12.04 (running on a 64-bit processor). The DNAnexus Platform and the SDK provide some assistance with this if your development environment is not Ubuntu 12.04. See Cross-compilation for more information.

Next steps

Your app runs in the Execution Environment, a fully capable, isolated Linux environment. See the Execution Environment Reference for information about the execution process.

See the API Specification for a complete reference to the behavior of the API methods that insert apps and applets into the DNAnexus platform.

A variety of sample applications are available for your reference:

Last edited by Thanh-Ha Nguyen, 2015-09-02 18:58:23

 Feedback