spviz-build

Files (1)

• SKILL.md

SKILL.md (first lines)

# Build SPViz-generated projects
Use this skill after the DSLs exist.
Keep generation, visualization build, and generator build as separate diagnosable steps.

## Preconditions
Check that the input `.spvizmodel` and, for a visualization, the importing `.spviz` exist and parse.
Check Java and Maven before a long build:
```
java -version
mvn -version
```

Generated SPViz visualization projects are configured for Java 21 and built with Maven 3.9.
Use compatible versions and do not change generated dependency versions merely to get past a local setup problem.
On Windows, use `mvn.cmd` if `mvn` is not on PATH.

## Generate
Use `spviz-cli-tools` to obtain and verify the bundled SPViz CLI.
Consult `spviz-troubleshooting` if the bundled CLI is unavailable or invalid.

Verify the jar with `java -jar <spviz-cli.jar> --version`, then generate into a dedicated output directory:
`java -jar <spviz-cli.jar> <path>/architecture.spvizmodel <path>/visualization.spviz -o <output-path>/generated`

The CLI accepts any number of `.spvizmodel` and `.spviz` files.
`--no-model-dsl` and `--no-diff` reduce generated modules when those features are intentionally not wanted.
`--validate` checks the DSLs for correctness and reports errors without generating anything.
Do not use `-b` or `-g` until a plain generation has succeeded.
The CLI flags are available as a convenience for human interaction, but separate Maven commands make failures and manual generator changes easier to diagnose.

## Select the correct build root
Read the package declaration in the `.spviz` file and inspect the generated folders.
The visualization build root is:
`<generated>/<visualization package>.build/`

For example, package `de.cau.cs.kieler.spviz.osgiviz` produces `de.cau.cs.kieler.spviz.osgiviz.build`.
Do not build from the shared `spviz.build` folder.
The generated build root's POM contains a default Maven profile for the whole visualization and a `generator` profile for the model generator.

## Build the visualization
From the visualization build root, or using `-f`:
`mvn clean package -f <generated>/<visualization package>.build/pom.xml`
This builds the generated model/viz/language-server modules, the Eclipse feature and repository, and the packaged artifacts.
Locate the outputs here:
- language server: `<visualization package>.language.server/target/*-shaded.jar`
- P2 repository: `<visualization package>.build/<visualization package>.repository/target/repository`

Never edit `xtend-gen` or generated Java output to fix a build.
Change the corresponding DSL and regenerate and consult `spviz-troubleshooting` if the build fails.
Modify generated Xtend code only after consulting the user.
Usually, this is a bad idea because future regeneration may overwrite the changes.

## Build the project model generator
Run `mvn clean package -P generator -f <generated>/<visualization package>.build/pom.xml`

The `generator` profile builds the `<a2m package>.generate` module and required modules, it does not replace the full visualization build.
Locate the shaded generator jar in `<a2m package>.generate/target/` and verify it (the one without the "original-" prefix):
`java -jar <generator-shaded.jar> --help`

Use the `spviz-model-generator` skill to run it against a repository and inspect the resulting model before asking KLighD to open it.

## Handoff
If the build fails, route to `spviz-troubleshooting` for diagnosis.
If the build succeeds, hand back to the previous context.

From kieler/SoftwareProjectViz, EPL-2.0.

More from kieler/SoftwareProjectViz