Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Configuration.props
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
<AndroidLatestStablePlatformId Condition="'$(AndroidLatestStablePlatformId)' == ''">37.0</AndroidLatestStablePlatformId>
<AndroidLatestStableFrameworkVersion Condition="'$(AndroidLatestStableFrameworkVersion)'==''">v17.0</AndroidLatestStableFrameworkVersion>
<!-- If there is a second *stable* API level (e.g. 38.1 alongside 38), set it here: -->
<AndroidLatestStableApiLevel2 Condition="'$(AndroidLatestStableApiLevel2)' == ''">37.1</AndroidLatestStableApiLevel2>
<AndroidLatestStableApiLevel2 Condition="'$(AndroidLatestStableApiLevel2)' == ''">37.2</AndroidLatestStableApiLevel2>
<!-- *Latest* *unstable* API level binding that we support; this can be the same as *stable* -->
<AndroidLatestUnstableApiLevel Condition="'$(AndroidLatestUnstableApiLevel)' == ''">37.2</AndroidLatestUnstableApiLevel>
<AndroidLatestUnstablePlatformId Condition="'$(AndroidLatestUnstablePlatformId)' == ''">37.2</AndroidLatestUnstablePlatformId>
Expand Down Expand Up @@ -56,7 +56,7 @@
<AndroidBuildApiLevel Include="37.2">
<PlatformId>37.2</PlatformId>
<FrameworkVersion>v17.2</FrameworkVersion>
<Unstable>true</Unstable>
<Unstable>false</Unstable>
Comment thread
jonathanpeppers marked this conversation as resolved.
Resolved
</AndroidBuildApiLevel>
</ItemGroup>
<PropertyGroup Condition=" '$(HostOS)' == '' ">
Expand Down
35 changes: 30 additions & 5 deletions Documentation/workflow/HowToAddNewApiLevel.md
Original file line number Diff line number Diff line change
Expand Up @@ -474,16 +474,39 @@ BindingStudio crashes.

The left tree view can be updated by saving and reopening the `map.csv` file.

Once `map.csv` has been updated, run the following command:
Once `map.csv` has been updated, run the following commands:

```sh
# BindingStudio currently produces a slightly different CSV format.
# "Update" to what's currently in git(1) to reduce diff size.
tr -d '\r' < src/Mono.Android/map.csv > src/Mono.Android/new-map.csv
sed 's/,$//' < src/Mono.Android/new-map.csv > src/Mono.Android/map.csv

# Check for two-letter package parts.
git grep '\.[A-Z][a-z]\.' src/Mono.Android/map.csv
```

This checks for any namespace-parts which are two letters long, the first letter is
upper-case, and the second letter is lower-case, e.g. `.Pm.`. These should be all
upper-case, e.g. `.PM.`.

See the next section on how to rename Java "package parts".

### PascalCase new namespaces

