rules.md

Public API re-exports

nim_cc_binary

load("@rules_nim//nim:defs.bzl", "nim_cc_binary")

nim_cc_binary(name, deps, data, additional_compiler_inputs, additional_linker_inputs, conlyopts,
              copts, cxxopts, defines, includes, linkopts, linkstatic, local_defines, main, proj_cfg)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	The list of nim or cc dependencies of the current target.	List of labels	optional	[]
data	The list of files needed by this target at runtime. See general comments about data at 'Typical attributes' defined by most build rules. If a data is the name of a generated file, then this target automatically depends on the generating target. If a data is a rule name, then this target automatically depends on that rule, and that rule's outs are automatically added to this target's data files.	List of labels	optional	[]
additional_compiler_inputs	List of additional files needed for compilation of srcs	List of labels	optional	[]
additional_linker_inputs	Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target.	List of labels	optional	[]
conlyopts	Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.	List of strings	optional	[]
copts	Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.	List of strings	optional	[]
cxxopts	Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.	List of strings	optional	[]
defines	List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead.	List of strings	optional	[]
includes	List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with -isystem and added to COPTS. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead. Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).	List of strings	optional	[]
linkopts	Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target. Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps.	List of strings	optional	[]
linkstatic	"Link the artifact in static mode. For nim_cc_binary and nim_cc_test: link the binary in static mode. For nim_cc_library.link_static: see below. By default this option is on for cc_binary and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static. There are really three different ways to link an executable: - STATIC with fully_static_link feature, in which everything is linked statically; e.g. "gcc -static foo.o libbar.a libbaz.a -lm". This mode is enabled by specifying fully_static_link in the features attribute. - STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "gcc foo.o libfoo.a libbaz.a -lm". This mode is enabled by specifying linkstatic=True. - DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "gcc foo.o libfoo.so libbaz.so -lm". This mode is enabled by specifying linkstatic=False. If the linkstatic attribute or fully_static_link in features is used outside of //third_party please include a comment near the rule to explain why. The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area.	Boolean	optional	True
local_defines	List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents.	List of strings	optional	[]
main	The nim file containg executable logic.	Label	required
proj_cfg	The project's configuration file. Doesn't have to be named exactly as the 'main' file. rules_nim assures the name consistency during build phase.	Label	optional	None

nim_cc_library

load("@rules_nim//nim:defs.bzl", "nim_cc_library")

nim_cc_library(name, deps, data, additional_compiler_inputs, additional_linker_inputs, alwayslink,
               conlyopts, copts, cxxopts, defines, includes, linkopts, linkstatic, local_defines,
               main, proj_cfg)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	The list of nim or cc dependencies of the current target.	List of labels	optional	[]
data	The list of files needed by this target at runtime. See general comments about data at 'Typical attributes' defined by most build rules. If a data is the name of a generated file, then this target automatically depends on the generating target. If a data is a rule name, then this target automatically depends on that rule, and that rule's outs are automatically added to this target's data files.	List of labels	optional	[]
additional_compiler_inputs	List of additional files needed for compilation of srcs	List of labels	optional	[]
additional_linker_inputs	Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target.	List of labels	optional	[]
alwayslink	If 1, any binary that depends (directly or indirectly) on this C++ library will link in all the object files for the files listed in srcs, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary, e.g., if your code registers to receive some callback provided by some service.	Boolean	optional	False
conlyopts	Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.	List of strings	optional	[]
copts	Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.	List of strings	optional	[]
cxxopts	Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.	List of strings	optional	[]
defines	List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead.	List of strings	optional	[]
includes	List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with -isystem and added to COPTS. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead. Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).	List of strings	optional	[]
linkopts	Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target. Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps.	List of strings	optional	[]
linkstatic	"Link the artifact in static mode. For nim_cc_binary and nim_cc_test: link the binary in static mode. For nim_cc_library.link_static: see below. By default this option is on for cc_binary and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static. There are really three different ways to link an executable: - STATIC with fully_static_link feature, in which everything is linked statically; e.g. "gcc -static foo.o libbar.a libbaz.a -lm". This mode is enabled by specifying fully_static_link in the features attribute. - STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "gcc foo.o libfoo.a libbaz.a -lm". This mode is enabled by specifying linkstatic=True. - DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "gcc foo.o libfoo.so libbaz.so -lm". This mode is enabled by specifying linkstatic=False. If the linkstatic attribute or fully_static_link in features is used outside of //third_party please include a comment near the rule to explain why. The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area.	Boolean	optional	False
local_defines	List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents.	List of strings	optional	[]
main	The nim file containg executable logic.	Label	required
proj_cfg	The project's configuration file. Doesn't have to be named exactly as the 'main' file. rules_nim assures the name consistency during build phase.	Label	optional	None

nim_cc_test

load("@rules_nim//nim:defs.bzl", "nim_cc_test")

nim_cc_test(name, deps, data, additional_compiler_inputs, additional_linker_inputs, conlyopts,
            copts, cxxopts, defines, includes, linkopts, linkstatic, local_defines, main, proj_cfg)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	The list of nim or cc dependencies of the current target.	List of labels	optional	[]
data	The list of files needed by this target at runtime. See general comments about data at 'Typical attributes' defined by most build rules. If a data is the name of a generated file, then this target automatically depends on the generating target. If a data is a rule name, then this target automatically depends on that rule, and that rule's outs are automatically added to this target's data files.	List of labels	optional	[]
additional_compiler_inputs	List of additional files needed for compilation of srcs	List of labels	optional	[]
additional_linker_inputs	Pass these files to the C++ linker command. For example, compiled Windows .res files can be provided here to be embedded in the binary target.	List of labels	optional	[]
conlyopts	Add these options to the C compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.	List of strings	optional	[]
copts	Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization. Each string in this attribute is added in the given order to COPTS before compiling the binary target. The flags take effect only for compiling this target, not its dependencies, so be careful about header files included elsewhere. All paths should be relative to the workspace, not to the current package. If the package declares the feature no_copts_tokenization, Bourne shell tokenization applies only to strings that consist of a single "Make" variable.	List of strings	optional	[]
cxxopts	Add these options to the C++ compilation command. Subject to "Make variable" substitution and Bourne shell tokenization.	List of strings	optional	[]
defines	List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line to this target, as well as to every rule that depends on it. Be very careful, since this may have far-reaching effects. When in doubt, add define values to local_defines instead.	List of strings	optional	[]
includes	List of include dirs to be added to the compile line. Subject to "Make variable" substitution. Each string is prepended with -isystem and added to COPTS. Unlike COPTS, these flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects. When in doubt, add "-I" flags to COPTS instead. Headers must be added to srcs or hdrs, otherwise they will not be available to dependent rules when compilation is sandboxed (the default).	List of strings	optional	[]
linkopts	Add these flags to the C++ linker command. Subject to "Make" variable substitution, Bourne shell tokenization and label expansion. Each string in this attribute is added to LINKOPTS before linking the binary target. Each element of this list that does not start with $ or - is assumed to be the label of a target in deps. The list of files generated by that target is appended to the linker options. An error is reported if the label is invalid, or is not declared in deps.	List of strings	optional	[]
linkstatic	"Link the artifact in static mode. For nim_cc_binary and nim_cc_test: link the binary in static mode. For nim_cc_library.link_static: see below. By default this option is on for cc_binary and off for the rest. If enabled and this is a binary or test, this option tells the build tool to link in .a's instead of .so's for user libraries whenever possible. System libraries such as libc (but not the C/C++ runtime libraries, see below) are still linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static. There are really three different ways to link an executable: - STATIC with fully_static_link feature, in which everything is linked statically; e.g. "gcc -static foo.o libbar.a libbaz.a -lm". This mode is enabled by specifying fully_static_link in the features attribute. - STATIC, in which all user libraries are linked statically (if a static version is available), but where system libraries (excluding C/C++ runtime libraries) are linked dynamically, e.g. "gcc foo.o libfoo.a libbaz.a -lm". This mode is enabled by specifying linkstatic=True. - DYNAMIC, in which all libraries are linked dynamically (if a dynamic version is available), e.g. "gcc foo.o libfoo.so libbaz.so -lm". This mode is enabled by specifying linkstatic=False. If the linkstatic attribute or fully_static_link in features is used outside of //third_party please include a comment near the rule to explain why. The linkstatic attribute has a different meaning if used on a cc_library() rule. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area. For a C++ library, linkstatic=True indicates that only static linking is allowed, so no .so will be produced. linkstatic=False does not prevent static libraries from being created. The attribute is meant to control the creation of dynamic libraries. There should be very little code built with linkstatic=False in production. If linkstatic=False, then the build tool will create symlinks to depended-upon shared libraries in the *.runfiles area.	Boolean	optional	True
local_defines	List of defines to add to the compile line. Subject to "Make" variable substitution and Bourne shell tokenization. Each string, which must consist of a single Bourne shell token, is prepended with -D and added to the compile command line for this target, but not to its dependents.	List of strings	optional	[]
main	The nim file containg executable logic.	Label	required
proj_cfg	The project's configuration file. Doesn't have to be named exactly as the 'main' file. rules_nim assures the name consistency during build phase.	Label	optional	None

nim_module

load("@rules_nim//nim:defs.bzl", "nim_module")

nim_module(name, deps, srcs, strip_import_prefix)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other nim dependencies for this module.	List of labels	optional	[]
srcs	Nim sources that form a module.	List of labels	required
strip_import_prefix	The prefix to strip from the paths of the nim imports of this rule.	String	optional	""

nimble_lock_update

load("@rules_nim//nim:defs.bzl", "nimble_lock_update")

nimble_lock_update(name, nimble_repo, nimble_lock_file)

PARAMETERS

Name	Description	Default Value
name	-	none
nimble_repo	-	none
nimble_lock_file	-	none