odb: add LEFDEF grammar railroad diagram documentation #9866
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| name: Update Grammar Railroad Diagrams | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - master | ||
| paths: | ||
| - "**/*.y" | ||
|
|
||
| jobs: | ||
| regenerate: | ||
| if: github.repository_owner != 'The-OpenROAD-Project-private' | ||
| runs-on: ${{ vars.USE_SELF_HOSTED == 'true' && 'self-hosted' || 'ubuntu-latest' }} | ||
| permissions: | ||
| contents: write | ||
| pull-requests: write | ||
|
|
||
| steps: | ||
| - name: Check out repository code | ||
| uses: actions/checkout@v6 | ||
|
|
||
| - name: Set up Java | ||
| uses: actions/setup-java@v4 | ||
| with: | ||
| distribution: temurin | ||
| java-version: "21" | ||
|
|
||
| - name: Cache railroad diagram tools | ||
| uses: actions/cache@v4 | ||
| id: cache-tools | ||
| with: | ||
| path: src/odb/doc/tools | ||
| key: railroad-tools-ebnf-v0.73-rr-2.6 | ||
|
Contributor
There was a problem hiding this comment. Is it possible that this cache might cache invalid tools? Can you validate the cache before using/storing it?
Contributor
Author
There was a problem hiding this comment. Added a Validate cached railroad tools step that runs after cache restore. It checks both WARs are non-empty and uses jar tf to verify internal contents, WEB-INF/lib/Saxon-HE-12.9.jar in ebnf-convert and de/bottlecaps/railroad/Railroad.class in rr.war. If either fails, the files are deleted and the build step is forced to run regardless of cache hit status. |
||
|
|
||
| - name: Validate cached railroad tools | ||
| id: validate-tools | ||
| run: | | ||
| set -euo pipefail | ||
| tools_dir="$GITHUB_WORKSPACE/src/odb/doc/tools" | ||
| ebnf_war="$tools_dir/ebnf-convert.war" | ||
| rr_war="$tools_dir/rr.war" | ||
|
|
||
| valid=true | ||
| if [[ ! -s "$ebnf_war" ]] || [[ ! -s "$rr_war" ]]; then | ||
| valid=false | ||
| elif ! jar tf "$ebnf_war" | grep -q "WEB-INF/lib/Saxon-HE-12.9.jar"; then | ||
|
Contributor
There was a problem hiding this comment. Why is named a
Contributor
Author
There was a problem hiding this comment. ebnf-convert.war is a proper WAR, the .jar in the grep is Saxon-HE-12.9.jar, a dependency bundled inside WEB-INF/lib/ per standard WAR layout. rr.war is actually rr-lib-2.6.jar from Maven Central renamed to .war (verified by MD5), so it has no WEB-INF structure, its check looks for a class at the root level instead. |
||
| valid=false | ||
| elif ! jar tf "$rr_war" | grep -q "de/bottlecaps/railroad/Railroad.class"; then | ||
| valid=false | ||
| fi | ||
|
|
||
| if [[ "$valid" == "false" ]]; then | ||
| echo "Cached tools are missing or invalid; forcing rebuild." | ||
| rm -f "$ebnf_war" "$rr_war" | ||
| fi | ||
|
|
||
| echo "valid=$valid" >> "$GITHUB_OUTPUT" | ||
|
|
||
| - name: Build ebnf-convert and fetch rr.war | ||
|
Member
There was a problem hiding this comment. Do we really have to build from source on every PR?
Contributor
Author
There was a problem hiding this comment. No, the Gradle build is gated behind if: steps.cache-tools.outputs.cache-hit != 'true' || steps.validate-tools.outputs.valid != 'true'. The cache key railroad-tools-ebnf-v0.73-rr-2.6 is pinned to exact tool versions, so normal PRs skip the build entirely and just restore from cache. |
||
| if: steps.cache-tools.outputs.cache-hit != 'true' || steps.validate-tools.outputs.valid != 'true' | ||
| run: | | ||
| git clone --depth 1 --branch v0.73 \ | ||
| https://github.com/GuntherRademacher/ebnf-convert.git /tmp/ebnf-convert | ||
| cd /tmp/ebnf-convert && ./gradlew war | ||
| mkdir -p $GITHUB_WORKSPACE/src/odb/doc/tools | ||
| cp build/libs/ebnf-convert.war \ | ||
| $GITHUB_WORKSPACE/src/odb/doc/tools/ebnf-convert.war | ||
| curl -fsSL -o $GITHUB_WORKSPACE/src/odb/doc/tools/rr.war \ | ||
| https://repo1.maven.org/maven2/de/bottlecaps/rr/rr-lib/2.6/rr-lib-2.6.jar | ||
|
|
||
| - name: Regenerate railroad diagram SVGs | ||
| run: python3 src/odb/doc/generate_railroad_diagrams.py | ||
|
|
||
| - name: Detect diagram changes | ||
| id: diagram-changes | ||
| run: | | ||
| if [ -z "$(git status --porcelain src/odb/doc/images/)" ]; then | ||
| echo "changed=false" >> "$GITHUB_OUTPUT" | ||
| else | ||
| echo "changed=true" >> "$GITHUB_OUTPUT" | ||
| fi | ||
|
|
||
| - name: Open PR if diagrams changed | ||
|
Contributor
There was a problem hiding this comment. What happens in the case of successive updates? Is there a flag in this action that you can use for pruning old branches/rebasing?
Contributor
Author
There was a problem hiding this comment. peter-evans/create-pull-request@v7 uses a fixed branch name (auto/grammar-railroad-diagrams), so on successive runs it force-pushes to that same branch and updates the existing open PR instead of creating a new one. delete-branch: true is set so the branch is automatically pruned after merge. I also verified that update-branch is not a valid input in v7's action.yml, the fixed-branch behavior handles successive updates natively.
Member
There was a problem hiding this comment. What makes this conditional on changes? Is that somehow within peter-evans/create-pull-request?
Contributor
Author
There was a problem hiding this comment. I added an explicit Detect diagram changes step that runs git diff --quiet -- src/odb/doc/images/ and sets a changed output. The Open PR step is gated with if: steps.diagram-changes.outputs.changed == 'true', so no PR is opened if the diagrams are unchanged. This is explicit rather than relying on action internals. |
||
| if: steps.diagram-changes.outputs.changed == 'true' | ||
| uses: peter-evans/create-pull-request@v7 | ||
|
Comment on lines
+83
to
+85
Member
There was a problem hiding this comment. Why not add a commit to the current PR rather than make a new one?
Contributor
Author
There was a problem hiding this comment. The workflow triggers on pushes to master after a grammar PR is already merged, so there is no open PR to commit back to at that point. Opening a dedicated PR for the SVG updates keeps diagram regeneration separate from grammar changes and gives maintainers a focused diff to review. |
||
| with: | ||
| commit-message: "odb: regenerate LEF/DEF railroad diagram SVGs" | ||
| branch: auto/grammar-railroad-diagrams | ||
| delete-branch: true | ||
| title: "odb: regenerate LEF/DEF railroad diagram SVGs" | ||
| body: | | ||
| Auto-generated by the `Update Grammar Railroad Diagrams` workflow. | ||
|
|
||
| Triggered by a change to `lef.y` or `def.y`. | ||
| labels: automated | ||
| add-paths: | | ||
| src/odb/doc/images/ | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| # Intermediate conversion files | ||
| *.ebnf | ||
| *.zip | ||
| src/odb/doc/tools/*.war | ||
| src/odb/doc/tools/*.jar |
Uh oh!
There was an error while loading. Please reload this page.