From e7c4c9451129e0b49d48d19c1c4e5fb53853adfe Mon Sep 17 00:00:00 2001 From: Ben Liblit Date: Sun, 21 Jul 2024 18:23:10 -0400 Subject: [PATCH] Add a Markdown linter to `check` validation tasks I would rather use Spotless for these checks, for consistency with other format checkers that we already use. [Spotless supports Markdown via flexmark](https://github.com/diffplug/spotless/tree/main/plugin-gradle#flexmark), but unfortunately [Spotless does not provide access to any of flexmark's configuration options](https://github.com/diffplug/spotless/issues/2183). That would leave us with a Markdown linter that is too lenient for my tastes. For example, [Spotless's flexmark configuration does not even restrict maximum line length](https://github.com/diffplug/spotless/issues/2167). Resolves #818. --- CONTRIBUTING.md | 2 +- README-Gradle.md | 72 +++++++++++++++++++-------------------- README.md | 20 ++++++----- build.gradle.kts | 21 +++++++++++- gradle/libs.versions.toml | 1 + 5 files changed, 68 insertions(+), 48 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6cd1f90293..b059f74443 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ Beyond tests, other checks run as part of `./gradlew check` and 1. Compilation with the Java compiler from [Eclipse JDT Core](https://www.eclipse.org/jdt/core/), which runs additional - lint checks + Lint checks 1. Checking that all Java and Kotlin code is formatted according to [Google Java Format](https://github.com/google/google-java-format) diff --git a/README-Gradle.md b/README-Gradle.md index 7943a9d80b..1098485e79 100644 --- a/README-Gradle.md +++ b/README-Gradle.md @@ -1,10 +1,12 @@ +# WALA’s Gradle Build System + This document describes some WALA-specific aspects of our Gradle build system, plus a few general Gradle features that may be of particular interest to WALA developers. However, it is not a Gradle tutorial. -# Getting Started +## Getting Started -## External Dependencies: Patience is a Virtue +### External Dependencies: Patience is a Virtue Gradle downloads many packages and supporting Java libraries as needed. Your first Gradle build may take a long time. On a fast @@ -17,32 +19,31 @@ faster. Rerunning `./gradlew assemble processTestResources` with a warm cache in an already-built tree takes under three seconds. WALA components are built using a mix of Java 11 and Java 17. Gradle -will [download suitable JDKs -automatically](https://docs.gradle.org/current/userguide/toolchains.html#sec:provisioning) -if they are not already [locally -installed](https://docs.gradle.org/current/userguide/toolchains.html#sec:auto_detection) +will +[download suitable JDKs automatically](https://docs.gradle.org/current/userguide/toolchains.html#sec:provisioning) +if they are not already +[locally installed](https://docs.gradle.org/current/userguide/toolchains.html#sec:auto_detection) or [custom-configured](https://docs.gradle.org/current/userguide/toolchains.html#sec:custom_loc). -## Eclipse +### Eclipse -### One-Time Eclipse Configuration +#### One-Time Eclipse Configuration To work with WALA inside Eclipse, first **install Eclipse Buildship -3.1 or later** using either [the Eclipse -Marketplace](http://www.vogella.com/tutorials/EclipseGradle/article.html#installation-via-the-marketplace) -or [the Eclipse update -manager](http://www.vogella.com/tutorials/EclipseGradle/article.html#installation-via-the-eclipse-update-manager). +3.1 or later** using either +[the Eclipse Marketplace](http://www.vogella.com/tutorials/EclipseGradle/article.html#installation-via-the-marketplace) +or +[the Eclipse update manager](http://www.vogella.com/tutorials/EclipseGradle/article.html#installation-via-the-eclipse-update-manager). Buildship integrates Eclipse with Gradle, much like how M2Eclipse integrates Eclipse with Maven. Restart Eclipse after installing this feature. -### Importing WALA Projects Into Eclipse +#### Importing WALA Projects Into Eclipse -Once you are running a Buildship-enabled Eclipse, **[use the “Existing -Gradle Project” import -wizard](http://www.vogella.com/tutorials/EclipseGradle/article.html#import-an-existing-gradle-project) -to import WALA into Eclipse.** Select and import the topmost level of +Once you are running a Buildship-enabled Eclipse, +[use the “Existing Gradle Project” import wizard](http://www.vogella.com/tutorials/EclipseGradle/article.html#import-an-existing-gradle-project) +to import WALA into Eclipse. Select and import the topmost level of your WALA source tree. On the “Import Options” page of the import wizard, leave all settings at their defaults: the “Override workspace settings” option should be off, and the grayed-out “Gradle @@ -67,15 +68,14 @@ connection. Note: a pristine WALA source tree is *not* pre-configured as a group of Eclipse projects. Using the standard Eclipse “Existing Projects -into Workspace” import wizard will not work correctly. You must [use -the “Existing Gradle Project” import -wizard](http://www.vogella.com/tutorials/EclipseGradle/article.html#import-an-existing-gradle-project) +into Workspace” import wizard will not work correctly. You must +[use the “Existing Gradle Project” import wizard](http://www.vogella.com/tutorials/EclipseGradle/article.html#import-an-existing-gradle-project) instead. -### `.classpath` and `.project` as Generated Files +#### `.classpath` and `.project` as Generated Files You will find no `.classpath` or `.project` files anywhere in [the -Gradle fork of WALA’s git repository](https://github.com/liblit/WALA). +Gradle fork of WALA’s Git repository](https://github.com/liblit/WALA). Importing using the “Existing Gradle Project” wizard creates these Eclipse project configuration files automatically based on the underlying Gradle configuration. @@ -96,9 +96,9 @@ plugin](https://docs.gradle.org/current/userguide/eclipse_plugin.html). A few WALA sub-projects already use this: look for `eclipse.project` in `*/build.gradle.kt` for examples. -## IntelliJ IDEA +### IntelliJ IDEA -### Opening WALA in IntelliJ IDEA +#### Opening WALA in IntelliJ IDEA Open the top-level WALA directory as a project; it should have a distinctive badge on its folder icon marking it as a directory @@ -115,7 +115,7 @@ patient](#external-dependencies-patience-is-a-virtue) during the initial project open, especially if you have a slow network connection. -### Benign Warning About Non-Managed Maven Project +#### Benign Warning About Non-Managed Maven Project Each time you open the WALA project, IntelliJ IDEA may report “Non-managed pom.xml file found” in its event log. This arises @@ -125,7 +125,7 @@ safely ignore this notification, permanently disable it using the offered “Disable notification” link, or even disable the IntelliJ IDEA Maven plugin entirely if you have no other need for it. -### Project Configuration as Derived Model +#### Project Configuration as Derived Model IntelliJ IDEA automatically derives its project models from the Gradle build configuration, including all information about both internal and @@ -142,7 +142,7 @@ to change module and library settings is to change the Gradle configuration such that the *derived* IntelliJ IDEA model is what you want it to be. -## Gradle Command Line +### Gradle Command Line You do not need to install Gradle separately. **WALA includes its own copy of Gradle, available as the `gradlew` script in the top-level @@ -156,7 +156,7 @@ under `*/build`. For example the jar archives created by the that Eclipse-generated artifacts will appear in Eclipse-specific places, such as `*/bin` and `*/target`. -### Trustworthy Dependencies For Incremental Builds +#### Trustworthy Dependencies For Incremental Builds Gradle has excellent understanding of task and file dependencies. You can trust it to perform incremental rebuilds rather than always @@ -165,7 +165,7 @@ and rebuilding from scratch after every change, I recommend that you drop `clean` as a reflexive extra step and **trust Gradle to do incremental builds correctly.** -### Favorite Build Tasks +#### Favorite Build Tasks Some useful Gradle tasks include: @@ -182,7 +182,7 @@ Some useful Gradle tasks include: - `clean`: remove all Gradle-generated artifacts -### Tasks in Specific Sub-Projects +#### Tasks in Specific Sub-Projects When you run `./gradlew` in the top-level WALA directory, any tasks you list will be built in all sub-projects. For example, `./gradlew @@ -198,15 +198,14 @@ want to build tasks only in specific sub-projects, you have two options: and then run `../gradlew assemble`. Note the proper relative path to the top-level Gradle script: `../gradle` instead of `./gradlew`. -### Task Name Abbreviation +#### Task Name Abbreviation -[Any build task can be -abbreviated](https://docs.gradle.org/current/userguide/command_line_interface.html#_task_name_abbreviation) +[Any build task can be abbreviated](https://docs.gradle.org/current/userguide/command_line_interface.html#_task_name_abbreviation) by shortening each camel-case-delimited word in its name. For example, the `processTestResources` task can probably be abbreviated as `procTeRes` or even `pTR`. -### Useful Command-Line Flags +#### Useful Command-Line Flags Among Gradle’s command-line flags, I have found the following particularly useful: @@ -217,8 +216,7 @@ particularly useful: see multiple test failures rather than giving up after the first failure. -- [`-t`, - `--continuous`](https://docs.gradle.org/current/userguide/command_line_interface.html#_continuous_build): +- [`-t`, `--continuous`](https://docs.gradle.org/current/userguide/command_line_interface.html#_continuous_build): keep Gradle process running and re-execute the given tasks whenever input files change. Similar to Eclipse’s behavior of updating the build whenever you change and save a file. @@ -236,7 +234,7 @@ particularly useful: good way to gain insights into why Gradle did what it did, and how long each piece took. -### Composite Builds +#### Composite Builds Gradle’s [composite builds](https://docs.gradle.org/current/userguide/composite_builds.html) diff --git a/README.md b/README.md index 93131711d2..8c2712222d 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ +# WALA + ![WALA logo](https://wala.github.io/logos/WALA-banner.png) -[![GitHub Actions -status](https://github.com/wala/WALA/workflows/Continuous%20integration/badge.svg)](https://github.com/wala/WALA/actions?query=workflow%3A%22Continuous+integration%22) -[![Join the chat at -https://gitter.im/WALAHelp/Lobby](https://badges.gitter.im/WALAHelp/Lobby.svg)](https://gitter.im/WALAHelp/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +[![GitHub Actions status](https://github.com/wala/WALA/workflows/Continuous%20integration/badge.svg)](https://github.com/wala/WALA/actions?query=workflow%3A%22Continuous+integration%22) +[![Join the chat at https://gitter.im/WALAHelp/Lobby](https://badges.gitter.im/WALAHelp/Lobby.svg)](https://gitter.im/WALAHelp/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -------------------------- +--- The T. J. Watson Libraries for Analysis (WALA) provide static analysis capabilities for Java bytecode and related languages and for @@ -46,8 +46,7 @@ technical documentation. In the meantime, you can check out tutorial slides to get an overview of WALA: * [Core WALA](https://wala.github.io/tutorials/PLDI_WALA_Tutorial.pdf) (PDF) -* [WALA - JavaScript](https://wala.github.io/tutorials/WALAJavaScriptTutorial.pdf) +* [WALA JavaScript](https://wala.github.io/tutorials/WALAJavaScriptTutorial.pdf) (PDF) You can also watch screencasts of the WALA JavaScript tutorial [here](https://www.youtube.com/user/WALALibraries/videos). @@ -60,7 +59,7 @@ graph"](https://github.com/wala/WALA/search?q=call+graph&type=wikis). We're hosting documentation for WALA on [the GitHub wiki](https://github.com/wala/WALA/wiki). **We've chosen a wiki -format just so that _you_ can contribute.** Don't be shy! +format just so that *you* can contribute.** Don't be shy! The WALA publications department is populating this wiki with technical documentation on a demand-driven basis, driven by questions @@ -117,4 +116,7 @@ page. ![YourKit logo](https://www.yourkit.com/images/yklogo.png) -We thank [YourKit](https://www.yourkit.com) for providing WALA developers with a complimentary license for their excellent [Java profiler](https://www.yourkit.com/java/profiler/), which we use to improve and maintain WALA performance. +We thank [YourKit](https://www.yourkit.com) for providing WALA developers with +a complimentary license for their excellent +[Java profiler](https://www.yourkit.com/java/profiler/), which we use to +improve and maintain WALA performance. diff --git a/build.gradle.kts b/build.gradle.kts index bca564a142..c584968c04 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -3,6 +3,11 @@ // plugin configuration must precede everything else // +import com.appmattus.markdown.rules.ConsistentHeaderStyleRule +import com.appmattus.markdown.rules.ConsistentUlStyleRule +import com.appmattus.markdown.rules.LowerCaseFilenameRule +import com.appmattus.markdown.rules.config.HeaderStyle +import com.appmattus.markdown.rules.config.UnorderedListStyle import com.diffplug.gradle.pde.EclipseRelease import com.github.benmanes.gradle.versions.updates.DependencyUpdatesTask @@ -13,6 +18,7 @@ plugins { java alias(libs.plugins.dependency.analysis) alias(libs.plugins.file.lister) + alias(libs.plugins.markdown) alias(libs.plugins.shellcheck) alias(libs.plugins.task.tree) alias(libs.plugins.version.catalog.update) @@ -101,7 +107,20 @@ shellcheck { } } -tasks.named("check") { dependsOn("buildHealth") } +// Markdown +markdownlint { + rules { + +ConsistentHeaderStyleRule(HeaderStyle.Consistent) + +ConsistentUlStyleRule(UnorderedListStyle.Consistent) + +LowerCaseFilenameRule { excludes = listOf(".*/README-Gradle.md") } + } +} + +tasks.named("markdownlint") { + notCompatibleWithConfigurationCache("https://github.com/appmattus/markdown-lint/issues/39") +} + +tasks.named("check") { dependsOn("buildHealth", "markdownlint") } tasks.named("shellcheck") { group = "verification" } diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index fda0838f40..f77dbc78fe 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -48,6 +48,7 @@ dependency-analysis = "com.autonomousapps.dependency-analysis:1.32.0" file-lister = "all.shared.gradle.file-lister:1.0.2" google-java-format = "com.github.sherter.google-java-format:0.9" ktfmt = "com.ncorti.ktfmt.gradle:0.18.0" +markdown = "com.appmattus.markdown:0.6.0" shellcheck = "com.felipefzdz.gradle.shellcheck:1.4.6" spotless = { id = "com.diffplug.spotless", version.ref = "spotless" } task-tree = "com.dorongold.task-tree:3.0.0"