System Initiative

# Copyright (c) Meta Platforms, Inc. and affiliates. # # This source code is licensed under both the MIT license found in the # LICENSE-MIT file in the root directory of this source tree and the Apache # License, Version 2.0 found in the LICENSE-APACHE file in the root directory # of this source tree. # TODO(cjhopman): This was generated by scripts/hacks/rules_shim_with_docs.py, # but should be manually edited going forward. There may be some errors in # the generated docs, and so those should be verified to be accurate and # well-formatted (and then delete this TODO) load(":common.bzl", "CxxSourceType", "IncludeType", "RawHeadersAsHeadersMode", "RuntimeDependencyHandling") def _srcs_arg(): return { "srcs": attrs.list(attrs.one_of(attrs.source(), attrs.tuple(attrs.source(), attrs.list(attrs.arg()))), default = [], doc = """ The set of C, C++, Objective-C, Objective-C++, or assembly source files to be preprocessed, compiled, and assembled by this rule. We determine which stages to run on each input source based on its file extension. See the [GCC documentation](https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html) for more detail on how file extensions are interpreted. Each element can be either a string specifying a source file (e.g. `''`) or a tuple of a string specifying a source file and a list of compilation flags (e.g. `('', ['-Wall', '-Werror'])` ). In the latter case the specified flags will be used in addition to the rule's other flags when preprocessing and compiling that file (if applicable). """), } def _deps_arg(): return { "deps": attrs.list(attrs.dep(), default = [], doc = """ Other rules that list `srcs` from which this rule imports. """), } def _platform_srcs_arg(): return { "platform_srcs": attrs.list(attrs.tuple(attrs.regex(), attrs.set(attrs.one_of(attrs.source(), attrs.tuple(attrs.source(), attrs.list(attrs.arg()))), sorted = True)), default = [], doc = """ Platform specific source files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of source files or a list of tuples of source files and a list of compilation flags to be preprocessed, compiled and assembled if the platform matches the regex. See `srcs` for more information. """), } def _supported_platforms_regex_arg(): return { "supported_platforms_regex": attrs.option(attrs.regex(), default = None, doc = """ If present, an un-anchored regex (in java.util.regex.Pattern syntax) that matches all platforms that this library supports. It will not be built for other platforms. """), } def _headers_arg(): return { "headers": attrs.named_set(attrs.source(), sorted = True, default = [], doc = """ The set of header files that are made available for inclusion to the source files in this target. These should be specified as either a list of header files or a dictionary of header names to header files. The header name can contain forward slashes (`/`). The headers can be included with `#include "$HEADER_NAMESPACE/$HEADER_NAME"` or `#include <$HEADER_NAMESPACE/$HEADER_NAME>` , where `$HEADER_NAMESPACE` is the value of the target's `header_namespace` attribute, and `$HEADER_NAME` is the header name if specified, and the filename of the header file otherwise. See `header_namespace` for more information. """), } def _platform_headers_arg(): return { "platform_headers": attrs.list(attrs.tuple(attrs.regex(), attrs.named_set(attrs.source(), sorted = True)), default = [], doc = """ Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target if the platform matches the regex. See `headers` for more information. """), } def _exported_headers_arg(): return { "exported_headers": attrs.named_set(attrs.source(), sorted = True, default = [], doc = """ The set of header files that are made available for inclusion to the source files in the target and all targets that transitively depend on it. These should be specified as either a list of header files or a dictionary of header names to header files. The headers can be included with `#include "$HEADER_NAMESPACE/$HEADER_NAME"` or `#include <$HEADER_NAMESPACE/$HEADER_NAME>`, where `$HEADER_NAMESPACE` is the value of the target's `header_namespace` attribute, and `$HEADER_NAME` is the header name if specified, and the filename of the header file otherwise. Note that the header name can contain forward slashes (`/`). See `header_namespace` for more information. """), } def _exported_header_style_arg(): return { "exported_header_style": attrs.enum(IncludeType, default = "local", doc = """ How dependents should include exported headers from this rule. Can be either `local` (e.g. `-I`) or `system` (e.g. `-isystem`). """), } def _exported_platform_headers_arg(): return { "exported_platform_headers": attrs.list(attrs.tuple(attrs.regex(), attrs.named_set(attrs.source(), sorted = True)), default = [], doc = """ Platform specific header files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is either a list of header files or a dictionary of header names to header files that will be made available for inclusion to the source files in the target and all targets that transitively depend on it if the platform matches the regex. See `headers` for more information. """), } def _header_namespace_arg(): return { "header_namespace": attrs.option(attrs.string(), default = None, doc = """ A path prefix when including headers of this target. Defaults to the path from the root of the repository to the directory where this target is defined. Can contain forward slashes (`/`), but cannot start with one. See `headers` for more information. """), } def _preprocessor_flags_arg(): return { "preprocessor_flags": attrs.list(attrs.arg(), default = [], doc = """ Flags to use when preprocessing any of the above sources (which require preprocessing). """), } def _lang_preprocessor_flags_arg(): return { "lang_preprocessor_flags": attrs.dict(key = attrs.enum(CxxSourceType), value = attrs.list(attrs.arg()), sorted = False, default = {}, doc = """ Language-specific preprocessor flags. These should be specified as a map of C-family language short names to lists of flags and is used to target flags to sources files for a specific language in the C-family (C, C++, assembler, etc.). The keys in the map can be: * `c` for C * `c++` for C++ * `objective-c` for Objective-C * `objective-c++` for Objective-C++ * `cuda` for Cuda * `assembler-with-cpp` for Assembly * `asm-with-cpp` for ASM """), } def _exported_lang_preprocessor_flags_arg(): return { "exported_lang_preprocessor_flags": attrs.dict(key = attrs.enum(CxxSourceType), value = attrs.list(attrs.arg()), sorted = False, default = {}, doc = """ Just as `lang_preprocessor_flags`, but these flags also apply to rules that transitively depend on this rule. """), } def _lang_platform_preprocessor_flags_arg(): return { "lang_platform_preprocessor_flags": attrs.dict(key = attrs.enum(CxxSourceType), value = attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg()))), sorted = False, default = {}, doc = """ Language- and platform-specific preprocessor flags. These should be specified as a map of C-family language short names, as described in `lang_preprocessor_flags`, to lists of pairs, as described in `platform_preprocessor_flags`. """), } def _exported_lang_platform_preprocessor_flags_arg(): return { "exported_lang_platform_preprocessor_flags": attrs.dict(key = attrs.enum(CxxSourceType), value = attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg()))), sorted = False, default = {}, doc = """ Just as `lang_platform_preprocessor_flags`, but these flags also apply to rules that transitively depend on this rule. """), } def _platform_preprocessor_flags_arg(): return { "platform_preprocessor_flags": attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg())), default = [], doc = """ Platform specific preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the target's sources. See `preprocessor_flags` for more information. """), } def _exported_preprocessor_flags_arg(exported_preprocessor_flags_type): return { "exported_preprocessor_flags": exported_preprocessor_flags_type, } def _exported_platform_preprocessor_flags_arg(): return { "exported_platform_preprocessor_flags": attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg())), default = [], doc = """ Platform specific exported preprocessor flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when preprocessing the source files in the target and all targets that transitively depend on it if the platform matches the regex. See `exported_preprocessor_flags` for more information. """), } def _compiler_flags_arg(): return { "compiler_flags": attrs.list(attrs.arg(), default = [], doc = """ Flags to use when compiling any of the above sources (which require compilation). """), } def _platform_compiler_flags_arg(): return { "platform_compiler_flags": attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg())), default = [], doc = """ Platform specific compiler flags. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of flags to use when compiling the target's sources. See `compiler_flags` for more information. """), } def _lang_compiler_flags_arg(): return { "lang_compiler_flags": attrs.dict(key = attrs.enum(CxxSourceType), value = attrs.list(attrs.arg()), sorted = False, default = {}, doc = """ Language-specific compiler flags. These should be specified as a map of C-family language short names to lists of flags and is used to target flags to sources files for a specific language in the C-family (C, C++, assembler, etc.). The keys in the map can be: * `cpp-output` for C * `c++-cpp-output` for C++ * `objective-c-cpp-output` for Objective-C * `objective-c++-cpp-output` for Objective-C++ * `cuda-cpp-output` for Cuda * `assembler` for Assembly * `asm` for ASM """), } def _lang_platform_compiler_flags_arg(): return { "lang_platform_compiler_flags": attrs.dict(key = attrs.enum(CxxSourceType), value = attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg()))), sorted = False, default = {}, doc = """ Language- and platform-specific compiler flags. These should be specified as a map of C-family language short names, as described in `lang_compiler_flags`, to lists of pairs, as described in `platform_compiler_flags`. """), } def _linker_extra_outputs_arg(): return { "linker_extra_outputs": attrs.list(attrs.string(), default = [], doc = """ Declares extra outputs that the linker emits. These identifiers can be used in `$(output ...)` macros in `linker_flags` to interpolate the output path into the linker command line. Useful for custom linkers that emit extra output files. """), } def _linker_flags_arg(): return { "linker_flags": attrs.list(attrs.arg(anon_target_compatible = True), default = [], doc = """ Flags to add to the linker command line whenever the output from this rule is used in a link operation, such as linked into an executable or a shared library. """), } def _local_linker_flags_arg(): return { "local_linker_flags": attrs.list(attrs.arg(), default = [], doc = """ Flags to add to the linker command line whenever the output from this rule is used in a link operation *driven by this rule* (e.g. when this rule links a shared library, but *not* when the output is linked into a shared library by another rule's link group links). """), } # TODO(christylee): remove this arg once link group map migrates to its own rule def _local_linker_script_flags_arg(): return { "local_linker_script_flags": attrs.list(attrs.arg(), default = [], doc = """ Linker script lags to add to the linker command line whenever the output from this rule is used in a link operation *driven by this rule*. Used by rules that need to treat linker script flags different from normal linker flags. """), } def _platform_linker_flags_arg(): return { "platform_linker_flags": attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg(anon_target_compatible = True))), default = [], doc = """ Platform-specific linker flags. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use `java.util.regex.Pattern` syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule is used in a link operation. """), } def _exported_linker_flags_arg(): return { "exported_linker_flags": attrs.list(attrs.arg(anon_target_compatible = True), default = [], doc = """ Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation. """), } def _exported_post_linker_flags_arg(): return { "exported_post_linker_flags": attrs.list(attrs.arg(anon_target_compatible = True), default = [], doc = """ Flags to add to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation—with the additional feature that these flags are guaranteed to be placed *after* the compiled object (`.o`) files on the linker command line. """), } def _exported_platform_linker_flags_arg(): return { "exported_platform_linker_flags": attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg(anon_target_compatible = True))), default = [], doc = """ Platform-specific linker flags for this rule and for all rules that transitively depend on this rule. This argument is specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched. The regex should use `java.util.regex.Pattern` syntax. The second element in each pair is a list of linker flags. If the regex matches the platform, these flags are added to the linker command line when the output from this rule, or the output from any rule that transitively depends on this rule, is used in a link operation. """), } def _exported_post_platform_linker_flags_arg(): return { "exported_post_platform_linker_flags": attrs.list(attrs.tuple(attrs.regex(), attrs.list(attrs.arg(anon_target_compatible = True))), default = [], doc = """ Platform-specific linker flags for this rule and for all rules that transitively depend on this rule—and that are guaranteed to be placed *after* the compiled object (`.o`) files on the linker command line. In other respects, the syntax and semantics of this argument are the same as for the `exported_platform_linker_flags` argument. """), } def _precompiled_header_arg(): return { "precompiled_header": attrs.option(attrs.source(), default = None, doc = """ Path to a `cxx_precompiled_header` to use when compiling this rule's sources. The precompiled header (PCH) is built on-demand, using compiler flags matching those used in this rule's compile jobs. This is to ensure compatibility between this rule and the PCH. Also, this rule will inherit additional `deps` from the PCH rule, and as a result, additional include paths as well (e.g. `-I`, `-isystem`, `-iquote` path lists, and framework paths specified with `-F`). """), } def _force_static(force_static_type): return { "force_static": force_static_type, } def _reexport_all_header_dependencies_arg(): return { "reexport_all_header_dependencies": attrs.option(attrs.bool(), default = None, doc = """ Whether to automatically re-export the exported headers of all dependencies. When this is set to false, only exported headers from `exported_deps` are re-exported. """), } def _exported_deps_arg(): return { "exported_deps": attrs.list(attrs.dep(), default = [], doc = """ Dependencies that will also appear to belong to any rules that depend on this one. This has two effects: * Exported dependencies will also be included in the link line of dependents of this rules, but normal dependencies will not. * When `reexport_all_header_dependencies = False`, only exported headers of the rules specified here are re-exported. """), } def _exported_platform_deps_arg(): return { "exported_platform_deps": attrs.list(attrs.tuple(attrs.regex(), attrs.set(attrs.dep(), sorted = True)), default = [], doc = """ Platform specific dependencies that will also appear to belong to any rules that depend on this one. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched, and the second element is a list of external dependencies (same format as `exported_deps`) that are exported if the platform matches the regex. See `exported_deps` for more information. """), } def _supports_merged_linking(): return { "supports_merged_linking": attrs.option(attrs.bool(), default = None, doc = """ Whether this rule supports building with the merged linking strategy when building for non-native binaries (e.g. when using `.buckconfig` s `merged` setting). """), } def _raw_headers_arg(): return { "raw_headers": attrs.set(attrs.source(), sorted = True, default = [], doc = """ The set of header files that can be used for inclusion to the source files in the target and all targets that transitively depend on it. Buck doesn't add raw headers to the search path of a compiler/preprocessor automatically. `include_directories` and `public_include_directories` are the recommended way to add raw headers to the search path (they will be added via `-I`). `compiler_flags`, `preprocessor_flags` and `exported_preprocessor_flags` can also be used to add such raw headers to the search path if inclusion via `-isystem` or `-iquote` is needed. `raw_headers` cannot be used together with `headers` or `exported_headers` in the same target. """), } def _raw_headers_as_headers_mode_arg(): return { "raw_headers_as_headers_mode": attrs.option(attrs.enum(RawHeadersAsHeadersMode), default = None, doc = """ Controls whether raw_headers and *include_directories attributes should be automatically converted to headers and symlink trees and/or header maps via headers. Only has an effect if the cxx_toolchain has explicitly opted into supporting this behavior via a non-default value, even if the value is disabled. """), } def _include_directories_arg(): return { "include_directories": attrs.set(attrs.string(), sorted = True, default = [], doc = """ A list of include directories (with `raw_headers`) to be added to the compile command for compiling this target (via `-I`). An include directory is relative to the current package. """), } def _public_include_directories_arg(): return { "public_include_directories": attrs.set(attrs.string(), sorted = True, default = [], doc = """ A list of include directories (with `raw_headers`) to be added to the compile command for compiling this target and every target that depends on it (via `-I`). An include directory is relative to the current package. """), } def _public_system_include_directories_arg(): return { "public_system_include_directories": attrs.set(attrs.string(), sorted = True, default = [], doc = """ A list of include directories (with `raw_headers`) to be added to the compile command for compiling this target and every target that depends on it (via `-isystem` if the compiler supports it of via `-I` otherwise). An include directory is relative to the current package. """), } def _version_arg(): return { "version": attrs.option(attrs.string(), default = None, doc = """ A string denoting a meaningful version of this rule that is optionally passed to the linker as extra metadata. """), } def _runtime_dependency_handling_arg(): return { "runtime_dependency_handling": attrs.option(attrs.enum(RuntimeDependencyHandling), default = None, doc = """ When this is set to `symlink`, shared library dependencies are included in a symlink tree alongside the resulting executable, even if the link style is not shared. Can be `none` or `symlink`. """), } cxx_common = struct( srcs_arg = _srcs_arg, deps_arg = _deps_arg, platform_srcs_arg = _platform_srcs_arg, supported_platforms_regex_arg = _supported_platforms_regex_arg, headers_arg = _headers_arg, platform_headers_arg = _platform_headers_arg, exported_headers_arg = _exported_headers_arg, exported_header_style_arg = _exported_header_style_arg, exported_platform_headers_arg = _exported_platform_headers_arg, header_namespace_arg = _header_namespace_arg, preprocessor_flags_arg = _preprocessor_flags_arg, lang_preprocessor_flags_arg = _lang_preprocessor_flags_arg, exported_lang_preprocessor_flags_arg = _exported_lang_preprocessor_flags_arg, lang_platform_preprocessor_flags_arg = _lang_platform_preprocessor_flags_arg, exported_lang_platform_preprocessor_flags_arg = _exported_lang_platform_preprocessor_flags_arg, platform_preprocessor_flags_arg = _platform_preprocessor_flags_arg, exported_preprocessor_flags_arg = _exported_preprocessor_flags_arg, exported_platform_preprocessor_flags_arg = _exported_platform_preprocessor_flags_arg, compiler_flags_arg = _compiler_flags_arg, platform_compiler_flags_arg = _platform_compiler_flags_arg, lang_compiler_flags_arg = _lang_compiler_flags_arg, lang_platform_compiler_flags_arg = _lang_platform_compiler_flags_arg, linker_extra_outputs_arg = _linker_extra_outputs_arg, linker_flags_arg = _linker_flags_arg, local_linker_flags_arg = _local_linker_flags_arg, local_linker_script_flags_arg = _local_linker_script_flags_arg, platform_linker_flags_arg = _platform_linker_flags_arg, exported_linker_flags_arg = _exported_linker_flags_arg, exported_post_linker_flags_arg = _exported_post_linker_flags_arg, exported_platform_linker_flags_arg = _exported_platform_linker_flags_arg, exported_post_platform_linker_flags_arg = _exported_post_platform_linker_flags_arg, precompiled_header_arg = _precompiled_header_arg, force_static = _force_static, reexport_all_header_dependencies_arg = _reexport_all_header_dependencies_arg, exported_deps_arg = _exported_deps_arg, exported_platform_deps_arg = _exported_platform_deps_arg, supports_merged_linking = _supports_merged_linking, raw_headers_arg = _raw_headers_arg, raw_headers_as_headers_mode_arg = _raw_headers_as_headers_mode_arg, include_directories_arg = _include_directories_arg, public_include_directories_arg = _public_include_directories_arg, public_system_include_directories_arg = _public_system_include_directories_arg, version_arg = _version_arg, runtime_dependency_handling_arg = _runtime_dependency_handling_arg, )