Infra to add sub-project settings.gradle files
This CL adds a `playground-common` functionality that allows
creating additional settings.gradle files inside AndroidX
that can be run independently.
The major functionality is under `playground-common` and each
project only needs to declare a settings.gradle file + symlink
a bunch of files from playground-common (see playground-common/README.md
for details).
As we use project dependencies for tests, it has a cascading
effect to include many unrelated projects to make these settings
files work. To workaround it, I've added a `projectOrArtifact`
method that will resolve to the project if it exists or else
declare a dependency on the latest artifact.
To make sure we don't download an additional studio for each of
these projects, I've updated the Studio task to let these projects
define an install location so that Playground and Room can re-use
the same studio installation that is used for AndroidX.
Right now only playground & room uses this setup.
It is best not to extend it for now since there is no CI running
these projects so they can break easily.
Bug: 158536544
Test: existing tests for the main AndroidX checkout
Test: ./gradlew tasks projects in room & playground + manual test
Change-Id: I81b75bb5534c47deba753fbd71179b4c799f52a1
diff --git a/playground-common/README.md b/playground-common/README.md
new file mode 100644
index 0000000..063dfb6
--- /dev/null
+++ b/playground-common/README.md
@@ -0,0 +1,52 @@
+# Playground Setup for AndroidX Projects
+
+AndroidX is a fairly large project with 300+ modules which makes it a
+very resource heavy project for local development.
+
+Playground setup allows sub projects to have an additional settings.gradle
+file that can be run independent of the main project.
+It also allows using external resources for artifacts such that just checking
+out the AndroidX git repository is enough without the prebuilt repositories
+that are needed by the main AndroidX project.
+
+These project setups are only meant to be used for local development and
+all CI tasks run using the root AndroidX project.
+
+## How it works?
+A playground project needs a `settings.gradle` file that applies
+`playground-common/playground-settings.gradle` which provides functionality
+to pull select projects from AndroidX.
+
+To share as much common configuration as possible, it is also recommended
+to symlink to the following files of `playground-common`:
+
+```
+gradle -> playground-common/gradle
+gradlew -> playground-common/gradlew
+gradlew.bat -> playground-common/gradlew.bat
+```
+
+The `playground-settings.gradle` file sets a pre-defined build file (`playground-build.gradle`)
+for the root project and also provides `includeProject` and `selectProjectsFromAndroidX`
+methods.
+
+The custom `settings.gradle` file should first call `setupPlayground(this, "..")` to
+run the main configuration. Here, the first argument is the `script` object itself and
+the second argument is the relative path to the main AndroidX project.
+
+After running `setupPlayground`, it can either include projects via `includeProject`
+method or filter projects from the main AndroidX settings gradle file using the
+`selectProjectsFromAndroidX` method.
+
+### Optional Dependencies
+Even though sub-projects usually declare exact coordinates for their dependencies,
+for tests, it is a common practice to declare `project` dependencies. To avoid needing
+to include all of those projects to make the build file work, `AndroidXPlaygroundRootPlugin`
+adds a `projectOrArtifact` method to each sub project. This function can be used instead of
+`project` to declare optional project dependencies. This function will return the
+`project` if it exists or default to its latest artifact if it doesn't.
+
+Note that range artifacts are not allowed in the main AndroidX build so when the sub
+project is opened as part of the main AndroidX build, `projectOrArtifact` always resolves
+to the `project`. In playground projects, it always resolves to the latest `SNAPSHOT`
+artifact that is included in the playground build.
