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 - Source for the built-in IDL ornament demo and its worked program.
• 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.

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

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