frameworks_base/docs/html/tools/debugging/improving-w-lint.jd

page.title=Improving Your Code with lint
parent.title=Debugging
parent.link=index.html
@jd:body

<div id="qv-wrapper">
    <div id="qv">
      <h2>In This Document</h2>

      <ol>
        <li><a href="#overview">Overview</a></li>
        <li><a href="#studio">Running lint from Android Studio</a></li>
        <li><a href="#commandline">Running lint from the command-line</a></li>
         <li><a href="#config">Configuring lint</a>
            <ol>
		<LI><a href="#studio_config">Configuring Lint in Android Studio</a></LI>
                <LI><a href="#pref">Configuring the lint file</a></LI>
                <LI><a href="#src">Configuring lint checking in Java and XML source files</a></LI>
            </ol>
         </li>
      </ol>
      <h2>See Also</h2>
          <ol>
              <li><a href="{@docRoot}tools/help/lint.html">lint (reference)</a></li>
              <li><a href="{@docRoot}tools/degugging/annotations.html">Using Android Annotations</a></li>
          </ol>
    </div>
</div>


<p>
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.</p>

<h2 id="overview">Overview</h2>
<p>The Android SDK provides a code scanning tool called <a href="{@docRoot}tools/help/lint.html"><code>lint</code></a>
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.</p>
<p>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 Android Studio.</p>

<p class="note"><strong>Note:</strong> In Android Studio, additional
<a href="https://www.jetbrains.com/idea/help/inspection-basics.html?search=inspection" class="external-link"
target="_blank">IntelliJ code inspections</a> run when your code is compiled in Android Studio to
streamline code review.</p>

<p>Figure 1 shows how the {@code lint} tool processes the application source files.</p>
<img id="Fig1" src="{@docRoot}images/tools/lint.png" alt="">
<p class="img-caption"><strong>Figure 1.</strong> Code scanning workflow with the {@code lint} tool</p>
<dl>
<dt><b>Application source files</b></dt>
<dd>The source files consist of files that make up your Android project, including Java and XML
files, icons, and ProGuard configuration files. </dd>
<dt><b>The <code>lint.xml</code> file</b></dt>
<dd>A configuration file that you can use to specify any {@code lint} checks that you want to
exclude and to customize problem severity levels.</dd>
<dt><b>The {@code lint} tool</b></dt>
<dd>A static code scanning tool that you can run on your Android project from the command-line or
Android Studio.  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.</dd>
<dt><b>Results of {@code lint} checking</b></dt>
<dd>You can view the results from {@code lint} in the console or in the <strong>Event Log</strong>
in Android Studio.  Each issue is identified by the location in the source files where it occurred
and a description of the issue.</dd>
</dl>
<p>The {@code lint} tool is automatically installed as part of the Android SDK Tools revision 16 or
higher.</p>


<h2 id="studio">Running lint in Android Studio</h2>
<p>In Android Studio, the configured <code>lint</code> and
IDE inspections run automatically whenever you build your app. The IDE inspections are
configured along with the {@code lint} checks to run
<a href="https://www.jetbrains.com/idea/help/inspection-basics.html?search=inspection" class="external-link"
target="_blank">IntelliJ code inspections</a> to streamline code review.</p>

<p class="note"><strong>Note:</strong> To view and modify inspection severity
levels, use the <strong>File &gt; Settings &gt; Project Settings</strong> menu to open the
<em>Inspection Configuration</em> page with a list of the supported inspections.</p>


<p>With Android Studio, you can also run {@code lint} inspections for a specific build variant,
or for all build variants from the <code>build.gradle</code> file. Add the
<code>lintOptions</code> property to the <code>android</code> settings in the build file.
This code snippet from a Gradle build file shows how to set the <code>quiet</code> option to
<code>true</code> and the <code>abortOnError</code> option to <code>false</code>. </p>

<pre>
android {
    lintOptions {
       // set to true to turn off analysis progress reporting by lint
       quiet true
       // if true, stop the gradle build if errors are found
       abortOnError false
       // if true, only report errors
       ignoreWarnings true
       }
       ...
    }
</pre>


<p>To manually run inspections in Android Studio, from the application or right-click menu,
choose <strong>Analyze &gt; Inspect Code</strong>. The <em>Specify Inspections Scope</em> dialog
appears so you can specify the desired inspection scope and profile.</p>




