PackagingOptions

DSL object for configuring APK packaging options.

Packaging options are configured with three sets of paths: first-picks, merges and excludes:

First-pick
Paths that match a first-pick pattern will be selected into the APK. If more than one path matches the first-pick, only the first found will be selected.
Merge
Paths that match a merge pattern will be concatenated and merged into the APK. When merging two files, a newline will be appended to the end of the first file, if it doesn't end with a newline already. This is done for all files, regardless of the type of contents.
Exclude
Paths that match an exclude pattern will not be included in the APK.

To decide the action on a specific path, the following algorithm is used:

  1. If any of the first-pick patterns match the path and that path has not been included in the APK, add it to the APK.
  2. If any of the first-pick patterns match the path and that path has already been included in the APK, do not include the path in the APK.
  3. If any of the merge patterns match the path and that path has not been included in the APK, add it to the APK.
  4. If any of the merge patterns match the path and that path has already been included in the APK, concatenate the contents of the file to the ones already in the APK.
  5. If any of the exclude patterns match the path, do not include it in the APK.
  6. If none of the patterns above match the path and the path has not been included in the APK, add it to the APK.
  7. Id none of the patterns above match the path and the path has been included in the APK, fail the build and signal a duplicate path error.

Patterns in packaging options are specified as globs following the syntax in the Java Filesystem API. All paths should be configured using forward slashes (/).

All paths to be matched are provided as absolute paths from the root of the apk archive. So, for example, classes.dex is matched as /classes.dex. This allows defining patterns such as **/foo to match the file foo in any directory, including the root. Any pattern that does not start with a forward slash (or wildcard) is automatically prepended with a forward slash. So, file and /file are effectively the same pattern.

The default values are:

  • Pick first: none
  • Merge: /META-INF/services/**
  • Exclude:
    • /META-INF/LICENCE
    • /META-INF/LICENCE.txt
    • /META-INF/NOTICE
    • /META-INF/NOTICE.txt
    • /LICENCE
    • /LICENCE.txt
    • /NOTICE
    • /NOTICE.txt
    • **/.svn/** (all .svn directory contents)
    • **/CVS/** (all CVS directory contents)
    • **/SCCS/** (all SCCS directory contents)
    • **/.* (all UNIX hidden files)
    • **/.*/** (all contents of UNIX hidden directories)
    • **/*~ (temporary files)
    • **/thumbs.db
    • **/picasa.ini
    • **/about.html
    • **/package.html
    • **/overview.html
    • **/_*
    • **/_*/**

Example that adds the first anyFileWillDo file found and ignores all the others and that excludes anything inside a secret-data directory that exists in the root: 

packagingOptions {
    pickFirst "anyFileWillDo"
    exclude "/secret-data/**"
}

Example that removes all patterns: 

packagingOptions {
    pickFirsts = [] // Not really needed because the default is empty.
    merges = []     // Not really needed because the default is empty.
    excludes = []
}

Example that merges all LICENCE.txt files in the root. 

packagingOptions {
    merge "/LICENCE.txt" // Same as: merges += ["/LICENSE.txt"]
    excludes -= ["/LICENCE.txt"] // Not really needed because merges take precedence over excludes.
}

Properties

PropertyDescription
doNotStrip

The list of patterns for native library that should not be stripped of debug symbols.

excludes

The list of excluded paths.

merges

The list of patterns where all occurrences are concatenated and packaged in the APK.

pickFirsts

The list of patterns where the first occurrence is packaged in the APK. First pick patterns do get packaged in the APK, but only the first occurrence found gets packaged.

Methods

MethodDescription
exclude(pattern)

Adds an excluded pattern.

merge(pattern)

Adds a merge pattern.

pickFirst(pattern)

Adds a first-pick pattern.

Script blocks

No script blocks

Property details

Set<String> doNotStrip

The list of patterns for native library that should not be stripped of debug symbols.

Example: packagingOptions.doNotStrip "*/armeabi-v7a/libhello-jni.so"

Set<String> excludes

The list of excluded paths.

Set<String> merges

The list of patterns where all occurrences are concatenated and packaged in the APK.

Set<String> pickFirsts

The list of patterns where the first occurrence is packaged in the APK. First pick patterns do get packaged in the APK, but only the first occurrence found gets packaged.

Method details

void exclude(String pattern)

Adds an excluded pattern.

void merge(String pattern)

Adds a merge pattern.

void pickFirst(String pattern)

Adds a first-pick pattern.