updates documentation with Extension description and UPM mode for pak…

…et-unity

docs/Unity.md

@@ -8,10 +8,45 @@ Tasks
 
 The `paket-unity` plugin adds a few tasks that will hook themself onto `paket-get`
 
-| Task name           | Depends on          | Type                                                | Description |
-| ------------------- | ------------------- | --------------------------------------------------- | ----------- |
-| paketUnityInstall   | | `wooga.gradle.paket.unity.tasks.PaketUnityInstall`  | Installs the dependencies into the Unity3d project
+| Task name         | Depends on | Type                                               | Description                                        |
+|-------------------|------------|----------------------------------------------------|----------------------------------------------------|
+| paketUnityInstall |            | `wooga.gradle.paket.unity.tasks.PaketUnityInstall` | Installs the dependencies into the Unity3d project |
 
-The `paketUnityInstall` will configure itself as a [`finalizedBy`][gradle_finalizedBy] task for `paketInstall`, `paketRestore` and `paketUpdate`. There is no need to call this task manually. The task also gets skipped when no `paket.unity3d.references` file can be found anywhere in the project directory tree.
+The `paketUnityInstall` will configure itself as a [`finalizedBy`][gradle_finalizedBy] task
+for `paketInstall`, `paketRestore` and `paketUpdate`. There is no need to call this task manually. The task also gets
+skipped when no `paket.unity3d.references` file can be found anywhere in the project directory tree.
+
+
+Extension
+---------
+
+The `paketUnity` extension provided by the plugin can be used for configuration. It has all properties
+from `PaketPluginExtension`, plus the ones below:
+
+| Property                       | Type                                    | Description                                                                                     |
+|--------------------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------|
+| paketReferenceFiles            | `FileCollection` (Read only)            | A list of all `paket.unity3D.references` files                                                  |
+| paketOutputDirectoryName       | `String`                                | Output directory for the paket installation. Relative to `<unity_project>/Assets`.              |
+| assemblyDefinitionFileStrategy | `AssemblyDefinitionFileStrategy` (Enum) | Strategy regarding assemble definition files.                                                   |
+| includeAssemblyDefinitions     | `Boolean`                               | Whether assembly definition files should be included during installation.                       |
+| paketUpmPackageEnabled         | `Property<Boolean>`                     | Enables/Disables UPM package mode.                                                              |
+| paketUpmPackageManifests       | `MapProperty<String, Map>`              | Maps `[paketName: upmPackageManifestMap]` for package.json files generated in UPM package mode. |
+
+
+UPM mode
+--------
+
+Paket packages can also be configured to be installed as UPM packages. This can be useful when your paket package
+contains an UPM one (with a `package.json` file).
+This mode sets the installation directory (`paketOutputDirectoryName`) to the unity project's `Packages` folder, and
+ensures that the `package.json`
+file for each dependency is in the installed package root.
+
+If an installed package is not UPM-compatible, that is, it doesn't have a `package.json` file, such file will be created. 
+By default, a `package.json` is generated with `com.wooga.nuget.${paketPackage.toLowerCase()}` name, and version `0.0.0`, 
+but those can be overridden and more properties can be added on using the mappings in `paketUpmPacakgeJson`. 
+
+UPM mode can be enabled through the `paketUpmPackageEnabled` property, or using the `paketUnity.enablePaketUpmPackages()` extension
+method. It is disabled by default.
 
 [gradle_finalizedBy]:   https://docs.gradle.org/3.5/dsl/org.gradle.api.Task.html#org.gradle.api.Task:finalizedBy

src/integrationTest/groovy/wooga/gradle/paket/unity/PaketUnityIntegrationSpec.groovy

@@ -27,7 +27,6 @@ import wooga.gradle.extensions.PaketDependencyInterceptor
 import wooga.gradle.paket.get.PaketGetPlugin
 import wooga.gradle.paket.unity.fixtures.PaketFixturesTrait
 import wooga.gradle.paket.unity.tasks.PaketUnityInstall
