Speed up workspace compilation e.g. in Eclipse - New -rebuildtriggerpolicy instruction to avoid unnecessary rebuild cascades

[Copilot]

This pull request introduces a new build optimization to the bnd build system, allowing projects to avoid unnecessary rebuilds of dependent artifacts when the output JAR's content or exported API has not changed. The feature is controlled by a new -rebuildtriggerpolicy property, which can be set to either always (the default) or api. When set to api, the system preserves the JAR's timestamp if the content or exported API is unchanged, thereby preventing downstream rebuild cascades. The implementation includes content and API digest calculation and storage, as well as comprehensive tests validating the new behavior.

Testing

1. use Eclipse with bndtools
2. put the following in your /cnf/build.bnd

-rebuildtriggerpolicy: api

or to tie it only to Eclipse builds

-rebuildtriggerpolicy: ${if;${driver;eclipse};api;always}

3. Press Refresh Bnd Workspace button

4. rebuild the whole workspace (e.g. clean all just once)

5. Go to a Bundle A of your choise which has many downstream bundles which depend on A (usually some util bundle at the root of the bundle hiearchy which is used by every bundle)

6. Pick a random java method and add a System.out.println("hello");

7. Save the file

Expected result:

• now only the bundle where you added the change should be build (this is the new behavior and optimization... it just builds the bundle you just changed). Try the same with adding a method comment.

8. Now make a public API change: e.g. add a new default method to an interface (which just prints hello world)
   Expected result:

• the current bundle and all downstream bundles should be rebuild (since this is an API change it should behave as before)

Previous bahavior before this PR:
If you remove -rebuildtriggerpolicy from build.bnd if should behave as before this PR - all downstream projects should be build with each change all the time.

Key changes:

Build Optimization: Content/API Digest and Timestamp Preservation

• Introduced the RebuildTriggerPolicy mechanism in Project.java, which determines whether to preserve the build artifact's timestamp based on content or API digests. This prevents unnecessary downstream rebuilds when the output JAR is unchanged or only non-API changes occurred. The policy supports always (default) and api modes, with digest files (.digest and .api-digest) used for comparison. [1] [2] [3]
• On build, content and API digests are computed and stored as sidecar files. If the digests match the previous build, the JAR's timestamp is preserved. If not, the timestamp is updated as usual. [1] [2]
• When removing build files, any associated digest files are also deleted to avoid stale state.

Configuration and Documentation

• Added the new -rebuildtriggerpolicy property to Constants.java and included it in the recognized options set. [1] [2]
• Updated the help system with a detailed description of the new property, including usage and examples, in Syntax.java.

Testing

• Added comprehensive tests in ProjectTest.java to verify:
  • Builds are skipped and timestamps preserved when content is unchanged.
  • JARs are rewritten and digests updated when content changes.
  • The API digest mechanism correctly preserves timestamps when only internal (non-API) changes are made.

Dependency and Import Updates

• Added necessary imports for digest calculation and API analysis in Project.java. [1] [2] [3] [4] [5]

[chrisrueger]

First experiments in my larger project look very promising. Simple java changes which do not change public API or the manifest do not cause a downstream rebuild cascade. Only e.g. changes to interfaces , method signatures etc. would cause a downstream rebuild of dependant projects like before.

This makes development nicer since it cuts down waiting time a lot.

[chrisrueger]

@peterkir FYI Let's discuss next week.