From 1afb2d5335b4a27866d89e3529664dd5345ac8dd Mon Sep 17 00:00:00 2001 From: Luan Nguyen Date: Fri, 16 Jan 2015 08:21:57 -0800 Subject: docs: Pare down the adb guide and remove sections that are duplicated in the tools list. bug: 12879186 Change-Id: Ic2d17ef29eac15a9ffc40e05b056dc17d71069e8 --- docs/html/about/versions/android-4.3.jd | 2 +- docs/html/guide/components/intents-common.jd | 2 +- docs/html/tools/help/adb.jd | 963 +-------------------- docs/html/tools/help/index.jd | 9 +- docs/html/tools/help/shell.jd | 898 +++++++++++++++++++ docs/html/tools/tools_toc.cs | 8 +- docs/html/training/enterprise/app-compatibility.jd | 8 +- 7 files changed, 922 insertions(+), 968 deletions(-) create mode 100644 docs/html/tools/help/shell.jd (limited to 'docs') diff --git a/docs/html/about/versions/android-4.3.jd b/docs/html/about/versions/android-4.3.jd index e18c285..2496854 100644 --- a/docs/html/about/versions/android-4.3.jd +++ b/docs/html/about/versions/android-4.3.jd @@ -1029,7 +1029,7 @@ APIs allow you to inspect the screen content and inject arbitrary keyboard and t android.app.Instrumentation#getUiAutomation Instrumentation.getUiAutomation()}. In order for this to work, you must supply the {@code -w} option with the {@code instrument} command when running your {@link android.test.InstrumentationTestCase} from {@code adb shell}.

+href="{@docRoot}tools/help/shell.html#am">{@code adb shell}.

