자바 SDK 라이브러리 구현

Android 플랫폼에는 다수의 공유 자바 라이브러리가 포함되어 있습니다. 이러한 라이브러리는 앱 매니페스트에서 <uses-library> 태그를 사용하여 앱의 클래스 경로에 선택적으로 포함할 수 있습니다. 앱은 이러한 라이브러리에 연결되어 호환성, API 검토 및 도구 지원 측면에서 라이브러리를 Android API의 일부인 것처럼 취급합니다. 그러나 대부분의 라이브러리에는 이러한 기능이 없습니다.

java_sdk_library 모듈 유형을 사용하면 이러한 종류의 라이브러리를 관리하는 데 도움이 됩니다. 기기 제조업체에서는 이러한 메커니즘을 자체 공유 자바 라이브러리에 사용하여 자체 API의 하위 호환성을 유지할 수 있습니다. 기기 제조업체가 부팅 클래스 경로 대신 <uses-library> 태그를 통해 자체 공유 자바 라이브러리를 사용하는 경우 java_sdk_library는 이러한 자바 라이브러리가 API에 대해 안정적인지 확인할 수 있습니다.

java_sdk_library는 선택사항인 SDK API를 앱에서 사용하도록 구현합니다. 빌드 파일(Android.bp)의 java_sdk_library를 통해 구현된 라이브러리는 다음과 같은 작업을 실행합니다.

스텁 라이브러리는 stubs, stubs.system, stubs.test를 포함하도록 생성됩니다. 이러한 스텁 라이브러리는 @hide, @SystemApi, @TestApi 주석을 인식하는 방식으로 생성됩니다.
java_sdk_library는 API 하위 디렉터리의 API 사양 파일(예: current.txt)을 관리합니다. 최신 코드와 비교하여 이러한 파일이 최신 버전인지 확인합니다. 최신 버전이 아닌 경우 업데이트 방법을 설명하는 오류 메시지가 표시됩니다. 모든 업데이트 변경사항을 직접 검토하여 예상과 일치하는지 확인합니다.

모든 API를 업데이트하려면 m update-api를 사용합니다. API가 최신 상태인지 확인하려면 m checkapi를 사용합니다.
API 사양 파일은 가장 최근에 게시된 Android 버전과 비교하여 API가 이전 버전과 호환되는지 확인합니다. AOSP의 일부로 제공되는 java_sdk_library 모듈은 이전에 출시된 버전을 prebuilts/sdk/<latest number>에 배치합니다.
API 사양 파일 검사와 관련하여 다음 3가지 중 하나를 실행하면 됩니다.

검사를 진행하도록 허용합니다. (별도의 작업 필요 없음)
java_sdk_library에 다음을 추가하여 검사를 사용 중지합니다.
unsafe_ignore_missing_latest_api: true,
version/scope/api 디렉터리에 module_name.txt라는 빈 텍스트 파일을 만들어 새 java_sdk_library 모듈에 빈 API를 제공합니다.

런타임의 구현 라이브러리가 설치되면 XML 파일이 생성되고 설치됩니다.

java_sdk_library 작동 방식

X라는 java_sdk_library가 다음을 만듭니다.

구현 라이브러리의 사본 두 개(X와 X.impl)를 만듭니다. 라이브러리 X는 기기에 설치됩니다. 라이브러리 X.impl은 다른 모듈(예: 테스트에서 사용)에서 구현 라이브러리에 명시적으로 액세스해야 하는 경우에만 존재합니다. 명시적인 액세스는 거의 필요하지 않습니다.
범위를 사용 설정하거나 사용 중지하여 액세스를 맞춤설정할 수 있습니다. 자바 키워드 액세스 수정자와 마찬가지로 공개 범위는 광범위한 액세스 권한을 제공합니다. 테스트 범위에는 테스트에만 사용되는 API가 포함됩니다. 사용 설정된 범위마다 라이브러리에서 다음을 생성합니다.

