Asset Directory Structure

A DNAnexus asset can be built using the dx build_asset utility in the
DNAnexus SDK, which builds an asset bundle in an isolated environment. The
utility expects a directory with the following structure:

In order to build this asset, run the command dx build_asset asset_name.

Each component of the directory is described in detail below.

dxasset.json and asset metadata

The dxasset.json file contains essential metadata that define the asset. This
file is required to build an asset and therefore must be present in the
asset source directory. The following is a sample dxasset.json file:

{
"name": "asset_name", # Asset bundle name
"title": "Example Asset", # Human-readable name
"description": "Libraries required for a tool you've built",
# A detailed description of the asset bundle and its
# contents
"version": "0.0.1", # Version number
"distribution": "Ubuntu", # The flavor and version of Linux that the asset is
# targeted to (default Ubuntu)
"instanceType": "mem2_ssd1_x4", # The instance type on which the asset bundle
# will be built
"release": "14.04", # The version of Linux flavor (only 14.04)
"excludeResource": [ # Files and directories that should not be included
"/src/my.ccp", # in the asset bundle (optional)
"/scripts"
],
"execDepends": [ # The list of packages on which the asset depends
{"name": "samtools", "package_manager": "apt"},
{"name": "pandas","package_manager": "pip"}
]
}

resources/ subdirectory

If anything is present in the resources/ subdirectory of the asset directory,
it will be archived by dx build_asset and unpacked into the root of a clean
Ubuntu installation during the asset build process. Files here can be
propagated directly into the asset, or they can be used to build other
artifacts that are themselves propagated into the asset.

For example, if you have some C or C++ source files that should be compiled so
that their binary output can be included in the asset bundle, you can do one of
the following:

Put your source files somewhere in the resources/ directory, such as
resources/example_dir/.

Invoke your build process from the Makefile included in the asset source
directory (see below). In the asset build environment, your source files are
available in the directory /example_dir.

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

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

Makefile

The optional Makefile contains instructions to build and copy additional
resources required by the asset. If present in the asset source directory, the
Makefile is copied to the working directory /home/dnanexus of the asset build
environment and executed. Here is an example Makefile that downloads and
installs various resources:

Building an asset

Assuming the directory asset_name contains a dxasset.json file, you can use
the following command to build your asset:

dx build_asset asset_name

A virtual worker starts a new DNAnexus job in order to provide an isolated
build environment in which the following steps are performed:

A snapshot is taken of the worker's filesystem. During this process, all the
directories, files, and symbolic links are recorded, except those mentioned in
the excludeResource field of the dxasset.json file. Files in directories
matching the following paths are excluded: /proc*, /tmp*, /run*,
/boot*, /home/dnanexus*, /sys*.

Any packages mentioned in the execDepends field of the dxasset.json are
installed in the worker's execution environment.

If a resources/ directory is present in the asset source directory, its
contents are copied to the root directory / of the worker's execution environment.

If a Makefile is present in the asset source directory, it is copied to the
/home/dnanexus on the worker and executed as sudo make -C /home/dnanexus.

A second snapshot of the worker's execution environment is taken.

All new and modified (files with different timestamps from those on the
earlier snapshot) files are packaged in the resulting asset bundle.