-import wooga.gradle.paket.unity.tasks.PaketUnwrapUPMPackages
 
 class PaketUnityIntegrationSpec extends IntegrationSpec implements PaketFixturesTrait {
 
@@ -294,7 +293,7 @@ class PaketUnityIntegrationSpec extends IntegrationSpec implements PaketFixtures
             paketUnity {
                 paketUpmPackageEnabled = $paketUpmPackageEnabled
                 ${overrides ?
-                "paketUpmPackageJson = ['test': ${PropertyUtils.wrapValueBasedOnType(overrides, Map)}]" :
+                "paketUpmPackageManifests = ['test': ${PropertyUtils.wrapValueBasedOnType(overrides, Map)}]" :
                 ""
         }
             }
@@ -306,23 +305,23 @@ class PaketUnityIntegrationSpec extends IntegrationSpec implements PaketFixtures
         then:
         result.success
         def pkgJsonFile = new File(pktUnityInstallDir, "package.json")
-        if (hasPackageJson) {
+        if (hasPackageManifest) {
             pkgJsonFile.file
             manifestJson.file
             def pkgJson = new JsonSlurper().parse(pkgJsonFile) as Map<String, Object>
             pkgJson['name'] == (overrides?.get('name') ?: "com.wooga.nuget.${pktUnityInstallDir.name.toLowerCase()}")
-            pkgJson.entrySet().containsAll(overrides?.entrySet()?: [:])
+            pkgJson.entrySet().containsAll(overrides?.entrySet() ?: [:])
         } else {
             !pkgJsonFile.file
             !manifestJson.file
         }
 
         where:
-        paketUpmPackageEnabled | hasPackageJson | overrides                 | msg
-        true                   | true           | null                      | "has"
-        true                   | true           | [name: "com.custom.name"] | "has"
-        true                   | true           | [custom: "customfield"]   | "has"
-        false                  | false          | null                      | "hasn't"
+        paketUpmPackageEnabled | hasPackageManifest | overrides                 | msg
+        true                   | true               | null                      | "has"
+        true                   | true               | [name: "com.custom.name"] | "has"
+        true                   | true               | [custom: "customfield"]   | "has"
+        false                  | false              | null                      | "hasn't"
     }
 
     private void setupPaketProject(dependencyName, unityProjectName) {

src/main/groovy/wooga/gradle/paket/unity/PaketUnityPlugin.groovy

@@ -86,7 +86,7 @@ class PaketUnityPlugin implements Plugin<Project> {
                 t.lockFile = extension.getPaketLockFile()
                 t.referencesFile = referenceFile
                 t.paketUpmPackageEnabled.convention(extension.paketUpmPackageEnabled)
-                t.paketUpmPackageJson.convention(extension.paketUpmPackageJson)
+                t.paketUpmPackageManifests.convention(extension.paketUpmPackageManifests)
             }
             return installProvider
         }

src/main/groovy/wooga/gradle/paket/unity/PaketUpmPackageSpec.groovy

@@ -9,25 +9,26 @@ import org.gradle.api.tasks.Optional
 
 trait PaketUpmPackageSpec implements BaseSpec {
 
+    private final MapProperty<String, Map<String, Object>> paketUpmPackageManifests = objects.mapProperty(String, Map)
+
     /**
-     *
+     * Map [<paket_package_name>: <upm_manifest_contents>] that overrides the contents of generated package.json files in UPM package mode.
      */
-    private final MapProperty<String, Map<String, Object>> paketUpmPackageJson = objects.mapProperty(String, Map)
-
     @Input
     @Optional
-    MapProperty<String, Map<String, Object>> getPaketUpmPackageJson() {
-        return paketUpmPackageJson
+    MapProperty<String, Map<String, Object>> getPaketUpmPackageManifests() {
+        return paketUpmPackageManifests
     }
 
-    void setPaketUpmPackageJson(Map paketUpmPackages) {
-        this.paketUpmPackageJson.set(paketUpmPackages)
+    void setPaketUpmPackageManifests(Map paketUpmPackages) {
+        this.paketUpmPackageManifests.set(paketUpmPackages)
     }
 
-    void setPaketUpmPackageJson(Provider<Map<String, String>> paketUpmPackages) {
-        this.paketUpmPackageJson.set(paketUpmPackages)
+    void setPaketUpmPackageManifests(Provider<Map<String, String>> paketUpmPackages) {
+        this.paketUpmPackageManifests.set(paketUpmPackages)
     }
 
+
     private final Property<Boolean> paketUpmPackageEnabled = objects.property(Boolean)
 
     /**
@@ -39,15 +40,14 @@ trait PaketUpmPackageSpec implements BaseSpec {
      * {@code paketUpmPackages} property. If a mapping is not found there,
      * a generic 'com.wooga.nuget.<paket-package-name>' name will be used.
      * <br>
-     * <br>
-     * This mode only works with PackageManagerSystem == paket, and throws otherwise.
-     *
-     * @throws {@code java.lang.IllegalStateException if PackageManagerSystem != paket}
      */
     void enablePaketUpmPackages() {
         paketUpmPackageEnabled.set(true)
     }
 
+    /**
+     * Enables/Disables "UPM package mode" for paket. See {@code PaketUpmPackageSpec::enablePaketUpmPackages} for more details.
+     */
     @Input
     @Optional
     Property<Boolean> getPaketUpmPackageEnabled() {

src/main/groovy/wooga/gradle/paket/unity/internal/UPMPaketPackage.groovy

@@ -12,23 +12,23 @@ class UPMPaketPackage {
         this.name = baseDir.name
     }
 
-    Optional<File> getPackageDotJson() {
+    Optional<File> getPackageManifest() {
         return Optional.ofNullable(new File(baseDir, "package.json")).map {
             it.exists()? it : null
         }
     }
 
-    File writePackageJson(Map<String, Object> contents) {
-        return writePackageJson(baseDir, contents)
+    File writePackageManifest(Map<String, Object> contents) {
+        return writePackageManifest(baseDir, contents)
     }
 
-    static File writePackageJson(File baseDir, Map<String, Object> contents) {
+    static File writePackageManifest(File baseDir, Map<String, Object> contents) {
         def createdPkgJson = new File(baseDir, "package.json")
         createdPkgJson << JsonOutput.prettyPrint(JsonOutput.toJson(contents))
         return createdPkgJson
     }
 
-    static Map<String, Object> basicUPMPackageJson(String packageName, Map<String, Object> overrides = [:]) {
+    static Map<String, Object> basicUPMPackageManifest(String packageName, Map<String, Object> overrides = [:]) {
         Map<String, Object> base = [
                 name: packageName,
                 version: "0.0.0"

src/main/groovy/wooga/gradle/paket/unity/tasks/PaketUnityInstall.groovy

@@ -134,7 +134,7 @@ class PaketUnityInstall extends ConventionTask implements PaketUpmPackageSpec {
                 def packages = locks.getAllDependencies(references.nugets).collect {
                     new File(outputDirectory, it)
                 }
-                packages.each { createPackageDotJsonIfNotExists(it) }
+                packages.each { createPackageManifestIfNotExists(it) }
             }
         }
     }
@@ -208,14 +208,14 @@ class PaketUnityInstall extends ConventionTask implements PaketUpmPackageSpec {
         })
     }
 
-    protected void createPackageDotJsonIfNotExists(File packageDir) {
+    protected void createPackageManifestIfNotExists(File packageDir) {
         def upmPaket = new UPMPaketPackage(packageDir)
-        if(packageDir.exists() && !upmPaket.packageDotJson.present) {
+        if(packageDir.exists() && !upmPaket.packageManifest.present) {
 
-            def pkgJsonOverrides = paketUpmPackageJson.getting(upmPaket.name).getOrElse([:])
-            def pkgJson = UPMPaketPackage.basicUPMPackageJson("com.wooga.nuget.${upmPaket.name.toLowerCase()}", pkgJsonOverrides)
+            def pkgJsonOverrides = paketUpmPackageManifests.getting(upmPaket.name).getOrElse([:])
+            def pkgJson = UPMPaketPackage.basicUPMPackageManifest("com.wooga.nuget.${upmPaket.name.toLowerCase()}", pkgJsonOverrides)
 
-            upmPaket.writePackageJson(pkgJson)
+            upmPaket.writePackageManifest(pkgJson)
             logger.info("generated package.json (${pkgJson['name']}) for $packageDir")
         }
     }