fplutil.buildutil.android.BuildEnvironment Class Reference

Class representing an Android build environment. More...

Inheritance diagram for fplutil.buildutil.android.BuildEnvironment:

Public Member Functions
def	build_android_libraries
	Build list of Android library projects. More...
def	get_manifest_path
	Get the path of the manifest file. More...
def	parse_manifest
	Parse the project's manifest. More...
def	create_update_build_xml
	Create or update ant build.xml for an Android project. More...
def	get_apk_filenames
	Get the set of output APK names for the project. More...
def	build_android_apk
	Build an Android APK. More...
def	find_projects
	Find all Android projects under the specified path. More...
def	build_all
	Locate and build all Android sub-projects as appropriate. More...
def	get_adb_devices
	Get the set of attached devices. More...
def	check_adb_devices
	Gets the only attached device, or the attached device matching a serial. More...
def	get_adb_device_argument
	Construct the argument for ADB to select the specified device. More...
def	list_installed_packages
	Get the list of packages installed on an Android device. More...
def	get_adb_device_name
	Get the string which describes an AdbDevice based upon the verbose mode. More...
def	install_android_apk
	Install an android apk on the given device. More...
def	install_all
	Locate and install all Android APKs. More...
def	stop_process
	Attempts to stop a process running under the given package name. More...
def	get_device_dpi
	Returns the dpi of a device connected to adb. More...
def	take_screencap
	Takes a screencap on the device and saves it to destination. More...
def	run_android_apk
	Run an android apk on the given device. More...
def	run_all
	Locate and run all Android APKs. More...
Public Member Functions inherited from fplutil.buildutil.common.BuildEnvironment
def	run_subprocess
	Run a subprocess as specified by the given argument list. More...
def	run_make
	Run make based on the specified build environment. More...
def	make_archive
	Archive build artifacts at the specified directory paths. More...
def	git_clean
	Cleans build directory back to last git commit. More...
def	get_project_directory
	Retrieve an absolute path relative to the project_directory. More...

Static Public Member Functions
def	build_defaults
	Helper function to set build defaults. More...
def	add_arguments
	Add module-specific command line arguments to an argparse parser. More...
def	ndk_location_changed
	Determine whether the NDK install location changed. More...
def	write_ndk_location
	Stores the current NDK path to a file. More...
def	parse_delete_local_properties
	Parse local properties and if the sdk location changed delete it. More...
def	generate_password
	Generate a psuedo random password. More...
Static Public Member Functions inherited from fplutil.buildutil.common.BuildEnvironment
def	build_defaults
	Helper function to set build defaults. More...
def	add_arguments
	Add module-specific command line arguments to an argparse parser. More...

Public Attributes
	ndk_home
	Path to the Android NDK, if found. More...
	sdk_home
	Path to the Android SDK, if found. More...
	ant_path
	Path to the ant binary, if found. More...
	ant_flags
	Flags to pass to the ant binary, if used. More...
	ant_target
	Ant build target name. More...
	sign_apk
	Enable signing of Android APKs. More...
	apk_keystore
	Keystore file path to use when signing an APK. More...
	apk_keyalias
	Alias of key to use when signing an APK. More...
	apk_passfile
	Path to file containing a password to use when signing an.
	apk_keycertpair
	(key, cert) tuple where Key is a .pk8 key file and
	always_make
	Whether to build when the project is already up to date. More...
	adb_logcat_args
	List of additional arguments passed to logcat when.
	adb_logcat_monitor
	Whether to continue to monitor the application's.
	ignore_sdk_version_missing
Public Attributes inherited from fplutil.buildutil.common.BuildEnvironment
	project_directory
	The top-level project directory to build. More...
	output_directory
	The top level directory to copy the build archive to. More...
	enable_git_clean
	Boolean value to enable cleaning for git-based projects. More...
	make_path
	Path to the make binary, for make-based projects. More...
	git_path
	Path to the git binary, for projects based on git. More...
	make_flags
	Flags to pass to make, for make-based projects. More...
	cpu_count
	Number of CPU cores to use while building. More...
	verbose
	Boolean to enable verbose message output. More...
	clean
	Boolean value which specifies whether to clean the project. More...
	host_os_name
	Lowercased name of host operating system. More...
	host_architecture
	Lowercased name of host machine architecture. More...

