This tutorial will walk you through important features of the DNAnexus app build infrastructure that will help you build your app:
dxapp.json file, a central point for information about your app
/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 16.04 or 14.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
│ └── ...
│ └── ...
dxapp.json (App metadata)
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.md file, if present, is inlined into the
of the app or applet.
Readme.developer.md file, if present, is inlined into the
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
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
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
subdirectory, or have your build step generate files there, or a combination of
By default, the
PATH in the environment is the following (it is inherited
from Ubuntu's defaults):
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
/usr/bin/bwa at runtime (and you can therefore easily call it as a
subprocess from your entry point method).
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 16.04 or 14.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 16.04/14.04. See
Cross-compilation for more information.
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: