From a58935afafb57949e89fa5562b800a49c4af11b5 Mon Sep 17 00:00:00 2001 From: Fabian Meumertzheim Date: Mon, 23 Jan 2023 16:58:10 +0100 Subject: [PATCH] Update stardoc to 0.5.3 (#3427) --- WORKSPACE | 6 ++-- docs/go/core/rules.md | 72 ++++++++++++++++++++-------------------- docs/go/extras/extras.md | 8 ++--- 3 files changed, 43 insertions(+), 43 deletions(-) diff --git a/WORKSPACE b/WORKSPACE index 285020ff5c..d436703ff0 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -154,10 +154,10 @@ local_repository( # so we declare it in the WORKSPACE http_archive( name = "io_bazel_stardoc", - sha256 = "c9794dcc8026a30ff67cf7cf91ebe245ca294b20b071845d12c192afe243ad72", + sha256 = "3fd8fec4ddec3c670bd810904e2e33170bedfe12f90adf943508184be458c8bb", urls = [ - "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", - "https://github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", + "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz", + "https://github.com/bazelbuild/stardoc/releases/download/0.5.3/stardoc-0.5.3.tar.gz", ], ) diff --git a/docs/go/core/rules.md b/docs/go/core/rules.md index 10f4a9b6dc..2227c22188 100644 --- a/docs/go/core/rules.md +++ b/docs/go/core/rules.md @@ -146,18 +146,18 @@ This builds an executable from a set of source files, | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | +| name | A unique name for this target. | Name | required | | | basename | The basename of this binary. The binary basename may also be platform-dependent: on Windows, we add an .exe extension. | String | optional | "" | -| cdeps | The list of other libraries that the c code depends on. This can be anything that would be allowed in [cc_library deps] Only valid if cgo = True. | List of labels | optional | [] | +| cdeps | The list of other libraries that the c code depends on. This can be anything that would be allowed in [cc_library deps] Only valid if cgo = True. | List of labels | optional | [] | | cgo | If True, the package may contain [cgo] code, and srcs may contain C, C++, Objective-C, and Objective-C++ files and non-Go assembly files. When cgo is enabled, these files will be compiled with the C/C++ toolchain and included in the package. Note that this attribute does not force cgo to be enabled. Cgo is enabled for non-cross-compiling builds when a C/C++ toolchain is configured. | Boolean | optional | False | | clinkopts | List of flags to add to the C link command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | copts | List of flags to add to the C compilation command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | cppopts | List of flags to add to the C/C++ preprocessor command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | cxxopts | List of flags to add to the C++ compilation command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | -| data | List of files needed by this rule at run-time. This may include data files needed or other programs that may be executed. The [bazel] package may be used to locate run files; they may appear in different places depending on the operating system and environment. See [data dependencies] for more information on data files. | List of labels | optional | [] | -| deps | List of Go libraries this package imports directly. These may be go_library rules or compatible rules with the [GoLibrary] provider. | List of labels | optional | [] | -| embed | List of Go libraries whose sources should be compiled together with this binary's sources. Labels listed here must name go_library, go_proto_library, or other compatible targets with the [GoLibrary] and [GoSource] providers. Embedded libraries must all have the same importpath, which must match the importpath for this go_binary if one is specified. At most one embedded library may have cgo = True, and the embedding binary may not also have cgo = True. See [Embedding] for more information. | List of labels | optional | [] | -| embedsrcs | The list of files that may be embedded into the compiled package using //go:embed directives. All files must be in the same logical directory or a subdirectory as source files. All source files containing //go:embed directives must be in the same logical directory. It's okay to mix static and generated source files and static and generated embeddable files. | List of labels | optional | [] | +| data | List of files needed by this rule at run-time. This may include data files needed or other programs that may be executed. The [bazel] package may be used to locate run files; they may appear in different places depending on the operating system and environment. See [data dependencies] for more information on data files. | List of labels | optional | [] | +| deps | List of Go libraries this package imports directly. These may be go_library rules or compatible rules with the [GoLibrary] provider. | List of labels | optional | [] | +| embed | List of Go libraries whose sources should be compiled together with this binary's sources. Labels listed here must name go_library, go_proto_library, or other compatible targets with the [GoLibrary] and [GoSource] providers. Embedded libraries must all have the same importpath, which must match the importpath for this go_binary if one is specified. At most one embedded library may have cgo = True, and the embedding binary may not also have cgo = True. See [Embedding] for more information. | List of labels | optional | [] | +| embedsrcs | The list of files that may be embedded into the compiled package using //go:embed directives. All files must be in the same logical directory or a subdirectory as source files. All source files containing //go:embed directives must be in the same logical directory. It's okay to mix static and generated source files and static and generated embeddable files. | List of labels | optional | [] | | gc_goopts | List of flags to add to the Go compilation command when using the gc compiler. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. | List of strings | optional | [] | | gc_linkopts | List of flags to add to the Go link command when using the gc compiler. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. | List of strings | optional | [] | | goarch | Forces a binary to be cross-compiled for a specific architecture. It's usually better to control this on the command line with --platforms.

This disables cgo by default, since a cross-compiling C/C++ toolchain is rarely available. To force cgo, set pure = off.

See [Cross compilation] for more information. | String | optional | "auto" | @@ -169,9 +169,9 @@ This builds an executable from a set of source files, | out | Sets the output filename for the generated executable. When set, go_binary will write this file without mode-specific directory prefixes, without linkmode-specific prefixes like "lib", and without platform-specific suffixes like ".exe". Note that without a mode-specific directory prefix, the output file (but not its dependencies) will be invalidated in Bazel's cache when changing configurations. | String | optional | "" | | pure | Controls whether cgo source code and dependencies are compiled and linked, similar to setting CGO_ENABLED. May be one of on, off, or auto. If auto, pure mode is enabled when no C/C++ toolchain is configured or when cross-compiling. It's usually better to control this on the command line with --@io_bazel_rules_go//go/config:pure. See [mode attributes], specifically [pure]. | String | optional | "auto" | | race | Controls whether code is instrumented for race detection. May be one of on, off, or auto. Not available when cgo is disabled. In most cases, it's better to control this on the command line with --@io_bazel_rules_go//go/config:race. See [mode attributes], specifically [race]. | String | optional | "auto" | -| srcs | The list of Go source files that are compiled to create the package. Only .go and .s files are permitted, unless the cgo attribute is set, in which case, .c .cc .cpp .cxx .h .hh .hpp .hxx .inc .m .mm files are also permitted. Files may be filtered at build time using Go [build constraints]. | List of labels | optional | [] | +| srcs | The list of Go source files that are compiled to create the package. Only .go and .s files are permitted, unless the cgo attribute is set, in which case, .c .cc .cpp .cxx .h .hh .hpp .hxx .inc .m .mm files are also permitted. Files may be filtered at build time using Go [build constraints]. | List of labels | optional | [] | | static | Controls whether a binary is statically linked. May be one of on, off, or auto. Not available on all platforms or in all modes. It's usually better to control this on the command line with --@io_bazel_rules_go//go/config:static. See [mode attributes], specifically [static]. | String | optional | "auto" | -| x_defs | Map of defines to add to the go link command. See [Defines and stamping] for examples of how to use these. | Dictionary: String -> String | optional | {} | +| x_defs | Map of defines to add to the go link command. See [Defines and stamping] for examples of how to use these. | Dictionary: String -> String | optional | {} | @@ -201,10 +201,10 @@ This wraps an executable built by `go_binary` to cross compile it | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| platform | The platform to cross compile the target for. If unspecified, the target will be compiled with the same platform as it would've with the original go_binary rule. | Label | optional | None | +| name | A unique name for this target. | Name | required | | +| platform | The platform to cross compile the target for. If unspecified, the target will be compiled with the same platform as it would've with the original go_binary rule. | Label | optional | None | | sdk_version | The golang SDK version to use for compiling the target. Supports specifying major, minor, and/or patch versions, eg. "1", "1.17", or "1.17.1". The first Go SDK provider installed in the repo's workspace (via go_download_sdk, go_wrap_sdk, etc) that matches the specified version will be used for compiling the given target. If unspecified, the target will be compiled with the same SDK as it would've with the original go_binary rule. Transitions target by changing the --@io_bazel_rules_go//go/toolchain:sdk_version build flag to the value provided for sdk_version here. | String | optional | "" | -| target | Go binary target to transition to the given platform and/or sdk_version. | Label | required | | +| target | Go binary target to transition to the given platform and/or sdk_version. | Label | required | | @@ -236,23 +236,23 @@ This builds a Go library from a set of source files that are all part of | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| cdeps | List of other libraries that the c code depends on. This can be anything that would be allowed in [cc_library deps] Only valid if cgo = True. | List of labels | optional | [] | +| name | A unique name for this target. | Name | required | | +| cdeps | List of other libraries that the c code depends on. This can be anything that would be allowed in [cc_library deps] Only valid if cgo = True. | List of labels | optional | [] | | cgo | If True, the package may contain [cgo] code, and srcs may contain C, C++, Objective-C, and Objective-C++ files and non-Go assembly files. When cgo is enabled, these files will be compiled with the C/C++ toolchain and included in the package. Note that this attribute does not force cgo to be enabled. Cgo is enabled for non-cross-compiling builds when a C/C++ toolchain is configured. | Boolean | optional | False | | clinkopts | List of flags to add to the C link command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | copts | List of flags to add to the C compilation command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | cppopts | List of flags to add to the C/C++ preprocessor command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | cxxopts | List of flags to add to the C++ compilation command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | -| data | List of files needed by this rule at run-time. This may include data files needed or other programs that may be executed. The [bazel] package may be used to locate run files; they may appear in different places depending on the operating system and environment. See [data dependencies] for more information on data files. | List of labels | optional | [] | -| deps | List of Go libraries this package imports directly. These may be go_library rules or compatible rules with the [GoLibrary] provider. | List of labels | optional | [] | -| embed | List of Go libraries whose sources should be compiled together with this package's sources. Labels listed here must name go_library, go_proto_library, or other compatible targets with the [GoLibrary] and [GoSource] providers. Embedded libraries must have the same importpath as the embedding library. At most one embedded library may have cgo = True, and the embedding library may not also have cgo = True. See [Embedding] for more information. | List of labels | optional | [] | -| embedsrcs | The list of files that may be embedded into the compiled package using //go:embed directives. All files must be in the same logical directory or a subdirectory as source files. All source files containing //go:embed directives must be in the same logical directory. It's okay to mix static and generated source files and static and generated embeddable files. | List of labels | optional | [] | +| data | List of files needed by this rule at run-time. This may include data files needed or other programs that may be executed. The [bazel] package may be used to locate run files; they may appear in different places depending on the operating system and environment. See [data dependencies] for more information on data files. | List of labels | optional | [] | +| deps | List of Go libraries this package imports directly. These may be go_library rules or compatible rules with the [GoLibrary] provider. | List of labels | optional | [] | +| embed | List of Go libraries whose sources should be compiled together with this package's sources. Labels listed here must name go_library, go_proto_library, or other compatible targets with the [GoLibrary] and [GoSource] providers. Embedded libraries must have the same importpath as the embedding library. At most one embedded library may have cgo = True, and the embedding library may not also have cgo = True. See [Embedding] for more information. | List of labels | optional | [] | +| embedsrcs | The list of files that may be embedded into the compiled package using //go:embed directives. All files must be in the same logical directory or a subdirectory as source files. All source files containing //go:embed directives must be in the same logical directory. It's okay to mix static and generated source files and static and generated embeddable files. | List of labels | optional | [] | | gc_goopts | List of flags to add to the Go compilation command when using the gc compiler. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. | List of strings | optional | [] | | importmap | The actual import path of this library. By default, this is importpath. This is mostly only visible to the compiler and linker, but it may also be seen in stack traces. This must be unique among packages passed to the linker. It may be set to something different than importpath to prevent conflicts between multiple packages with the same path (for example, from different vendor directories). | String | optional | "" | | importpath | The source import path of this library. Other libraries can import this library using this path. This must either be specified in go_library or inherited from one of the libraries in embed. | String | optional | "" | | importpath_aliases | - | List of strings | optional | [] | -| srcs | The list of Go source files that are compiled to create the package. Only .go and .s files are permitted, unless the cgo attribute is set, in which case, .c .cc .cpp .cxx .h .hh .hpp .hxx .inc .m .mm files are also permitted. Files may be filtered at build time using Go [build constraints]. | List of labels | optional | [] | -| x_defs | Map of defines to add to the go link command. See [Defines and stamping] for examples of how to use these. | Dictionary: String -> String | optional | {} | +| srcs | The list of Go source files that are compiled to create the package. Only .go and .s files are permitted, unless the cgo attribute is set, in which case, .c .cc .cpp .cxx .h .hh .hpp .hxx .inc .m .mm files are also permitted. Files may be filtered at build time using Go [build constraints]. | List of labels | optional | [] | +| x_defs | Map of defines to add to the go link command. See [Defines and stamping] for examples of how to use these. | Dictionary: String -> String | optional | {} | @@ -279,9 +279,9 @@ go_path(name, data, name | A unique name for this target. | Name | required | | -| data | A list of targets producing data files that will be stored next to the src/ directory. Useful for including things like licenses and readmes. | List of labels | optional | [] | -| deps | A list of targets that build Go packages. A directory will be generated from files in these targets and their transitive dependencies. All targets must provide [GoArchive] ([go_library], [go_binary], [go_test], and similar rules have this).

Only targets with explicit importpath attributes will be included in the generated directory. Synthetic packages (like the main package produced by [go_test]) and packages with inferred import paths will not be included. The values of importmap attributes may influence the placement of packages within the generated directory (for example, in vendor directories).

The generated directory will contain original source files, including .go, .s, .h, and .c files compiled by cgo. It will not contain files generated by tools like cover and cgo, but it will contain generated files passed in srcs attributes like .pb.go files. The generated directory will also contain runfiles found in data attributes. | List of labels | optional | [] | +| name | A unique name for this target. | Name | required | | +| data | A list of targets producing data files that will be stored next to the src/ directory. Useful for including things like licenses and readmes. | List of labels | optional | [] | +| deps | A list of targets that build Go packages. A directory will be generated from files in these targets and their transitive dependencies. All targets must provide [GoArchive] ([go_library], [go_binary], [go_test], and similar rules have this).

Only targets with explicit importpath attributes will be included in the generated directory. Synthetic packages (like the main package produced by [go_test]) and packages with inferred import paths will not be included. The values of importmap attributes may influence the placement of packages within the generated directory (for example, in vendor directories).

The generated directory will contain original source files, including .go, .s, .h, and .c files compiled by cgo. It will not contain files generated by tools like cover and cgo, but it will contain generated files passed in srcs attributes like .pb.go files. The generated directory will also contain runfiles found in data attributes. | List of labels | optional | [] | | include_data | When true, data files referenced by libraries, binaries, and tests will be included in the output directory. Files listed in the data attribute for this rule will be included regardless of this attribute. | Boolean | optional | True | | include_pkg | When true, a pkg subdirectory containing the compiled libraries will be created in the generated GOPATH containing compiled libraries. | Boolean | optional | False | | include_transitive | When true, the transitive dependency graph will be included in the generated GOPATH. This is the default behaviour. When false, only the direct dependencies will be included in the generated GOPATH. | Boolean | optional | True | @@ -314,12 +314,12 @@ This declares a set of source files and related dependencies that can be embedde | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| data | List of files needed by this rule at run-time. This may include data files needed or other programs that may be executed. The [bazel] package may be used to locate run files; they may appear in different places depending on the operating system and environment. See [data dependencies] for more information on data files. | List of labels | optional | [] | -| deps | List of Go libraries this source list imports directly. These may be go_library rules or compatible rules with the [GoLibrary] provider. | List of labels | optional | [] | -| embed | List of Go libraries whose sources should be compiled together with this package's sources. Labels listed here must name go_library, go_proto_library, or other compatible targets with the [GoLibrary] and [GoSource] providers. Embedded libraries must have the same importpath as the embedding library. At most one embedded library may have cgo = True, and the embedding library may not also have cgo = True. See [Embedding] for more information. | List of labels | optional | [] | +| name | A unique name for this target. | Name | required | | +| data | List of files needed by this rule at run-time. This may include data files needed or other programs that may be executed. The [bazel] package may be used to locate run files; they may appear in different places depending on the operating system and environment. See [data dependencies] for more information on data files. | List of labels | optional | [] | +| deps | List of Go libraries this source list imports directly. These may be go_library rules or compatible rules with the [GoLibrary] provider. | List of labels | optional | [] | +| embed | List of Go libraries whose sources should be compiled together with this package's sources. Labels listed here must name go_library, go_proto_library, or other compatible targets with the [GoLibrary] and [GoSource] providers. Embedded libraries must have the same importpath as the embedding library. At most one embedded library may have cgo = True, and the embedding library may not also have cgo = True. See [Embedding] for more information. | List of labels | optional | [] | | gc_goopts | List of flags to add to the Go compilation command when using the gc compiler. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. | List of strings | optional | [] | -| srcs | The list of Go source files that are compiled to create the package. The following file types are permitted: .go, .c, .s, .S .h. The files may contain Go-style [build constraints]. | List of labels | optional | [] | +| srcs | The list of Go source files that are compiled to create the package. The following file types are permitted: .go, .c, .s, .S .h. The files may contain Go-style [build constraints]. | List of labels | optional | [] | @@ -371,18 +371,18 @@ This builds a set of tests that can be run with `bazel test`.

| Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | -| cdeps | The list of other libraries that the c code depends on. This can be anything that would be allowed in [cc_library deps] Only valid if cgo = True. | List of labels | optional | [] | +| name | A unique name for this target. | Name | required | | +| cdeps | The list of other libraries that the c code depends on. This can be anything that would be allowed in [cc_library deps] Only valid if cgo = True. | List of labels | optional | [] | | cgo | If True, the package may contain [cgo] code, and srcs may contain C, C++, Objective-C, and Objective-C++ files and non-Go assembly files. When cgo is enabled, these files will be compiled with the C/C++ toolchain and included in the package. Note that this attribute does not force cgo to be enabled. Cgo is enabled for non-cross-compiling builds when a C/C++ toolchain is configured. | Boolean | optional | False | | clinkopts | List of flags to add to the C link command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | copts | List of flags to add to the C compilation command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | cppopts | List of flags to add to the C/C++ preprocessor command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | | cxxopts | List of flags to add to the C++ compilation command. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. Only valid if cgo = True. | List of strings | optional | [] | -| data | List of files needed by this rule at run-time. This may include data files needed or other programs that may be executed. The [bazel] package may be used to locate run files; they may appear in different places depending on the operating system and environment. See [data dependencies] for more information on data files. | List of labels | optional | [] | -| deps | List of Go libraries this test imports directly. These may be go_library rules or compatible rules with the [GoLibrary] provider. | List of labels | optional | [] | -| embed | List of Go libraries whose sources should be compiled together with this package's sources. Labels listed here must name go_library, go_proto_library, or other compatible targets with the [GoLibrary] and [GoSource] providers. Embedded libraries must have the same importpath as the embedding library. At most one embedded library may have cgo = True, and the embedding library may not also have cgo = True. See [Embedding] for more information. | List of labels | optional | [] | -| embedsrcs | The list of files that may be embedded into the compiled package using //go:embed directives. All files must be in the same logical directory or a subdirectory as source files. All source files containing //go:embed directives must be in the same logical directory. It's okay to mix static and generated source files and static and generated embeddable files. | List of labels | optional | [] | -| env | Environment variables to set for the test execution. The values (but not keys) are subject to [location expansion](https://docs.bazel.build/versions/main/skylark/macros.html) but not full [make variable expansion](https://docs.bazel.build/versions/main/be/make-variables.html). | Dictionary: String -> String | optional | {} | +| data | List of files needed by this rule at run-time. This may include data files needed or other programs that may be executed. The [bazel] package may be used to locate run files; they may appear in different places depending on the operating system and environment. See [data dependencies] for more information on data files. | List of labels | optional | [] | +| deps | List of Go libraries this test imports directly. These may be go_library rules or compatible rules with the [GoLibrary] provider. | List of labels | optional | [] | +| embed | List of Go libraries whose sources should be compiled together with this package's sources. Labels listed here must name go_library, go_proto_library, or other compatible targets with the [GoLibrary] and [GoSource] providers. Embedded libraries must have the same importpath as the embedding library. At most one embedded library may have cgo = True, and the embedding library may not also have cgo = True. See [Embedding] for more information. | List of labels | optional | [] | +| embedsrcs | The list of files that may be embedded into the compiled package using //go:embed directives. All files must be in the same logical directory or a subdirectory as source files. All source files containing //go:embed directives must be in the same logical directory. It's okay to mix static and generated source files and static and generated embeddable files. | List of labels | optional | [] | +| env | Environment variables to set for the test execution. The values (but not keys) are subject to [location expansion](https://docs.bazel.build/versions/main/skylark/macros.html) but not full [make variable expansion](https://docs.bazel.build/versions/main/be/make-variables.html). | Dictionary: String -> String | optional | {} | | env_inherit | Environment variables to inherit from the external environment. | List of strings | optional | [] | | gc_goopts | List of flags to add to the Go compilation command when using the gc compiler. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. | List of strings | optional | [] | | gc_linkopts | List of flags to add to the Go link command when using the gc compiler. Subject to ["Make variable"] substitution and [Bourne shell tokenization]. | List of strings | optional | [] | @@ -395,8 +395,8 @@ This builds a set of tests that can be run with `bazel test`.

| pure | Controls whether cgo source code and dependencies are compiled and linked, similar to setting CGO_ENABLED. May be one of on, off, or auto. If auto, pure mode is enabled when no C/C++ toolchain is configured or when cross-compiling. It's usually better to control this on the command line with --@io_bazel_rules_go//go/config:pure. See [mode attributes], specifically [pure]. | String | optional | "auto" | | race | Controls whether code is instrumented for race detection. May be one of on, off, or auto. Not available when cgo is disabled. In most cases, it's better to control this on the command line with --@io_bazel_rules_go//go/config:race. See [mode attributes], specifically [race]. | String | optional | "auto" | | rundir | A directory to cd to before the test is run. This should be a path relative to the root directory of the repository in which the test is defined, which can be the main or an external repository.

The default behaviour is to change to the relative path corresponding to the test's package, which replicates the normal behaviour of go test so it is easy to write compatible tests.

Setting it to . makes the test behave the normal way for a bazel test, except that the working directory is always that of the test's repository, which is not necessarily the main repository.

Note: If runfile symlinks are disabled (such as on Windows by default), the test will run in the working directory set by Bazel, which is the subdirectory of the runfiles directory corresponding to the main repository. | String | optional | "" | -| srcs | The list of Go source files that are compiled to create the package. Only .go and .s files are permitted, unless the cgo attribute is set, in which case, .c .cc .cpp .cxx .h .hh .hpp .hxx .inc .m .mm files are also permitted. Files may be filtered at build time using Go [build constraints]. | List of labels | optional | [] | +| srcs | The list of Go source files that are compiled to create the package. Only .go and .s files are permitted, unless the cgo attribute is set, in which case, .c .cc .cpp .cxx .h .hh .hpp .hxx .inc .m .mm files are also permitted. Files may be filtered at build time using Go [build constraints]. | List of labels | optional | [] | | static | Controls whether a binary is statically linked. May be one of on, off, or auto. Not available on all platforms or in all modes. It's usually better to control this on the command line with --@io_bazel_rules_go//go/config:static. See [mode attributes], specifically [static]. | String | optional | "auto" | -| x_defs | Map of defines to add to the go link command. See [Defines and stamping] for examples of how to use these. | Dictionary: String -> String | optional | {} | +| x_defs | Map of defines to add to the go link command. See [Defines and stamping] for examples of how to use these. | Dictionary: String -> String | optional | {} | diff --git a/docs/go/extras/extras.md b/docs/go/extras/extras.md index 8a6b984ebe..e3697f8fa0 100644 --- a/docs/go/extras/extras.md +++ b/docs/go/extras/extras.md @@ -63,17 +63,17 @@ go_embed_data_dependencies() | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | -| name | A unique name for this target. | Name | required | | +| name | A unique name for this target. | Name | required | | | flatten | If True and srcs is used, map keys are file base names instead of relative paths. | Boolean | optional | False | | package | Go package name for the generated .go file. | String | optional | "" | -| src | A single file to embed. This cannot be used at the same time as srcs. The generated file will have a variable of type []byte or string with the contents of this file. | Label | optional | None | -| srcs | A list of files to embed. This cannot be used at the same time as src. The generated file will have a variable of type map[string][]byte or map[string]string with the contents of each file. The map keys are relative paths of the files from the repository root. Keys for files in external repositories will be prefixed with "external/repo/" where "repo" is the name of the external repository. | List of labels | optional | [] | +| src | A single file to embed. This cannot be used at the same time as srcs. The generated file will have a variable of type []byte or string with the contents of this file. | Label | optional | None | +| srcs | A list of files to embed. This cannot be used at the same time as src. The generated file will have a variable of type map[string][]byte or map[string]string with the contents of each file. The map keys are relative paths of the files from the repository root. Keys for files in external repositories will be prefixed with "external/repo/" where "repo" is the name of the external repository. | List of labels | optional | [] | | string | If True, the embedded data will be stored as string instead of []byte. | Boolean | optional | False | | unpack | If True, sources are treated as archives and their contents will be stored. Supported formats are .zip and .tar | Boolean | optional | False | | var | Name of the variable that will contain the embedded data. | String | optional | "Data" | - + ## gomock