Sometimes your application's layout can slow down your application.
To help debug issues in your layout, the Android SDK provides the Hierarchy Viewer and
- layoutopt tools.
+ lint tools.
The Hierarchy Viewer application allows you to debug and optimize your user interface. It provides a visual representation of the layout's View hierarchy (the View Hierarchy window) and a magnified view of the display (the Pixel Perfect window).
-layoutopt is a command-line tool that helps you optimize the layouts and layout
- hierarchies of your applications. You can run it against your layout files or resource
+
Android lint is a static code scanning tool that helps you optimize the layouts and layout
+ hierarchies of your applications, as well as detect other common coding problems. You can run it against your layout files or resource
directories to quickly check for inefficiencies or other types of problems that could be
affecting the performance of your application.
Figure 4. The Pixel Perfect window
-Using layoutopt
-
- The layoutopt tool lets you analyze the XML files that define your
- application's UI to find inefficiencies in the view hierarchy.
- To run the tool, open a terminal and launch layoutopt <xmlfiles>
- from your SDK tools/ directory. The <xmlfiles> argument is a space-
- delimited list of resources you want to analyze, either uncompiled resource xml files or
- directories of such files.
-
- The tool loads the specified XML files and analyzes their definitions and - hierarchies according to a set of predefined rules. For every issue it detects, it - displays the following information: -
--
-
- - The filename in which the issue was detected. - -
- - The line number for the issue. - -
- - A description of the issue, and for some types of issues it also suggests a resolution. - -
The following is a sample of the output from the tool:
--$ layoutopt samples/ -samples/compound.xml - 7:23 The root-level <FrameLayout/> can be replaced with <merge/> - 11:21 This LinearLayout layout or its FrameLayout parent is useless -samples/simple.xml - 7:7 The root-level <FrameLayout/> can be replaced with <merge/> -samples/too_deep.xml - -1:-1 This layout has too many nested layouts: 13 levels, it should have <= 10! - 20:81 This LinearLayout layout or its LinearLayout parent is useless - 24:79 This LinearLayout layout or its LinearLayout parent is useless - 28:77 This LinearLayout layout or its LinearLayout parent is useless - 32:75 This LinearLayout layout or its LinearLayout parent is useless - 36:73 This LinearLayout layout or its LinearLayout parent is useless - 40:71 This LinearLayout layout or its LinearLayout parent is useless - 44:69 This LinearLayout layout or its LinearLayout parent is useless - 48:67 This LinearLayout layout or its LinearLayout parent is useless - 52:65 This LinearLayout layout or its LinearLayout parent is useless - 56:63 This LinearLayout layout or its LinearLayout parent is useless -samples/too_many.xml - 7:413 The root-level <FrameLayout/> can be replaced with <merge/> - -1:-1 This layout has too many views: 81 views, it should have <= 80! -samples/useless.xml - 7:19 The root-level <FrameLayout/> can be replaced with <merge/> - 11:17 This LinearLayout layout or its FrameLayout parent is useless -+
Using lint to Optimize Your UI
+The Android {@code lint} tool lets you analyze the XML files that define your application's UI to find inefficiencies in the view hierarchy.
+Note: The Android layoutopt tool has been replaced by the {@code lint} tool beginning in ADT and SDK Tools revision 16. The {@code lint} tool reports UI layout performance issues in a similar way as layoutopt, and detects additional problems.
For more information about using {@code lint}, see Improving Your Code with lint and the lint reference documentation.
diff --git a/docs/html/tools/debugging/improving-w-lint.jd b/docs/html/tools/debugging/improving-w-lint.jd new file mode 100644 index 0000000000000..7e238fa5a86fc --- /dev/null +++ b/docs/html/tools/debugging/improving-w-lint.jd @@ -0,0 +1,219 @@ +page.title=Improving Your Code with lint +parent.title=Debugging +parent.link=index.html +@jd:body + +In This Document
+ +-
+
- Overview +
- Running lint from Eclipse +
- Running lint from the command-line +
- Configuring lint + + +
See Also
+-
+
- lint (reference) +
+In addition to testing that your Android application meets its functional requirements, it's important to ensure that your code has no structural problems. Poorly structured code can impact the reliability and efficiency of your Android apps and make your code harder to maintain. For example, if your XML resource files contain unused namespaces, this takes up space and incurs unnecessary processing. Other structural issues, such as use of deprecated elements or API calls that are not supported by the target API versions, might lead to code failing to run correctly.
+ +Overview
+The Android SDK provides a code scanning tool called {@code lint} that can help you to easily identify and correct problems with the structural quality of your code, without having to execute the app or write any test cases. Each problem detected by the tool is reported with a description message and a severity level, so that you can quickly prioritize the critical improvements that need to be made. You can also configure a problem's severity level to ignore issues that are not relevant for your project, or raise the severity level. The tool has a command-line interface, so you can easily integrate it into your automated testing process.
+The {@code lint} tool checks your Android project source files for potential bugs and optimization improvements for correctness, security, performance, usability, accessibility, and internationalization. You can run {@code lint} from the command-line or from the Eclipse environment.
+Figure 1 shows how the {@code lint} tool processes the application source files.
+
+Figure 1. Code scanning workflow with the {@code lint} tool
+-
+
- Application source files +
- The source files consist of files that make up your Android project, including Java and XML files, icons, and ProGuard configuration files. +
- The
lint.xmlfile
+ - A configuration file that you can use to specify any {@code lint} checks that you want to exclude and to customize problem severity levels. +
- The {@code lint} tool +
- A static code scanning tool that you can run on your Android project from the command-line or from Eclipse. The {@code lint} tool checks for structural code problems that could affect the quality and performance of your Android application. It is strongly recommended that you correct any errors that {@code lint} detects before publishing your application. +
- Results of {@code lint} checking +
- You can view the results from {@code lint} in the console or in the Lint Warnings view in Eclipse. Each issue is identified by the location in the source files where it occurred and a description of the issue. +
The {@code lint} tool is automatically installed as part of the Android SDK Tools revision 16 or higher. If you want to use {@code lint} in the Eclipse environment, you must also install the Android Development Tools (ADT) Plugin for Eclipse revision 16 or higher. For more information about installing the SDK or the ADT Plugin for Eclipse, see Installing the SDK.
+ +Running lint from Eclipse
+If the ADT Plugin is installed in your Eclipse environment, the {@code lint} tool runs automatically when you perform one of these actions:
+-
+
- Export an APK +
- Edit and save an XML source file in your Android project (such as a manifest or layout file) +
- Use the layout editor in Eclipse to make changes +
Note that when you export an APK, {@code lint} only runs an automatic check for fatal errors and aborts the export if fatal errors are found. You can turn off this automatic checking from the Lint Error Checking page in Eclipse Preferences.
+The output is displayed in the Lint Warnings view. If the Lint Warnings view is not showing in the workbench, you can bring it up from the Eclipse menu by clicking Window > Show View > Other > Android > Lint Warnings.
+Figure 2 shows an example of the output in the Lint Warnings view.
+
+Figure 2. Sample output in the Lint Warnings view
+You can also run a {@code lint} scan manually on your Android project in Eclipse by right-clicking on the project folder in the Package Explorer > Android Tools > Run Lint: Check for Common Errors.
+ + +Running lint from the Command-Line
++To run {@code lint} against a list of files in a project directory: +
lint [flags] <project directory>+
For example, you can issue the following command to scan the files under the {@code myproject} directory and its subdirectories. The issue ID MissingPrefix tells {@code lint} to only scan for XML attributes that are missing the Android namespace prefix.
lint --check MissingPrefix myproject+
To see the full list of flags and command-line arguments supported by the tool:
+lint --help+ + +
Example lint output
+The following example shows the console output when the {@code lint} command is run against a project called Earthquake.
++$ lint Earthquake + +Scanning Earthquake: ............................................................................................................................... +Scanning Earthquake (Phase 2): ....... +AndroidManifest.xml:23: Warning: <uses-sdk> tag appears after <application> tag [ManifestOrder] + <uses-sdk android:minSdkVersion="7" /> + ^ +AndroidManifest.xml:23: Warning: <uses-sdk> tag should specify a target API level (the highest verified version; when running on later versions, compatibility behaviors may be enabled) with android:targetSdkVersion="?" [UsesMinSdkAttributes] + <uses-sdk android:minSdkVersion="7" /> + ^ +res/layout/preferences.xml: Warning: The resource R.layout.preferences appears to be unused [UnusedResources] +res: Warning: Missing density variation folders in res: drawable-xhdpi [IconMissingDensityFolder] +0 errors, 4 warnings ++
The output above lists four warnings and no errors in this project. Three warnings ({@code ManifestOrder}, {@code UsesMinSdkAttributes}, and {@code UsesMinSdkAttributes}) were found in the project's AndroidManifest.xml file. The remaining warning ({@code IconMissingDensityFolder}) was found in the Preferences.xml layout file.
Configuring lint
+By default, when you run a {@code lint} scan, the tool checks for all issues that are supported by {@code lint}. You can also restrict the issues for {@code lint} to check and assign the severity level for those issues. For example, you can disable {@code lint} checking for specific issues that are not relevant to your project and configure {@code lint} to report non-critical issues at a lower severity level.
+You can configure {@code lint} checking at different levels:
+-
+
- Globally, for all projects +
- Per project +
- Per file +
- Per Java class or method (by using the
@SuppressLintannotation), or per XML element (by using thetools:ignoreattribute.
+
Configuring lint in Eclipse
+You can configure global, project-specific, and file-specific settings for {@code lint} from the Eclipse user interface.
+ +Global preferences
+-
+
- Open Window > Preferences > Android > Lint Error Checking. +
- Specify your preferences and click OK. +
These settings are applied by default when you run {@code lint} on your Android projects in Eclipse.
+ +Project and file-specific preferences
+-
+
- Run the {@code lint} tool on your project by right-clicking on your project folder in the Package Explorer and selecting Android Tools > Run Lint: Check for Common Errors. This action brings up the Lint Warnings view which displays a list of issues that {@code lint} detected in your project. +
- From the Lint Warnings view, use the toolbar options to configure {@code lint} preferences for individual projects and files in Eclipse. The options you can select include:
+
-
+
- Suppress this error with an annotation/attribute - If the issue appears in a Java class, the {@code lint} tool adds a
@SuppressLintannotation to the method where the issue was detected. If the issue appears in an {@code .xml} file, {@code lint} inserts atools:ignoreattribute to disable checking for the {@code lint} issue in this file.
+ - Ignore in this file - Disables checking for this {@code lint} issue in this file. +
- Ignore in this project - Disables checking for this {@code lint} issue in this project. +
- Always ignore - Disables checking for this {@code lint} issue globally for all projects. +
+ - Suppress this error with an annotation/attribute - If the issue appears in a Java class, the {@code lint} tool adds a
If you select the second or third option, the {@code lint} tool automatically generates a lint.xml file with these configuration settings in your Android application project folder.
Configuring the lint file
+You can specify your {@code lint} checking preferences in the lint.xml file. If you are creating this file manually, place it in the root directory of your Android project. If you are configuring {@code lint} preferences in Eclipse, the lint.xml file is automatically created and added to your Android project for you.
The lint.xml file consists of an enclosing <lint> parent tag that contains one or more children <issue> elements. Each <issue> is identified by a unique id attribute value, which is defined by {@code lint}.
+<?xml version="1.0" encoding="UTF-8"?> + <lint> + <!-- list of issues to configure --> +</lint> ++
By setting the severity attribute value in the <issue> tag, you can disable {@code lint} checking for an issue or change the severity level for an issue.
Tip: To see the full list of issues supported by the {@code lint} tool and their corresponding issue IDs, run the lint --list command.
Sample lint.xml file
+The following example shows the contents of a lint.xml file.
+<?xml version="1.0" encoding="UTF-8"?> +<lint> + <!-- Disable the given check in this project --> + <issue id="IconMissingDensityFolder" severity="ignore" /> + + <!-- Ignore the ObsoleteLayoutParam issue in the specified files --> + <issue id="ObsoleteLayoutParam"> + <ignore path="res/layout/activation.xml" /> + <ignore path="res/layout-xlarge/activation.xml" /> + </issue> + + <!-- Ignore the UselessLeaf issue in the specified file --> + <issue id="UselessLeaf"> + <ignore path="res/layout/main.xml" /> + </issue> + + <!-- Change the severity of hardcoded strings to "error" --> + <issue id="HardcodedText" severity="error" /> +</lint> ++ +
Configuring lint checking in Java and XML source files
+You can disable {@code lint} checking from your Java and XML source files.
+ +Tip: If you are using Eclipse, you can use the Quick Fix feature to automatically add the annotation or attribute to disable {@code lint} checking to your Java or XML source files: +
-
+
- Open the Java or XML file that has a {@code lint} warning or error in an Eclipse editor. +
- Move your cursor to the location in the file where is {@code lint} issue is found, then press
Ctrl+1to bring up the Quick Fix pop-up.
+ - From the Quick Fix pop-up, select the action to add an annotation or attribute to ignore the {@code lint} issue. +
Configuring lint checking in Java
+To disable {@code lint} checking specifically for a Java class or method in your Android project, add the @SuppressLint annotation to that Java code.
The following example shows how you can turn off {@code lint} checking for the {@code NewApi} issue in the onCreate method. The {@code lint} tool continues to check for the {@code NewApi} issue in other methods of this class.
+@SuppressLint("NewApi")
+@Override
+public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main);
+
+The following example shows how to turn off {@code lint} checking for the {@code ParserError} issue in the FeedProvider class:
+@SuppressLint("ParserError")
+public class FeedProvider extends ContentProvider {
+
+To suppress checking for all {@code lint} issues in the Java file, use the {@code all} keyword, like this:
+
+@SuppressLint("all")
+
+
+Configuring lint checking in XML
+You can use the tools:ignore attribute to disable {@code lint} checking for specific sections of your XML files. In order for this attribute to be recognized by the {@code lint} tool, the following namespace value must be included in your XML file:
+namespace xmlns:tools="http://schemas.android.com/tools" ++
The following example shows how you can turn off {@code lint} checking for the {@code UnusedResources} issue for the <LinearLayout> element of an XML layout file. The ignore attribute is inherited by the children elements of the parent element in which the attribute is declared. In this example, the {@code lint} check is also disabled for the child <TextView> element.
+<LinearLayout + xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:tools="http://schemas.android.com/tools" + tools:ignore="UnusedResources" > + + <TextView + android:text="@string/auto_update_prompt" /> +</LinearLayout> ++
To disable more than one issue, list the issues to disable in a comma-separated string. For example:
++tools:ignore="NewApi,StringFormatInvalid" ++
To suppress checking for all {@code lint} issues in the XML element, use the {@code all} keyword, like this:
++tools:ignore="all" +diff --git a/docs/html/tools/help/lint.jd b/docs/html/tools/help/lint.jd new file mode 100644 index 0000000000000..ba31f6d6bc1c2 --- /dev/null +++ b/docs/html/tools/help/lint.jd @@ -0,0 +1,178 @@ +page.title=lint +parent.title=Tools +parent.link=index.html +@jd:body + +
In this document
+ +The Android {@code lint} tool is a static code analysis tool that checks your Android project source files for potential bugs and optimization improvements for correctness, security, performance, usability, accessibility, and internationalization.
+For more information on running {@code lint}, see Improving Your Code with lint.
+ +Syntax
++
lint [flags] <project directory>+ +For example, you can issue the following command to scan the Java and XML files under the {@code myproject} directory and its subdirectories. The result is displayed on the console. +
lint myproject+ +You can also use {@code lint} to check for a specific issue. For example, you can run the following command to scan the files under the {@code myproject} directory and its subdirectories to check for XML attributes missing the Android namespace prefix. The issue ID {@code MissingPrefix} tells lint to only scan for this issue. +
lint --check MissingPrefix myproject+ +You can create an HTML report for the issues that {@code lint} detects. For example, you can run the following command to scan the {@code myproject} directory and its subdirectories for accessibility issues, then generate an HTML report in the {@code accessibility_report.html} file. +
lint --check Accessibility --HTML accessibility_report.html myproject+ + +
Options
+Table 1 describes the command-line options for {@code lint}.
++ Table 1. Command-line options for lint
+| Category | +Option | +Description | +Comments | +
|---|---|---|---|
| Checking | +--disable <list> |
+Disable checking for a specific list of issues. | +The <list> must be a comma-separated list of {@code lint} issue IDs or categories. |
+
--enable <list> |
+Check for all the default issues supported by {@code lint} as well as the specifically enabled list of issues. | +The <list> must be a comma-separated list of {@code lint} issue IDs or categories. |
+|
--check <list> |
+Check for a specific list of issues. | +The <list> must be a comma-separated list of {@code lint} issue IDs or categories. |
+|
-w or --nowarn |
+Only check for errors and ignore warnings | ++ | |
-Wall |
+Check for all warnings, including those that are disabled by default | ++ | |
-Werror |
+Report all warnings as errors | ++ | |
--config <filename> |
+Use the specified configuration file to determine if issues are enabled or disabled for {@code lint} checking | +If the project contains a {@code lint.xml} file, the {@code lint.xml} file will be used as the configuration file by default. | +|
| Reporting | +--html <filename> |
+Generate an HTML report. | +The report is saved in the output file specified in the argument. The HTML output includes code snippets of the source code where {@code lint} detected an issue, a verbose description of the issue found, and links to the source file. | +
--url <filepath>=<url> |
+In the HTML output, replace a local path prefix <filepath> with a url prefix <url>. |
+The {@code --url} option only applies when you are generating an HTML report with the {@code --html} option. You can specify multiple <filepath>=<url> mappings in the argument by separating each mapping with a comma. To turn off linking to files, use {@code --url none} |
+|
--simplehtml <filename> |
+Generate a simple HTML report | +The report is saved in the output file specified in the argument. | +|
--xml <filename> |
+Generate an XML report | +The report is saved in the output file specified in the argument. | +|
--fullpath |
+Show the full file paths in the {@code lint} checking results. | ++ | |
--showall |
+Don't truncate long messages or lists of alternate locations. | ++ | |
--nolines |
+Don't include code snippets from the source files in the output. | ++ | |
--exitcode |
+Set the exit code to 1 if errors are found. | ++ | |
--quiet |
+Don't show the progress indicator. | ++ | |
| Help | +--help |
+List the command-line arguments supported by the {@code lint} tool. | +Use {@code --help <topic>} to see help information for a specific topic, such as "suppress". | +
--list |
+List the ID and short description for issues that can be checked by {@code lint} | ++ | |
--show |
+List the ID and verbose description for issues that can be checked by {@code lint} | +Use {@code --show <ids>} to see descriptions for a specific list of {@code lint} issue IDs. | +|
--version |
+Show the {@code lint} version | ++ |
Configuring Java and XML Source Files
+To configure lint checking, you can apply the following annotation or attribute to the source files in your Android project.
+-
+
- To disable lint checking for a specific Java class or method, use the
@SuppressLintannotation.
+ - To disable lint checking for specific sections of your XML file, use the
tools:ignoreattribute.
+
You can also specify your lint checking preferences for a specific Android project in the lint.xml file. For more information on configuring lint, see Improving Your Code with lint.
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index c7cdded460f3d..850e0ecb55fb4 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -107,6 +107,7 @@