@@ -54,13 +54,174 @@ acceptable "breaks":
5454
5555When Google announces that the APIs are frozen, additional work such as enumification is needed.
5656
57- ---- Somewhat outdated docs below, update when we do this year's stabilization ----
57+ There have been many, many attempts to "automate" the enumification process in the past, to varying
58+ degrees of success. The main problem is that no automated process is going to be perfect, so
59+ they all rely on a human verifying and modifying the results.
60+
61+ However this verification process is long and tedious. Doing it correctly requires almost as much
62+ effort as doing the full process manually. Thus it generally isn't done correctly and many errors
63+ slip in, leaving our users with bad bindings that are hard to fix in the future without breaking API.
64+
65+ Currently we have taken the opposite approach and do the process completely manually, but we
66+ have invested in tooling to make the process as easy as possible.
67+
68+ This tooling is BindingStudio:
69+ https://github.com/jpobst/BindingStudio
70+
71+ It's a Winforms app, so it only runs on Windows. It's ugly as sin, and has very poor UX. However,
72+ it prompts you with the exact decisions you need to make, and handles as much dirty work as possible,
73+ allowing enumification to be done in a few days.
74+
75+ ### Extract constants from API
76+
77+ Using BindingStudio:
78+
79+ - Update ` CURRENT_API_LEVEL ` in MainForm.cs
80+ - Choose ` Tools ` -> ` Add API Level Constants `
81+ - Fill in existing ` map.csv ` : ` xamarin-android/src/Mono.Android/map.csv `
82+ - Fill in new ` api.xml ` : ex: ` xamarin-android/src/Mono.Android/obj/Debug/net6.0/android-32/mcw/api.xml `
83+ - Choose ` File ` -> ` Save `
84+
85+ This adds all the new possible constants from the API level to ` map.csv ` . They will be
86+ marked with a ` ? ` indicating no determination has been made if they should be enumified or not.
87+
88+ Example:
89+ ```
90+ ?,32,android/media/Spatializer.SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL,1,,,,
91+ ?,32,android/media/Spatializer.SPATIALIZER_IMMERSIVE_LEVEL_NONE,0,,,,
92+ ?,32,android/media/Spatializer.SPATIALIZER_IMMERSIVE_LEVEL_OTHER,-1,,,,
93+ ```
94+
95+ ### Creating enums
96+
97+ Using BindingStudio:
98+
99+ - Choose ` File ` -> ` Open Constant Map `
100+ - Choose existing ` map.csv ` : ` xamarin-android/src/Mono.Android/map.csv `
101+
102+ The left tree view will be populated with every type that has possible constants that require
103+ a decision. Clicking a tree node will show the grid of all constants in the type. The ones
104+ that need to be handled are the ones with ` Action ` = ` None ` . (The others are shown because
105+ sometimes the correct action is to add a new constant to an existing enum.)
106+
107+ Select the row(s) containing the constants you want to act on. (Use Control and Shift to select
108+ multiple rows.) There are 3 possible options for constants:
109+
110+ 1 ) Ignore
111+
112+ If the constant(s) should not be part of an enum (like ` Math.PI ` ), click the ` Ignore ` toolbar
113+ button to leave them as constants.
114+
115+ 2 ) Add to existing enum
116+
117+ If the constant(s) should be added to an existing enum:
118+ - Click the ` Add to existing enum ` toolbar button.
119+ - The dialog will show all other enums in this type
120+ - Choose the existing enum to add the new constant(s) to
121+ - After accepting the dialog, you may need to click the grid to cause it to refresh
122+ - The constant(s) will be marked as ` Enumify ` with the ` EnumFullType ` you specified
123+ - The enum member names may need to be tweaked by changing the ` EnumMember ` column
124+
125+ 3 ) Create a new enum
126+
127+ If the constant(s) should be added to a brand new enum:
128+ - Click the ` Create Enum ` toolbar button
129+ - In the dialog, a suggested enum namespace and name will be pre-populated. This may need to be
130+ tweaked as needed.
131+ - Mark ` Is Flags ` if this should be a ` [Flags] ` enum type.
132+ - After accepting the dialog, you may need to click the grid to cause it to refresh
133+ - The constant(s) will be marked as ` Enumify ` with the ` EnumFullType ` you specified
134+ - The enum member names may need to be tweaked by changing the ` EnumMember ` column
135+
136+ Once decisions have been made for all new constants in a type, use the left tree view to move
137+ to the next type. You should periodically save your progress with ` File ` -> ` Save ` in case
138+ BindingStudio crashes.
139+
140+ The left tree view can be updated by saving and reopening the ` map.csv ` file.
141+
142+ ### Extract methods that possibly need enums
58143
59- 5 ) enumification
144+ Using BindingStudio:
60145
61- See ` build-tools/enumification-helpers/README ` . Usually it takes many days to complete...
146+ - Update the file paths in ` MainForm.FindAPILevelMethodsToolStripMenuItem_Click `
147+ - Run BindingStudio and choose ` Tools ` -> ` Find API Level Methods `
62148
63- Enumification work can be delayed and only the final API has to be enumified.
149+ This will create a file of every method in the new API level that takes an ` int ` as a parameter
150+ or returns an ` int ` as a return value. Each method will be marked with a ` ? ` in the file
151+ to indicate a decision needs to be made to ignore it or map it to an enum.
152+
153+ Example:
154+ ```
155+ ?,32,android/media,AudioAttributes,getSpatializationBehavior,return,
156+ ?,32,android/media,AudioAttributes$Builder,setSpatializationBehavior,sb,
157+ ```
158+
159+ ### Mapping methods
160+
161+ Using BindingStudio:
162+
163+ - Choose ` File ` -> ` Open Constant Map `
164+ - Choose existing ` map.csv ` : ` xamarin-android/src/Mono.Android/map.csv `
165+ - Choose ` File ` -> ` Open Method Map `
166+ - Choose the new ` .csv ` created in the previous step
167+
168+ The left tree will populate with every method that possibly should be enumified and
169+ needs a decision to be made. Clicking a method shows the Android documentation for
170+ the method to help make the decision, as well as an area to input the decision.
171+
172+ Note a method may show up multiple times, once for each parameter or return type
173+ (Parameter Name = "return") that is an int. Each one may require a different action.
174+
175+ There are 3 possible options for a method parameter/return type:
176+
177+ 1 ) Unknown
178+
179+ You don't how to handle this method currently, so leaving it in the initial state
180+ of "Unknown" will leave it alone until a decision can be made.
181+
182+ 2 ) Ignore
183+
184+ The method parameter/return type should remain an ` int ` and not be converted to an enum.
185+
186+ Ex:
187+ ```
188+ int Add (int value1, int value2) { ... }
189+ ```
190+
191+ Click the "Ignore" radio button and then the "Save" button.
192+
193+ 3 ) Enumify
194+
195+ The method parameter/return type should be changed to an enum.
196+
197+ Ex:
198+ ```
199+ void AudioAttributesBuilder.SetSpatializationBehavior (int sb) { ... }
200+ ```
201+
202+ - Choose the "Enumify" radio option
203+ - Use the DropDown in the middle to select the enum to use
204+ - When selected, the members of that enum will be shown in the box below the enum
205+ - Alternatively, search for a enum by enum member name using the Search box in the right
206+ - If desired enum is found, clicking it will populate dropdown
207+ - Click "Save"
208+
209+ Use ` File ` -> ` Save ` to save your work often!
210+
211+ ### Finishing the method map
212+
213+ The official ` methodmap.csv ` uses a slightly different format than the one used for enumification.
214+
215+ Using BindingStudio:
216+ - Ensure the "new api level method map" CSV file is loaded.
217+ - Choose ` Tools ` -> ` Export Final Method Map `
218+ - Choose a temporary file name
219+ - Open the temporary file, copy the contents to the bottom of the official:
220+ - xamarin-android/src/Mono.Android/methodmap.csv
221+
222+ Congrats! Enumification is complete!
223+
224+ ---- Somewhat outdated docs below, update when we do this year's stabilization ----
64225
652266 ) new AndroidManifest.xml elements and attributes
66227
0 commit comments