With the {@link android.app.UiAutomation} instance, you can execute arbitrary events to test your app by calling {@link android.app.UiAutomation#executeAndWaitForEvent diff --git a/docs/html/guide/components/intents-common.jd b/docs/html/guide/components/intents-common.jd index 964f075..dbc14fa 100644 --- a/docs/html/guide/components/intents-common.jd +++ b/docs/html/guide/components/intents-common.jd @@ -2236,7 +2236,7 @@ adb shell am start -a android.intent.action.DIAL \

For more information, see -Using activity manager (am).

+ADB Shell Commands.

diff --git a/docs/html/tools/help/adb.jd b/docs/html/tools/help/adb.jd index 41c6686..641d463 100644 --- a/docs/html/tools/help/adb.jd +++ b/docs/html/tools/help/adb.jd @@ -16,18 +16,7 @@ page.tags=adb
  • Installing an Application
  • Forwarding Ports
  • Copying Files to or from an Emulator/Device Instance
    • -
  • Issuing Shell Commands -
      -
    1. Using activity manager (am)
      2. -
    2. Using package manager (pm)
      3. -
    3. Examining sqlite3 databases from a remote shell
      4. -
    4. Recording a device screen
      5. -
    5. UI/Application Exerciser Monkey
      6. -
    6. Other shell commands
      7. -
    -
    • -
  • Enabling logcat logging
    • -
  • Stopping the adb server
    • +
  • Stopping the adb Server
  • Wireless usage
    • @@ -279,7 +268,7 @@ would issue the install command as soon as the emulator or device i Shell shell Starts a remote shell in the target emulator/device instance. -See Issuing Shell Commands for more information. +See ADB Shell Commands for more information. @@ -412,950 +401,10 @@ emulator/device instance (remote). For example:

    +

    Stopping the adb Server

    - - - - -

    Issuing Shell Commands

    - -

    Adb provides a Unix shell that you can use to run a variety of commands on an emulator -or connected device. The command binaries are stored in the file system of the emulator or device, -at /system/bin/... - -

    Two of the most common command tools are activity manager ({@code am}) and -package manager ({@code pm}).

    - -

    You can use the shell command to issue commands, with or without entering -the adb remote shell on the emulator/device. To issue a single command without entering a -remote shell, use the shell command like this:

    - - 
    adb [-d|-e|-s <serialNumber>] shell <shell_command>
    - -

    Or enter a remote shell on an emulator/device like this:

    - - 
    adb [-d|-e|-s <serialNumber>] shell
    - -

    When you are ready to exit the remote shell, press CTRL+D or type -exit.

    - - - - - -

    Using activity manager (am)

    - -

    Within an adb shell, you can issue commands with the activity manager ({@code am}) tool to -perform various system actions, such as start an activity, force-stop a process, -broadcast an intent, modify the device screen properties, and more. While in a shell, -the syntax is:

    -
    -am <command>
-
    - -

    You can also issue an activity manager command directly from adb -without entering a remote shell. For example:

    -
    -adb shell am start -a android.intent.action.VIEW
-
    - - -

    Table 2. Available activity manager commands

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    CommandDescription
    -start [options] <INTENT> -Start an {@link android.app.Activity} specified by {@code <INTENT>}.

    See the -Specification for <INTENT> arguments. -

    Options are: -

      -
    • {@code -D}: Enable debugging. -
    • {@code -W}: Wait for launch to complete. -
    • {@code --start-profiler <FILE>}: Start profiler and send results to {@code <FILE>}. -
    • {@code -P <FILE>}: Like --start-profiler, - but profiling stops when the app goes idle. -
    • {@code -R}: Repeat the activity launch {@code <COUNT>} times. Prior to each repeat, - the top activity will be finished. -
    • {@code -S}: Force stop the target app before starting the activity. -
    • {@code --opengl-trace}: Enable tracing of OpenGL functions. -
    • {@code --user <USER_ID> | current}: Specify which user to run as; if not - specified, then run as the current user. -
    -
    -startservice [options] <INTENT> -Start the {@link android.app.Service} specified by {@code <INTENT>}.

    See the -Specification for <INTENT> arguments. -

    Options are: -

      -
    • {@code --user <USER_ID> | current}: Specify which user to run as; if not - specified, then run as the current user. -
    -
    -force-stop <PACKAGE> -Force stop everything associated with {@code <PACKAGE>} (the app's package name). -
    -kill [options] <PACKAGE> - Kill all processes associated with {@code <PACKAGE>} - (the app's package name). This command kills only - processes that are safe to kill and that will not impact the user - experience. -

    Options are: -

      -
    • {@code --user <USER_ID> | all | current}: Specify user whose processes to kill; - all users if not specified. -
    -
    -kill-all -Kill all background processes. -
    -broadcast [options] <INTENT> -Issue a broadcast intent.

    See the -Specification for <INTENT> arguments. -

    Options are: -

      -
    • {@code [--user <USER_ID> | all | current]}: Specify which user to send to; if not - specified then send to all users. -
    -
    -instrument [options] <COMPONENT> -Start monitoring with an {@link android.app.Instrumentation} instance. - Typically the target {@code <COMPONENT>} - is the form {@code <TEST_PACKAGE>/<RUNNER_CLASS>}.

    Options are: -

      -
    • {@code -r}: Print raw results (otherwise decode - {@code <REPORT_KEY_STREAMRESULT>}). Use with - {@code [-e perf true]} to generate raw output for performance measurements. - -
    • {@code -e <NAME> <VALUE>}: Set argument {@code <NAME>} to {@code <VALUE>}. - For test runners a common form is {@code - -e <testrunner_flag> <value>[,<value>...]}. - -
    • {@code -p <FILE>}: Write profiling data to {@code <FILE>}. - -
    • {@code -w}: Wait for instrumentation to finish before returning. Required for - test runners. - -
    • {@code --no-window-animation}: Turn off window animations while running. -
    • {@code --user <USER_ID> | current}: Specify which user instrumentation runs in; - current user if not specified. -
    - -
    -profile start <PROCESS> <FILE> -Start profiler on {@code <PROCESS>}, write results to {@code <FILE>}. -
    -profile stop <PROCESS> -Stop profiler on {@code <PROCESS>}. -
    -dumpheap [options] <PROCESS> <FILE> -Dump the heap of {@code <PROCESS>}, write to {@code <FILE>}.

    Options are: -

      -
    • {@code --user [<USER_ID>|current]}: When supplying a process name, - specify user of process to dump; uses current user if not specified. -
    • {@code -n}: Dump native heap instead of managed heap. -
    -
    -set-debug-app [options] <PACKAGE> -Set application {@code <PACKAGE>} to debug.

    Options are: -

      -
    • {@code -w}: Wait for debugger when application starts. -
    • {@code --persistent}: Retain this value. -
    -
    -clear-debug-app -Clear the package previous set for debugging with {@code set-debug-app}. -
    -monitor [options] -Start monitoring for crashes or ANRs.

    Options are: -

      -
    • {@code --gdb}: Start gdbserv on the given port at crash/ANR. -
    -
    -screen-compat [on|off] <PACKAGE> -Control screen -compatibility mode of {@code <PACKAGE>}.

    -
    -display-size [reset|<WxH>] -Override emulator/device display size. -This command is helpful for testing your app across different screen sizes by mimicking a small -screen resolution using a device with a large screen, and vice versa. -

    Example:
    am display-size 1280x800 -

    -display-density <dpi> -Override emulator/device display density. -This command is helpful for testing your app across different screen densities on high-density -screen environment using a low density screen, and vice versa. -

    Example:
    am display-density 480 -

    -to-uri <INTENT> -Print the given intent specification as a URI.

    See the -Specification for <INTENT> arguments. -

    -to-intent-uri <INTENT> -Print the given intent specification as an {@code intent:} URI.

    See the -Specification for <INTENT> arguments. -

    - - - - - -

    -

    - - - - - - -

    Using package manager (pm)

    - -

    Within an adb shell, you can issue commands with the package manager ({@code pm}) tool to -perform actions and queries on application packages installed on the device. While in a shell, -the syntax is:

    -
    -pm <command>
-
    - -

    You can also issue a package manager command directly from adb -without entering a remote shell. For example:

    -
    -adb shell pm uninstall com.example.MyApp
-
    - -

    Table 3. Available package manager commands.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    CommandDescription
    -list packages [options] <FILTER> -Prints all packages, optionally only - those whose package name contains the text in {@code <FILTER>}.

    Options: -

      -
    • {@code -f}: See their associated file. -
    • {@code -d}: Filter to only show disabled packages. -
    • {@code -e}: Filter to only show enabled packages. -
    • {@code -s}: Filter to only show system packages. -
    • {@code -3}: Filter to only show third party packages. -
    • {@code -i}: See the installer for the packages. -
    • {@code -u}: Also include uninstalled packages. -
    • {@code --user <USER_ID>}: The user space to query. -
    -
    -list permission-groups -Prints all known permission groups. -
    -list permissions [options] <GROUP> -Prints all known permissions, optionally only - those in {@code <GROUP>}.

    Options: -

      -
    • {@code -g}: Organize by group. -
    • {@code -f}: Print all information. -
    • {@code -s}: Short summary. -
    • {@code -d}: Only list dangerous permissions. -
    • {@code -u}: List only the permissions users will see. -
    -
    -list instrumentation -List all test packages.

    Options: -

      -
    • {@code -f}: List the APK file for the test package. -
    • {@code <TARGET_PACKAGE>}: List test packages for only this app. -
    -
    -list features -Prints all features of the system. -
    -list libraries -Prints all the libraries supported by the current device. -
    -list users -Prints all users on the system. -
    -path <PACKAGE> -Print the path to the APK of the given {@code <PACKAGE>}. -
    -install [options] <PATH> -Installs a package (specified by {@code <PATH>}) to the system.

    Options: -

      -
    • {@code -r}: Reinstall an exisiting app, keeping its data. -
    • {@code -t}: Allow test APKs to be installed. -
    • {@code -i <INSTALLER_PACKAGE_NAME>}: Specify the installer package name. -
    • {@code -s}: Install package on the shared mass storage (such as sdcard). -
    • {@code -f}: Install package on the internal system memory. -
    • {@code -d}: Allow version code downgrade. -
    -
    -uninstall [options] <PACKAGE> -Removes a package from the system.

    Options: -

      -
    • {@code -k}: Keep the data and cache directories around after package removal. -
    -
    -clear <PACKAGE> -Deletes all data associated with a package. -
    -enable <PACKAGE_OR_COMPONENT> -Enable the given package or component (written as "package/class"). -
    -disable <PACKAGE_OR_COMPONENT> -Disable the given package or component (written as "package/class"). -
    -disable-user [options] <PACKAGE_OR_COMPONENT> -

    Options: -

      -
    • {@code --user <USER_ID>}: The user to disable. -
    -
    -grant <PACKAGE_PERMISSION> -Grant permissions - to applications. Only optional permissions the application has - declared can be granted. -
    -revoke <PACKAGE_PERMISSION> -Revoke permissions - to applications. Only optional permissions the application has - declared can be revoked. -
    -set-install-location <LOCATION> -Changes the default install location. Location values: -
      -
    • {@code 0}: Auto—Let system decide the best location. -
    • {@code 1}: Internal—install on internal device storage. -
    • {@code 2}: External—install on external media. -
    -

    Note: This is only intended for debugging; using this can cause - applications to break and other undesireable behavior.

    -
    -get-install-location -Returns the current install location. Return values: -
      -
    • {@code 0 [auto]}: Lets system decide the best location -
    • {@code 1 [internal]}: Installs on internal device storage -
    • {@code 2 [external]}: Installs on external media -
    -
    -set-permission-enforced <PERMISSION> [true|false] -Specifies whether the given permission should be enforced. -
    -trim-caches <DESIRED_FREE_SPACE> -Trim cache files to reach the given free space. -
    -create-user <USER_NAME> -Create a new user with the given {@code <USER_NAME>}, - printing the new user identifier of the user. -
    -remove-user <USER_ID> -Remove the user with the given {@code <USER_IDENTIFIER>}, - deleting all data associated with that user -
    -get-max-users -Prints the maximum number of users supported by the device. -
    - - - - - - - -

    Examining sqlite3 databases from a remote shell

    - -

    From an adb remote shell, you can use the -sqlite3 command-line program to -manage SQLite databases created by Android applications. The -sqlite3 tool includes many useful commands, such as -.dump to print out the contents of a table and -.schema to print the SQL CREATE statement for an existing table. -The tool also gives you the ability to execute SQLite commands on the fly.

    - -

    To use sqlite3, enter a remote shell on the emulator instance, as described above, -then invoke the tool using the sqlite3 command. Optionally, when invoking -sqlite3 you can specify the full path to the database you want to explore. -Emulator/device instances store SQLite3 databases in the folder -/data/data/<package_name>/databases/.

    - -

    Here's an example:

    - -
    adb -s emulator-5554 shell
-# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
-SQLite version 3.3.12
-Enter ".help" for instructions
-.... enter commands, then quit...
-sqlite> .exit
    - -

    Once you've invoked sqlite3, you can issue sqlite3 commands in the -shell. To exit and return to the adb remote shell, use exit or CTRL+D. - - - - -

    Recording a device screen

    - -

    The {@code screenrecord} command is a shell utility for recording the display of devices - running Android 4.4 (API level 19) and higher. The utility records screen activity to an MPEG-4 - file, which you can then download and use as part of a video presentation. This utility is useful - for developers who want to create promotional or training videos without using a separate - recording device.

    - -

    To use the {@code screenrecord} from the command line, type the following: - -

    -$ adb shell screenrecord /sdcard/demo.mp4
-
    - -

    Stop the screen recording by pressing Ctrl-C, otherwise the recording stops automatically -at three minutes or the time limit set by {@code --time-limit}.

    - -

    Here's an example recording session, using the adb shell to record the video and the -{@code pull} command to download the file from the device:

    - -

    -$ adb shell
-shell@ $ screenrecord --verbose /sdcard/demo.mp4
-(press Ctrl-C to stop)
-shell@ $ exit
-$ adb pull /sdcard/demo.mp4
-
    - -

    The {@code screenrecord} utility can record at any supported resolution and bit rate you - request, while retaining the aspect ratio of the device display. The utility records at the native - display resolution and orientation by default, with a maximum length of three minutes.

    - -

    There are some known limitations of the {@code screenrecord} utility that you should be aware - of when using it:

    - - - - -

    Table 4. {@code screenrecord} options

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    OptionsDescription
    --help - Displays a usage summary.
    - --size <WIDTHxHEIGHT> - Sets the video size, for example: {@code 1280x720}. The default value is the device's main - display resolution (if supported), 1280x720 if not. For best results, use a size supported - by your device's Advanced Video Coding (AVC) encoder.
    --bit-rate <RATE>Sets the video bit rate for the video, in megabits per second. The default value is 4Mbps. - You can increase the bit rate to improve video quality or lower it for smaller movie - files. The following example sets the recording bit rate to 6Mbps: - 
    screenrecord --bit-rate 6000000 /sdcard/demo.mp4
    -
    --time-limit <TIME>Sets the maximum recording time, in seconds. The default and maximum value is 180 - (3 minutes).
    --rotateRotates the output 90 degrees. This feature is experimental.
    --verboseDisplays log information on command line screen. If you do not set this option, - the utility does not display any information while running.
    - - - - -

    UI/Application Exerciser Monkey

    - -

    The Monkey is a program that runs on your emulator or device and generates pseudo-random -streams of user events such as clicks, touches, or gestures, as well as a number of system-level -events. You can use the Monkey to stress-test applications that you are developing, -in a random yet repeatable manner.

    - -

    The simplest way to use the monkey is with the following command, which launches your -application and sends 500 pseudo-random events to it.

    - -
    adb shell monkey -v -p your.package.name 500
    - -

    For more information about command options for Monkey, see the complete -UI/Application Exerciser Monkey documentation page.

    - - - - - -

    Other shell commands

    - -

    For a list of all the available shell programs, use the following command:

    - -
    adb shell ls /system/bin
    - -

    Help is available for most of the commands.

    - -

    Table 5 lists some of the more common adb shell commands.

    - -

    Table 5. Some other adb shell commands

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Shell CommandDescriptionComments
    dumpsysDumps system data to the screen.The Dalvik Debug Monitor Server -(DDMS) tool offers integrated debug environment that you may find easier to use.
    dumpstateDumps state to a file.
    logcat [option]... [filter-spec]...Enables system and app logging and prints output to the screen.
    dmesgPrints kernel debugging messages to the screen.
    startStarts (restarts) an emulator/device instance. 
    stopStops execution of an emulator/device instance. 
    - - - - - - - - - - - - - - -

    Enabling logcat logging

    - -

    The Android logging system provides a mechanism for collecting and viewing system debug output. Logs from various applications and portions of the system are collected in a series of circular buffers, which then can be viewed and filtered by the logcat command.

    - -

    You can use the logcat command to view and follow the contents of the system's log buffers. The general usage is:

    - -
    [adb] logcat [option] ... [filter-spec] ...
    - -

    You can use the logcat command from your development computer or from a remote adb shell in an emulator/device instance. To view log output in your development computer, you use

    - -
    adb logcat
    - -

    and from a remote adb shell you use

    - -
    logcat
    - -

    See Reading and Writing Logs for complete information about logcat commend options and filter specifications.

    - - - - - -

    Stopping the adb server

    - -

    In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not respond to a command, you can terminate the server and restart it and that may resolve the problem.

    +

    In some cases, you might need to terminate the adb server process and then restart it +to resolve the problem (e.g., if adb does not respond to a command).

    To stop the adb server, use the kill-server command. You can then restart the server by issuing any other adb command.

    @@ -1457,4 +506,4 @@ adb kill-server and then start over from the beginning. - + \ No newline at end of file diff --git a/docs/html/tools/help/index.jd b/docs/html/tools/help/index.jd index 4c97d0c..f90d029 100644 --- a/docs/html/tools/help/index.jd +++ b/docs/html/tools/help/index.jd @@ -68,7 +68,10 @@ avd) the emulator (emulator), and the Dalvik Debug Monitor S
    adb
    Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with an emulator instance or connected Android-powered device. It also provides access to the - device shell for advanced command-line operations.
    + device shell. + +
    ADB Shell Commands
    +
    Learn the commands available for advanced command-line operations.
    Dalvik Debug Monitor Server (ddms)
    @@ -109,11 +112,9 @@ you can view the file in a profiling tool of your choice.
    JOBB
    Allows you to build encrypted and unencrypted - APK expansion files in Opaque + APK expansion files in Opaque Binary Blob (OBB) format.
    -APK expansion files -
    ProGuard
    Shrinks, optimizes, and obfuscates your code by removing unused code and renaming classes, fields, and methods with semantically obscure names.
    diff --git a/docs/html/tools/help/shell.jd b/docs/html/tools/help/shell.jd new file mode 100644 index 0000000..417c871 --- /dev/null +++ b/docs/html/tools/help/shell.jd @@ -0,0 +1,898 @@ +page.title=ADB Shell Commands +parent.title=Tools +parent.link=index.html +page.tags=shell,adb,am,pm,screenrecord,screencap +@jd:body + +
    + +
    + +

    The Android Debug Bridge (adb) provides a Unix shell +that you can use to run a variety of commands on an emulator or connected device. The command +binaries are stored in the file system of the emulator or device, at /system/bin/... +

    + +

    Issuing Shell Commands

    + +

    You can use the shell command to issue commands, with or without entering +the adb remote shell on the emulator/device. To issue a single command without entering a +remote shell, use the shell command like this:

    + + 
    adb [-d|-e|-s <serialNumber>] shell <shell_command>
    + +

    Or enter a remote shell on an emulator/device like this:

    + + 
    adb [-d|-e|-s <serialNumber>] shell
    + +

    When you are ready to exit the remote shell, press CTRL+D or type +exit.

    + + + + + +

    Using activity manager (am)

    + +

    Within an adb shell, you can issue commands with the activity manager ({@code am}) tool to +perform various system actions, such as start an activity, force-stop a process, +broadcast an intent, modify the device screen properties, and more. While in a shell, +the syntax is:

    +
    +am <command>
+
    + +

    You can also issue an activity manager command directly from adb +without entering a remote shell. For example:

    +
    +adb shell am start -a android.intent.action.VIEW
+
    + + +

    Table 2. Available activity manager commands

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CommandDescription
    +start [options] <INTENT> +Start an {@link android.app.Activity} specified by {@code <INTENT>}.

    See the +Specification for <INTENT> arguments. +

    Options are: +

      +
    • {@code -D}: Enable debugging. +
    • {@code -W}: Wait for launch to complete. +
    • {@code --start-profiler <FILE>}: Start profiler and send results to {@code <FILE>}. +
    • {@code -P <FILE>}: Like --start-profiler, + but profiling stops when the app goes idle. +
    • {@code -R}: Repeat the activity launch {@code <COUNT>} times. Prior to each repeat, + the top activity will be finished. +
    • {@code -S}: Force stop the target app before starting the activity. +
    • {@code --opengl-trace}: Enable tracing of OpenGL functions. +
    • {@code --user <USER_ID> | current}: Specify which user to run as; if not + specified, then run as the current user. +
    +
    +startservice [options] <INTENT> +Start the {@link android.app.Service} specified by {@code <INTENT>}.

    See the +Specification for <INTENT> arguments. +

    Options are: +

      +
    • {@code --user <USER_ID> | current}: Specify which user to run as; if not + specified, then run as the current user. +
    +
    +force-stop <PACKAGE> +Force stop everything associated with {@code <PACKAGE>} (the app's package name). +
    +kill [options] <PACKAGE> + Kill all processes associated with {@code <PACKAGE>} + (the app's package name). This command kills only + processes that are safe to kill and that will not impact the user + experience. +

    Options are: +

      +
    • {@code --user <USER_ID> | all | current}: Specify user whose processes to kill; + all users if not specified. +
    +
    +kill-all +Kill all background processes. +
    +broadcast [options] <INTENT> +Issue a broadcast intent.

    See the +Specification for <INTENT> arguments. +

    Options are: +

      +
    • {@code [--user <USER_ID> | all | current]}: Specify which user to send to; if not + specified then send to all users. +
    +
    +instrument [options] <COMPONENT> +Start monitoring with an {@link android.app.Instrumentation} instance. + Typically the target {@code <COMPONENT>} + is the form {@code <TEST_PACKAGE>/<RUNNER_CLASS>}.

    Options are: +

      +
    • {@code -r}: Print raw results (otherwise decode + {@code <REPORT_KEY_STREAMRESULT>}). Use with + {@code [-e perf true]} to generate raw output for performance measurements. + +
    • {@code -e <NAME> <VALUE>}: Set argument {@code <NAME>} to {@code <VALUE>}. + For test runners a common form is {@code + -e <testrunner_flag> <value>[,<value>...]}. + +
    • {@code -p <FILE>}: Write profiling data to {@code <FILE>}. + +
    • {@code -w}: Wait for instrumentation to finish before returning. Required for + test runners. + +
    • {@code --no-window-animation}: Turn off window animations while running. +
    • {@code --user <USER_ID> | current}: Specify which user instrumentation runs in; + current user if not specified. +
    + +
    +profile start <PROCESS> <FILE> +Start profiler on {@code <PROCESS>}, write results to {@code <FILE>}. +
    +profile stop <PROCESS> +Stop profiler on {@code <PROCESS>}. +
    +dumpheap [options] <PROCESS> <FILE> +Dump the heap of {@code <PROCESS>}, write to {@code <FILE>}.

    Options are: +

      +
    • {@code --user [<USER_ID>|current]}: When supplying a process name, + specify user of process to dump; uses current user if not specified. +
    • {@code -n}: Dump native heap instead of managed heap. +
    +
    +set-debug-app [options] <PACKAGE> +Set application {@code <PACKAGE>} to debug.

    Options are: +

      +
    • {@code -w}: Wait for debugger when application starts. +
    • {@code --persistent}: Retain this value. +
    +
    +clear-debug-app +Clear the package previous set for debugging with {@code set-debug-app}. +
    +monitor [options] +Start monitoring for crashes or ANRs.

    Options are: +

      +
    • {@code --gdb}: Start gdbserv on the given port at crash/ANR. +
    +
    +screen-compat [on|off] <PACKAGE> +Control screen +compatibility mode of {@code <PACKAGE>}.

    +
    +display-size [reset|<WxH>] +Override emulator/device display size. +This command is helpful for testing your app across different screen sizes by mimicking a small +screen resolution using a device with a large screen, and vice versa. +

    Example:
    am display-size 1280x800 +

    +display-density <dpi> +Override emulator/device display density. +This command is helpful for testing your app across different screen densities on high-density +screen environment using a low density screen, and vice versa. +

    Example:
    am display-density 480 +

    +to-uri <INTENT> +Print the given intent specification as a URI.

    See the +Specification for <INTENT> arguments. +

    +to-intent-uri <INTENT> +Print the given intent specification as an {@code intent:} URI.

    See the +Specification for <INTENT> arguments. +

    + + + + + +

    +

    + + + + + + +

    Using package manager (pm)

    + +

    Within an adb shell, you can issue commands with the package manager ({@code pm}) tool to +perform actions and queries on application packages installed on the device. While in a shell, +the syntax is:

    +
    +pm <command>
+
    + +

    You can also issue a package manager command directly from adb +without entering a remote shell. For example:

    +
    +adb shell pm uninstall com.example.MyApp
+
    + +

    Table 3. Available package manager commands.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CommandDescription
    +list packages [options] <FILTER> +Prints all packages, optionally only + those whose package name contains the text in {@code <FILTER>}.

    Options: +

      +
    • {@code -f}: See their associated file. +
    • {@code -d}: Filter to only show disabled packages. +
    • {@code -e}: Filter to only show enabled packages. +
    • {@code -s}: Filter to only show system packages. +
    • {@code -3}: Filter to only show third party packages. +
    • {@code -i}: See the installer for the packages. +
    • {@code -u}: Also include uninstalled packages. +
    • {@code --user <USER_ID>}: The user space to query. +
    +
    +list permission-groups +Prints all known permission groups. +
    +list permissions [options] <GROUP> +Prints all known permissions, optionally only + those in {@code <GROUP>}.

    Options: +

      +
    • {@code -g}: Organize by group. +
    • {@code -f}: Print all information. +
    • {@code -s}: Short summary. +
    • {@code -d}: Only list dangerous permissions. +
    • {@code -u}: List only the permissions users will see. +
    +
    +list instrumentation +List all test packages.

    Options: +

      +
    • {@code -f}: List the APK file for the test package. +
    • {@code <TARGET_PACKAGE>}: List test packages for only this app. +
    +
    +list features +Prints all features of the system. +
    +list libraries +Prints all the libraries supported by the current device. +
    +list users +Prints all users on the system. +
    +path <PACKAGE> +Print the path to the APK of the given {@code <PACKAGE>}. +
    +install [options] <PATH> +Installs a package (specified by {@code <PATH>}) to the system.

    Options: +

      +
    • {@code -l}: Install the package with forward lock. +
    • {@code -r}: Reinstall an exisiting app, keeping its data. +
    • {@code -t}: Allow test APKs to be installed. +
    • {@code -i <INSTALLER_PACKAGE_NAME>}: Specify the installer package name. +
    • {@code -s}: Install package on the shared mass storage (such as sdcard). +
    • {@code -f}: Install package on the internal system memory. +
    • {@code -d}: Allow version code downgrade. +
    +
    +uninstall [options] <PACKAGE> +Removes a package from the system.

    Options: +

      +
    • {@code -k}: Keep the data and cache directories around after package removal. +
    +
    +clear <PACKAGE> +Deletes all data associated with a package. +
    +enable <PACKAGE_OR_COMPONENT> +Enable the given package or component (written as "package/class"). +
    +disable <PACKAGE_OR_COMPONENT> +Disable the given package or component (written as "package/class"). +
    +disable-user [options] <PACKAGE_OR_COMPONENT> +

    Options: +

      +
    • {@code --user <USER_ID>}: The user to disable. +
    +
    +grant <PACKAGE_PERMISSION> +Grant permissions + to applications. Only optional permissions the application has + declared can be granted. +
    +revoke <PACKAGE_PERMISSION> +Revoke permissions + to applications. Only optional permissions the application has + declared can be revoked. +
    +set-install-location <LOCATION> +Changes the default install location. Location values: +
      +
    • {@code 0}: Auto—Let system decide the best location. +
    • {@code 1}: Internal—install on internal device storage. +
    • {@code 2}: External—install on external media. +
    +

    Note: This is only intended for debugging; using this can cause + applications to break and other undesireable behavior.

    +
    +get-install-location +Returns the current install location. Return values: +
      +
    • {@code 0 [auto]}: Lets system decide the best location +
    • {@code 1 [internal]}: Installs on internal device storage +
    • {@code 2 [external]}: Installs on external media +
    +
    +set-permission-enforced <PERMISSION> [true|false] +Specifies whether the given permission should be enforced. +
    +trim-caches <DESIRED_FREE_SPACE> +Trim cache files to reach the given free space. +
    +create-user <USER_NAME> +Create a new user with the given {@code <USER_NAME>}, + printing the new user identifier of the user. +
    +remove-user <USER_ID> +Remove the user with the given {@code <USER_IDENTIFIER>}, + deleting all data associated with that user +
    +get-max-users +Prints the maximum number of users supported by the device. +
    + + +

    Taking a device screenshot

    + +

    The {@code screencap} command is a shell utility for taking a screenshot of a device display. +While in a shell, the syntax is: +

    + +
    +screencap <filename>
+
    + + +

    To use the {@code screencap} from the command line, type the following: + +

    +$ adb shell screencap /sdcard/screen.png
+
    + +

    Here's an example screenshot session, using the adb shell to capture the screenshot and the +{@code pull} command to download the file from the device:

    + +

    +$ adb shell
+shell@ $ screencap /sdcard/screen.png
+shell@ $ exit
+$ adb pull /sdcard/screen.png
+
    + + +

    Recording a device screen

    + +

    The {@code screenrecord} command is a shell utility for recording the display of devices + running Android 4.4 (API level 19) and higher. The utility records screen activity to an MPEG-4 + file.

    + +

    Note: Audio is not recorded with the video file.

    + +

    A developer can use this file to create promotional or training videos. While in a shell, the syntax is:

    + +
    +screenrecord [options] <filename>
+
    + +

    To use {@code screenrecord} from the command line, type the following: + +

    +$ adb shell screenrecord /sdcard/demo.mp4
+
    + +

    Stop the screen recording by pressing Ctrl-C, otherwise the recording stops automatically +at three minutes or the time limit set by {@code --time-limit}.

    + +

    To begin recording your device screen, run the {@code screenrecord} command to record +the video. Then, run the {@code pull} command to download the video from the device to the host +computer. Here's an example recording session:

    + +

    +$ adb shell
+shell@ $ screenrecord --verbose /sdcard/demo.mp4
+(press Ctrl-C to stop)
+shell@ $ exit
+$ adb pull /sdcard/demo.mp4
+
    + +

    The {@code screenrecord} utility can record at any supported resolution and bit rate you + request, while retaining the aspect ratio of the device display. The utility records at the native + display resolution and orientation by default, with a maximum length of three minutes.

    + +

    There are some known limitations of the {@code screenrecord} utility that you should be aware + of when using it:

    + + + + +

    Table 4. {@code screenrecord} options

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OptionsDescription
    --help + Displays command syntax and options
    + --size <WIDTHxHEIGHT> + Sets the video size: {@code 1280x720}. The default value is the device's native + display resolution (if supported), 1280x720 if not. For best results, use a size supported + by your device's Advanced Video Coding (AVC) encoder.
    --bit-rate <RATE>Sets the video bit rate for the video, in megabits per second. The default value is 4Mbps. + You can increase the bit rate to improve video quality, but doing so results in larger movie + files. The following example sets the recording bit rate to 6Mbps: + 
    screenrecord --bit-rate 6000000 /sdcard/demo.mp4
    +
    --time-limit <TIME>Sets the maximum recording time, in seconds. The default and maximum value is 180 + (3 minutes).
    --rotateRotates the output 90 degrees. This feature is experimental.
    --verboseDisplays log information on the command-line screen. If you do not set this option, + the utility does not display any information while running.
    + + +

    Other shell commands

    + +

    For a list of all the available shell programs, use the following command:

    + +
    adb shell ls /system/bin
    + +

    Help is available for most of the commands.

    + +

    Table 5 lists some of the more common adb shell commands.

    + +

    Table 5. Some other adb shell commands

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Shell CommandDescriptionComments
    dumpsysDumps system data to the screen.The Dalvik Debug Monitor Server +(DDMS) tool offers integrated debug environment that you may find easier to use.
    dumpstateDumps state to a file.
    logcat [option]... [filter-spec]...Enables system and app logging and prints output to the screen.
    dmesgPrints kernel debugging messages to the screen.
    startStarts (restarts) an emulator/device instance. 
    stopStops execution of an emulator/device instance. 
    \ No newline at end of file diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 9ba7a22..6ba8fa4 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -150,7 +150,12 @@
    Tools Help
    -- cgit v1.1