Skip to main content

Code generation and upstream reuse

Your application depends on upstream products: Genesis itself, and any PBCs it uses. Each of them has generated code of its own, built from its system definition, fields, tables and views. Rather than regenerate that code every time you build your application, the build reuses the generated code that each upstream product has already published. This makes application builds faster.

This page explains how the generated code is split, how upstream reuse works, and the settings that control it. For an overview of the generated modules, see DAO.

Slices and facades​

The generated modules for system definition, fields and DAOs are each generated in two parts:

  • The slice contains the classes for one product only: for example, that product's tables and entities, and its own <Product>Fields holder.
  • The facade contains the aggregate classes that span every product on the classpath: SysDef, Fields and Tables. Separate tasks generate the facades: generateSysDefFacade, generateFieldsFacade and generateDaoFacade.

Views have no facade. The view module is generated in one part.

Upstream reuse​

With upstream reuse switched on, the build puts each upstream product's published slice jars on the code-generation classpath. Code generation reads the table and view metadata stored in those jars instead of evaluating that product's .kts files again. It then generates your own product's slices, and the facades that combine everything.

Genesis is always an upstream product. The others are the product dependencies declared in your settings file.

The slice jars are resolved with these coordinates:

<groupId>:<artifactId>-generated-sysdef:<version>:slice
<groupId>:<artifactId>-generated-fields:<version>:slice
<groupId>:<artifactId>-generated-dao:<version>:slice
<groupId>:<artifactId>-generated-view:<version>

The view module has no slice jar, so its regular jar is used.

The <groupId> is the Gradle group of the upstream product's build. A generated project sets it in the allprojects { } block of server/build.gradle.kts; for Genesis and auth it is global.genesis. The <version> is the upstream project's Gradle version, which a generated project sets in the same allprojects { } block (for example version = "1.0.0-SNAPSHOT", next to group = ...). It is the version the consumer puts in dependency("groupId:productName:version").

For example, auth's DAO slice jar is global.genesis:auth-generated-dao:<version>:slice, and Genesis's is global.genesis:genesis-generated-dao:<version>:slice.

Upstream products must be built with Genesis 10.0​

Upstream reuse needs slice jars, and only products built and published with Genesis 10.0 have them. A PBC published with an earlier version has none, so use PBC versions built with Genesis 10.0.

The build reports any upstream product whose version has no codegen slice jars. The report looks like this, with one line for each product concerned:

[genesis codegen] Upstream product(s) in '<module>' have no codegen slice jars, so reuseUpstream cannot use them:
- auth 8.15.3 (missing auth-generated-sysdef, ...)
Those versions were most likely not built with Genesis 10.0, or could not be downloaded. Upgrade them to versions built with Genesis 10.0, or set genesis.codegen.overrideSlices=auth to generate their classes locally.

By default this is a warning; with genesis.codegen.reuseUpstream.strict=true the build fails with the same message. If a version has no slice jars, either upgrade to a version built with Genesis 10.0, or list the product in genesis.codegen.overrideSlices so that its generated code is produced locally.

Publishing slice jars​

Each generated system-definition, fields and DAO module has a sliceJar task. It builds the slice jar, with the classifier slice, in build/slice-libs. The jar is published through a Maven publication called generatedSlice, so that applications using your product can reuse it. A slice jar never contains the facade classes.

To publish the slice jars to your local Maven repository, run the publishAllGeneratedSlicesToMavenLocal task of your dictionary-cache module (server/build/internal-modules/<product>-dictionary-cache); to publish them to a remote repository, use the normal publish task. An application that depends on your product resolves the slice jars from its configured repositories like any other dependency, except when your product's generated modules are part of the same composite build: then it reads them directly from your local Maven repository, so publish them there first.

The consuming project must be able to resolve from the repository you published to. For a local publication, add a plain mavenLocal() to the repositories block of its server/build.gradle.kts, after its other repositories:

repositories {
// Keep your existing repositories here.
// Add mavenLocal() last, as a final fallback.
mavenLocal()
}

In a generated project this repositories block may sit inside an allprojects { } block rather than at the top level of the file; if so, add the line there.

A generated project may already declare a mavenLocal earlier in that block, restricted to the launcher's own artifacts. Leave it as it is: the plain mavenLocal() at the end is the one that resolves your slice jars.

Publishing the slice jars is not enough on its own. An application that declares your product as a product dependency also resolves the product's own -distribution and -config artifacts, so you must publish the upstream product in full as well, with its usual publish task (for example publishToMavenLocal). Run publishAllGeneratedSlicesToMavenLocal in addition to that task, not instead of it. For example, from the server directory:

./gradlew publishToMavenLocal :<product>-dictionary-cache:publishAllGeneratedSlicesToMavenLocal

If the full publication is missing, the consuming build fails with an error such as Could not find global.genesis:upstream-distribution:1.0.0-SNAPSHOT.

Settings​

Set these as Gradle properties, for example in your gradle.properties file. Table names and IDs must not collide with those of any upstream product; see the data model.

PropertyDefaultDescription
genesis.codegen.reuseUpstreamtrueSwitches upstream reuse on or off.
genesis.codegen.overrideSlicesNoneA comma-separated list of upstream products to regenerate locally instead of reusing their slice jars, for example genesis,auth.
genesis.codegen.reuseUpstream.strictfalseWhen true, the build fails in the situations described below, instead of logging a warning and carrying on.

You can also set genesis.codegen.reuseUpstream as codegenReuseUpstream in the genesis { } block of your settings.gradle.kts file. If you set it in both places, the settings file wins. Either way, the value applies to the whole build: every generated module in your application uses it.

