@@ -36,14 +36,17 @@ dependencies on Android) provides solutions for each of these problems.
3636## Android Dependency Management
3737
3838The * Android Resolver* component of this plugin will download and integrate
39- Android libraries and handle any conflicts between plugins using shared
40- libraries. For example, if a Unity plugin ` SomePlugin ` requires the Google
41- Play Games Android library and redistributes this library and its transitive
42- dependencies in the folder ` SomePlugin/Android/ ` when a user imports
43- ` SomeOtherPlugin ` that includes the same libraries (potentially at a different
44- version) in ` SomeOtherPlugin/Android/ ` the developer using ` SomePlugin ` and
45- ` SomeOtherPlugin ` will see a hard to interpret build error when building for
46- Android.
39+ Android library dependencies and handle any conflicts between plugins that share
40+ the same dependencies.
41+ 42+ Without the Android Resolver, typically Unity plugins bundle their AAR and
43+ JAR dependencies, e.g. a Unity plugin ` SomePlugin ` that requires the Google
44+ Play Games Android library would redistribute the library and its transitive
45+ dependencies in the folder ` SomePlugin/Android/ ` . When a user imports
46+ ` SomeOtherPlugin ` that includes the same libraries (potentially at different
47+ versions) in ` SomeOtherPlugin/Android/ ` , the developer using ` SomePlugin ` and
48+ ` SomeOtherPlugin ` will see an error when building for Android that can be hard
49+ to interpret.
4750
4851Using the Android Resolver to manage Android library dependencies:
4952
@@ -95,12 +98,12 @@ The Version Handler solves the problem of managing transitive dependencies by:
9598
9699When using the Version Handler to manage ` Play Services Resolver ` included in
97100` SomePlugin ` and ` SomeOtherPlugin ` , from the prior example, version 1.2 will
98- always be actived in a developers Unity project.
101+ always be the version activated in a developer's Unity project.
99102
100103Plugin creators are encouraged to adopt this library to ease integration for
101- their customers. For more information about integrating in other plugins
102- see the [ Plugin Redistribution] ( #plugin-redistribution ) section of this
103- document.
104+ their customers. For more information about integrating Play Services Resolver
105+ into your own plugin, see the [ Plugin Redistribution] ( #plugin-redistribution )
106+ section of this document.
104107
105108# Requirements
106109
@@ -110,26 +113,80 @@ Unity version 4.6.8 or higher.
110113The * Version Handler* component only works with Unity 5.x or higher as it
111114depends upon the ` PluginImporter ` UnityEditor API.
112115
113- # Android Resolver
116+ # Getting Started
117+ 118+ Before you import the Play Services Resolver into your plugin project, you first
119+ need to consider whether you intend to * redistribute* Play Services Resolver
120+ along with your own plugin.
121+ 122+ Redistributing the ` Play Services Resolver ` inside your own plugin will ease
123+ the integration process for your users, by resolving dependency conflicts
124+ between your plugin and other plugins in a user's project.
125+ 126+ If you wish to redistribute the ` Play Services Resolver ` inside your plugin,
127+ you ** must** follow these steps when importing the
128+ ` play-services-resolver-*.unitypackage ` , and when exporting your own plugin
129+ package:
130+ 131+ 1 . Import the ` play-services-resolver-*.unitypackage ` into your plugin
132+ project by
133+ [ running Unity from the command line] ( https://docs.unity3d.com/Manual/CommandLineArguments.html ) , ensuring that
134+ you add the ` -gvh_disable ` option.
135+ 1 . Export your plugin by [ running Unity from the command line] ( https://docs.unity3d.com/Manual/CommandLineArguments.html ) , ensuring that
136+ you:
137+ - Include the contents of the ` Assets/PlayServicesResolver ` directory.
138+ - Add the ` -gvh_disable ` option.
139+ 140+ You ** must** specify the ` -gvh_disable ` option in order for the Version
141+ Handler to work correctly!
142+ 143+ For example, the following command will import the
144+ ` play-services-resolver-1.2.46.0.unitypackage ` into the project
145+ ` MyPluginProject ` and export the entire Assets folder to
146+ ` MyPlugin.unitypackage ` :
147+ 148+ ```
149+ Unity -gvh_disable \
150+ -batchmode \
151+ -importPackage play-services-resolver-1.2.46.0.unitypackage \
152+ -projectPath MyPluginProject \
153+ -exportPackage Assets MyPlugin.unitypackage \
154+ -quit
155+ ```
156+ 157+ ## Background
158+ 159+ The * Version Handler* component relies upon deferring the load of editor DLLs
160+ so that it can run first and determine the latest version of a plugin component
161+ to activate. The build of the ` Play Services Resolver ` plugin has Unity asset
162+ metadata that is configured so that the editor components are not
163+ initially enabled when it's imported into a Unity project. To maintain this
164+ configuration when importing the ` Play Services Resolver ` .unitypackage
165+ into a Unity plugin project, you * must* specify the command line option
166+ ` -gvh_disable ` which will prevent the Version Handler component from running and
167+ changing the Unity asset metadata.
168+ 169+ # Android Resolver Usage
114170
115171The Android Resolver copies specified dependencies from local or remote Maven
116172repositories into the Unity project when a user selects Android as the build
117173target in the Unity editor.
118174
119- ## Usage
175+ 1 . Add the ` play-services-resolver-*.unitypackage ` to your plugin
176+ project (assuming you are developing a plugin). If you are redistributing
177+ the Play Services Resolver with your plugin, you ** must** follow the
178+ import steps in the [ Getting Started] ( #getting-started ) section!
120179
121- 1 . Add the unitypackage to your plugin project (assuming you are developing a
122- plugin). Please read the [ Plugin Redistribution] ( #plugin-redistribution )
123- section when you're considering how to export your package to share with
124- your users.
125- 126- 2 . Copy and rename the SampleDependencies.xml file into your
180+ 2 . Copy and rename the ` SampleDependencies.xml ` file into your
127181 plugin and add the dependencies your plugin requires.
128182
129183 The XML file just needs to be under an ` Editor ` directory and match the
130184 name ` *Dependencies.xml ` . For example,
131185 ` MyPlugin/Editor/MyPluginDependencies.xml ` .
132186
187+ 3 . Follow the steps in the [ Getting Started] ( #getting-started )
188+ section when you are exporting your plugin package.
189+ 133190For example, to add the Google Play Games library
134191(` com.google.android.gms:play-services-games ` package) at version ` 9.8.0 ` to
135192the set of a plugin's Android dependencies:
@@ -172,8 +229,9 @@ element:
172229## Auto-resolution
173230
174231By default the Android Resolver automatically monitors the dependencies you have
175- specified and the ` Plugins/Android ` folder of your Unity project running the
176- resolution process when specified dependencies are not present in your project.
232+ specified and the ` Plugins/Android ` folder of your Unity project. The
233+ resolution process runs when the specified dependencies are not present in your
234+ project.
177235
178236The * auto-resolution* process can be disabled via the
179237` Assets > Play Services Resolver > Android Resolver > Settings ` menu.
@@ -189,8 +247,8 @@ Some AAR files (for example play-services-measurement) contain variables that
189247are processed by the Android Gradle plugin. Unfortunately, Unity does not
190248perform the same processing when using Unity's Internal Build System, so the
191249Android Resolver plugin handles known cases of this variable substition
192- by exploding the AAR into a folder and replacing ${applicationId} with the
193- bundleID.
250+ by exploding the AAR into a folder and replacing ` ${applicationId} ` with the
251+ ` bundleID ` .
194252
195253Disabling AAR explosion and therefore Android manifest processing can be done
196254via the ` Assets > Play Services Resolver > Android Resolver > Settings ` menu.
@@ -222,7 +280,7 @@ build system and Gradle / Android Studio project export.
222280Also, the Android Resolver supports an * experimental* Gradle prebuild mode to
223281provide minification without exporting to a Gradle / Android Studio project.
224282For more information about this mode see
225- [ gradle_prebuild.md] ( gralde_prebuild .md) .
283+ [ gradle_prebuild.md] ( gradle_prebuild .md) .
226284
227285It's possible to change the resolution strategy via the
228286` Assets > Play Services Resolver > Android Resolver > Settings ` menu.
@@ -234,21 +292,19 @@ The Android Resolver creates the
234292of resolved dependencies in a project. This is used by the auto-resolution
235293process to only run the expensive resolution process when necessary.
236294
237- # iOS Resolver
295+ # iOS Resolver Usage
238296
239297The iOS resolver component of this plugin manages
240298[ CocoaPods] ( https://cocoapods.org/ ) . A CocoaPods ` Podfile ` is generated and
241299the ` pod ` tool is executed as a post build process step to add dependencies
242300to the Xcode project exported by Unity.
243301
244- ## Usage
245- 246302Dependencies for iOS are added by referring to CocoaPods.
247303
248- 1 . Add the unitypackage to your plugin project (assuming you are developing a
249- plugin). Please read the [ Plugin Redistribution ] ( # plugin-redistribution )
250- section when you're considering how to export your package to share with
251- your users.
304+ 1 . Add the ` play-services-resolver-*. unitypackage` to your plugin
305+ project (assuming you are developing a plugin). If you are redistributing
306+ the Play Services Resolver with your plugin, you ** must ** follow the
307+ import steps in the [ Getting Started ] ( #getting-started ) section!
252308
253309 2 . Copy and rename the SampleDependencies.xml file into your
254310 plugin and add the dependencies your plugin requires.
@@ -257,6 +313,9 @@ Dependencies for iOS are added by referring to CocoaPods.
257313 name ` *Dependencies.xml ` . For example,
258314 ` MyPlugin/Editor/MyPluginDependencies.xml ` .
259315
316+ 3 . Follow the steps in the [ Getting Started] ( #getting-started )
317+ section when you are exporting your plugin package.
318+ 260319For example, to add the AdMob pod, version 7.0 or greater with bitcode enabled:
261320
262321```
@@ -280,15 +339,13 @@ The `CocoaPods` are either:
280339The resolution strategy can be changed via the
281340` Assets > Play Services Resolver > Android Resolver > Settings ` menu.
282341
283- # Version Handler
342+ # Version Handler Usage
284343
285344The Version Handler component of this plugin manages:
286345* Shared Unity plugin dependencies.
287346* Upgrading Unity plugins by cleaning up old files from previous versions.
288347
289- ## Usage
290- 291- Unity plugins can be managed by the ` Version Handler ` using the following steps:
348+ Unity plugins can be managed by the Version Handler using the following steps:
292349
293350 1 . Add the ` gvh ` asset label to each asset (file) you want Version Handler
294351 to manage.
@@ -298,13 +355,13 @@ Unity plugins can be managed by the `Version Handler` using the following steps:
298355 plugin and disable ` editor ` as a target platform for the DLL.
299356 The Version Handler will enable the most recent version of this DLL when
300357 the plugin is imported.
301- 1 . Optional: If your plugin is included in other Unity plugins you should
358+ 1 . Optional: If your plugin is included in other Unity plugins, you should
302359 add the version number to each filename and change the GUID of each asset.
303360 This allows multiple versions of your plugin to be imported into a Unity
304- project and the Version Handler component to activate the most recent
305- version.
361+ project, with the Version Handler component activating only the most
362+ recent version.
306363 1 . Create a manifest text file named ` MY_UNIQUE_PLUGIN_NAME_VERSION.txt `
307- that lists all files in your plugin relative to the project root.
364+ that lists all the files in your plugin relative to the project root.
308365 Then add the ` gvh_manifest ` label to the asset to indicate this file is
309366 a plugin manifest.
310367 1 . Redistribute the ` Play Services Resolver ` Unity plugin with your plugin.
@@ -318,31 +375,6 @@ If you follow these steps:
318375 multiple packages that include your plugin, assuming the steps in
319376 [ Plugin Redistribution] ( #plugin-redistribution ) are followed.
320377
321- # Plugin Redistribution
322- 323- The * Version Handler* component relies upon deferring the load of editor DLLs
324- so that it can run and determine the latest version of a plugin component to
325- activate. The build of the ` Play Services Resolver ` plugin has Unity asset
326- metadata that is configured to so that the all editor components are not
327- initially enabled when it's imported into a Unity project. To maintain this
328- configuration when importing the ` Play Services Resolver ` .unitypackage file
329- into a Unity plugin you * must* specify the command line option ` -gvh_disable `
330- which will prevent the Version Handler component from running and changing the
331- Unity asset metadata.
332- 333- For example, the following will import the
334- ` play-services-resolver-1.2.46.0.unitypackage ` into the project ` pathToPlugin `
335- and export the whole project to ` MyPlugin.unitypackage ` .
336- 337- ```
338- Unity -gvh_disable \
339- -batchmode \
340- -importPackage \
341- -projectPath pathToPlugin \
342- -exportPackage Assets MyPlugin.unitypackage \
343- -quit
344- ```
345- 346378## Building from Source
347379
348380To build this plugin from source you need the following tools installed:
0 commit comments