ytt code docs - HackMD

--- title: ytt code docs tags: ytt --- ## Source Code Structure The `ytt` source is deliberately organized into layers (each of which is detailed, below): 1. [Applications](#Applications) (`./cmd`) 2. [Processing User Input / Commands](#Processing-User-Input--Commands) (`./pkg/cmd`) 3. [Core Workflow](#Core-Workflow) (`./pkg/workspace`) 4. [Templating](#Templating) 5. [Primitives](#Primitives) ### Applications There are two applications, each with their own `main()`: - [cmd/ytt](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/cmd/ytt) — is the main() for the command-line tool, `ytt` - ytt uses Cobra for processing command-line input and executing. - [cmd/ytt-lambda-website](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/cmd/ytt-lambda-website) — is the main() for the AWS Lambda function that the ytt Playground uses to process inputs. _(Note: `cmd`, here, is short for command-line tool.)_ ### Processing User Input / Commands Each `ytt` invocation is processing command-line arguments and running a specific "command" (i.e. a [Cobra](https://github.com/spf13/cobra#readme) command). - [pkg/cmd/template](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/cmd/template) — implementation of the `template` command. This is the most used command in `ytt`. (not to be confused with `pkg/template`) - `Options.RunWithFiles()` — entry point to `template` command. - ... - [pkg/cmd](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/cmd/) — all other `ytt` commands are entirely contained in single `.go` files of the same name. - [pkg/cmd/ui](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/cmd/ui) — abstraction of the user interface (typically is stdin/stdout aka "tty") Note: `cmd`, here, is short for [Command](https://refactoring.guru/design-patterns/command). ### Core Workflow The `template` command relies on these "services" to perform the "real work." - [pkg/workspace](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/workspace) — keeps input files from the filesystem in memory for later access. Provides set of tools for loading files from file system for initial interpretation like data values, schemas, templates. - [`Library`](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/workspace/library.go) — a [Composite](https://refactoring.guru/design-patterns/composite), that is the total set of files to be processed in a run. - Each `Library` instance roughly corresponds to a directory on disk. - [`LibraryExecution`](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/workspace/library_execution.go)— an evaluation of a `Library` (i.e. loading schema, setting data values, evaluating templates, applying overlays) - - data-values-pre-processing - Overlay post processing - `load(...)` directive goes through `TemplateLoader` to load files - [pkg/files](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/files) - handles files/dirs/symlinks as input (reading); defines the 'type' of file based on user flags/marks - handles output files/dirs (writing) --- ### Templating Processing YAML and text inputs that contain `ytt` annotations, Starlark expressions and code. There are two "dialects" of templates: YAML and text. - [pkg/template](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/template) -- compile an input template into a Starlark program that generates the corresponding output (not to be confused with `pkg/cmd/template`). - [`CompiledTemplate`](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/template/compiled_template.go) — the input "structure" (either a YAML or text AST) turned into a Starlark program that, when executed, builds the output "structure" (an `EvaluationNode` [composite](https://refactoring.guru/design-patterns/composite)). - `InstructionSet` provides generic template instruction set for building Starlark templates - [pkg/yamltemplate](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/yamltemplate) -- implementation of YAML-based templates - [pkg/texttemplate](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/texttemplate) -- implementation of text templates --- ### Primitives - pkg/yamlmeta - Parse the stream of bytes into YAML AST, attaches data to its node - [pkg/schema](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/schema) — - ... --- ### Utility Packages - pkg/filepos - contains Position object and operations for - pkg/orderedmap - converts --- ## Original Docs... _(this is what documentation we start with...)_ - [pkg/cmd/template/cmd.go](https://github.com/vmware-tanzu/carvel-ytt/blob/develop/pkg/cmd/template/cmd.go#L95) is the top level call site for the template command - [pkg/files](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/files) allows reading files from filesystem - [pkg/yamlmeta](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/yamlmeta) parses YAML and tracks YAML node annotations (metas) - [pkg/yamltemplate](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/yamltemplate) generates Starlark template based on yamlmeta package structures - [pkg/texttemplate](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/texttemplate) parses text templates and generates Starlark template - [pkg/template](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/template) - `InstructionSet` provides generic template instruction set for building Starlark templates - `CompiledTemplate` uses [Starlark Go library](https://github.com/google/starlark-go) to evaluate Starlark code - [pkg/yttlibrary](https://github.com/vmware-tanzu/carvel-ytt/tree/develop/pkg/yttlibrary) is bundled `@ytt` library - you can also make your own libraries as exemplified by [vmware-tanzu/carvel-ytt-library-for-kubernetes](https://github.com/vmware-tanzu/carvel-ytt-library-for-kubernetes) --- Other diagrams/docs: - https://excalidraw.com/#room=f42aed35d60e4b2ad3c3,1-KgnLlxNSvfHHouF77psg Schema validations cheat sheet | Use Case | Syntax | | --------------- | ----------------------------- | | | | | Required String | #@schema/validation min_len=1 username: "" <td></td> | | | | The action of every agent <br /> into the world <br /> starts <br /> from their physical selves. <br />