Gradle project structure
This page explains Gradle modules, Kotlin source placement, packages, and task selection. For the logical element tree and engineering work products, start with CREATE modeling and the element hierarchy.
Gradle project vs. “module” (leaf-only)
In STIG documentation we use module to mean a Gradle subproject (a Gradle project that is included from the root settings.gradle.kts).
STIG assumes a leaf-only Gradle structure:
You can have any filesystem layout (nested folders),
but only the leaf modules are added to
settings.gradle.ktswhen import is enabled,and no intermediate folders are turned into Gradle projects.
Example (leaf-only include):
When using the default STIG_SUBDIR placement, the module root is the stig/ subfolder while the module name stays the same:
The CREATE tutorial explains how the element hierarchy relates to this Gradle/Kotlin layout.
Shared model libraries
A catalogue of service interfaces can live in a Kotlin module without representing an architectural element. Initialize it with its intended package, preserving the package when moving existing declarations:
The initializer registers the module, creates its build file and ordinary Dokka module description, and creates no Element or CREATE viewpoint templates. Its module configuration explicitly disables checks and selects compact documentation. Model libraries do not inherit native source analyses from project defaults. Consumers keep ordinary Kotlin dependencies; use api(project(":interfaces:shared")) when their public port types expose types from the library. This dependency does not introduce an Element.parent relationship.
The library still compiles and supplies declarations for model loading and PSI reference resolution. Findings about its declarations belong to the library, so consumers do not repeat those defects. stig { modelCheck { enabled = false } } disables all of that module's viewpoint checks. IDEA honors this explicitly authored module setting before live inspection materialization. Other modules can still use the declarations as check context.
See compact model documentation for rendering controls and import and export for routing shared interfaces into the library.
Element directory
STIG treats a directory as the home of an element. In practice, this is often the same directory as a Gradle module, except when using STIG_SUBDIR where the module root is <elementDir>/stig.
The element/module directory can contain:
implementation sources (C/C++/Kotlin/etc.),
build metadata (e.g. Bazel targets),
generated artifacts,
and STIG modeling work products.
Placement (where viewpoint sources live)
The five CREATE viewpoints use the conventional context/, requirements/, design/, analysis/, and tests/ packages. STIG supports two placements for their sources. Both use the standard Kotlin source layout and include the package path.
DIRECT
Viewpoints are located directly under the module’s Kotlin source tree:
Use this when the module is “model-only” and you do not need extra separation.
STIG_SUBDIR (default)
Viewpoints are placed under a dedicated stig/ folder inside the module:
Use this when the module also contains implementation (or multiple languages) and you want the STIG work products isolated.
The module root for Gradle becomes <module>/stig (build file lives there), while the module name in settings.gradle.kts remains unchanged.
Context compilation
Each element project compiles sources under context/ in its stigContext source set. The other viewpoints compile in main. Files keep their authored paths and remain part of one element's checks and documentation. The main artifact includes the Context declarations, while stigContextJar packages those declarations separately.
This permits parent Design → child Context → parent Context dependencies. The parent's compileKotlin can use the child's compileStigContextKotlin output without requiring the child's other viewpoints. A child Analysis can still use an ordinary implementation(project(...)) dependency on its parent's Analysis. Splitting declarations across files alone does not remove a Gradle compilation cycle.
STIG prepares Context dependencies for element references found in Kotlin sources, using configured element IDs. Context compilation also consumes the Context artifacts of ordinary STIG project dependencies. External library dependencies remain available. For a reference assembled by a Kotlin factory that source discovery cannot identify, declare the Context artifact explicitly:
When the reference appears in Context code itself, add that dependency to stigContextImplementation. Keep Context declarations independent of Requirements, Design, Analysis, and Tests. If two Contexts require each other during JVM initialization, use the supported delayed modelReferences({ target }) lists where applicable; delayed evaluation does not remove a compilation cycle between two Context source sets.
Checks and Dokka share a separate context-loading configuration. They compile and load the complete child viewpoints selected by Design.children, including unreferenced Analysis roots. Use stigModelContext for additional complete model modules produced by dynamic references; it is separate from compilation dependencies.
Packages
STIG tasks write Kotlin files into .../<packagePath>/... and set the package ... declaration accordingly.
The package can be inferred (recommended for quick start).
You can always override it explicitly using
basePackage.
For deterministic behavior in “unbalanced” repository layouts, package inference should be based on the module directory relative to the root project directory.
Project-wide base package prefix
Set a reverse-domain prefix once in the consumer's settings.gradle.kts to namespace every inferred package across the project:
With the example above, an element at activities/aeb/X/ infers package com.example.app.activities.aeb.X instead of activities.aeb.X. Empty default = no prefix (legacy behavior). An explicit task option such as --basePackage is treated as the full FQN and bypasses the prefix.
Selecting an element at the command line
Two Gradle properties (-P...) select which element root-level pipeline tasks should operate on:
-Pelement=<selector>— canonical form is the fully-qualified Gradle project path (matches what IntelliJ's Gradle tool window shows):./gradlew :activities:aeb:fusion_activity:stigCheckModel ./gradlew stigCheckModel -Pelement=:activities:aeb:fusion_activityThe leaf element name is accepted as shorthand when unambiguous:
./gradlew stigCheckModel -Pelement=fusion_activity-PimplementationDir=<absolute path>— selects by the absolute path of the source implementation directory. Useful from Bazel/CI wrappers that already know the path.
All other former selectors (Maven group, build system, import-from settings, user repo dir, etc.) are configured via gradle.properties or the stigProject { ... } settings DSL — not via -P.
Component vs. other element kinds
Some tasks (for example complexity + flow analysis) run only on Component.
STIG determines whether a module is a component by reading the Kotlin context model (usually in the context/ viewpoint) and checking the element’s base type (for example, whether the class derives from Component).
Running tasks
Run tasks from the repository root (the directory with settings.gradle.kts):
If you are in a subdirectory, point Gradle at the root build: