Go Build Tags: Difference between revisions
| (14 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
=External= | |||
* https://pkg.go.dev/go/build#hdr-Build_Constraints | |||
=Internal= | =Internal= | ||
* [[Go_build#-tags|<tt>go build</tt>]] | |||
* [[Go_test_Command#-tags|<tt>go test</tt>]] | |||
=Overview= | =Overview= | ||
A '''build tag''' is an identifier added to a piece of code that determines when the file should be including in a package during the build process. | A '''build tag''' is an identifier added to a piece of code that determines when the file should be including in a package during the build process. | ||
Build tags provide conditional compilation in Go. Go does not have a preprocessor, a macro system, or a #define declaration to control the inclusion of platform-specific code, it uses build tags instead. | Build tags provide conditional compilation in Go. Go does not have a preprocessor, a macro system, or a #define declaration to control the inclusion of platform-specific code, it uses build tags instead. Build tags are implemented as comments which must appear '''at the top of the file''' in any source file (not just go files). To differentiate between the package and build tags, there must be a blank line between them: | ||
Build tags are implemented as comments which must appear '''at the top of the file''' in any source file (not just go files). To differentiate between the package and build tags, there must be a blank line between them: | |||
<syntaxhighlight lang='go'> | <syntaxhighlight lang='go'> | ||
// | //go:build tag_a tag_b | ||
package somepkg | package somepkg | ||
</syntaxhighlight> | </syntaxhighlight> | ||
To select building or test execution: | |||
<syntaxhighlight lang='bash'> | |||
go build|test [...] -tags=tag_a,tag_x [...] | |||
</syntaxhighlight> | |||
If a file contains build tags, but no <code>-tags</code> build option is provided on the compiler's or tester's command line, the file will '''not''' be compiled/included in testing. Once a file has been marked with a build tag, the build tag must be present for the file to be handled. | |||
=Providing Tags on Command Line= | =Providing Tags on Command Line= | ||
| Line 22: | Line 33: | ||
Multiple tags are supported, and they can be combined using an OR, AND or NOT logic. | Multiple tags are supported, and they can be combined using an OR, AND or NOT logic. | ||
==File will be Included if Either Tags are Present During Compilation== | ==File will be Included if Either Tags are Present During Compilation== | ||
When the | When the <code>||</code> operator is used, is sufficient that any of them is present for the file to be compiled. The following declaration: | ||
<syntaxhighlight lang='go'> | <syntaxhighlight lang='go'> | ||
// | //go:build tag_a || tag_b || tag_c | ||
package somepkg | package somepkg | ||
| Line 34: | Line 45: | ||
==File will be Included if All Tags are Present During Compilation== | ==File will be Included if All Tags are Present During Compilation== | ||
When the tags are separated by | When the tags are separated by the <code>&&</code> operator, all of them must be present . The following declaration: | ||
<syntaxhighlight lang='go'> | <syntaxhighlight lang='go'> | ||
// | //go:build tag_a && tag_b && tag_c | ||
package somepkg | package somepkg | ||
| Line 44: | Line 55: | ||
tag_a AND tag_b AND tag_c | tag_a AND tag_b AND tag_c | ||
</font> | </font> | ||
==File will Not Be Included if the Tag Is Present During Compilation== | ==File will Not Be Included if the Tag Is Present During Compilation== | ||
A negated tag means that the file will not be compiled if the tag is provided at compilation: | A negated tag means that the file will not be compiled if the tag is provided at compilation: | ||
<syntaxhighlight lang='go'> | <syntaxhighlight lang='go'> | ||
// | //go:build !tag_a | ||
package somepkg | package somepkg | ||
</syntaxhighlight> | |||
=Controlling Test Execution with Build Tags= | |||
See [[Go_Testing#unit_test_Build_Tag|<code>unit_test</code>]], [[Go_Testing#integration_test_Build_Tag|<code>integration_test</code>]], [[Go_Testing#system_test_Build_Tag|<code>system_test</code>]] and [[Github.com/stretchr/testify#Build_Tags|build tags in mock files]]. | |||
To run tests selectively: | |||
<syntaxhighlight lang='bash'> | |||
go test [...] -tags=unit_test,integration_test,system_test [...] | |||
</syntaxhighlight> | </syntaxhighlight> | ||
Latest revision as of 22:51, 12 March 2024
External
Internal
Overview
A build tag is an identifier added to a piece of code that determines when the file should be including in a package during the build process.
Build tags provide conditional compilation in Go. Go does not have a preprocessor, a macro system, or a #define declaration to control the inclusion of platform-specific code, it uses build tags instead. Build tags are implemented as comments which must appear at the top of the file in any source file (not just go files). To differentiate between the package and build tags, there must be a blank line between them:
//go:build tag_a tag_b
package somepkg
To select building or test execution:
go build|test [...] -tags=tag_a,tag_x [...]
If a file contains build tags, but no -tags build option is provided on the compiler's or tester's command line, the file will not be compiled/included in testing. Once a file has been marked with a build tag, the build tag must be present for the file to be handled.
Providing Tags on Command Line
go build|test -tags=tag_a [...]
Combining Tags
Multiple tags are supported, and they can be combined using an OR, AND or NOT logic.
File will be Included if Either Tags are Present During Compilation
When the || operator is used, is sufficient that any of them is present for the file to be compiled. The following declaration:
//go:build tag_a || tag_b || tag_c
package somepkg
has the semantics:
tag_a OR tag_b OR tag_c
File will be Included if All Tags are Present During Compilation
When the tags are separated by the && operator, all of them must be present . The following declaration:
//go:build tag_a && tag_b && tag_c
package somepkg
has the semantics:
tag_a AND tag_b AND tag_c
File will Not Be Included if the Tag Is Present During Compilation
A negated tag means that the file will not be compiled if the tag is provided at compilation:
//go:build !tag_a
package somepkg
Controlling Test Execution with Build Tags
See unit_test, integration_test, system_test and build tags in mock files.
To run tests selectively:
go test [...] -tags=unit_test,integration_test,system_test [...]