If you have the "Android API Differences Report", e.g.
[this one for API-37.2 vs. API-37.1](https://developer.android.com/sdk/api_diff/37.2/changes),
review the **Added Packages** section for *new* packages, and consider PascalCasing them.

PascalCasing namespaces requires changes to three places:

1. Add `<ns-replace/>` elements to [`src/Mono.Android/metadata`](../../src/Mono.Android/metadata).
2. [`src/Mono.Android/map.csv`](../../src/Mono.Android/map.csv) will need to be updated to match (1).
2. [`src/Mono.Android/methodmap.csv`](../../src/Mono.Android/methodmap.csv) will need to be updated to match (1).

As BindingStudio doesn't know about `<ns-replace/>`, it is recommended that namespace renames
be done after enum creation.

### Extract methods that possibly need enums

Using BindingStudio:
Expand Down Expand Up @@ -562,12 +585,14 @@ the `csv` variable within `MainForm.FindAPILevelMethodsToolStripMenuItem_Click`.
Once this process is complete, use `Tools` -> `Export Final Method Map`, and create a *new*
`.csv` file, e.g. `new-methodmap.csv`.

Note: `new-methodmap.csv` will likely use JNI syntax for package names, e.g. `android/widget`.
`methodmap.csv` ***must*** use *Java* syntax for package names, e.g. `android.widget`.
Use **sed**(1) to fix package names and nested class names:
Note: `new-methodmap.csv` will likely use JNI syntax for package names, e.g. `android/widget`,
and contain a leading action column. `methodmap.csv` ***must*** contain only the enumified rows,
without the action column, and use *Java* syntax for package names, e.g. `android.widget`.
Use **grep**(1) and **sed**(1) to normalize the output:

```sh
sed 's,/,.,g;s/\$/./g' < src/Mono.Android/new-methodmap.csv > src/Mono.Android/new-methodmap2.csv
grep '^E,' src/Mono.Android/new-methodmap.csv |
sed 's/^E,//;s,/,.,g;s/\$/./g' > src/Mono.Android/new-methodmap2.csv
```

Copy the contents of `new-methodmap2.csv` and *append* to `src/Mono.Android/methodmap.csv`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 💡 Documentation — Appending the generated block makes this workflow non-idempotent: rerunning it for the same API appends the same mappings again, and the uniq command below only removes adjacent duplicates, so it will not remove a duplicated block. Please either replace the existing API-level block or use an order-preserving whole-file deduplication step after appending.

Rule: Generation workflows should be repeatable

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is fine, it's a doc.

Expand Down
82 changes: 41 additions & 41 deletions build-tools/manifest-attribute-codegen/manifest-definition.xml
Original file line number Diff line number Diff line change
Expand Up @@ -95,14 +95,14 @@
<a name='resetEnabledSettingsOnAppDataCleared' format='boolean' api-level='33' />
<a name='knownActivityEmbeddingCerts' api-level='33' />
<a name='enableOnBackInvokedCallback' format='boolean' api-level='33' />
<a name='allowCrossUidActivitySwitchFromBelow' format='boolean' api-level='35' />
<a name='allowCrossUidActivitySwitchFromBelow' format='boolean' api-level='35-2' />
<a name='pageSizeCompat' api-level='36.1' />
<a name='intentMatchingFlags' api-level='36.1' />
<a name='alternateLauncherIcons' format='reference' api-level='36.1' />
<a name='alternateLauncherLabels' format='reference' api-level='36.1' />
<a name='backupAgentProcess' api-level='37.0' />
<a name='zygotePreloadNativeLib' api-level='37.0' />
<a name='zygotePreloadNativeFunc' api-level='37.0' />
<a name='backupAgentProcess' api-level='37.0-2' />
<a name='zygotePreloadNativeLib' api-level='37.0-2' />
<a name='zygotePreloadNativeFunc' api-level='37.0-2' />
</e>
<e name='permission' api-level='10'>
<parent>manifest</parent>
Expand All @@ -122,8 +122,8 @@
<a name='maxSdkVersion' api-level='34' />
<a name='requiresPurpose' format='boolean' api-level='36.1' />
<a name='requiresPurposeTargetSdkVersion' format='integer' api-level='36.1' />
<a name='requiresGeneralPurposeTargetSdkVersion' format='integer' api-level='37.0' />
<a name='requiresPurposeStringTargetSdkVersion' format='integer' api-level='37.0' />
<a name='requiresGeneralPurposeTargetSdkVersion' format='integer' api-level='37.0-2' />
<a name='requiresPurposeStringTargetSdkVersion' format='integer' api-level='37.0-2' />
</e>
<e name='permission-group' api-level='10'>
<parent>manifest</parent>
Expand Down Expand Up @@ -158,7 +158,7 @@
<a name='requiredNotFeature' format='string' api-level='26' />
<a name='usesPermissionFlags' api-level='31' />
<a name='minSdkVersion' format='integer|string' api-level='34' />
<a name='purposeString' format='reference' api-level='37.0' />
<a name='purposeString' format='reference' api-level='37.0-2' />
</e>
<e name='uses-configuration' api-level='10'>
<parent>manifest</parent>
Expand Down Expand Up @@ -233,9 +233,9 @@
<a name='splitName' api-level='26' />
<a name='forceUriPermissions' api-level='29' />
<a name='attributionTags' api-level='31' />
<a name='systemUserOnly' format='boolean' api-level='35' />
<a name='systemUserOnly' format='boolean' api-level='35-2' />
<a name='intentMatchingFlags' api-level='36.1' />
<a name='privateComputeCore' api-level='37.0' />
<a name='privateComputeCore' api-level='37.0-2' />
</e>
<e name='grant-uri-permission' api-level='10'>
<parent>provider</parent>
Expand Down Expand Up @@ -280,10 +280,10 @@
<a name='foregroundServiceType' api-level='29' />
<a name='attributionTags' api-level='31' />
<a name='allowSharedIsolatedProcess' format='boolean' api-level='34' />
<a name='systemUserOnly' format='boolean' api-level='35' />
<a name='systemUserOnly' format='boolean' api-level='35-2' />
<a name='intentMatchingFlags' api-level='36.1' />
<a name='privateComputeCore' api-level='37.0' />
<a name='nativeService' format='boolean' api-level='37.0' />
<a name='privateComputeCore' api-level='37.0-2' />
<a name='nativeService' format='boolean' api-level='37.0-2' />
</e>
<e name='receiver' api-level='10'>
<parent>application</parent>
Expand All @@ -302,7 +302,7 @@
<a name='roundIcon' api-level='25' />
<a name='attributionTags' api-level='31' />
<a name='intentMatchingFlags' api-level='36.1' />
<a name='privateComputeCore' api-level='37.0' />
<a name='privateComputeCore' api-level='37.0-2' />
</e>
<e name='activity' api-level='10'>
<parent>application</parent>
Expand Down Expand Up @@ -373,9 +373,9 @@
<a name='knownActivityEmbeddingCerts' api-level='33' />
<a name='requiredDisplayCategory' format='string' api-level='34' />
<a name='enableOnBackInvokedCallback' format='boolean' api-level='34' />
<a name='requireContentUriPermissionFromCaller' format='string' api-level='35' />
<a name='requireContentUriPermissionFromCaller' format='string' api-level='35-2' />
<a name='intentMatchingFlags' api-level='36.1' />
<a name='privateComputeCore' api-level='37.0' />
<a name='privateComputeCore' api-level='37.0-2' />
</e>
<e name='activity-alias' api-level='10'>
<parent>application</parent>
Expand All @@ -395,7 +395,7 @@
<a name='allowUntrustedActivityEmbedding' api-level='33' />
<a name='knownActivityEmbeddingCerts' api-level='33' />
<a name='intentMatchingFlags' api-level='36.1' />
<a name='privateComputeCore' api-level='37.0' />
<a name='privateComputeCore' api-level='37.0-2' />
</e>
<e name='meta-data' api-level='10'>
<parent>application</parent>
Expand Down Expand Up @@ -444,16 +444,16 @@
<a name='sspAdvancedPattern' format='string' api-level='31' />
<a name='sspSuffix' format='string' api-level='31' />
<a name='pathSuffix' api-level='31' />
<a name='query' format='string' api-level='35' />
<a name='queryPrefix' format='string' api-level='35' />
<a name='queryPattern' format='string' api-level='35' />
<a name='queryAdvancedPattern' format='string' api-level='35' />
<a name='querySuffix' format='string' api-level='35' />
<a name='fragment' format='string' api-level='35' />
<a name='fragmentPrefix' format='string' api-level='35' />
<a name='fragmentPattern' format='string' api-level='35' />
<a name='fragmentAdvancedPattern' format='string' api-level='35' />
<a name='fragmentSuffix' format='string' api-level='35' />
<a name='query' format='string' api-level='35-2' />
<a name='queryPrefix' format='string' api-level='35-2' />
<a name='queryPattern' format='string' api-level='35-2' />
<a name='queryAdvancedPattern' format='string' api-level='35-2' />
<a name='querySuffix' format='string' api-level='35-2' />
<a name='fragment' format='string' api-level='35-2' />
<a name='fragmentPrefix' format='string' api-level='35-2' />
<a name='fragmentPattern' format='string' api-level='35-2' />
<a name='fragmentAdvancedPattern' format='string' api-level='35-2' />
<a name='fragmentSuffix' format='string' api-level='35-2' />
</e>
<e name='category' api-level='10'>
<parent>intent-filter</parent>
Expand Down Expand Up @@ -618,7 +618,7 @@
<a name='memtagMode' api-level='31' />
<a name='nativeHeapZeroInitialized' api-level='31' />
<a name='name' api-level='33' />
<a name='useEmbeddedDex' api-level='35' />
<a name='useEmbeddedDex' api-level='35-2' />
<a name='singleUser' api-level='37.1' />
</e>
<e name='deny-permission' api-level='30'>
Expand Down Expand Up @@ -660,7 +660,7 @@
<a name='name' api-level='33' />
<a name='versionMajor' format='integer' api-level='33' />
<a name='certDigest' format='string' api-level='33' />
<a name='optional' format='boolean' api-level='35' />
<a name='optional' format='boolean' api-level='35-2' />
</e>
<e name='apex-system-service' api-level='33'>
<parent>application</parent>
Expand All @@ -677,9 +677,9 @@
<parent>install-constraints</parent>
<a name='value' api-level='34' />
</e>
<e name='uri-relative-filter-group' api-level='35'>
<e name='uri-relative-filter-group' api-level='35-2'>
<parent>intent-filter</parent>
<a name='allow' format='boolean' api-level='35' />
<a name='allow' format='boolean' api-level='35-2' />
</e>
<e name='valid-purpose' api-level='36.1'>
<parent>permission</parent>
Expand All @@ -696,24 +696,24 @@
<parent>manifest</parent>
<a name='name' api-level='36.1' />
</e>
<e name='valid-general-purpose' api-level='37.0'>
<e name='valid-general-purpose' api-level='37.0-2'>
<parent>permission</parent>
<a name='name' format='string' api-level='37.0' />
<a name='maxTargetSdkVersion' format='integer' api-level='37.0' />
<a name='name' format='string' api-level='37.0-2' />
<a name='maxTargetSdkVersion' format='integer' api-level='37.0-2' />
</e>
<e name='general-purpose' api-level='37.0'>
<e name='general-purpose' api-level='37.0-2'>
<parent>uses-permission</parent>
<a name='name' format='string' api-level='37.0' />
<a name='minSdkVersion' format='integer|string' api-level='37.0' />
<a name='maxSdkVersion' format='integer' api-level='37.0' />
<a name='name' format='string' api-level='37.0-2' />
<a name='minSdkVersion' format='integer|string' api-level='37.0-2' />
<a name='maxSdkVersion' format='integer' api-level='37.0-2' />
</e>
<e name='allow-component-access' api-level='37.0'>
<e name='allow-component-access' api-level='37.0-2'>
<parent>manifest</parent>
</e>
<e name='allow-component-access-package' api-level='37.0'>
<e name='allow-component-access-package' api-level='37.0-2'>
<parent>allow-component-access</parent>
<a name='name' api-level='37.0' />
<a name='certDigest' format='string' api-level='37.0' />
<a name='name' api-level='37.0-2' />
<a name='certDigest' format='string' api-level='37.0-2' />
</e>
<e name='memory-budget' api-level='37.1'>
<parent>application</parent>
Expand Down
Loading
Loading