1*89a63228SAndroid Build Coastguard WorkerThis directory contains annotated stub files which can be merged into 2*89a63228SAndroid Build Coastguard Workerthe main source files by metalava when it is producing API stubs. This 3*89a63228SAndroid Build Coastguard Workermechanism is used instead of adding the annotations to the main source 4*89a63228SAndroid Build Coastguard Workerfiles, to avoid carrying patches against the upstream sources. 5*89a63228SAndroid Build Coastguard Worker 6*89a63228SAndroid Build Coastguard WorkerDirectory structure 7*89a63228SAndroid Build Coastguard Worker=================== 8*89a63228SAndroid Build Coastguard Worker 9*89a63228SAndroid Build Coastguard Workerlibcore/ojluni/annotations/sdk: 10*89a63228SAndroid Build Coastguard Worker - Contains annotations to be included in the public SDK, for example 11*89a63228SAndroid Build Coastguard Worker annotations specifying additional details about method contracts. 12*89a63228SAndroid Build Coastguard Worker 13*89a63228SAndroid Build Coastguard Workerlibcore/ojluni/annotations/sdk/nullability: 14*89a63228SAndroid Build Coastguard Worker - Contains annotations to be included in the public SDK specifically 15*89a63228SAndroid Build Coastguard Worker relating to nullability. Adding an annotated stub file to this subdirectory 16*89a63228SAndroid Build Coastguard Worker will cause the annotations to be validated for correctness and completeness. 17*89a63228SAndroid Build Coastguard Worker - To add some new files under this directory: 18*89a63228SAndroid Build Coastguard Worker 1. make openjdk-sdk-stubs-no-javadoc 19*89a63228SAndroid Build Coastguard Worker 2. for FILE in your/package/and/Class.java another/package/AnotherClass.java; do unzip out/soong/.intermediates/libcore/openjdk-sdk-stubs-no-javadoc/android_common/metalava/openjdk-sdk-stubs-no-javadoc-stubs.srcjar ${FILE} -d libcore/ojluni/annotations/sdk/nullability/ && mv libcore/ojluni/annotations/sdk/nullability/$FILE libcore/ojluni/annotations/sdk/nullability/${FILE/%.java/.annotated.java}; done 20*89a63228SAndroid Build Coastguard Worker 3. Add nullability annotations to the new files. 21*89a63228SAndroid Build Coastguard Worker - To see the effect of the files under this directory: 22*89a63228SAndroid Build Coastguard Worker 1. m art.module.public.api.stubs.source-update-current-api 23*89a63228SAndroid Build Coastguard Worker 2. Look for the file under libcore/api/ 24*89a63228SAndroid Build Coastguard Worker 25*89a63228SAndroid Build Coastguard Workerlibcore/ojluni/annotations/flagged_api: 26*89a63228SAndroid Build Coastguard Worker - Contains @FlaggedApi annotations to be included in the core_current stubs. 27*89a63228SAndroid Build Coastguard Worker - To add some new files under this directory: 28*89a63228SAndroid Build Coastguard Worker 1. libcore/tools/ojluni-annotations/generate_flagged_api_files.sh your.package.Bar another.package.Foo 29*89a63228SAndroid Build Coastguard Worker 2. Add @FlaggedApi annotations to the new files. 30*89a63228SAndroid Build Coastguard Worker - To see the effect of the files under this directory: 31*89a63228SAndroid Build Coastguard Worker 1. m art.module.public.api.stubs.source-update-current-api 32*89a63228SAndroid Build Coastguard Worker 2. Look for the file under libcore/api/ 33*89a63228SAndroid Build Coastguard Worker 34*89a63228SAndroid Build Coastguard Workerlibcore/ojluni/annotations/mmodule: 35*89a63228SAndroid Build Coastguard Worker - Contains annotations which determine what is included in the core-platform 36*89a63228SAndroid Build Coastguard Worker and intra-core APIs. See the documentation in libcore/openjdk_java_files.bp. 37*89a63228SAndroid Build Coastguard Worker - To add some new files under this directory: 38*89a63228SAndroid Build Coastguard Worker 1. In libcore/openjdk_java_files.bp, move the files from the 39*89a63228SAndroid Build Coastguard Worker openjdk_internal_files filegroup to openjdk_mmodule_extra_files. *DO NOT* 40*89a63228SAndroid Build Coastguard Worker check in this change, it will have undesirable consequences until you 41*89a63228SAndroid Build Coastguard Worker reach step 4, below. 42*89a63228SAndroid Build Coastguard Worker 2. make openjdk-mmodule-stubs-no-javadoc 43*89a63228SAndroid Build Coastguard Worker 3. FILES="your/package/and/Class.java another/package/AnotherClass.java"; for FILE in $FILES; do mkdir -p libcore/ojluni/annotations/mmodule/$(dirname ${FILE}) && unzip out/soong/.intermediates/libcore/openjdk-mmodule-stubs-no-javadoc/android_common/metalava/openjdk-mmodule-stubs-no-javadoc-stubs.srcjar ${FILE} && mv ${FILE} libcore/ojluni/annotations/mmodule/${FILE/%.java/.annotated.java}; done 44*89a63228SAndroid Build Coastguard Worker 4. Add @libcore.api.Hide to each class, methods and fields in the new files. This will prevent it from being added to the public API. A JavaDoc @hide tag will not work as metalava will ignore javadoc from the stub files. 45*89a63228SAndroid Build Coastguard Worker 5. Add @android.annotation.SystemApi(client = MODULE_LIBRARIES) and @libcore.api.IntraCoreApi as desired 46*89a63228SAndroid Build Coastguard Worker to the classes and members. 47*89a63228SAndroid Build Coastguard Worker - To see the effect of the files under this directory: 48*89a63228SAndroid Build Coastguard Worker 1. make make core-platform-api-stubs core-intra-stubs 49*89a63228SAndroid Build Coastguard Worker 2. Look for the files under out/soong/.intermediates/libcore/mmodules/core_platform_api/core-platform-api-stubs/android_common/stubsDir/ and out/soong/.intermediates/libcore/mmodules/intracoreapi/core-intra-stubs/android_common/stubsDir 50