# IDL example


This tour shows the built-in IDL ornament. It starts from a protobuf-style
builder spec and asks for generated outputs in two languages. The example
is smaller than the Node and C tours because the builder vocabulary already
lives in `mb.ornaments.idl`; the useful part is seeing how that ornament
still produces the same internalized program views.

## Start from the artifact

The IDL builder describes a generated artifact named
`example-idl-generated`. The spec declares protobuf as the IDL format
and asks for C++ and Java outputs. Materialization records both output
trees in the build plan.

## Source files

These pages are the complete source for the worked example: the builder module plus the files it consumes.

- [IDL builder module](/metaBuilder/examples/idl/source/builder.nix) - Source for the built-in IDL ornament demo and its worked program.
- [schema.proto](/metaBuilder/examples/idl/source/schema.proto) - Small protobuf schema fixture consumed by the IDL demo.

## Builder vocabulary

`mb.ornaments.idl.fromProtobuf` is the public constructor. It produces
an `IdlBuilder` value with IDL format, proto sources, language targets,
generated outputs, and tool-backed operations.

```nix
mb.ornaments.idl.fromProtobuf {
  name = "example-idl";
  protos = [ ./idl/schema.proto ];
  languages = [ "cpp" "java" ];
}
```

## Program walkthrough

The ornament lowers the IDL spec into a program that declares the
protobuf tool, runs one generation step per language, and materializes
the generated output tree. The same program can be validated, rendered
as a dry-run, shown as a shell plan, documented, and materialized.

## One build, many views

The section below is generated from `mb.program.introspect.run
program`. It shows the same interpretation surface as the greenfield
examples, but for a built-in ornament.

The same internalized program is interpreted several ways.

### Validation

- result: `ok`

### Dependency Graph

- nodes: `3`
- edges: `2`
- services: `0`
- node `tool:protoc` (tool) package `protobuf`
- node `operation:protoc-cpp-schema.proto` (operation) via `protoc`
- node `operation:protoc-java-schema.proto` (operation) via `protoc`
- edge `tool:protoc` -> `operation:protoc-cpp-schema.proto` (uses-tool)
- edge `tool:protoc` -> `operation:protoc-java-schema.proto` (uses-tool)

### Dry Run - Builder

- source `schema.proto`
- tool `protoc`
- run `protoc-cpp-schema.proto` with `protoc`
- run `protoc-java-schema.proto` with `protoc`
- transform `cpp` (tree)
- transform `java` (tree)
- descriptor `example-idl-idl`
- materialize `example-idl-generated` with `runCommand`

### Dry Run - Runtime

None.

### Plan View

- run `protoc-cpp-schema.proto`
- run `protoc-java-schema.proto`
- `protoc-cpp-schema.proto`: `protoc '--cpp_out='"$out"/cpp "$pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4"`
- `protoc-java-schema.proto`: `protoc '--java_out='"$out"/java "$pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4"`

### Plan Shell Excerpt

```sh
pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4=<source:schema.proto>
protoc '--cpp_out='"$out"/cpp "$pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4"
protoc '--java_out='"$out"/java "$pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4"
```

### Runtime Services

None.

### Descriptors

- descriptor `example-idl-idl` (payload keys `format`, `kind`, `languages`, `sources`)

### Builder Self-Documentation

- documented operations: `8`
- runtime services: `0`

### Materialized Outputs

- cpp -> $out/cpp (tree)
- java -> $out/java (tree)

### Materialization

- derivation: `example-idl-generated`
- outputs: `2`
- runtime artifacts: `0`

### Substrates

- dockerfile: `supported`
- shell: `supported`