Skip to content

Commit

Permalink
Add a Markdown linter to check validation tasks
Browse files Browse the repository at this point in the history
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](diffplug/spotless#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](diffplug/spotless#2167).

Resolves wala#818.
  • Loading branch information
liblit committed Jul 21, 2024
1 parent 3e7322d commit e7c4c94
Show file tree
Hide file tree
Showing 5 changed files with 68 additions and 48 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
72 changes: 35 additions & 37 deletions README-Gradle.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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.
Expand All @@ -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)
Expand Down
20 changes: 11 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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).
Expand All @@ -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
Expand Down Expand Up @@ -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.
21 changes: 20 additions & 1 deletion build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand Down Expand Up @@ -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" }

Expand Down
1 change: 1 addition & 0 deletions gradle/libs.versions.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down

0 comments on commit e7c4c94

Please sign in to comment.