[SuperSU] Frank Westlake:
Debug data collection

This is regarding the attachment. This particular file has been customized for use in collecting data related to SuperSU.

GENERAL

This archive (debug.2.2.zip) is a debugging tool for users of Android applications to assist the developers in debugging their applications. This tool can be used three ways:

1. The archive is installed (flashed) in Recovery immediately after installing an application.

2. The script "collect.cmd" is extracted and run on the Android device.

3. The script "collect.cmd" is extracted and run on a Linux or Windows computer which has the Android Debug Bridge program.

In alternatives 2 and 3 the script "collect.cmd" is a Linux shell, Windows CMD, and Android shell script. For Linux and Android, "collect.cmd" nay be renamed to remove the ".cmd" extension but this is not necessary.

All three methods will collect data (including 'logcat') and save that data to the directory that the archive or extracted script is in. The file will be either a ZIP or a tape archive with a name having the form "debug-[model]-[version]-[timestamp].[zip|tar]"; for example "debug-SM-N900T-4.3-20141109T0706.zip". If the ZIP program is available then a ZIP archive will be created, otherwise a tape archive is created.

MINIMAL INSTRUCTIONS

When installing a beta version application through Recovery, first install that application, then without rebooting install this debug archive. If there are problems with the application then send the resulting data archive created by installing the debug archive to the developer of the troublesome application. If there are no problems to report then delete the data archive.

If an application is forced closed while running Android then extract the script "collect.cmd" from the debug archive onto a Linux or Windows computer which has a functional Android Debug Bridge application and run the script while the Android device is connected to that computer. The data archive will be created on the computer in the same directory that the script exists in. Send this data archive to the developer of the troublesome application.

If an application is forced closed as in the preceding paragraph but a Windows or Linux computer is not available for Android Debug Bridge usage then extract the script "collect.cmd" from the debug archive onto the Android device and run the script on the Android device. The data archive will be created on the Android device in the same directory that the script exists in. Send this data archive to the developer of the troublesome application.

DEVELOPERS

This debug system has been created so that it can be used as a general tool to collect standard data or it can be easily customized for your application's needs. Without customization the debug scripts try to collect the following:

- the environment (set > environment.txt).

- the logcat (logcat -d >logcat-all.txt).

- the build properties (cat /system/build.prop > build.prop).

- the Recovery log (cp /tmp/recovery.log OR /cache/recovery/last_log > recovery.log)

The debug archive contains a file named 'plan' for use when the debug archive is installed in Recovery, and the script "collect.cmd" contains a variable named 'plan' at the top of the script for use when that script is run on the device or from across the Debug Bridge.

The plan is a list of lines, each line divided left and right by the characters '>>'. The left side of the '>>' is the command to run and the right side is the name of the file to redirect output to (stdout and stderr). Output is always appended (>>) so you may use the same file for multiple comands.

When installed through Recovery you may also add your own programs to run. Copy them to the root of the archive and invoke them in 'plan' from the directory "/$my". For example, here's a short plan showing the collection of logcat with a filter and a custom script run from the archive root:

logcat -d|grep -E 'supersu|installer|/dev/log/main' >> logcat.txt

sh $my/custom.sh >> custom.txt

The script "custom.sh" would have first been placed in the srchive's root directory.

Frank