builders

README

Go and proto builders
=====================

This directory contains a set of small programs for building pieces of Go
programs. These are used by Bazel during the execution phase instead of
Bash scripts, which are not portable and are prone to spacing and quoting
errors.

Most builders invoke programs in the Go toolchain. For example, ``compile.go``
invokes ``go tool compile``. Builders generally perform some extra actions
(for example, source filtering) before invoking the underlying tool.

Builder programs are constructed using a special rule, ``go_tool_binary``,
which breaks a cyclic dependency (``go_binary`` and other rules depend on
builders implicitly). This rule does not allow any library dependencies,
so all sources need to be compiled together in the ``main`` package.

Principles for writing builders
-------------------------------

* Builders that need to be directly available on the toolchain should be
  registered with the ``builder`` rule in ``go/private/rules/builders.bzl``.
  Special purpose builders like ``stdlib.go`` don't need to do this.
* Builders should have a package comment describing what the builder is for.
* ``log.SetFlags(0)`` should be called in ``main`` to avoid logging timestamps.
  ``log.SetPrefix`` should be called with the builder's mnemonic
  (e.g., ``GoCompile``).
* Builders should accept arguments in three forms:

  * Builder arguments (before ``--``) are interpreted directly by builders.
    These arguments may or may not be passed on to underlying tools.
  * Tool arguments (after ``--``) are passed on to underlying tools. Builders
    may add additional arguments before or after these.
  * Environment variables are passed on to underlying tools. Builders will
    usually not modify these.

* Arguments common to multiple builders (for example, ``-go``, ``-v``) should
  be handled in ``env.go``.
* Subcommands should be run through ``env.runGoCommand`` for uniform logging
  and error reporting.

Documentation

Overview

asm builds a single .s file with "go tool asm". It is invoked by the Go rules as an action.

compile compiles .go files with "go tool compile". It is invoked by the Go rules as an action.

cover transforms a source file with "go tool cover". It is invoked by the Go rules as an action.

embed generates a .go file from the contents of a list of data files. It is invoked by go_embed_data as an action.

info prints debugging information about the go environment. It is used to help examine the execution environment of rules_go

link combines the results of a compile step using "go tool link". It is invoked by the Go rules as an action.

md5sum replicates the equivalent functionality of the unix tool of the same name.

pack copies an .a file and appends a list of .o files to the copy using go tool pack. It is invoked by the Go rules as an action.

pack can also append .o files contained in a static library passed in with the -arc option. That archive may be in BSD or SysV / GNU format. pack has a primitive parser for these formats, since cmd/pack can't handle them, and ar may not be available (cpp.ar_executable is libtool on darwin).

protoc invokes the protobuf compiler and captures the resulting .pb.go file.

stdlib builds the standard library in the appropriate mode into a new goroot.

stdlib builds the standard library in the appropriate mode into a new goroot.