1# Playground Setup for AndroidX Projects
2
3AndroidX is a fairly large project with 300+ modules which makes it a
4very resource heavy project for local development.
5
6Playground setup allows sub projects to have an additional settings.gradle
7file that can be run independent of the main project.
8It also allows using external resources for artifacts such that just checking
9out the AndroidX git repository is enough without the prebuilt repositories
10that are needed by the main AndroidX project.
11
12These project setups are only meant to be used for local development and
13all CI tasks run using the root AndroidX project.
14
15## How it works?
16A playground project needs a `settings.gradle` file that includes the
17`playground-common/playground-plugin` build and applies the `playground` plugin.
18
19The `playground` plugin provides functionality allowing the playground project
20to be executed independently of the main AndroidX build, and to pull select projects
21from AndroidX.
22
23To share as much common configuration as possible, it is also recommended
24to symlink some common files like `gradle` and `.idea` configuration.
25
26To do that, execute "setup-playground.sh" command in your playground directory.
27```
28cd room;
29../playground-common/setup-playground.sh
30```
31This script will create symbolic links for `gradle` and `.idea` files that are committed
32to the git repository. It also force adds the `.idea` files to the git repository because
33by default any nested .idea folder is ignored from git.
34
35The `playground` plugin sets a pre-defined build file (`playground-build.gradle`) for
36the root project and also provides a `playground` extension for `settings.gradle` with
37useful configuration methods.
38
39The custom `settings.gradle` file should first call `setupPlayground("..")`  on the
40`playground` extension to establish the main configuration, providing the relative
41path of the playground project to the main AndroidX project.
42
43After running `setupPlayground`, it can either include projects via `includeProject`
44method or filter projects from the main AndroidX settings gradle file using the
45`selectProjectsFromAndroidX` method.
46
47### Properties
48When a `gradle.properties` file shows up under a sub project, main AndroidX build ends up
49reading it. For this reason, we can only keep a minimal `gradle.properties` file in these
50sub modules that also support playground setup.
51
52We cannot avoid creating `gradle.properties` as certain properties (e.g. `useAndroidX`) are
53read at configuration time and we cannot set it dynamically.
54
55Properties that will be set dynamically are kept in `playground.properties` file while
56shared properties are kept in `androidx-shared.properties` file.
57The dynamic properties are read in the `playground` plugin and set on each project.
58
59There is a `VerifyPlaygroundGradleConfigurationTask` task that validates the contents of
60`androidx-shared.properties` file as part of the main AndroidX build.
61
62### Optional Dependencies
63Even though sub-projects usually declare exact coordinates for their dependencies,
64for tests, it is a common practice to declare `project` dependencies. To avoid needing
65to include all of those projects to make the build file work, `AndroidXPlaygroundRootPlugin`
66adds a `projectOrArtifact` method to each sub project. This function can be used instead of
67`project` to declare optional project dependencies. This function will return the
68`project` if it exists or default to its latest artifact if it doesn't.
69
70Note that range artifacts are not allowed in the main AndroidX build so when the sub
71project is opened as part of the main AndroidX build, `projectOrArtifact` always resolves
72to the `project`. In playground projects, it always resolves to the latest `SNAPSHOT`
73artifact that is included in the playground build.
74