Static Public Attributes
string	ADB = 'adb'
string	ANDROID = 'android'
string	ANT = 'ant'
string	JARSIGNER = 'jarsigner'
string	KEYTOOL = 'keytool'
string	NDK_BUILD = 'ndk-build'
string	ZIPALIGN = 'zipalign'
Static Public Attributes inherited from fplutil.buildutil.common.BuildEnvironment
string	GIT = 'git'
string	MAKE = 'make'

Detailed Description

Class representing an Android build environment.

This class adds Android-specific functionality to the common BuildEnvironment.

Member Function Documentation

def fplutil.buildutil.android.BuildEnvironment.add_arguments (   parser )

static

Add module-specific command line arguments to an argparse parser.

This will take an argument parser and add arguments appropriate for this module. It will also set appropriate default values.

Parameters

parser

The argparse.ArgumentParser instance to use.

def fplutil.buildutil.android.BuildEnvironment.build_all	(		self,
			path = '.',
			apk_output = 'apks',
			lib_output = 'libs',
			exclude_dirs = None
	)

Locate and build all Android sub-projects as appropriate.

This function will recursively scan a directory tree for Android library and application projects and build them with the current build defaults. This will not work for projects which only wish for subsets to be built or have complicated external manipulation of makefiles and manifests, but it should handle the majority of projects as a reasonable default build.

Parameters

path	Optional path to start the search in, defaults to '.'.
apk_output	Optional path to apk output directory, default is 'apks'.
lib_output	Optional path to library output directory, default is 'libs'.
exclude_dirs	Optional list of directory names to exclude from project detection in addition to [apk_output, lib_output, 'bin', 'obj', 'res'], which are always excluded.

Returns

(retval, errmsg) tuple of an integer return value suitable for returning to the invoking shell, and an error string (if any) or None (on success).

def fplutil.buildutil.android.BuildEnvironment.build_android_apk	(		self,
			path = '.',
			output = None,
			manifest = None
	)

Build an Android APK.

This function builds an APK by using ndk-build and ant, at an optionally specified relative path from the current project directory, and output to an optionally specified output directory, also relative to the current project directory. Flags are passed to ndk-build and ant as specified in the build environment. This function does not install the resulting APK.

If no build.xml is found, one is generated via the 'android' command, if possible.

Parameters

path	Optional relative path from project directory to project to build.
output	Optional relative path from project directory to output
directory.
manifest	Parsed AndroidManifest instance.

Exceptions

SubCommandError	NDK toolchain invocation failed or returned an error.
ToolPathError	Android NDK or SDK location not found in configured build environment or $PATH, or ant not found.
ConfigurationError	Required build configuration file missing or broken in an unrecoverable way.
IOError	An error occurred writing or copying the APK.

def fplutil.buildutil.android.BuildEnvironment.build_android_libraries	(		self,
			subprojects,
			output = None,
			check_ndk_install_path = True
	)

Build list of Android library projects.

This function iteratively runs ndk-build over a list of paths relative to the current project directory.

Parameters

subprojects	A list pf paths relative to the project directory to build.
output	An optional directory relative to the project directory to receive the build output.
check_ndk_install_path	Whether to track the NDK install location and rebuild if it changes.

Exceptions

SubCommandError	ndk-build invocation failed or returned an error.
ToolPathError	Android NDK location not found in configured build environment or $PATH.

def fplutil.buildutil.android.BuildEnvironment.build_defaults ( )

static

Helper function to set build defaults.

Returns

A dict containing appropriate defaults for a build.

def fplutil.buildutil.android.BuildEnvironment.check_adb_devices	(		self,
			adb_device = None
	)

Gets the only attached device, or the attached device matching a serial.

When using adb to connect to a device, adb's behavior changes depending on how many devices are connected. If there is only one device connected, then no device needs to be specified (as the only device will be used). If more than one device is connected and no device is specified, adb will error out as it does not know which device to connect to.

This method ensures that for either case enough valid information is specified, and returns an instance of AdbDevice representing the valid device.

Parameters

adb_device

The serial to match a device on.

Returns

The only AdbDevice connected to adb, or AdbDevice matching the serial.

Exceptions

AdbError

More than one attached device and no serial specified, or device with matching serial specified cannot be found.

def fplutil.buildutil.android.BuildEnvironment.create_update_build_xml	(		self,
			manifest,
			path = '.'
	)

Create or update ant build.xml for an Android project.

Parameters

manifest	Parsed AndroidManifest instance.
path	Optional relative path from project directory to project to build.

