ninjagraph

Documentation

Overview

ninjagraph provides utilities to parse the DOT output from Ninja's `-t graph` tool to a Go native format.

Index

• type Edge
• type Graph
  • func FromDOT(r io.Reader) (Graph, error)
  • func WithStepsOnly(g Graph) (Graph, error)
  • func (g *Graph) CriticalPath() ([]ninjalog.Step, error)
  • func (g *Graph) CriticalPathV2() ([]ninjalog.Step, error)
  • func (g Graph) IsEmpty() bool
  • func (g *Graph) PopulateEdges(steps []ninjalog.Step) error
  • func (g *Graph) PopulatedSteps() ([]ninjalog.Step, error)
• type Node

Types

type Edge

type Edge struct {
	Inputs  []int64
	Outputs []int64
	Rule    string

	// Step is a build step associated with this edge. It can be derived from
	// joining with ninja_log. After the join, all steps on non-phony edges are
	// populated.
	Step *ninjalog.Step
	// contains filtered or unexported fields
}

Edge is an edge in Ninja's build graph. It links nodes with a build rule.

type Graph

type Graph struct {
	// Nodes maps from node IDs to nodes.
	Nodes map[int64]*Node
	// Edges contains all edges in the graph.
	Edges []*Edge
	// contains filtered or unexported fields
}

Graph is a Ninja build graph.

func FromDOT

func FromDOT(r io.Reader) (Graph, error)

FromDOT reads all lines from the input reader and parses it into a `Graph`.

This function expects the content to be parsed to follow the Ninja log format, otherwise the results is undefined.

func WithStepsOnly

func WithStepsOnly(g Graph) (Graph, error)

WithStepsOnly returns an extracted subgraph that contains edges that either have `Step`s associated with them, or are phonies. Only nodes with edges connected to them are kept in the returned graph.

This function is useful, after `Step`s are populated, for extracting a partial build graph from, for example, incremental builds and failed builds.

If this function returns successfully, the returned Graph is guaranteed to have steps associated to all non-phony edges. All phony edges are kept to preserve dependencies.

func (*Graph) CriticalPath

func (g *Graph) CriticalPath() ([]ninjalog.Step, error)

CriticalPath returns the build path that takes the longest time to finish. That is, the sum of build durations on edges along this path is the largest among all build paths.

`Step`s on all non-phony edges must be populated before this function is called, otherwise an error is returned.

func (*Graph) CriticalPathV2

func (g *Graph) CriticalPathV2() ([]ninjalog.Step, error)

CriticalPathV2 calculates critical path by looking for all actions with zero float.

A critical path is the path through the build that results in the latest completion of the build.

func (Graph) IsEmpty

func (g Graph) IsEmpty() bool

IsEmpty returns true iff the graph has no nodes and no edges.

func (*Graph) PopulateEdges

func (g *Graph) PopulateEdges(steps []ninjalog.Step) error

PopulateEdges joins the build steps from ninjalog with the graph and populates build time on edges.

`steps` should be deduplicated, so they have a 1-to-1 mapping to edges. Although the mapping can be partial, which means not all edges from the graph have a corresponding step from the input.

If any non-phony edges are missing steps, subsequent attempt to calculate critical path will fail. To avoid this, use `WithStepsOnly` to extract a partial graph.

func (*Graph) PopulatedSteps

func (g *Graph) PopulatedSteps() ([]ninjalog.Step, error)

PopulatedSteps returns all steps previously associated with the build graph through `PopulateEdges`, but with `OnCriticalPath`, `TotalFloat` and `Drag` set.

type Node

type Node struct {
	// ID is an unique ID of this node.
	ID int64
	// Path is the path to the input/output file this node represents.
	Path string
	// In is the edge that produced this node. Nil if this node is not produced by
	// any rule.
	In *Edge
	// Outs contains all edges that use this node as input.
	Outs []*Edge
	// contains filtered or unexported fields
}

Node is a node in Ninja's build graph. It represents an input/ouput file in the build.