From 90ebfbd4aa58ce4332dead57f062c47acf265273 Mon Sep 17 00:00:00 2001 From: Ian Cottrell Date: Thu, 14 Dec 2017 19:04:18 -0500 Subject: [PATCH] Review feedback plus documentation --- go/core.rst | 40 +++- go/modes.rst | 26 ++- go/private/actions/binary.bzl | 1 - go/private/context.bzl | 3 +- go/private/rules/cgo.bzl | 2 +- go/private/rules/test.bzl | 2 +- go/toolchains.rst | 415 +++++++++++++++++++++------------- 7 files changed, 324 insertions(+), 165 deletions(-) diff --git a/go/core.rst b/go/core.rst index a756f0c72b..52d34621c8 100644 --- a/go/core.rst +++ b/go/core.rst @@ -6,7 +6,7 @@ Core go rules .. _gazelle: tools/gazelle/README.rst .. _build constraints: http://golang.org/pkg/go/build/ .. _GoLibrary: providers.rst#GoLibrary -.. _GoSourceList: providers.rst#GoSourceList +.. _GoSource: providers.rst#GoSource .. _GoArchive: providers.rst#GoArchive .. _cgo: http://golang.org/cmd/cgo/ .. _"Make variable": https://docs.bazel.build/versions/master/be/make-variables.html @@ -15,6 +15,8 @@ Core go rules .. _cc library deps: https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library.deps .. _pure: modes.rst#pure .. _static: modes.rst#static +.. _goos: modes.rst#goos +.. _goarch: modes.rst#goarch .. _mode attributes: modes.rst#mode-attributes .. role:: param(kbd) @@ -58,7 +60,7 @@ Providers ^^^^^^^^^ * GoLibrary_ -* GoSourceList_ +* GoSource_ * GoArchive_ Attributes @@ -94,7 +96,7 @@ Attributes | :param:`embed` | :type:`label_list` | :value:`None` | +----------------------------+-----------------------------+---------------------------------------+ | List of Go libraries this test library directly. | -| These may be go_library rules or compatible rules with the GoSourceList_ provider. | +| These may be go_library rules or compatible rules with the GoLibrary_ provider. | | These can provide both :param:`srcs` and :param:`deps` to this library. | | See Embedding_ for more information about how and when to use this. | +----------------------------+-----------------------------+---------------------------------------+ @@ -167,7 +169,8 @@ Providers ^^^^^^^^^ * GoLibrary_ -* GoSourceList_ +* GoSource_ +* GoArchive_ Attributes ^^^^^^^^^^ @@ -202,7 +205,7 @@ Attributes | :param:`embed` | :type:`label_list` | :value:`None` | +----------------------------+-----------------------------+---------------------------------------+ | List of Go libraries this binary embeds directly. | -| These may be go_library rules or compatible rules with the GoSourceList_ provider. | +| These may be go_library rules or compatible rules with the GoLibrary_ provider. | | These can provide both :param:`srcs` and :param:`deps` to this binary. | | See Embedding_ for more information about how and when to use this. | +----------------------------+-----------------------------+---------------------------------------+ @@ -223,6 +226,26 @@ Attributes | This is one of the `mode attributes`_ that controls whether to link in static_ mode. | | It should be one of :value:`on`, :value:`off` or :value:`auto`. | +----------------------------+-----------------------------+---------------------------------------+ +| :param:`goos` | :type:`string` | :value:`auto` | ++----------------------------+-----------------------------+---------------------------------------+ +| This is one of the `mode attributes`_ that controls which goos_ to compile and link for. | +| | +| If set to anything other than :value:`auto` this overrideds the default as set by the current | +| target platform, and allows for single builds to make binaries for multiple architectures. | +| | +| Because this has no control over the cc toolchain, it does not work for cgo, so if this | +| attribute is set then :param:`pure` must be set to :value:`on`. | ++----------------------------+-----------------------------+---------------------------------------+ +| :param:`goarch` | :type:`string` | :value:`auto` | ++----------------------------+-----------------------------+---------------------------------------+ +| This is one of the `mode attributes`_ that controls which goarch_ to compile and link for. | +| | +| If set to anything other than :value:`auto` this overrideds the default as set by the current | +| target platform, and allows for single builds to make binaries for multiple architectures. | +| | +| Because this has no control over the cc toolchain, it does not work for cgo, so if this | +| attribute is set then :param:`pure` must be set to :value:`on`. | ++----------------------------+-----------------------------+---------------------------------------+ | :param:`gc_goopts` | :type:`string_list` | :value:`[]` | +----------------------------+-----------------------------+---------------------------------------+ | List of flags to add to the Go compilation command when using the gc compiler. | @@ -314,7 +337,7 @@ Attributes | :param:`embed` | :type:`label_list` | :value:`None` | +----------------------------+-----------------------------+---------------------------------------+ | List of Go libraries this test embeds directly. | -| These may be go_library rules or compatible rules with the GoSourceList_ provider. | +| These may be go_library rules or compatible rules with the GoLibrary_ provider. | | These can provide both :param:`srcs` and :param:`deps` to this test. | | See Embedding_ for more information about how and when to use this. | +----------------------------+-----------------------------+---------------------------------------+ @@ -438,7 +461,8 @@ This is used as a way of easily declaring a common set of sources re-used in mul Providers ^^^^^^^^^ -* GoSourceList_ +* GoLibrary_ +* GoSource_ Attributes ^^^^^^^^^^ @@ -464,7 +488,7 @@ Attributes | :param:`embed` | :type:`label_list` | :value:`None` | +----------------------------+-----------------------------+---------------------------------------+ | List of sources to directly embed in this list. | -| These may be go_library rules or compatible rules with the GoSourceList_ provider. | +| These may be go_library rules or compatible rules with the GoSource_ provider. | | These can provide both :param:`srcs` and :param:`deps` to this library. | | See Embedding_ for more information about how and when to use this. | +----------------------------+-----------------------------+---------------------------------------+ diff --git a/go/modes.rst b/go/modes.rst index e7f31ae7eb..93ae810124 100644 --- a/go/modes.rst +++ b/go/modes.rst @@ -63,7 +63,7 @@ The entire transitive set of libraries that a leaf depends on are built in the m the binary rule. The compiled libraries are distinct and multiple modes can be built in a single pass, but are shared between leaves building in the same mode. -Currently only static_ and pure_ can be specified as attributes. +Currently only static_, pure_, goos_ and goarch_ can be specified as attributes. Both of these can take one of the values "on", "off" or "auto", and "auto" is the default. +--------------+-------------------------------------------------------------------------+ @@ -88,6 +88,8 @@ following fields that control the bevhaviour of those actions: * link_ * debug_ * strip_ +* goos_ +* goarch_ Build modes ----------- @@ -148,6 +150,16 @@ strip Causes debugging information to be stripped from the binaries. +goos +~~~~ + +This controls which operating system to target. + +goarch +~~~~~~ + +This controls which architecture to target. + Using build modes ----------------- @@ -204,3 +216,15 @@ the mode of tests by using .. code:: bazel test --features=race //... + +but in general it is strongly recommended instead to turn it on for specific tests. + +.. code:: + + go_test( + name = "go_default_test", + srcs = ["lib_test.go"], + embed = [":go_default_library"], + race = "on", + ) + diff --git a/go/private/actions/binary.bzl b/go/private/actions/binary.bzl index 4fa8919431..f6dd1da850 100644 --- a/go/private/actions/binary.bzl +++ b/go/private/actions/binary.bzl @@ -17,7 +17,6 @@ def emit_binary(go, source = None, gc_linkopts = [], x_defs = {}, - wrap = None, linkstamp=None, version_file=None, info_file=None): diff --git a/go/private/context.bzl b/go/private/context.bzl index c7f1485528..e9acbe905b 100644 --- a/go/private/context.bzl +++ b/go/private/context.bzl @@ -1,4 +1,4 @@ -# Copyright 2014 The Bazel Authors. All rights reserved. +# Copyright 2017 The Bazel Authors. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -158,7 +158,6 @@ def go_context(ctx, attr=None): if not stdlib: fail("No matching standard library for "+mode_string(mode)) - members = structs.to_dict(toolchain.actions) return GoContext( # Fields toolchain = toolchain, diff --git a/go/private/rules/cgo.bzl b/go/private/rules/cgo.bzl index ae282b30e6..5e957137ac 100644 --- a/go/private/rules/cgo.bzl +++ b/go/private/rules/cgo.bzl @@ -213,7 +213,7 @@ def _pure(ctx, mode): def _not_pure(ctx, mode): return not mode.pure -def _cgo_library_to_source(ctx, attr, source, merge): +def _cgo_library_to_source(go, attr, source, merge): library = source["library"] if source["mode"].pure: source["srcs"] = library.input_go_srcs + source["srcs"] diff --git a/go/private/rules/test.bzl b/go/private/rules/test.bzl index 4b8ba19a35..5f01964dd1 100644 --- a/go/private/rules/test.bzl +++ b/go/private/rules/test.bzl @@ -32,7 +32,7 @@ load("@io_bazel_rules_go//go/private:rules/aspect.bzl", "go_archive_aspect", ) -def _testmain_library_to_source(ctx, attr, source, merge): +def _testmain_library_to_source(go, attr, source, merge): source["deps"] = source["deps"] + [attr.library] def _go_test_impl(ctx): diff --git a/go/toolchains.rst b/go/toolchains.rst index 8c11f9fa75..a427697af8 100644 --- a/go/toolchains.rst +++ b/go/toolchains.rst @@ -12,6 +12,9 @@ Go toolchains .. _register_toolchains: https://docs.bazel.build/versions/master/skylark/lib/globals.html#register_toolchains .. _compilation modes: modes.rst#compilation-modes .. _go assembly: https://golang.org/doc/asm +.. _GoLibrary: providers.rst#GoLibrary +.. _GoSource: providers.rst#GoSource +.. _GoArchive: providers.rst#GoArchive .. role:: param(kbd) .. role:: type(emphasis) @@ -28,7 +31,7 @@ customize the behavior of the core_ Go rules. Design ------ -The Go toolchain consists of two main layers, `the sdk`_ and `the toolchain`_. +The Go toolchain consists of three main layers, `the sdk`_ and `the toolchain`_ and `the context`_. The SDK ~~~~~~~ @@ -56,6 +59,9 @@ repository before you call go_register_toolchains_. The toolchain ~~~~~~~~~~~~~ +This a wrapper over the sdk that provides enough extras to match, target and work on a specific +platforms. It should be considered an opaqute type, you only ever use it through `the context`_. + Declaration ^^^^^^^^^^^ @@ -97,6 +103,13 @@ example of this in `limiting the available toolchains`_. It is important to note that you **must** also register the boostrap toolchain for any other toolchain that you register, otherwise the tools for that toolchain cannot be built. + + +The context +~~~~~~~~~~~ + +This is the type you use if you are writing custom rules that need + Use ^^^ @@ -109,6 +122,7 @@ First, you have to declare that you want to consume the toolchain on the rule de _my_rule_impl, attrs = { ... + "_go_context_data": attr.label(default=Label("@io_bazel_rules_go//:go_context_data")), }, toolchains = ["@io_bazel_rules_go//go:toolchain"], ) @@ -122,6 +136,24 @@ And then in the rule body, you need to get the toolchain itself and use it's act srcs, vars = go_toolchain.actions.cover(ctx, go_toolchain, ctx.files.srcs) + + + + + + + + + + + + + + + + + + Customizing ----------- @@ -227,6 +259,7 @@ WORKSPACE "@io_bazel_rules_go//go/toolchain:1.8.3_darwin_amd64-bootstrap", ) + API --- @@ -386,54 +419,139 @@ toolchain of type :value:`"@io_bazel_rules_go//go:bootstrap_toolchain"`. | should apply when using this toolchain. | +--------------------------------+-----------------------------+-----------------------------------+ -The toolchain object -~~~~~~~~~~~~~~~~~~~~ +go_context +~~~~~~~~~~ + +This collects the information needed to form and return a :type:`GoContext` from a rule ctx. +It uses the attrbutes and the toolchains. +It can only be used in the implementation of a rule that has the go toolchain attached and +the go context data as an attribute. + +.. code:: bzl + + my_rule = rule( + _my_rule_impl, + attrs = { + ... + "_go_context_data": attr.label(default=Label("@io_bazel_rules_go//:go_context_data")), + }, + toolchains = ["@io_bazel_rules_go//go:toolchain"], + ) + + ++--------------------------------+-----------------------------+-----------------------------------+ +| **Name** | **Type** | **Default value** | ++--------------------------------+-----------------------------+-----------------------------------+ +| :param:`ctx` | :type:`ctx` | |mandatory| | ++--------------------------------+-----------------------------+-----------------------------------+ +| The Bazel ctx object for the current rule. | ++--------------------------------+-----------------------------+-----------------------------------+ + +The context object +~~~~~~~~~~~~~~~~~~ + +GoContext is never returned by a rule, instead you build one using go_context(ctx) in the top of +any custom skylark rule that wants to interact with the go rules. +It provides all the information needed to create go actions, and create or interact with the other +go providers. + +When you get a GoContext from a context (see use_) it exposes a number of fields and methods. -When you get a Go toolchain from a context (see use_) it exposes a number of fields, of those -the stable public interface is +All methods take the GoContext as the only positional argument, all other arguments even if +mandatory must be specified by name, to allow us to re-order and deprecate individual parameters +over time. -* go_toolchain - * actions +Methods +******* + * Action generators + * archive_ * asm_ * binary_ * compile_ * cover_ - * library_ * link_ * pack_ + * Helpers + * args_ + * declare_file_ + * library_to_source_ + * new_library_ + + +Fields +****** + ++--------------------------------+-----------------------------------------------------------------+ +| **Name** | **Type** | ++--------------------------------+-----------------------------------------------------------------+ +| :param:`toolchain` | :type:`GoToolchain` | ++--------------------------------+-----------------------------------------------------------------+ +| The underlying toolchain. This should be considered an opaque type subject to change. | ++--------------------------------+-----------------------------------------------------------------+ +| :param:`mode` | :type:`Mode` | ++--------------------------------+-----------------------------------------------------------------+ +| Controls the compilation setup affecting things like enabling profilers and sanitizers. | +| See `compilation modes`_ for more information about the allowed values. | ++--------------------------------+-----------------------------------------------------------------+ +| :param:`stdlib` | :type:`GoStdlib` | ++--------------------------------+-----------------------------------------------------------------+ +| The standard library and tools to use in this build mode. | ++--------------------------------+-----------------------------------------------------------------+ +| :param:`actions` | :type:`ctx.actions` | ++--------------------------------+-----------------------------------------------------------------+ +| The actions structure from the Bazel context, which has all the methods for building new | +| bazel actions. | ++--------------------------------+-----------------------------------------------------------------+ +| :param:`exe_extension` | :type:`String` | ++--------------------------------+-----------------------------------------------------------------+ +| The suffix to use for all executables in this build mode. Mostly used when generating the output | +| filenames of binary rules. | ++--------------------------------+-----------------------------------------------------------------+ +| :param:`crosstool` | :type:`list of File` | ++--------------------------------+-----------------------------------------------------------------+ +| The files you need to add to the inputs of an action in order to use the cc toolchain. | ++--------------------------------+-----------------------------------------------------------------+ +| :param:`package_list` | :type:`File` | ++--------------------------------+-----------------------------------------------------------------+ +| A file that contains the package list of the standard library. | ++--------------------------------+-----------------------------------------------------------------+ + + +archive +~~~~~~~ +This emits actions to compile Go code into an archive. +It supports embedding, cgo dependencies, coverage, and assembling and packing .s files. -The only stable public interface is the actions member. -This holds a collection of functions for generating the standard actions the toolchain knows -about, compiling and linking for instance. -All the other members are there to provide information to those action functions, and the api of -any other part is subject to arbritary breaking changes at any time. +It returns a GoArchive_. -All action functions take the ctx and the go_toolchain as the only positional arguments, all -other arguments even if mandator must be specified by name, to allow us to re-order and -deprecate individual parameters over time. ++--------------------------------+-----------------------------+-----------------------------------+ +| **Name** | **Type** | **Default value** | ++--------------------------------+-----------------------------+-----------------------------------+ +| :param:`go` | :type:`GoContext` | |mandatory| | ++--------------------------------+-----------------------------+-----------------------------------+ +| This must be the same GoContext object you got this function from. | ++--------------------------------+-----------------------------+-----------------------------------+ +| :param:`source` | :type:`GoSource` | |mandatory| | ++--------------------------------+-----------------------------+-----------------------------------+ +| The GoSource_ that should be compiled into an archive. | ++--------------------------------+-----------------------------+-----------------------------------+ asm ~~~ The asm function adds an action that runs ``go tool asm`` on a source file -to produce an object. - -It does not return anything. +to produce an object, and returns the File of that object. +--------------------------------+-----------------------------+-----------------------------------+ | **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`ctx` | :type:`string` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| The current rule context, used to generate the actions. | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`go_toolchain` | :type:`the Go toolchain` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| This must be the same Go toolchain object you got this function from. | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ | :param:`source` | :type:`File` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ @@ -444,10 +562,6 @@ It does not return anything. +--------------------------------+-----------------------------+-----------------------------------+ | The list of .h files that may be included by the source. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`out_obj` | :type:`File` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| The output object file that should be built by the generated action. | -+--------------------------------+-----------------------------+-----------------------------------+ binary @@ -461,44 +575,17 @@ It returns GoLibrary_. +--------------------------------+-----------------------------+-----------------------------------+ | **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`ctx` | :type:`string` | |mandatory| | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| The current rule context, used to generate the actions. | -+--------------------------------+-----------------------------+-----------------------------------+ -| :param:`go_toolchain` | :type:`the Go toolchain` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| This must be the same Go toolchain object you got this function from. | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ | :param:`name` | :type:`string` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ | The base name of the generated binaries. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`executable` | :type:`File` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| The binary to produce. | +| :param:`source` | :type:`GoSource` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`srcs` | :type:`File iterable` | :value:`[]` | -+--------------------------------+-----------------------------+-----------------------------------+ -| An iterable of Go source Files to be compiled. | -+--------------------------------+-----------------------------+-----------------------------------+ -| :param:`deps` | :type:`GoLibrary iterable` | :value:`[]` | -+--------------------------------+-----------------------------+-----------------------------------+ -| The list of direct dependencies of this package. | -+--------------------------------+-----------------------------+-----------------------------------+ -| :param:`cgo_info` | :type:`CgoInfo` | :value:`None` | -+--------------------------------+-----------------------------+-----------------------------------+ -| An optional CgoInfo provider for this library. | -| There may be at most one of these among the library and its embeds. | -+--------------------------------+-----------------------------+-----------------------------------+ -| :param:`embed` | :type:`GoSourceList list` | :value:`[]` | -+--------------------------------+-----------------------------+-----------------------------------+ -| Sources, dependencies, and other information from these are combined with the package | -| being compiled. | -| Used to build internal test packages. | -+--------------------------------+-----------------------------+-----------------------------------+ -| :param:`importpath` | :type:`string` | :value:`""` | -+--------------------------------+-----------------------------+-----------------------------------+ -| The import path this package represents. | +| The GoSource_ that should be compiled and linked. | +--------------------------------+-----------------------------+-----------------------------------+ | :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | +--------------------------------+-----------------------------+-----------------------------------+ @@ -521,13 +608,9 @@ It does not return anything. +--------------------------------+-----------------------------+-----------------------------------+ | **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`ctx` | :type:`string` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| The current rule context, used to generate the actions. | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`go_toolchain` | :type:`the Go toolchain` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| This must be the same Go toolchain object you got this function from. | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ | :param:`sources` | :type:`File iterable` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ @@ -538,18 +621,13 @@ It does not return anything. +--------------------------------+-----------------------------+-----------------------------------+ | The import path this package represents. This is passed to the -p flag. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`golibs` | :type:`GoLibrary iterable` | :value:`[]` | +| :param:`archives` | :type:`GoArchive iterable` | :value:`[]` | +--------------------------------+-----------------------------+-----------------------------------+ | An iterable of all directly imported libraries. | | The action will verify that all directly imported libraries were supplied, not allowing | | transitive dependencies to satisfy imports. It will not check that all supplied libraries were | | used though. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`mode` | :type:`string` | :value:`NORMAL_MODE` | -+--------------------------------+-----------------------------+-----------------------------------+ -| Controls the compilation setup affecting things like enabling profilers and sanitizers. | -| See `compilation modes`_ for more information about the allowed values. | -+--------------------------------+-----------------------------+-----------------------------------+ | :param:`out_lib` | :type:`File` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ | The archive file that should be produced. | @@ -566,156 +644,191 @@ cover The cover function adds an action that runs ``go tool cover`` on a set of source files to produce copies with cover instrumentation. -Returns a tuple of the covered source list and the cover vars. +Returns a tuple of a covered GoSource with the required source files processed for cover and +the cover vars that were added. Note that this removes most comments, including cgo comments. +--------------------------------+-----------------------------+-----------------------------------+ | **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`ctx` | :type:`string` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| The current rule context, used to generate the actions. | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`go_toolchain` | :type:`the Go toolchain` | |mandatory| | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ -| This must be the same Go toolchain object you got this function from. | +| :param:`source` | :type:`GoSource` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`sources` | :type:`File iterable` | :value:`[]` | -+--------------------------------+-----------------------------+-----------------------------------+ -| An iterable of Go source files. | -| These Must be pure .go files that are ready to be passed to compile_, no assembly or cgo is | -| allowed. | +| The source object to process. Any source files in the object that have been marked as needing | +| coverage will be processed and substiuted in the returned GoSource. | +--------------------------------+-----------------------------+-----------------------------------+ -library -~~~~~~~ +link +~~~~ -This emits actions to compile Go code into an archive. -It supports embedding, cgo dependencies, coverage, and assembling and packing .s files. +The link function adds an action that runs ``go tool link`` on a library. -It returns a tuple of GoLibrary_ and GoSourceList_. +It does not return anything. +--------------------------------+-----------------------------+-----------------------------------+ | **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`ctx` | :type:`string` | |mandatory| | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| The current rule context, used to generate the actions. | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`go_toolchain` | :type:`the Go toolchain` | |mandatory| | +| :param:`archive` | :type:`GoArchive` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| This must be the same Go toolchain object you got this function from. | +| The library to link. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`srcs` | :type:`File iterable` | :value:`[]` | +| :param:`executable` | :type:`File` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| An iterable of Go source Files to be compiled. | +| The binary to produce. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`deps` | :type:`GoLibrary iterable` | :value:`[]` | +| :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | +--------------------------------+-----------------------------+-----------------------------------+ -| The list of direct dependencies of this package. | +| Basic link options, these may be adjusted by the :param:`mode`. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`cgo_info` | :type:`CgoInfo` | :value:`None` | +| :param:`x_defs` | :type:`map` | :value:`{}` | +--------------------------------+-----------------------------+-----------------------------------+ -| An optional CgoInfo provider for this library. | -| There may be at most one of these among the library and its embeds. | +| Link defines, including build stamping ones. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`embed` | :type:`GoSourceList list` | :value:`[]` | + +pack +~~~~ + +The pack function adds an action that produces an archive from a base archive and a collection +of additional object files. + +It does not return anything. + +--------------------------------+-----------------------------+-----------------------------------+ -| Sources, dependencies, and other information from these are combined with the package | -| being compiled. | -| Used to build internal test packages. | +| **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`want_coverage` | :type:`boolean` | :value:`False` | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| A bool indicating whether sources should be instrumented for coverage. | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`importpath` | :type:`string` | :value:`""` | +| :param:`in_lib` | :type:`File` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| The import path this package represents. | +| The archive that should be copied and appended to. | +| This must always be an archive in the common ar form (like that produced by the go compiler). | ++--------------------------------+-----------------------------+-----------------------------------+ +| :param:`out_lib` | :type:`File` | |mandatory| | ++--------------------------------+-----------------------------+-----------------------------------+ +| The archive that should be produced. | +| This will always be an archive in the common ar form (like that produced by the go compiler). | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`importable` | :type:`boolean` | :value:`True` | +| :param:`objects` | :type:`File iterable` | :value:`()` | ++--------------------------------+-----------------------------+-----------------------------------+ +| An iterable of object files to be added to the output archive file. | ++--------------------------------+-----------------------------+-----------------------------------+ +| :param:`archive` | :type:`File` | :value:`None` | +--------------------------------+-----------------------------+-----------------------------------+ -| A bool indicating whether the package can be imported by other libraries. | +| An additional archive whose objects will be appended to the output. | +| This can be an ar file in either common form or either the bsd or sysv variations. | +--------------------------------+-----------------------------+-----------------------------------+ -link + +args ~~~~ -The link function adds an action that runs ``go tool link`` on a library. - -It does not return anything. +This creates a new args object, using the ctx.args method, and the populates it with the standard +arguments used by all the go toolchain builders. +--------------------------------+-----------------------------+-----------------------------------+ | **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`ctx` | :type:`string` | |mandatory| | -+--------------------------------+-----------------------------+-----------------------------------+ -| The current rule context, used to generate the actions. | -+--------------------------------+-----------------------------+-----------------------------------+ -| :param:`go_toolchain` | :type:`the Go toolchain` | |mandatory| | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| This must be the same Go toolchain object you got this function from. | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`library` | :type:`GoLibrary` | |mandatory| | + +declare_file +~~~~~~~~~~~~ + +This is the equivalent of ctx.actions.declare_file except it uses the current build mode to make +the filename unique between configurations. + +--------------------------------+-----------------------------+-----------------------------------+ -| The library to link. | +| **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`mode` | :type:`string` | :value:`NORMAL_MODE` | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| Controls the compilation setup affecting things like enabling profilers and sanitizers. | -| See `compilation modes`_ for more information about the allowed values. | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`executable` | :type:`File` | |mandatory| | +| :param:`path` | :type:`string` | :value:`""` | +--------------------------------+-----------------------------+-----------------------------------+ -| The binary to produce. | +| A path for this file, including the basename of the file. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`gc_linkopts` | :type:`string_list` | :value:`[]` | +| :param:`ext` | :type:`string` | :value:`""` | +--------------------------------+-----------------------------+-----------------------------------+ -| Basic link options, these may be adjusted by the :param:`mode`. | +| The extension to use for the file. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`x_defs` | :type:`map` | :value:`{}` | +| :param:`name` | :type:`string` | :value:`""` | +--------------------------------+-----------------------------+-----------------------------------+ -| Link defines, including build stamping ones. | +| A name to use for this file. If path is not present, this becomes a prefix to the path. | +| If this is not set, the current rule name is used in it's place. | +--------------------------------+-----------------------------+-----------------------------------+ -pack -~~~~ +library_to_source +~~~~~~~~~~~~~~~~~ -The pack function adds an action that produces an archive from a base archive and a collection -of additional object files. - -It does not return anything. +This is used to build a GoSource object for a given GoLibrary in the current build mode. +--------------------------------+-----------------------------+-----------------------------------+ | **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`ctx` | :type:`string` | |mandatory| | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| The current rule context, used to generate the actions. | +| This must be the same GoContext object you got this function from. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`go_toolchain` | :type:`the Go toolchain` | |mandatory| | +| :param:`attr` | :type:`ctx.attr` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| This must be the same Go toolchain object you got this function from. | +| The attributes of the rule being processed, in a normal rule implementation this would be | +| ctx.attr. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`in_lib` | :type:`File` | |mandatory| | +| :param:`library` | :type:`GoLibrary` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| The archive that should be copied and appended to. | -| This must always be an archive in the common ar form (like that produced by the go compiler). | +| The GoLibrary_ that you want to build a GoSource_ object for in the current build mode. | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`out_lib` | :type:`File` | |mandatory| | +| :param:`coverage_instrumented` | :type:`bool` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| The archive that should be produced. | -| This will always be an archive in the common ar form (like that produced by the go compiler). | +| This controls whether cover is enabled for this specific library in this mode. | +| This should generally be the value of ctx.coverage_instrumented() | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`objects` | :type:`File iterable` | :value:`()` | + +new_library +~~~~~~~~~~~ + +This creates a new GoLibrary. +You can add extra fields to the go library by providing extra named parameters to this function, +they will be visible to the resolver when it is invoked. + +--------------------------------+-----------------------------+-----------------------------------+ -| An iterable of object files to be added to the output archive file. | +| **Name** | **Type** | **Default value** | +--------------------------------+-----------------------------+-----------------------------------+ -| :param:`archive` | :type:`File` | :value:`None` | +| :param:`go` | :type:`GoContext` | |mandatory| | +--------------------------------+-----------------------------+-----------------------------------+ -| An additional archive whose objects will be appended to the output. | -| This can be an ar file in either common form or either the bsd or sysv variations. | +| This must be the same GoContext object you got this function from. | ++--------------------------------+-----------------------------+-----------------------------------+ +| :param:`resolver` | :type:`function` | :value:`None` | ++--------------------------------+-----------------------------+-----------------------------------+ +| This is the function that gets invoked when converting from a GoLibrary to a GoSource. | +| See resolver_ for a | +| The function's signature must be | +| | +| .. code:: bzl | +| | +| def _testmain_library_to_source(go, attr, source, merge) | +| | +| attr is the attributes of the rule being processed | +| source is the dictionary of GoSource fields being generated | +| merge is a helper you can call to merge | ++--------------------------------+-----------------------------+-----------------------------------+ +| :param:`importable` | :type:`bool` | |mandatory| | ++--------------------------------+-----------------------------+-----------------------------------+ +| This controls whether the GoLibrary_ is supposed to be importable. This is generally only false | +| for the "main" libraries that are built just before linking. | +--------------------------------+-----------------------------+-----------------------------------+