<h2 id="commandline">Running lint from the Command-Line</h2>
<p>
To run {@code lint} against a list of files in a project directory:
<pre>lint [flags] &lt;project directory&gt;</pre>
<p>For example, you can issue the following command to scan the files under the {@code myproject}
directory and its subdirectories. The issue ID  <code>MissingPrefix</code> tells {@code lint} to
only scan for XML attributes that are missing the Android namespace prefix.</p>
<pre>lint --check MissingPrefix myproject </pre>
<p>To see the full list of flags and command-line arguments supported by the tool:</p>
<pre>lint --help</pre>
</p>

<h3>Example lint output</h3>
<p>The following example shows the console output when the {@code lint} command is run against a
project called Earthquake.  </p>
<pre>
$ lint Earthquake

Scanning Earthquake: ...............................................................................................................................
Scanning Earthquake (Phase 2): .......
AndroidManifest.xml:23: Warning: &lt;uses-sdk&gt; tag appears after &lt;application&gt; tag [ManifestOrder]
  &lt;uses-sdk android:minSdkVersion="7" /&gt;
  ^
AndroidManifest.xml:23: Warning: &lt;uses-sdk&gt; 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]
  &lt;uses-sdk android:minSdkVersion="7" /&gt;
  ^
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
</pre>
<p>The output above lists four warnings and no errors in this project.  Three warnings
({@code ManifestOrder}, {@code UsesMinSdkAttributes}, and {@code UnusedResources}) were found in
the project's <code>AndroidManifest.xml</code> file. The remaining warning
({@code IconMissingDensityFolder}) was found in the <code>Preferences.xml</code> layout file.</p>

<h2 id="config">Configuring lint</h2>
<p>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.</p>
<p>You can configure {@code lint} checking at different levels:</p>
<ul>
<LI>Globally, for the entire project</LI>
<li>Per project module</li>
<li>Per production module</li>
<li>Per test module</li>
<li>Per open files</li>
<li>Per class hierarchy</li>
<li>Per Version Control System (VCS) scopes</li>
</ul>

<h3 id="studio_config">Configuring Lint in Android Studio</h3>

<p>The built-in Lint tool checks your code while you're using
Android Studio. You can view warnings and errors in two ways: </p>
<ul>
<li>As pop-up text in the Code Editor. When Lint finds a problem, it highlights
the problematic code in yellow, or underlines the code in red for more serious
issues.</li>
<li>In the Lint <em>Inspection Results</em> window after you select
<strong>Analyze</strong> &gt; <strong>Inspect Code</strong>.</li>
</ul>



<p>To set default Lint checks:</p>
<ol>
<li>In Android Studio, open your project.
</li>
<li>Select <strong>File</strong> &gt; <strong>Other Settings</strong> &gt;
  <strong>Default Settings</strong>.</li>
<li>In the <em>Default Preferences</em> dialog, select <strong>Editor</strong>
&gt; <strong>Inspections</strong>. </li>
<li>In the <strong>Profile</strong> field, select <strong>Default</strong> or
  <strong>Project Default</strong> to set the
  <a href="https://www.jetbrains.com/help/idea/2016.1/specify-inspection-scope-dialog.html?origin=old_help"
  class="external-link">scope</a> for Android Studio or just for this project,
  respectively. </li>
<li>Expand a category and change the Lint settings as needed.</li>
<p>You can select individual checks, or entire categories.</p>

<li>Click <strong>OK</strong>.</li>
</ol>



<p>To produce a list of Lint checks displayed in the <em>Inspection Results</em>
window:</p>
<ol>
<li>In Android Studio, open your project
  and select a portion of your project that you want to test.</li>
<li>Select <strong>Analyze</strong> &gt; <strong>Inspect Code</strong>.</li>
<li>In the <em>Specify Inspection Scope </em>dialog, select the inspection
<a href="https://www.jetbrains.com/help/idea/2016.1/specify-inspection-scope-dialog.html?origin=old_help"
  class="external-link">scope</a> and profile. </li>

<p>The scope specifies the files you want to analyze, and the profile specifies
the Lint checks you’d like to perform.</p>
<li>If you want to change the Lint settings, click <strong>…</strong>. In the
<em>Inspections</em> dialog, optionally click <strong>Manage</strong> to define
a new profile, specify the Lint settings you want, and then click
<strong>OK</strong>.</li>
<p>In the <em>Inspections</em> dialog, you can search for a string
to find Lint checks. Note that changing Lint settings for a
profile in the <em>Inspections</em> dialog doesn’t change the default settings,
as described in the previous procedure. It does change the settings for profiles
displayed in the <em>Inspections</em> dialog, however.</p>
<li>Click <strong>OK</strong>.</li>
<p>The results appear in the <em>Inspection Results</em> window, organized by
category.</p>

