github.com/bazelbuild/rules_go@v0.47.2-0.20240515105122-e7ddb9ea474e/docs/go/core/rules.bzl (about)

     1  """
     2    ["Make variable"]: https://docs.bazel.build/versions/master/be/make-variables.html
     3    [Bourne shell tokenization]: https://docs.bazel.build/versions/master/be/common-definitions.html#sh-tokenization
     4    [Gazelle]: https://github.com/bazelbuild/bazel-gazelle
     5    [GoArchive]: /go/providers.rst#GoArchive
     6    [GoLibrary]: /go/providers.rst#GoLibrary
     7    [GoPath]: /go/providers.rst#GoPath
     8    [GoSource]: /go/providers.rst#GoSource
     9    [build constraints]: https://golang.org/pkg/go/build/#hdr-Build_Constraints
    10    [cc_library deps]: https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library.deps
    11    [cgo]: http://golang.org/cmd/cgo/
    12    [config_setting]: https://docs.bazel.build/versions/master/be/general.html#config_setting
    13    [data dependencies]: https://docs.bazel.build/versions/master/build-ref.html#data
    14    [goarch]: /go/modes.rst#goarch
    15    [goos]: /go/modes.rst#goos
    16    [mode attributes]: /go/modes.rst#mode-attributes
    17    [nogo]: /go/nogo.rst#nogo
    18    [pure]: /go/modes.rst#pure
    19    [race]: /go/modes.rst#race
    20    [msan]: /go/modes.rst#msan
    21    [select]: https://docs.bazel.build/versions/master/be/functions.html#select
    22    [shard_count]: https://docs.bazel.build/versions/master/be/common-definitions.html#test.shard_count
    23    [static]: /go/modes.rst#static
    24    [test_arg]: https://docs.bazel.build/versions/master/user-manual.html#flag--test_arg
    25    [test_filter]: https://docs.bazel.build/versions/master/user-manual.html#flag--test_filter
    26    [test_env]: https://docs.bazel.build/versions/master/user-manual.html#flag--test_env
    27    [test_runner_fail_fast]: https://docs.bazel.build/versions/master/command-line-reference.html#flag--test_runner_fail_fast
    28    [write a CROSSTOOL file]: https://github.com/bazelbuild/bazel/wiki/Yet-Another-CROSSTOOL-Writing-Tutorial
    29    [bazel]: https://pkg.go.dev/github.com/bazelbuild/rules_go/go/tools/bazel?tab=doc
    30    [go_library]: #go_library
    31    [go_binary]: #go_binary
    32    [go_test]: #go_test
    33    [go_path]: #go_path
    34    [go_source]: #go_source
    35    [go_test]: #go_test
    36    [Examples]: examples.md#examples
    37    [Defines and stamping]: defines_and_stamping.md#defines-and-stamping
    38    [Stamping with the workspace status script]: defines_and_stamping.md#stamping-with-the-workspace-status-script
    39    [Embedding]: embedding.md#embedding
    40    [Cross compilation]: cross_compilation.md#cross-compilation
    41    [Platform-specific dependencies]: platform-specific_dependencies.md#platform-specific-dependencies
    42  
    43  # Core Go rules
    44  
    45  These are the core go rules, required for basic operation. The intent is that these rules are
    46  sufficient to match the capabilities of the normal go tools.
    47  
    48  ## Additional resources
    49  - ["Make variable"]
    50  - [Bourne shell tokenization]
    51  - [Gazelle]
    52  - [GoArchive]
    53  - [GoLibrary]
    54  - [GoPath]
    55  - [GoSource]
    56  - [build constraints]:
    57  - [cc_library deps]
    58  - [cgo]
    59  - [config_setting]
    60  - [data dependencies]
    61  - [goarch]
    62  - [goos]
    63  - [mode attributes]
    64  - [nogo]
    65  - [pure]
    66  - [race]
    67  - [msan]
    68  - [select]:
    69  - [shard_count]
    70  - [static]
    71  - [test_arg]
    72  - [test_filter]
    73  - [test_env]
    74  - [test_runner_fail_fast]
    75  - [write a CROSSTOOL file]
    76  - [bazel]
    77  
    78  
    79  ------------------------------------------------------------------------
    80  
    81  Introduction
    82  ------------
    83  
    84  Three core rules may be used to build most projects: [go_library], [go_binary],
    85  and [go_test]. These rules reimplement the low level plumping commands of a normal
    86  'go build' invocation: compiling package's source files to archives, then linking
    87  archives into go binary.
    88  
    89  [go_library] builds a single package. It has a list of source files
    90  (specified with `srcs`) and may depend on other packages (with `deps`).
    91  Each [go_library] has an `importpath`, which is the name used to import it
    92  in Go source files.
    93  
    94  [go_binary] also builds a single `main` package and links it into an
    95  executable. It may embed the content of a [go_library] using the `embed`
    96  attribute. Embedded sources are compiled together in the same package.
    97  Binaries can be built for alternative platforms and configurations by setting
    98  `goos`, `goarch`, and other attributes.
    99  
   100  [go_test] builds a test executable. Like tests produced by `go test`, this
   101  consists of three packages: an internal test package compiled together with
   102  the library being tested (specified with `embed`), an external test package
   103  compiled separately, and a generated test main package.
   104  
   105  Here is an example of a Bazel build graph for a project using these core rules:
   106  
   107  ![](./buildgraph.svg)
   108  
   109  By instrumenting the lower level go tooling, we can cache smaller, finer 
   110  artifacts with Bazel and thus, speed up incremental builds.
   111  
   112  Rules
   113  -----
   114  
   115  """
   116  
   117  load("//go/private/rules:binary.bzl", _go_binary = "go_binary")
   118  load("//go/private/rules:cross.bzl", _go_cross_binary = "go_cross_binary")
   119  load("//go/private/rules:library.bzl", _go_library = "go_library")
   120  load("//go/private/rules:source.bzl", _go_source = "go_source")
   121  load("//go/private/rules:test.bzl", _go_test = "go_test")
   122  load("//go/private/tools:path.bzl", _go_path = "go_path")
   123  
   124  go_library = _go_library
   125  go_binary = _go_binary
   126  go_test = _go_test
   127  go_source = _go_source
   128  go_path = _go_path
   129  go_cross_binary = _go_cross_binary