title: Android API level annotation for Android libraries
body: <p>I am writing an Android library. The vast majority of the interface in the lbirary supports Android API level 10 or above. Some functionality, though, requires a higher API level. For instance, part of the library requires API 18 for Bluetooth Low Energy.</p>
  
  <p>For the sake of concreteness, let's say that the library produces three classes <code>ClassA</code>, <code>ClassB</code> and <code>ClassC</code>. <code>ClassA</code> uses functionality available in API 10, <code>ClassB</code> uses functionality available in API 14 and <code>ClassC</code> uses functionality available in API 18.</p>
  
  <p>I want to be able to trigger a lint issue (warning/error) whenever someone uses a class from my library without having the required API level in their project (unless they suppress the warning with the appropriate annotation), similar to the already built-in NewApi issue used by lint.</p>
  
  <p>After searching, I have found the following possible solutions:</p>
  
  <p>1) This solution isn't along the lines of lint: Split the library into three .jar files, say <code>lib_10.jar</code> that includes all classes using functionality available in API 10 (ClassA in the example), <code>lib_14.jar</code> that includes all the classes using functionality available in API 14 (ClassB in the example) and <code>lib_18.jar</code> that includes all classes using functionality available in API 18 (ClassC in the example). This solution allows portability but would complicate the later maintainability of the codebase and would potentially require some code duplication as well.</p>
  
  <p>2) Create my own annotation (say, <code>@RequireAndroidApi(API_LEVEL)</code> indicating the minimum API level required by the annotated class/method/etc...) and use the <code>lint-api.jar</code> (<code>http://tools.android.com/tips/lint-custom-rules</code>) to create a custom lint rules that check the usage of any annotated classes/methods/etc... with a lower API than required. Something that would later look like this:</p>
  
  <pre><code>@RequireAndroidApi(10)
  Class ClassA {
  }
  
  @RequireAndroidApi(14)
  Class ClassB {
  }
  
  @RequireAndroidApi(18)
  Class ClassC {
  }
  </code></pre>
  
  <p>The problem is that I couldn't find good documentation for the lint API and it seems that this is reinventing the wheel for a functionality that lint already supports (lint already checks for the "NewApi" issue).</p>
  
  <p>3) Finally, I succeeded to edit <code>&lt;SDK&gt;/platform-tools/api/api-versions.xml</code> in order to indicate the API level required by each class as follows:</p>
  
  <pre><code>&lt;api version="1"&gt;
      ...
      &lt;class name="package/path/ClassA" since="10"&gt;
          &lt;extends name="java/lang/Object" /&gt;
          &lt;method name="&amp;lt;init&gt;()V" /&gt;
      &lt;/class&gt;
      &lt;class name="package/path/ClassB" since="14"&gt;
          &lt;extends name="java/lang/Object" /&gt;
          &lt;method name="&amp;lt;init&gt;()V" /&gt;
      &lt;/class&gt;
      &lt;class name="package/path/ClassC" since="18"&gt;
          &lt;extends name="java/lang/Object" /&gt;
          &lt;method name="&amp;lt;init&gt;()V" /&gt;
      &lt;/class&gt;
  &lt;/api&gt;
  </code></pre>
  
  <p>Which caused lint to trigger the NewApi issue in the same manner as it would with the Android APIs. I like this type of solution because it doesn't reinvent the wheel and further any errors thrown this way would utilize the suggested solutions programmed in Eclipse or Android Studio to deal with the problem (i.e. "quick fixes" in Eclipse). The problem with this solution is that it requires editing <code>api-versions.xml</code> that ships with the Android SDK, which makes this solution not very portable for releasing the library for several reasons including: a) the <code>api-versions.xml</code> file is not local to a project and changes the behavior of lint for all android projects, including the ones that do not use the library; and b) <code>api-versions.xml</code> will be overwritten every time the SDK is updated from the Android SDK manager which would overwrite any changes made.</p>
  
  <p>I was wondering if there is a simpler solution to achieve this "minimum API errors/warnings" or if there is a way to write a separate file similar to <code>api-versions.xml</code> that can be placed in the project directory which can be read by lint whenever lint is ran on the project in question (something similar to <code>lint.xml</code>).</p>
  
  <p>Thanks for bearing with me during this long description of the problem and I appreciate any help in advance.</p>