</ol>



<h3 id="pref">Configuring the lint file</h3>
<p>You can specify your {@code lint} checking preferences in the <code>lint.xml</code> 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 Android Studio, the <code>lint.xml</code> file is
automatically created and added to your Android project for you.</p>
<p>The <code>lint.xml</code> file consists of an enclosing <code>&lt;lint&gt;</code> parent tag that
contains one or more children <code>&lt;issue&gt;</code> elements.  Each <code>&lt;issue&gt;</code>
is identified by a unique <code>id</code> attribute value, which is defined by {@code lint}.</p>
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;lint&gt;
        &lt;!-- list of issues to configure --&gt;
&lt;/lint&gt;
</pre>
<p>By setting the severity attribute value in the <code>&lt;issue&gt;</code> tag, you can disable
{@code lint} checking for an issue or change the severity level for an issue.  </p>
<p class="note"><strong>Tip: </strong>To see the full list of issues supported by the {@code lint}
tool and their corresponding issue IDs, run the <code>lint --list</code> command.</p>

<h4>Sample lint.xml file</h4>
<p>The following example shows the contents of a <code>lint.xml</code> file.</p>
<pre>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;lint&gt;
    &lt;!-- Disable the given check in this project --&gt;
    &lt;issue id="IconMissingDensityFolder" severity="ignore" /&gt;

    &lt;!-- Ignore the ObsoleteLayoutParam issue in the specified files --&gt;
    &lt;issue id="ObsoleteLayoutParam"&gt;
        &lt;ignore path="res/layout/activation.xml" /&gt;
        &lt;ignore path="res/layout-xlarge/activation.xml" /&gt;
    &lt;/issue>

    &lt;!-- Ignore the UselessLeaf issue in the specified file --&gt;
    &lt;issue id="UselessLeaf"&gt;
        &lt;ignore path="res/layout/main.xml" /&gt;
    &lt;/issue&gt;

    &lt;!-- Change the severity of hardcoded strings to "error" --&gt;
    &lt;issue id="HardcodedText" severity="error" /&gt;
&lt;/lint&gt;
</pre>

<h3 id="src">Configuring lint checking in Java and XML source files</h3>
<p>You can disable {@code lint} checking from your Java and XML source files.</p>

<p class="note"><strong>Tip: </strong>If you are using Android Studio, you can use the
<strong>File &gt; Settings &gt; Project Settings &gt; Inspections</strong> feature to manage the
{@code lint} checking to your Java or XML source files.
</p>

<h4>Configuring lint checking in Java</h4>
<p>To disable {@code lint} checking specifically for a Java class or method in your Android project,
add the <code>&#64;SuppressLint</code> annotation to that Java code. </p>
<p>The following example shows how you can turn off {@code lint} checking for the {@code NewApi}
issue in the <code>onCreate</code> method.  The {@code lint} tool continues to check for the
{@code NewApi} issue in other methods of this class.</p>
<pre>
&#64;SuppressLint("NewApi")
&#64;Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
</pre>
<p>The following example shows how to turn off {@code lint} checking for the {@code ParserError}
issue in the <code>FeedProvider</code> class:</p>
<pre>
&#64;SuppressLint("ParserError")
public class FeedProvider extends ContentProvider {
</pre>
<p>To suppress checking for all {@code lint} issues in the Java file, use the {@code all} keyword,
like this:</p>
<pre>
&#64;SuppressLint("all")
</pre>

<h4>Configuring lint checking in XML</h4>
<p>You can use the <code>tools:ignore</code> 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:</p>
<pre>
namespace xmlns:tools="http://schemas.android.com/tools"
</pre>
<p>The following example shows how you can turn off {@code lint} checking for the
{@code UnusedResources} issue for the <code>&lt;LinearLayout&gt;</code> element of an XML layout
file.  The <code>ignore</code> 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 <code>&lt;TextView&gt;</code> element. </p>
<pre>
&lt;LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:ignore="UnusedResources" &gt;

    &lt;TextView
        android:text="&#64;string/auto_update_prompt" /&gt;
&lt;/LinearLayout&gt;
</pre>
<p>To disable more than one issue, list the issues to disable in a comma-separated string.  For
example:</p>
<pre>
tools:ignore="NewApi,StringFormatInvalid"
</pre>
<p>To suppress checking for all {@code lint} issues in the XML element, use the {@code all} keyword,
like this:</p>
<pre>
tools:ignore="all"
</pre>