genesis {
productName = "position"
codegenReuseUpstream = false
}

The productName also sets the prefix of your dictionary file names: each must start with <productName>-, for example position-tables-dictionary.kts. For a product that other projects depend on, the build fails on any other name.

When reuse switches off automatically​

Even with upstream reuse switched on, the build switches it off for a dictionary-cache module that belongs to one of the upstream products itself.

The build also detects an override of an upstream dictionary file. If your application overrides a dictionary file from an upstream product, for example with its own copy of an upstream *-tables-dictionary.kts file in src/main/genesis/cfg, the build logs a warning like this:

[genesis codegen] reuseUpstream disabled for '<module>': app overrides upstream dictionary files ([<file>]) ...

It then switches upstream reuse off and generates every upstream product locally, so your override takes effect, at the cost of a slower build. With genesis.codegen.reuseUpstream.strict=true, the build fails with the same message instead.

Keeping upstream reuse while overriding an upstream dictionary file is not supported yet. Listing the product in genesis.codegen.overrideSlices does not work for this yet: the build fails in generateView.

To override auth's tables:

  1. Copy auth-tables-dictionary.kts into the src/main/genesis/cfg directory of your application's module. You don't need to look for it in a jar: the build unpacks auth's configuration (from its auth-config artifact) into your application's Genesis Home, so you can take the file from build/genesis-home/auth/cfg/auth-tables-dictionary.kts in your application module, for example server/<product>-app/build/genesis-home/auth/cfg/auth-tables-dictionary.kts. The app's sync fills that directory, which Genesis Start and the IntelliJ plugin do for you, so if it is empty, start or sync the app from one of them first (if you are working outside both tools, run ./gradlew genesisSync).
  2. Make your changes in the copy.
  3. Build as usual. The build detects the override, switches upstream reuse off and generates every upstream product locally. To avoid the warning, you can switch reuse off yourself:
genesis.codegen.reuseUpstream=false

Your copy replaces auth's whole table dictionary, not just the tables you change. The build copies your application's own configuration before the dependencies' and keeps the first file it finds with a given name. So keep every auth table in your copy, not only the ones you edit.

When an upstream product's system definition doesn't match​

An upstream product's slice jar records the system definition values that its dictionary used when it was generated. If your deployment changes one of those values, the entity classes in the slice jar may not match your deployment. For example, a table might have a field that is included only when a particular system definition value is set. In auth, for instance, setting ADMIN_PERMISSION_ENTITY_TABLE and ADMIN_PERMISSION_ENTITY_FIELD adds a USER_<table>_MAP table to auth's generated code (see Table entities for the generated entity class name), where <table> is the value of ADMIN_PERMISSION_ENTITY_TABLE. For other products and values, the build tells you: its warning or error lists the changed keys for each product.

To change an upstream product's system definition value, add it to your application's own genesis-system-definition.kts. That file takes precedence over the system definitions of upstream products, so for example you set ADMIN_PERMISSION_ENTITY_TABLE and ADMIN_PERMISSION_ENTITY_FIELD there, not in a copy of auth's system definition file. Never copy an upstream product's system definition file.

What happens next depends on genesis.codegen.reuseUpstream.strict:

  • false (the default): the build regenerates the affected products locally, into your application's own dictionary-cache module alongside its own generated classes, and logs a *** DEPRECATION WARNING ***.
  • true: the build fails, with a message that names the genesis.codegen.overrideSlices value to add. For the auth example above, it reads:
[codegen] Upstream product(s) [auth] sysdef has changed — their slice jars may have structurally incorrect entity classes for this deployment (e.g. sysdef-conditional fields are missing or have wrong values).
Changed products:
- auth: changed keys [ADMIN_PERMISSION_ENTITY_TABLE, ADMIN_PERMISSION_ENTITY_FIELD]
Add 'genesis.codegen.overrideSlices=auth' to gradle.properties to regenerate those products' entity classes locally.

The warning looks like this (trimmed):

[codegen] *** DEPRECATION WARNING ***
...
genesis.codegen.overrideSlices=<products>
...

The lenient behaviour is deprecated, with no removal version set. To opt in to the future behaviour now, set genesis.codegen.reuseUpstream.strict=true and list the products concerned in genesis.codegen.overrideSlices. Use the value that the build's warning or error names.

genesis.codegen.reuseUpstream.strict=true
genesis.codegen.overrideSlices=genesis,auth

This example lists genesis as well as auth because Genesis's own dictionary also reads ADMIN_PERMISSION_ENTITY_FIELD, so setting these values flags both products.

Your application's own product is always handled automatically. You never need to list it in genesis.codegen.overrideSlices.

Extending an upstream table with tableUnion​

If your application uses tableUnion to add fields to a table that belongs to an upstream product, that product's slice jar doesn't contain your extra fields. You must list the product in genesis.codegen.overrideSlices so that it is regenerated locally. This applies whatever the strict setting. If the product isn't listed, the build fails with a message that names the value to add. Tables that belong to your application's own product don't need this.

The error looks like this. The table and product names depend on your build:

[codegen] tableUnion detected for table(s) [PROFILE] belonging to upstream product(s) [auth] — their slice jars lack the union fields. Add 'genesis.codegen.overrideSlices=auth' to gradle.properties to regenerate those products' entity classes locally.

For example, this position-tables-dictionary.kts adds the field DEPARTMENT, declared inline inside the tableUnion, to auth's PROFILE table:

tables {
tableUnion(name = "PROFILE") {
field("DEPARTMENT", STRING)
}
}

For what tableUnion accepts, see tableUnion in the data model reference.