Javadoc caching

2 minute read

The CloudBees Build Acceleration Javadoc caching feature can improve build performance by caching and reusing Javadoc files.

Enabling Javadoc caching

To enable Javadoc caching for a specific rule, add the following before that rule:

#pragma jobcache javadoc

Alternatively, you can mention the target again in a separate makefile:

#pragma jobcache javadoc mytarget :

By default, the cache becomes obsolete when *.java files are added to or removed from directories that are read by the rule body. You can override this default wildcard pattern by invoking:

#pragma jobcache javadoc -readdir pattern

pattern is the pattern that you want to ignore. You can use multiple wildcard (glob) patterns.

eMake permanently ignores the effect on a given result of certain special files that might have existed when it was created, in all cases using the names they would have had at that time:

  • Anything in ".emake" or whatever alternative directory you specified using --emake-assetdir

  • Client-side eMake debug log (as specified by --emake-logfile )

  • Annotation file (as specified by --emake-annofile )

  • History file (as specified by --emake-historyfile )

-hdf arguments are removed from consideration for which cache slot to use.

If you want to delete the cache, see Deleting the Cache.

For debugging information, see Debugging.

Limitations

  • The following Javadoc invocations are not supported:

  • Javadoc is invoked indirectly, such as through a wrapper script

  • The rule body recursively invokes eMake

  • If Javadoc is named something other than "javadoc"

  • Javadoc caching is sensitive to changes in *.java wildcard outcomes in directories that are actually read by the job, and any new subdirectories thereof.

  • #pragma jobcache …​ cannot be applied to patterns as such, only to explicitly specified targets (though the commands might be provided by a pattern).

  • Windows is not supported.

  • The Javadoc caching feature does not detect the need to rebuild Javadoc files in these cases:

  • Changes to input files and programs that are used by a rule body but that CloudBees Build Acceleration does not virtualize (because they are not located under --emake-root=…​ ).

  • Changes to non file system, non-registry aspects of the environment, for example, the current time of day

  • If a rule job checks the existence or timestamp of a file without reading it, Javadoc caching might not invalidate its cached result when the file is created, destroyed, or modified. However, Javadoc caching will detect when files matching "*.java" (or the pattern specified by "-readdir") are added or removed from directories read by the rule body, or any new subdirectories thereof. In that case eMake will rerun Javadoc.