Returns

BuildXml instance which references the created / updated ant project.

def fplutil.buildutil.android.BuildEnvironment.find_projects	(		self,
			path = '.',
			exclude_dirs = None
	)

Find all Android projects under the specified path.

Parameters

path	Path to start the search in, defaults to '.'.
exclude_dirs	List of directory names to exclude from project detection in addition to ['bin', 'obj', 'res'], which are always
excluded.

Returns

(apk_dirs, lib_dirs) where apk_dirs is the list of directories which contain Android projects that build an APK and lib_dirs is alist of Android project directories that only build native libraries.

def fplutil.buildutil.android.BuildEnvironment.generate_password ( )

static

Generate a psuedo random password.

Returns

8 character hexadecimal string.

def fplutil.buildutil.android.BuildEnvironment.get_adb_device_argument	(		self,
			adb_device = None
	)

Construct the argument for ADB to select the specified device.

Parameters

adb_device

Serial of the device to use with ADB.

Returns

A string which contains the second argument passed to ADB to select a target device.

def fplutil.buildutil.android.BuildEnvironment.get_adb_device_name	(		self,
			device
	)

Get the string which describes an AdbDevice based upon the verbose mode.

Parameters

device

AdbDevice instance.

Returns

String which describes the device.

def fplutil.buildutil.android.BuildEnvironment.get_adb_devices

(

self

)

Get the set of attached devices.

Returns

(device_list, command_output) where device_list is a list of AdbDevice instances, one for each attached device and command_output is the raw output of the ADB command.

def fplutil.buildutil.android.BuildEnvironment.get_apk_filenames	(		self,
			app_name,
			path = '.'
	)

Get the set of output APK names for the project.

Parameters

app_name	Basename of the APK parsed from build.xml.
path	Relative path from project directory to project to build.

Returns

(signed_apkpath, unsigned_apkpath) where signed_apkpath and unsigned_apkpath are paths to the signed and unsigned APKs respectively. Signing is optional so the signed APK may not be present when the project has been built successfully.

def fplutil.buildutil.android.BuildEnvironment.get_device_dpi	(		self,
			adb_device = None
	)

Returns the dpi of a device connected to adb.

Parameters

adb_device

Serial of the device to get the dpi from. If none specified, the only device connected will be used.

Returns

int of the device's pixel density.

def fplutil.buildutil.android.BuildEnvironment.get_manifest_path	(		self,
			path = '.'
	)

Get the path of the manifest file.

Parameters

path	Optional relative path from project directory to project to build.

Returns

Path of the manifest file.

def fplutil.buildutil.android.BuildEnvironment.install_all	(		self,
			path = '.',
			adb_device = None,
			exclude_dirs = None
	)

Locate and install all Android APKs.

This function recursively scans a directory tree for Android application projects and installs them on the specified device.

Parameters

path	Path to search the search in, defaults to '.'
adb_device	The serial of the device to install the APK to. If None the only device connected will be used.
exclude_dirs	List of directory names to exclude from project detection (see find_projects() for more information).

Returns

(retval, errmsg) tuple of an integer return value suitable for returning to the invoking shell, and an error string (if any) or None (on success).

def fplutil.buildutil.android.BuildEnvironment.install_android_apk	(		self,
			path = '.',
			adb_device = None,
			force_install = True
	)

Install an android apk on the given device.

This function will attempt to install an unsigned APK if a signed APK is not available which will only work on rooted devices.

Parameters

path	Relative path from project directory to project to run.
adb_device	The serial of the device to run the apk on. If None it will the only device connected will be used.
force_install	Whether to install the package if it's older than the package on the target device.

Exceptions

ConfigurationError	If no APKs are found.
AdbError	If it's not possible to install the APK.

def fplutil.buildutil.android.BuildEnvironment.list_installed_packages	(		self,
			adb_device = None
	)

Get the list of packages installed on an Android device.

Parameters

adb_device

The serial of the device to query.

Returns

List of package strings.

Exceptions

AdbError

If it's not possible to query the device.

def fplutil.buildutil.android.BuildEnvironment.ndk_location_changed (   project,   ndk_build_path  )

static

Determine whether the NDK install location changed.

Parameters

project	Path to the project directory being built with the NDK.
ndk_build_path	Path to the NDK.

Returns

True if the NDK was previously used to build the project and the NDK install location changed.