스텁 소스 모듈(droidstubs 모듈 유형) - 구현 소스를 사용하고 API 사양 파일과 함께 스텁 소스 집합을 출력합니다.
스텁 라이브러리(java_library 모듈 유형) - 스텁의 컴파일된 버전입니다. 이를 컴파일하는 데 사용되는 라이브러리는 java_sdk_library에 제공된 것과 같지 않으므로 구현 세부정보가 API 스텁으로 유출되지 않습니다.
스텁을 컴파일하기 위해 추가 라이브러리가 필요한 경우 stub_only_libs 및 stub_only_static_libs 속성을 사용하여 제공합니다.

java_sdk_library의 이름이 'X'이고 'X'로 컴파일되는 경우 항상 이런 식으로 참조하고 이름을 수정하면 안 됩니다. 빌드에서 적절한 라이브러리를 선택합니다. 가장 적절한 라이브러리가 있도록 하려면 스텁을 검사하여 빌드에 오류가 발생했는지 확인합니다. 수정사항이 있는 경우 다음 안내를 따르세요.

범위를 확인하기 위해 명령줄을 살펴보고 나열된 스텁을 검사하여 적합한 라이브러리가 있는지 확인합니다.

범위가 너무 넓은 경우: 종속 라이브러리에 특정 API 범위가 필요합니다. 하지만, 공개 API가 포함된 시스템 API와 같이 이 범위에 포함되지 않는 API가 라이브러리에 포함되어 있습니다.
범위가 너무 좁은 경우: 종속 라이브러리에 일부 필수 라이브러리에 대한 액세스 권한이 없습니다. 예를 들어, 종속 라이브러리가 시스템 API를 사용해야 하지만 대신 공개 API를 가져옵니다. 이렇게 하면 필요한 API가 누락되기 때문에 일반적으로 컴파일 오류가 발생합니다.

라이브러리를 수정하려면 다음 중 하나만 실행합니다.

sdk_version을 변경하여 필요한 버전을 선택하거나
<X>.stubs 또는 <X>.stubs.system과 같은 적절한 라이브러리를 명시적으로 지정합니다.

java_sdk_library X 사용

구현 라이브러리 X는 apex.java_libs에서 참조될 때 사용됩니다. 하지만, Soong 제한으로 인해 라이브러리 X가 동일한 APEX 라이브러리 내에 있는 다른 java_sdk_library 모듈에서 참조되면 라이브러리 X가 아닌 X.impl을 명시적으로 사용해야 합니다.

java_sdk_library가 다른 위치에서 참조되면 스텁 라이브러리가 사용됩니다. 스텁 라이브러리는 종속 모듈의 sdk_version 속성 설정에 따라 선택됩니다. 예를 들어 sdk_version: "current"를 지정하는 모듈은 공개 스텁을 사용하고 sdk_version: "system_current"를 지정하는 모듈은 시스템 스텁을 사용합니다. 완전히 일치하는 항목을 찾을 수 없으면 가장 가까운 스텁 라이브러리가 사용됩니다. 공개 API만 제공하는 java_sdk_library는 모든 사용자에게 공개 스텁을 제공합니다.

예시 및 소스

srcs 및 api_packages 속성은 java_sdk_library에 있어야 합니다.

java_sdk_library {
        name: "com.android.future.usb.accessory",
        srcs: ["src/**/*.java"],
        api_packages: ["com.android.future.usb"],
    }

AOSP에서는 새 java_sdk_library 인스턴스가 사용하려는 API 범위를 명시적으로 사용 설정하도록 권장합니다(필수는 아님). (선택사항) 기존 java_sdk_library 인스턴스를 이전하여 사용할 API 범위를 명시적으로 사용 설정할 수도 있습니다.

java_sdk_library {
         name: "lib",
         public: {
           enabled: true,
         },
         system: {
           enabled: true,
         },
         …
    }

런타임에 사용되는 impl 라이브러리를 구성하려면 hostdex, compile_dex, errorprone 등 일반 java_library 속성을 모두 사용할 수 있습니다.

java_sdk_library {
        name: "android.test.base",

        srcs: ["src/**/*.java"],

        errorprone: {
          javacflags: ["-Xep:DepAnn:ERROR"],
        },

        hostdex: true,

        api_packages: [
            "android.test",
            "android.test.suitebuilder.annotation",
            "com.android.internal.util",
            "junit.framework",
        ],

        compile_dex: true,
    }

