Merge pull request #99 from gradle/android-studio-guidelines

Refresh the Support for Android and the Setup Guide

README.md

@@ -12,6 +12,16 @@ This is an experimental project, stay tuned for updates!
 Learn more in the [Declarative Gradle Announcement](https://blog.gradle.org/declarative-gradle)
 blog post and [other publications](./publications/README.md).
 
+## Disclaimer
+
+!!! info
+ _Declarative Gradle_ is an experimental project.
+ Currently, no compatibility is guaranteed, and there is no commitment to the DSL syntax
+ and available features.
+ More information will be released soon.
+ Any feedback is welcome!
+ See more on the [Contributor Guide](./docs/CONTRIBUTING.md).
+
 ## Key Principles
 
 - **Ease of use** for regular software developers.
@@ -29,15 +39,6 @@ The [Declarative Gradle Announcement](https://blog.gradle.org/declarative-gradle
 outlines more details about the project and the new
 Declarative DSL we are building.
 
-## Disclaimer
-
-_Declarative Gradle_ is an experimental project.
-Currently, no compatibility is guaranteed, and there is no commitment to the DSL syntax
-and available features.
-More information will be released soon.
-Any feedback is welcome!
-See more on the [Contributor Guide](./docs/CONTRIBUTING.md).
-
 <!-- TODO: Add project manifesto -->
 
 ## Concept

docs/android/README.md

@@ -1,9 +1,17 @@
 
 # Declarative Gradle for Android
 
-## 1. Summary
+Support for Android is our main priority in the first alpha releases.
+We target the classic Android applications and libraries,
+and also Kotlin Multiplatform projects.
 
-Declarative Gradle DSL is currently in alpha.
+!!! info
+ _Declarative Gradle_ is an experimental project.
+ Currently, no compatibility is guaranteed, and there is no commitment to the DSL syntax
+ and available features.
+ More information will be released soon.
+
+## Key Features
 
 The Declarative Gradle DSL code is available at <https://github.com/gradle/declarative-gradle/tree/main/unified-prototype>.
 The Declarative Gradle DSL plugin for Android is available at: 
@@ -14,18 +22,17 @@ Common build files written using the Groovy DSL or Kotlin DSL with the name `bui
 
 `.dcl` files are written in Kotlin in a fully declarative way. 
 
-## 2. Key features / Syntax examples
 
 The restricted DSL allows a limited set of constructs. Generic control flow and calls to arbitrary methods are not allowed.
+For Android development, we provide the following software types:
 
-For Android, the `androidLibrary` and `androidApplication` software types are used. For other applications, there are `jvmLibrary` and `kmpLibrary` types available as well. Therefore, your `build.gradle.dcl` files begin with:
-
-```kotlin
-androidLibrary {
-}
-```
+- `androidApplication` - Android Application
+- `androidLibrary` - Android Library
+- `jvmLibrary` - Generic library for a JVM-compatible virtual machine
+- `kmpLibrary` - A kotlin multi-platform library
 
-The `androidLibrary` software type exposes [several configuration options](https://github.com/gradle/declarative-gradle/blob/main/unified-prototype/unified-plugin/plugin-android/src/main/java/org/gradle/api/experimental/android/library/AndroidLibrary.java) and dependencies. 
+The `androidLibrary` software type exposes [several configuration options](https://github.com/gradle/declarative-gradle/blob/main/unified-prototype/unified-plugin/plugin-android/src/main/java/org/gradle/api/experimental/android/library/AndroidLibrary.java) and dependencies.
+As you can see, there is no imperative logic here:
 
 ```kotlin
 androidLibrary {
@@ -35,25 +42,52 @@ androidLibrary {
 }
 ```
 
-As you can see, there is no imperative logic here.
+The `androidApplication` software type example can be found [here](https://github.com/gradle/declarative-gradle/blob/main/unified-prototype/unified-plugin/plugin-jvm/src/main/java/org/gradle/api/experimental/java/JavaApplication.java).
 
-The `androidApplication` software type can be found [here](https://github.com/gradle/declarative-gradle/blob/main/unified-prototype/unified-plugin/plugin-jvm/src/main/java/org/gradle/api/experimental/java/JavaApplication.java).
+## Setting Up
 
-## 3. Getting Started with NowInAndroid
+### Environment
 
-[Now in Android](https://github.com/android/nowinandroid) is a fully functional Android app built entirely with Kotlin and Jetpack Compose from the Android team.
+- Make sure to use [JDK 17](https://www.oracle.com/fr/java/technologies/downloads/#java17) and that your JAVA_HOME points to Java 17.
 
-We forked _Now in Android_ and updated the build files using the Declarative Gradle DSL. The prototype repository can be found [here](https://github.com/gradle/nowinandroid/tree/main-declarative).
+### Gradle Plugins
 
-The [settings file](settings.gradle.dcl) applies a new "Android ecosystem plugin", which exposes `androidLibrary` and `androidApplication` software types that can be used in subprojects. 
+The experiimental Declarative Gradle DSL plugin for Android is available on the Gradle Plugin Portal:
+[`org.gradle.experimental.android-library`](https://plugins.gradle.org/plugin/org.gradle.experimental.android-library).
+The location **will** change before the final release.
 
-The current prototype is limited to a single `androidLibrary` software type convention, so only a few subprojects have been converted.
+You can find a list of all available Declarative Gradle plugins [here](https://plugins.gradle.org/search?term=declarative-gradle).
 
-Converted subprojects:
+### Android Studio
+
+The latest [Android Studio 2024.1.2 Nightly](https://developer.android.com/studio/nightly)
+supports code completion and syntax highlighting for Declarative Gradle files (*.dcl).
+Some features work out of the box on this version,
+others require additional configuration.
+
+- Make sure the recent [Android Studio Nigthly](https://developer.android.com/studio/nightly) is installed.
+- Set [`ANDROID_HOME`](https://developer.android.com/tools/variables#android_home) path to the location of the Android Studio Nigthly installation.
+- Enable semantic assistance (completion and error highlighting) for Declarative Gradle
+ 1. Open _Help -> Open Custom Vm Options_
+ 2. Add text `-Didea.is.internal=true`
+ 3. Restart the IDE
+ 4. Open _Tools -> Internal Actions -> Android -> Edit Studio Flags_ and type _"Gradle Declarative"_ in the search window
+ 5. Switch on the _Studio support for declarative files_ flag.
+
+## Getting Started with NowInAndroid
+
+[Now in Android](https://github.com/android/nowinandroid) is a fully functional Android app built entirely with Kotlin and Jetpack Compose from the Android team.
+To help you with getting started,
+we forked _Now in Android_ and updated the build files using the Declarative Gradle DSL. The prototype repository can be found [here](https://github.com/gradle/nowinandroid/tree/main-declarative).
+
+The [settings file](settings.gradle.dcl) applies a new "Android ecosystem plugin", which exposes `androidLibrary` and `androidApplication` software types that can be used in subprojects.
+
+The migration to Declarative Gradle is in proghress, not all subprojects have been migrated yet.
+Some of the converted subprojects:
+[`:core:common`](https://github.com/gradle/nowinandroid/blob/main-declarative/ccore/common/build.gradle.dcl),
+[`:core:data`](https://github.com/gradle/nowinandroid/blob/main-declarative/ccore/data/build.gradle.dcl),
+[`:core:domain`](https://github.com/gradle/nowinandroid/blob/main-declarative/ccore/domain/build.gradle.dcl).
 
-- [`:core:common`](https://github.com/gradle/nowinandroid/blob/main-declarative/core/common/build.gradle.dcl)
-- [`:core:data`](https://github.com/gradle/nowinandroid/blob/main-declarative/core/data/build.gradle.dcl)
-- [`:core:domain`](https://github.com/gradle/nowinandroid/blob/main-declarative/core/domain/build.gradle.dcl)
 
 Let’s take a look at a `build.gradle.dcl` file which replaces the common `build.gradle` or `build.gradle.kts` files:
 
@@ -76,13 +110,11 @@ androidLibrary {
 
 The `androidLibrary` software type exposes [several configuration options](https://github.com/gradle/declarative-gradle/blob/main/unified-prototype/unified-plugin/plugin-android/src/main/java/org/gradle/api/experimental/android/library/AndroidLibrary.java) and dependencies. 
 
-### 3.1 Prerequisites
+### Setup
 
-- Make sure to use [JDK 17](https://www.oracle.com/fr/java/technologies/downloads/#java17) and that your `JAVA_HOME` points to Java 17.
-- Make sure [Android Studio](https://developer.android.com/studio) is installed. Note that syntax highlighting works in [Android Studio nightlies](https://developer.android.com/studio/nightly) only. 
-- Make sure that your [ANDROID_HOME](https://developer.android.com/tools/variables#android_home) path is set.
+**Step 1.** Setup the Android development environment as documented above
 
-### 3.2 Setup
+**Step 2.** Checkout the repositories
 
 ```shell
 git clone https://github.com/gradle/nowinandroid.git
@@ -99,15 +131,15 @@ nowinandroid/
  declarative-gradle/
 ```
 
-### 3.3 Building
+### Building
 
 You can assemble the project with the following command:
 
 ```shell
 ./gradlew buildDemoDebug
 ```
 
-### 3.4 Testing
+### Testing
 
 You can run tests using the following commands:
 
@@ -120,6 +152,7 @@ You can run tests using the following commands:
 ```
 
 After starting a local Android emulator in Android Studio:
+
 ```shell
 ./gradlew connectedDemoDebugAndroidTest --daemon
 ```

docs/getting-started/README.md

@@ -12,10 +12,8 @@ so your mileage may vary.
  so for them, no extra steps are needed
 - Make sure to use [JDK 17](https://www.oracle.com/fr/java/technologies/downloads/#java17) and
  that your `JAVA_HOME` points to Java 17.
-- For Android projects:
- - Make sure [Android Studio](https://developer.android.com/studio) is installed.
- Note that syntax highlighting works in [Android Studio nightlies](https://developer.android.com/studio/nightly) only.
- - Make sure that your [ANDROID_HOME](https://developer.android.com/tools/variables#android_home) path is set.
+- For specific project types and IDEs, for example Android projects, extra installation steps.
+ See the guidelines on the respective documentation pages.
 
 ## Getting Started with Android development
 
@@ -24,7 +22,7 @@ To help with getting started,
 we updated the popular _Now in Android_ demo to use Declarative Gradle DSL and its DSL in the build definitions.
 You can find the repository [here](https://github.com/gradle/nowinandroid/tree/main-declarative).
 
-To get started, follow the steps in [this guide](../android/README.md#3-getting-started-with-nowinandroid)
+To get started, follow the steps in [this guide](../android/README.md#3-getting-started-with-nowinandroid).
 
 ## Getting started for other project types
 

mkdocs.yml

@@ -143,12 +143,14 @@ markdown_extensions:
  anchor_linenums: true
  line_spans: __span
  pygments_lang_class: true
+ - pymdownx.details
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
  alternate_style: true
  - toc:
  permalink: '#'
+ - admonition
  - attr_list
  - mdx_truly_sane_lists