def fplutil.buildutil.android.BuildEnvironment.parse_delete_local_properties (   project_path,   build_xml_path,   sdk_location  )

static

Parse local properties and if the sdk location changed delete it.

This also deletes build.xml so the entire project is refreshed if the tools path changes.

Parameters

project_path	Path containing local.properties file.
sdk_location	Install location of the sdk.

def fplutil.buildutil.android.BuildEnvironment.parse_manifest	(		self,
			path = '.'
	)

Parse the project's manifest.

Parameters

path	Optional relative path from project directory to project to build.

Returns

AndroidManifest instance parsed from the project manifest.

Exceptions

ConfigurationError	Required elements were missing or incorrect.
MissingActivityError	If a main activity element isn't present.

def fplutil.buildutil.android.BuildEnvironment.run_all	(		self,
			path = '.',
			adb_device = None,
			exclude_dirs = None,
			wait = True,
			continue_on_failure = False,
			gtest = False
	)

Locate and run all Android APKs.

This function recursively scans a directory tree for Android application projects and runs them on the specified device.

Parameters

path	Path to search the search in, defaults to '.'
adb_device	The device to run the APK on. If none it will use the only device connected.
exclude_dirs	List of directory names to exclude from project detection (see find_projects() for more information).
wait	Whether to wait for the application to start.
continue_on_failure	Whether to continue trying to execute all projects if a failure occurs.
gtest	Whether the target is a googletest and the output should be scraped for test failures.

Returns

(retval, errmsg, failures) tuple of an integer return value suitable for returning to the invoking shell, an error string (if any) and a list of packages that failed to launch or None (on success).

def fplutil.buildutil.android.BuildEnvironment.run_android_apk	(		self,
			path = '.',
			adb_device = None,
			wait = True,
			end_match = None,
			echo_log = True,
			apk_missing_allowed = True
	)

Run an android apk on the given device.

Parameters

path	Relative path from project directory to project to run.
adb_device	The serial of the device to run the apk on. If None the only device connected will be used.
wait	Optional argument to tell the function to wait until the process completes and dump the output.
end_match	Optional compiled regex applied to logs. When a match is found, the process is considered finished (sets wait to False).
echo_log	If set, prints the output from logcat.
apk_missing_allowed	If set to False, raise an AdbError if the activity couldn't be started.

Returns

String containing adb logcat output for the run. None if there is a manifest configuration problem.

Exceptions

AdbError

If the activity wasn't started.

def fplutil.buildutil.android.BuildEnvironment.stop_process	(		self,
			package_name,
			adb_device = None
	)

Attempts to stop a process running under the given package name.

Parameters

package_name	Name of the package to stop.
adb_device	Serial of the device to stop the app on. If none specified, the only device connected will be used.

def fplutil.buildutil.android.BuildEnvironment.take_screencap	(		self,
			destination,
			adb_device = None
	)

Takes a screencap on the device and saves it to destination.

Saves the screencap to a random filename on the device's sdcard, transfers the screencap to destination path, then deletes the screencap on the device.

Parameters

destination	The file path where the screencap will be saved.
adb_device	Serial of the device to take the screencap with. If none specified, the only device connected will be used.

def fplutil.buildutil.android.BuildEnvironment.write_ndk_location (   project,   ndk_build_path  )

static

Stores the current NDK path to a file.

Parameters

project	Path to the project directory being built with the NDK.
ndk_build_path	Path to the NDK.

Member Data Documentation

fplutil.buildutil.android.BuildEnvironment.always_make

Whether to build when the project is already up to date.

fplutil.buildutil.android.BuildEnvironment.ant_flags

Flags to pass to the ant binary, if used.

fplutil.buildutil.android.BuildEnvironment.ant_path

Path to the ant binary, if found.

fplutil.buildutil.android.BuildEnvironment.ant_target

Ant build target name.

fplutil.buildutil.android.BuildEnvironment.apk_keyalias

Alias of key to use when signing an APK.

fplutil.buildutil.android.BuildEnvironment.apk_keystore

Keystore file path to use when signing an APK.

fplutil.buildutil.android.BuildEnvironment.ndk_home

Path to the Android NDK, if found.

fplutil.buildutil.android.BuildEnvironment.sdk_home

Path to the Android SDK, if found.

fplutil.buildutil.android.BuildEnvironment.sign_apk

Enable signing of Android APKs.

---

The documentation for this class was generated from the following file:

• android.py