Skip to content

Add @Generated annotation to PObserve generated Java classes#941

Open
ylecaillez wants to merge 1 commit into
p-org:masterfrom
ylecaillez:feature/pobserve-generated-annotation
Open

Add @Generated annotation to PObserve generated Java classes#941
ylecaillez wants to merge 1 commit into
p-org:masterfrom
ylecaillez:feature/pobserve-generated-annotation

Conversation

@ylecaillez

@ylecaillez ylecaillez commented Mar 26, 2026

Copy link
Copy Markdown

NOTE: we do have a post compile script which add these @generated annotation at build time but maybe you'll be interested to have this embedded directly in the compiler.

Emit @generated(value="P Compiler", date=...) from javax.annotation.processing.Generated on the top-level PTypes, PEvents, and PMachines classes so that tools and IDEs can identify generated code.

Also unify the three separate DateTime.Now calls (DoNotEditWarning, FFI banner, and the new annotation) into a single GenerationTimestamp captured once at class-load time, ensuring all output files carry the same timestamp.

Example

/***************************************************************************
 * This file was auto-generated on Saturday, 11 April 2026 at 05:20:27 UTC.
 * Please do not edit manually!
 **************************************************************************/
...
@Generated(value = "P Compiler", date = "2026-04-11T05:20:27Z")
public class PMachines {
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
% P <-> Java Foreign Function Interface Stubs
% 
% This file was auto-generated on Saturday, 11 April 2026 at 05:20:27 UTC.
%

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the PObserve Java backend code generator to embed a Java @Generated annotation directly into the generated top-level Java classes (types, events, machines), and centralizes timestamp generation so file headers/annotations can share a single generation timestamp.

Changes:

  • Emit @javax.annotation.processing.Generated on PTypes, PEvents, and PMachines generated Java classes.
  • Add javax.annotation.processing.Generated to default imports for generated Java sources.
  • Capture a single GenerationTimestamp once and reuse it for the “do not edit” banner and FFI banner strings.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File Description
Src/PCompiler/CompilerCore/Backend/PObserve/TypesGenerator.cs Emits Constants.GeneratedAnnotation before the PTypes class declaration.
Src/PCompiler/CompilerCore/Backend/PObserve/MachineGenerator.cs Emits Constants.GeneratedAnnotation before the PMachines class declaration.
Src/PCompiler/CompilerCore/Backend/PObserve/EventGenerator.cs Emits Constants.GeneratedAnnotation before the PEvents class declaration.
Src/PCompiler/CompilerCore/Backend/PObserve/Constants.cs Adds a shared GenerationTimestamp, the generated-annotation string, and the required Java import; reuses the timestamp in existing banners.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread Src/PCompiler/CompilerCore/Backend/PObserve/Constants.cs Outdated
Emit @generated(value="P Compiler", date=...) from
javax.annotation.processing.Generated on the top-level PTypes, PEvents,
and PMachines classes so that tools and IDEs can identify generated
code.

Also unify the three separate DateTime.Now calls (DoNotEditWarning, FFI
banner, and the new annotation) into a single GenerationTimestamp
captured once at class-load time, ensuring all output files carry the
same timestamp.
@ylecaillez ylecaillez force-pushed the feature/pobserve-generated-annotation branch from 112f98d to f0caf56 Compare April 11, 2026 05:22
@ankushdesai

Copy link
Copy Markdown
Member

Thanks for the PR! One suggestion: I'd vote to drop the timestamp entirely — both the date= field on @Generated and the existing wall-clock timestamps in the FFI banner and DoNotEditWarning banner.

Reasoning: embedding DateTime.UtcNow in generated source means p compile produces different bytes on every run, even when no input changed. That breaks content-hash-based caching (Bazel, container layer caches, etc.), inflates incremental rebuild scope, and makes diffs of regenerated output noisy without adding information a reader can actually use (the git commit and the compiler version tell you "when" more reliably). JSR-269 makes date optional precisely for this reason — @Generated(value = "P Compiler") on its own is the common shape and gives IDEs and lints everything they need.

If keeping the banners' human-readable "this is generated" message is desirable, the wording works fine without a timestamp: just "This file was auto-generated by the P compiler. Please do not edit manually."

Concretely this would simplify the diff a lot — the whole GenerationTimestampUtc / Inv plumbing in Constants.cs goes away, and the four WriteLine(Constants.GeneratedAnnotation) call sites just emit @Generated(value = "P Compiler").

Bonus: if you'd ever want a timestamp back later, the reproducible-builds convention is to honor a SOURCE_DATE_EPOCH env var when set, falling back to no timestamp otherwise — that's an easy opt-in for users who genuinely want it.

(Separately, the Copilot review comment about UTC vs local-time mismatch looks stale — the current diff uses UTC consistently for both the annotation and the banners. Worth dismissing.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants