diff --git a/README.md b/README.md index 1426d1ee..8d66779c 100644 --- a/README.md +++ b/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). - ## Concept diff --git a/docs/android/README.md b/docs/android/README.md index dd96dbb5..a2fba0d5 100644 --- a/docs/android/README.md +++ b/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 . 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,7 +131,7 @@ nowinandroid/ declarative-gradle/ ``` -### 3.3 Building +### Building You can assemble the project with the following command: @@ -107,7 +139,7 @@ You can assemble the project with the following command: ./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 ``` diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index d0f3b456..e0d674ef 100644 --- a/docs/getting-started/README.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index b3fccbb1..c1997cdd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -143,6 +143,7 @@ markdown_extensions: anchor_linenums: true line_spans: __span pygments_lang_class: true + - pymdownx.details - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences @@ -150,5 +151,6 @@ markdown_extensions: alternate_style: true - toc: permalink: '#' + - admonition - attr_list - mdx_truly_sane_lists