CritasWang opened a new pull request, #19307:
URL: https://github.com/apache/iotdb/pull/19307
## Description
`AGENTS.md` → *Common Pitfalls / Build* told agents that a machine without
the `thrift` binary cannot
run a full build, and pointed them at a weaker compile command instead:
> **Missing Thrift compiler**: The local machine may not have the `thrift`
binary installed. Running
> `mvn clean package -pl <module> -am -DskipTests` will fail at the
`iotdb-thrift` module.
> **Workaround**: To verify your changes compile, use `mvn compile -pl
<module>` (without `-am` or
> `clean`) to leverage existing target caches.
That is no longer true on `master`. The root `pom.xml` carries a
self-activating `.thrift-generation`
profile (`pom.xml:1488`) that turns on for every module owning
`src/main/thrift`
(`<activation><file><exists>src/main/thrift</exists></file></activation>`).
For each such module it
1. unpacks
`org.apache.iotdb.tools:iotdb-tools-thrift:${iotdb-tools-thrift.version}`
(`maven-dependency-plugin`, execution `get-thrift`; version property at
`pom.xml:93`, currently
`0.25.0.0`) with the classifier of the running OS — `mac-aarch64`,
`mac-x86_64`,
`linux-x86_64`, `linux-aarch64`, `windows-x86_64`, `windows-aarch64` —
into
`${project.build.directory}/thrift`, and
2. runs `thrift-maven-plugin` for Java/Python/Go/C# with
`thriftExecutable=${project.build.directory}/thrift/bin/${thrift.executable}`.
So no local toolchain install is required. Worse, the workaround the old
text recommended is
counterproductive: `mvn compile -pl <module>` without `-am` is exactly the
shortcut the next bullet
in the same section warns about, because it hides cross-module and i18n
breakage behind stale
`~/.m2`/`target` artifacts.
This PR rewrites the bullet to describe the mechanism, and keeps only the
failure modes that still
exist: the first build on a machine (and any offline `-o` build) needs the
one-time download, and a
platform without a published classifier cannot generate sources at all.
The old bullet was also the referent of "`(the thrift workaround above)`" in
the following bullet, so
that dangling cross-reference is corrected to "`(no -am)`", while keeping
that bullet's actual point
unchanged.
### Before / After
**Before** — a full build is claimed to fail without a locally installed
compiler:
> **Missing Thrift compiler**: The local machine may not have the `thrift`
binary installed. Running `mvn clean package -pl <module> -am -DskipTests` will
fail at the `iotdb-thrift` module. **Workaround**: To verify your changes
compile, use `mvn compile -pl <module>` (without `-am` or `clean`) to leverage
existing target caches.
**After** — the profile is described, the workaround is dropped, and the
real prerequisites stay:
> **Thrift code generation needs no local `thrift` binary**: the root
`pom.xml` carries a self-activating `.thrift-generation` profile. It turns on
for any module containing `src/main/thrift`, unpacks
`org.apache.iotdb.tools:iotdb-tools-thrift` (…) with the classifier of the
current OS (…) into that module's `target/thrift/`, and runs
`thrift-maven-plugin` against it. So `mvn clean package -pl <module> -am
-DskipTests` succeeds on a machine with no `thrift` on `PATH`, and no compile
workaround is needed. The zip is downloaded once and cached in the local Maven
repository, so the first build on a machine (and any offline `-o` build) still
requires that download to have happened; a platform without a published
classifier cannot generate sources at all.
## Verification
`which thrift` → `NOT FOUND` on the machine used for the check.
```
$ mvn -pl iotdb-protocol/thrift-commons -am generate-sources -DskipTests
[INFO] --- dependency:3.6.0:unpack (get-thrift) @ iotdb-thrift-commons ---
[INFO] Configured Artifact:
org.apache.iotdb.tools:iotdb-tools-thrift:mac-aarch64:0.25.0.0:zip
[INFO] --- thrift:0.10.0:compile (generate-thrift-sources-java) @
iotdb-thrift-commons ---
[INFO] --- thrift:0.10.0:compile (generate-thrift-sources-python) @
iotdb-thrift-commons ---
[INFO] --- thrift:0.10.0:compile (generate-thrift-sources-go) @
iotdb-thrift-commons ---
[INFO] --- thrift:0.10.0:compile (generate-thrift-sources-csharp) @
iotdb-thrift-commons ---
[INFO] BUILD SUCCESS
```
Exit code `0`. The archive is cached at
`~/.m2/repository/org/apache/iotdb/tools/iotdb-tools-thrift/0.25.0.0/iotdb-tools-thrift-0.25.0.0-mac-aarch64.zip`,
which is why the first build on a new machine still needs network access.
Documentation-only change: no Java sources are touched, so no
`spotless`/compile/test run applies
here (`spotless` is configured for Java only, and `AGENTS.md` formats
nothing).
<hr>
This PR has:
- [x] been self-reviewed.
<hr>
##### Key changed/added classes (or packages if there are too many classes)
in this PR
None — `AGENTS.md` only.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]