# Build settings for `--dynamic-sbom-inference` How to write the `socket.json` settings that `--dynamic-sbom-inference` reads, by hand or with an agent. `socket manifest setup --dynamic-sbom-inference` asks the same questions interactively and writes the same files. ## What the scan does 1. Finds every file that looks like a build: `pom.xml` and its variants (`*-*.pom.xml`, `pom`), `.sln`, `.slnx`, `.csproj`, `.fsproj`, `.vbproj`, `build.gradle(.kts)`, `settings.gradle(.kts)`, `build.sbt`. It honours `.gitignore`, `socket.yml` ignores and `--exclude-paths`. 2. Runs each build's own tool (Maven, Gradle, sbt, the .NET SDK) to resolve its dependencies, unless another build already loads it. A Maven reactor builds its modules, including ones outside its directory such as `../core`; a Gradle or sbt build builds its subprojects. 3. Fails if any build it runs fails, naming the build. Settings tell the build tools how to run each build, and which builds not to run. ## Prefer builds Socket can load Socket learns what a build includes only by letting its tool load it: Maven profiles, Gradle settings scripts and sbt definitions are code. When a build loads: - each module is built once, inside the build that owns it; - skipping the build skips exactly it and its modules, wherever they are, and leaves the builds next to and beneath it alone. So fix a build that fails to load (usually a JDK, build tool or option) before reaching for a skip. ## Where settings live - Any directory may hold a `socket.json`. Its settings apply to that directory and everything beneath it. - Every `socket.json` from the filesystem root down to a build's directory applies; for each field the nearest one wins. `null` clears an inherited value. - `defaults.manifest.builds` in a directory's `socket.json` holds settings for one build of that directory, keyed by its build file name. They apply after all directory settings, to that build alone. ```json { "version": 1, "defaults": { "manifest": { "maven": { "javaHome": "$JAVA17_HOME" }, "builds": { "pom.xml": { "disabled": true }, "tools-cli.pom.xml": { "mavenOpts": "-Pcli" } } } } } ``` A Gradle or sbt build is keyed by any one of its build files that exists (`settings.gradle`, `build.gradle.kts`, `build.sbt`, ...); two entries for the same build are an error. ## Fields Under `defaults.manifest.maven`, `.gradle`, `.sbt` or `.dotnet`, or inside a `builds` entry: | Field | Meaning | |---|---| | `bin` | Build tool command. Relative paths are relative to the build's directory. Defaults to the project's wrapper (`mvnw`, `gradlew`) if present, else `mvn`, `gradle`, `sbt`, `dotnet`. | | `javaHome` | JDK for Maven, Gradle and sbt. `$VAR` and `${VAR}` expand from the environment. | | `mavenOpts`, `gradleOpts`, `sbtOpts`, `dotnetOpts` | Arguments passed to the build tool, for example profiles or `-p:Configuration=Release`. Maven's `-f`/`--file` is ignored: each POM is built by its own file. | | `includeConfigs`, `excludeConfigs` | Comma-separated globs over Maven scopes, Gradle and sbt configurations, or .NET target frameworks. | | `ignoreUnresolved` | `true` warns about dependencies that don't resolve instead of failing. | | `disabled` | `true` skips builds; see below. | | `facts` | Gradle and sbt: `false` skips the build. | | `verbose` | `true` streams the build tool's output. | ## Skipping builds | To skip | Set | Effect | |---|---|---| | One build and what it loads | `builds[""].disabled: true` in its directory | Socket still loads the build, resolving nothing, to find its modules. If it can't load it, the scan fails. | | A directory and everything beneath it | `defaults.manifest..disabled: true` in that directory | Nothing is loaded. A nearer `socket.json` with `disabled: false` turns builds beneath it back on. | Don't use `--exclude-paths` to skip builds: it also removes those files from the scan and from reachability analysis. Socket can't skip a module of a build that runs: the build resolves its modules itself. Settings for such a module are ignored, with a warning. ## Procedure for an agent 1. Run `socket manifest dynamic-sbom-inference --json` from the repository root. It runs every build and lists each with a status: | Status | Meaning | |---|---| | `generated` | Built. | | `empty` | Built; nothing to resolve. | | `skippedCovered` | Built as part of another build. | | `skippedDisabled` | Skipped by a setting, or loaded by a skipped build. | | `failed` | Its build tool failed; the output above it says why. | | `aborted` | Not run because a build in or above its directory failed. | 2. For each `failed` build, read the build tool's error and fix the cause in the nearest fitting `socket.json`: `javaHome` for a wrong JDK, `bin` for a missing tool, `Opts` for missing profiles or properties. 3. Skip a build only when it is not meant to be built (a test fixture, a template, an abandoned project), using the table above. Prefer `builds[""].disabled` when the build loads; use the directory form only when it doesn't. 4. Repeat until no build is `failed` or `aborted`. 5. Commit the `socket.json` files. ## Example ``` repo/ pom.xml reactor with modules api, web codegen/ pom.xml not shipped: skip it codegen-cli.pom.xml shipped legacy/ pom.xml doesn't load any more, with modules old-core, old-ui tool/pom.xml separate build, shipped ``` `codegen/socket.json` skips one of two builds in the directory: ```json { "version": 1, "defaults": { "manifest": { "builds": { "pom.xml": { "disabled": true } } } } } ``` `legacy/pom.xml` doesn't load, so `legacy/socket.json` skips the directory: ```json { "version": 1, "defaults": { "manifest": { "maven": { "disabled": true } } } } ``` and `legacy/tool/socket.json` turns the build beneath it back on: ```json { "version": 1, "defaults": { "manifest": { "maven": { "disabled": false } } } } ```