appc-aar-tools

Android Archive Tools for NodeJS

Set of tools to work with Android Archive (.aar) files outside of the Gradle build pipeline.

Installation

npm install appc-aar-tools

Usage

This module is used to extract the contents of an Android Archive (.aar) to a desired location and optionally copy any bundled assets and libraries to a new location. It can also regenerate the R.java class file from the R.txt that is included in Android Archives.

Extract Android Archive

Extracting an Android Archive and optionally copying assets and libraries to a new location can be done using the AarTransformer class.

Note: All paths are expected to be absolute (you can use path.join() for that).

var AarTransformer = require('appc-aar-tools').AarTransformer;
var transformer = new AarTransformer(logger) // logger is optional, can be any bunyan based logger

var options = {
  aarPathAndFilename: '/path/to/file.aar',
  outputPath: '/path/to/dist',
  assetsDestinationPath: '/path/to/assets',
  libraryDestinationPath: '/path/to/lib',
  sharedLibraryDestinationPath: '/path/to/jni'
};

transformer.transform(options, function(err, result) {
  console.log(result.explodedPath); // full path to the exploded archive folder
  console.log(result.packageName); // package key from AndroidManifest.xml
  console.log(result.jars); // array of JAR files found in the Android Archive
  console.log(result.nativeLibraries); // array of native libraries (.so) found in the Android Archive
});

All available options for the transform() method are described in the following table.

Option	Type	Description
aarPathAndFilename	String	The path and filename pointing to the .aar file to process.
outputPath	String	Base directory where the .aar file will be extracted to. The actual content will be extracted into a sub-directory (basename of the AAR file).
assetsDestinationPath	String	(Optional) Copy all assets contained in the .aar to this path.
libraryDestinationPath	String	(Optional) Copy all libraries (.jar) contained in the .aar to this path.
sharedLibraryDestinationPath	String	(Optional) Copy all shared libraries (.so) contained in the .aar to this path.

Generate R.java

Generating the R.java from a R.txt is handled by the SymboldLoader and SymbolWriter classes.

Symbols from a R.txt file can be loaded by the SymbolLoader

var SymbolLoader = require('appc-aar-tools').SymbolLoader;
var librarySymbols = new SymbolLoader('/path/to/exploded/archive/R.txt');
librarySymbols.load();

Those symbols can then be added to the SymbolWriter which will generate a R.java based on the symbols found. In addition to the library symbols the SymbolWriter requires the full symbol values to be passed to its constructor. This simply is a SymbolLoader instance which loaded the R.txt file that was generated by the AAPT command line tool from all merged resources using the --output-text-symbols option.

var SymbolLoader = require('appc-aar-tools').SymbolLoader;
var SymbolWriter = require('appc-aar-tools').SymbolWriter;
var fullSymbolValues = new SymbolLoader('/path/to/symbol/file/from/aapt/R.txt')
fullSymbolValues.load();
var outputPath = '/output/path';
var packageName = 'com.library.package.name';
var symbolWriter = new SymbolWriter(outputPath, packageName, fullSymbolValues);
symbolWriter.addSymbolsToWrite(librarySymbols);
symbolWriter.write();

After calling the write() method the generated file will be saved under a sub-folder in the output path which is based on the package name. In the above example that would be /output/path/com/library/package/name/R.java

Contributing

This is an open source project. Please consider forking this repo to improve, enhance or fix issues. If you feel like the community will benefit from your fork, please open a pull request.

To protect the interests of the contributors, Appcelerator, customers and end users we require contributors to sign a Contributors License Agreement (CLA) before we pull the changes into the main repository. Our CLA is simple and straightforward - it requires that the contributions you make to any Appcelerator open source project are properly licensed and that you have the legal authority to make those changes. This helps us significantly reduce future legal risk for everyone involved. It is easy, helps everyone, takes only a few minutes, and only needs to be completed once.

You can digitally sign the CLA online. Please indicate your e-mail address in your first pull request so that we can make sure that will locate your CLA. Once you've submitted it, you no longer need to send one for subsequent submissions.

License

This project is open source and provided under the Apache Public License (version 2).

Copyright (c) 2017, Appcelerator Inc. All Rights Reserved.