스텁 라이브러리를 구성하려면 다음 속성을 사용합니다.

merge_annotations_dirs 및 merge_inclusion_annotations_dirs
api_srcs: API의 일부이지만 런타임 라이브러리의 일부는 아닌 선택적 소스 파일 목록입니다.
stubs_only_libs: 스텁 빌드 시 클래스 경로에 위치하는 자바 라이브러리 목록입니다.
hidden_api_packages: API에서 숨겨야 하는 패키지 이름 목록입니다.
droiddoc_options: metalava의 추가 인수입니다.
droiddoc_option_files: $(location <label>)을 사용하여 droiddoc_options 내에서 참조할 수 있는 파일을 나열합니다. 여기서 <file>은 목록의 항목입니다.
annotations_enabled

java_sdk_library는 java_library지만, droidstubs 모듈이 아니므로 일부 droidstubs 속성은 지원하지 않습니다. 다음 예는 android.test.mock 라이브러리 빌드 파일의 일부입니다.

java_sdk_library {
        name: "android.test.mock",

        srcs: [":android-test-mock-sources"],
        api_srcs: [
            // Note: The following aren’t APIs of this library. Only APIs under the
            // android.test.mock package are taken. These do provide private APIs
            // to which android.test.mock APIs reference. These classes are present
            // in source code form to access necessary comments that disappear when
            // the classes are compiled into a Jar library.
            ":framework-core-sources-for-test-mock",
            ":framework_native_aidl",
        ],

        libs: [
            "framework",
            "framework-annotations-lib",
            "app-compat-annotations",
            "Unsupportedappusage",
        ],

        api_packages: [
            "android.test.mock",
        ],
        permitted_packages: [
            "android.test.mock",
        ],
        compile_dex: true,
        default_to_stubs: true,
    }

하위 호환성 유지

빌드 시스템은 최신 API 파일과 빌드 시에 생성된 API 파일을 비교하여 API의 하위 호환성이 유지되는지 확인합니다. java_sdk_library는 prebuilt_apis에서 제공하는 정보를 사용하여 호환성 검사를 실행합니다. java_sdk_library로 빌드된 모든 라이브러리는 prebuilt_apis에 최신 버전의 api_dirs API 파일이 있어야 합니다. 버전을 출시하면 PRODUCT=sdk_phone_armv7-sdk를 포함하는 dist 빌드로 API 목록 파일과 스텁 라이브러리를 가져올 수 있습니다.

api_dirs 속성은 prebuilt_apis의 API 버전 디렉터리 목록입니다. API 버전 디렉터리는 Android.bp 디렉터리 수준에 있어야 합니다.

prebuilt_apis {
       name: "foo",
       api_dirs: [
           "1",
           "2",
             ....
           "30",
           "current",
       ],
    }

version/scope/api/ 구조체를 포함하는 디렉터리를 사전 빌드된 디렉터리 아래에 구성합니다. version은 API 수준에 상응하며 scope은 디렉터리가 공개 디렉터리인지, 시스템 디렉터리인지 또는 테스트 디렉터리인지 정의합니다.

version/scope에는 자바 라이브러리가 포함됩니다.

version/scope/api에는 API .txt 파일이 포함됩니다. 여기서 module_name.txt 및 module_name-removed.txt라는 빈 텍스트 파일을 생성하세요.

 ├── 30
      │   ├── public
      │   │   ├── api
      │   │   │   ├── android.test.mock-removed.txt
      │   │   │   └── android.test.mock.txt
      │   │   └── android.test.mock.jar
      │   ├── system
      │   │   ├── api
      │   │   │   ├── android.test.mock-removed.txt
      │   │   │   └── android.test.mock.txt
      │   │   └── android.test.mock.jar
      │   └── test
      │       ├── api
      │       │   ├── android.test.mock-removed.txt
      │       │   └── android.test.mock.txt
      │       └── android.test.mock.jar
      └── Android.bp