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]

Reply via email to