generate

Documentation

Overview

Package generate implements code generation. It includes all available code generation strategies on Terramate and it also handles outdated code detection and deletion.

Index

• Constants
• func DetectOutdated(root *config.Root, target *config.Tree, vendorDir project.Path) ([]string, error)
• func ListStackGenFiles(root *config.Root, dir string) ([]string, error)
• type FailureResult
• type GenFile
• type LoadResult
  • func Load(root *config.Root, vendorDir project.Path) ([]LoadResult, error)
• type Report
  • func Do(root *config.Root, targetDir project.Path, parallel int, ...) *Report
  • func (r Report) Full() string
  • func (r Report) HasFailures() bool
  • func (r Report) Minimal() string
• type Result

Constants

const (
	// ErrLoadingGlobals indicates failure loading globals during code generation.
	ErrLoadingGlobals errors.Kind = "loading globals"

	// ErrManualCodeExists indicates code generation would replace code that
	// was not previously generated by Terramate.
	ErrManualCodeExists errors.Kind = "manually defined code found"

	// ErrConflictingConfig indicates that two code generation configurations
	// are conflicting, like both generates a file with the same name
	// and would overwrite each other.
	ErrConflictingConfig errors.Kind = "conflicting config detected"

	// ErrInvalidGenBlockLabel indicates that a generate block
	// has an invalid label as the target to save the generated code.
	ErrInvalidGenBlockLabel errors.Kind = "invalid generate block label"

	// ErrAssertion indicates that code generation configuration
	// has a failed assertion.
	ErrAssertion errors.Kind = "assertion failed"
)

Functions

func DetectOutdated

func DetectOutdated(root *config.Root, target *config.Tree, vendorDir project.Path) ([]string, error)

DetectOutdated will verify if the given config has outdated code in the target tree and return a list of filenames that are outdated, ordered lexicographically.

func ListStackGenFiles

func ListStackGenFiles(root *config.Root, dir string) ([]string, error)

ListStackGenFiles will list the path of all generated code inside the given dir and all its subdirs that are not stacks. The returned paths are relative to the given dir, like:

• filename.hcl
• dir/filename.hcl

The filenames are ordered lexicographically. They always use slash (/) as a dir separator (independent on the OS).

dir must be an absolute path and must be inside the given rootdir.

When called with a dir that is not a stack this function will provide a list of all orphaned generated files inside this dir, since it won't search inside any stacks. So calling with dir == rootdir will provide all orphaned files inside a project if the root of the project is not a stack.

When called with a dir that is a stack this function will list all generated files that are owned by the stack, since it won't search inside any child stacks.

Types

type FailureResult

type FailureResult struct {
	Result
	Error error
}

FailureResult represents a failure on code generation.

type GenFile

type GenFile interface {
	// Builtin tells if the generated file is builtin.
	Builtin() bool
	// Header is the header of the generated file, if any.
	Header() string
	// Body is the body of the generated file, if any.
	Body() string
	// Label is the label of the origin generate block that generated this file.
	Label() string
	// Context is the context of the generate block.
	Context() string
	// Range is the range of the origin generate block that generated this file.
	Range() info.Range
	// Condition is true if the origin generate block had a true condition, false otherwise.
	Condition() bool
	// Asserts is the origin generate block assert blocks.
	Asserts() []config.Assert
}

GenFile represents a generated file loaded from a Terramate configuration.

type LoadResult

type LoadResult struct {
	// Dir is from where the generated files were loaded, or where a failure occurred
	// if Err is not nil.
	Dir project.Path
	// Files is the generated files for this directory.
	Files []GenFile
	// Err will be non-nil if loading generated files for a specific dir failed
	Err error
}

LoadResult represents all generated files of a specific directory.

func Load

func Load(root *config.Root, vendorDir project.Path) ([]LoadResult, error)

Load will load all the generated files inside the given tree. Each directory will be represented by a single LoadResult inside the returned slice. Errors generating code for specific dirs will be found inside each LoadResult.

The given vendorDir is used when calculating the vendor path using tm_vendor on the generate blocks.

If a critical error that fails the loading of all results happens it returns a non-nil error. In this case the error is not specific to generating code for a specific dir.

type Report

type Report struct {
	// BootstrapErr is an error that happened before code generation
	// could be started, indicating that no changes were made to any stack.
	BootstrapErr error

	// Successes are the success results
	Successes []Result

	// Failures are stacks that failed without generating any code
	Failures []FailureResult

	// CleanupErr is an error that happened after code generation
	// was done while trying to cleanup files outside stacks.
	CleanupErr error
}

Report has the results of the code generation process.

func Do

func Do(
	root *config.Root,
	targetDir project.Path,
	parallel int,
	vendorDir project.Path,
	vendorRequests chan<- event.VendorRequest,
) *Report

Do will generate code for the entire configuration.

There generation mechanism depend on the generate_* block context attribute:

- context=stack

In this case, for each stack in the project, its blocks are loaded using a "Stack Evaluation Context" from the stack directory, checked for conflicts and generated. A Stack Evaluation Context contains the Project Metadata, Stack Metadata and the Globals hierarchically loaded for the stack.

- context=root

In this case, all of the generate_file blocks with context=root from the project are loaded, checked for conflicts, evaluated using a "Root Evaluation Context" and generated. A Root Evaluation Context contains just the Project Metadata.

The given vendorDir is used when calculating the vendor path using tm_vendor on the generate blocks. The vendorRequests channel will be used on tm_vendor calls to communicate each vendor request. If the caller is not interested on event.VendorRequest events just pass a nil channel.

It will return a report including details of which directories succeed and failed on code generation, any failure found is added to the report but does not abort the overall code generation process, so partial results can be obtained and the report needs to be inspected to check.

func (Report) Full

func (r Report) Full() string

Full provides a full report of the generated code, including information per stack.

func (Report) HasFailures

func (r Report) HasFailures() bool

HasFailures returns true if this report includes any failures.

func (Report) Minimal

func (r Report) Minimal() string

Minimal provides a minimal report of the generated code. It only lists created/deleted/changed files in a per file manner.

type Result

type Result struct {
	// Dir is the absolute path of the dir relative to the project root.
	Dir project.Path
	// Created contains filenames of all created files inside the stack
	Created []string
	// Changed contains filenames of all changed files inside the stack
	Changed []string
	// Deleted contains filenames of all deleted files inside the stack
	Deleted []string
}

Result represents code generation result