Skip to content

rules_flex.md

Latest commit

 

History

History
375 lines (245 loc) · 17.9 KB

rules_flex.md

File metadata and controls

375 lines (245 loc) · 17.9 KB

rules_flex

Bazel rules for Flex, the Fast Lexical Analyzer.

flex

load("@rules_flex//flex:flex.bzl", "flex")

flex(name, src, flex_options, language, output_src_ext)

Generate C/C++ source code for a Flex lexical analyzer.

This rule exists for special cases where the build needs to perform further modification of the generated .c / .h before compilation. Most users will find the flex_cc_library rule more convenient.

The output groups cc_srcs and cc_hdrs provide access to the generated {name}.c / {name}.cc sources and (if available) the {name}.h header.

Example

load("@rules_flex//flex:flex.bzl", "flex")

flex(
    name = "hello",
    src = "hello.l",
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
src A Flex source file.

Unless language is set, the source's file extension will determine whether Flex operates in C or C++ mode:
  • Inputs with file extension .l generate outputs {name}.c and {name}.h.
  • Inputs with file extension .ll, .l++, .lxx, or .lpp generate output {name}.cc. This is equivalent to invoking Flex as flex++.
The C++ output depends on FlexLexer.h, which is part of the Flex source distribution and may be obtained from the Flex toolchain.		 Label required
flex_options Additional options to pass to the flex command.

These will be added to the command args immediately before the source file.		 List of strings optional []
language Which language to generate the lexer in. String optional ""
output_src_ext Override the file extension used for the generated source file.

By default the extension is auto-detected according to the language attribute, which is itself auto-detected according to the input file extension.		 String optional ""

flex_cc_library

load("@rules_flex//flex:flex.bzl", "flex_cc_library")

flex_cc_library(name, deps, src, defines, flex_options, include_prefix, language, linkstatic,
                local_defines, output_src_ext, strip_include_prefix)

Generate a C/C++ library for a Flex lexical analyzer.

Example

load("@rules_flex//flex:flex.bzl", "flex_cc_library")

flex_cc_library(
    name = "hello_lib",
    src = "hello.l",
)

cc_binary(
    name = "hello",
    srcs = ["hello_main.c"],
    deps = [":hello_lib"],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of other C/C++ libraries that the library depends on.

See cc_library.deps for more details.		 List of labels optional []
src A Flex source file.

Unless language is set, the source's file extension will determine whether Flex operates in C or C++ mode:
  • Inputs with file extension .l generate outputs {name}.c and {name}.h.
  • Inputs with file extension .ll, .l++, .lxx, or .lpp generate output {name}.cc. This is equivalent to invoking Flex as flex++.
The C++ output depends on FlexLexer.h, which is part of the Flex source distribution and may be obtained from the Flex toolchain.		 Label required
defines List of defines to add to the compile line of this and all dependent targets.

See cc_library.defines for more details.		 List of strings optional []
flex_options Additional options to pass to the flex command.

These will be added to the command args immediately before the source file.		 List of strings optional []
include_prefix A prefix to add to the path of the generated header.

See cc_library.include_prefix for more details.		 String optional ""
language Which language to generate the lexer in. String optional ""
linkstatic Disable creation of a shared library output.

See cc_library.linkstatic for more details.		 Boolean optional False
local_defines List of defines to add to the compile line of this target.

See cc_library.local_defines for more details.		 List of strings optional []
output_src_ext Override the file extension used for the generated source file.

By default the extension is auto-detected according to the language attribute, which is itself auto-detected according to the input file extension.		 String optional ""
strip_include_prefix A prefix to strip from the path of the generated header.

See cc_library.strip_include_prefix for more details.		 String optional ""

flex_toolchain_info

load("@rules_flex//flex:flex.bzl", "flex_toolchain_info")

flex_toolchain_info(name, flex_env, flex_lexer_h, flex_tool)

Provides ToolchainInfo and TemplateVariableInfo for the Flex toolchain.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
flex_env Additional environment variables to set when running flex_tool. Dictionary: String -> String optional {}
flex_lexer_h Label of FlexLexer.h, used for generated C++ lexers. Label required
flex_tool A FilesToRunProvider for the flex binary. Label required

FlexToolchainInfo

load("@rules_flex//flex:flex.bzl", "FlexToolchainInfo")

FlexToolchainInfo(all_files, flex_tool, flex_env, flex_lexer_h)

Provider for a Flex toolchain.

FIELDS

Name Description
all_files A depset containing all files comprising this Flex toolchain.
flex_tool A FilesToRunProvider for the flex binary.
flex_env Additional environment variables to set when running flex_tool.
flex_lexer_h A File for the FlexLexer.h header.

flex_register_toolchains

load("@rules_flex//flex:flex.bzl", "flex_register_toolchains")

flex_register_toolchains(version, extra_copts)

A helper function for Flex toolchains registration.

This workspace macro will create a flex_repository named flex_v{version} and register it as a Bazel toolchain.

PARAMETERS

Name Description Default Value
version A supported version of Flex. "2.6.4"
extra_copts Additional C compiler options to use when building Flex. []

flex_toolchain

load("@rules_flex//flex:flex.bzl", "flex_toolchain")

flex_toolchain(ctx)

Returns the current FlexToolchainInfo.

PARAMETERS

Name Description Default Value
ctx A rule context, where the rule has a toolchain dependency on FLEX_TOOLCHAIN_TYPE. none

RETURNS

A FlexToolchainInfo.

flex_repository

load("@rules_flex//flex:flex.bzl", "flex_repository")

flex_repository(name, extra_copts, extra_linkopts, patch_strip, patches, version)

Repository rule for Flex.

The resulting repository will have a //bin:flex executable target.

Example

load("@rules_flex//flex:flex.bzl", "flex_repository")

flex_repository(
    name = "flex_v2.6.4",
    version = "2.6.4",
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
extra_copts Additional C compiler options to use when building Flex. List of strings optional []
extra_linkopts Additional linker options to use when building Flex. List of strings optional []
patch_strip Strip the specified number of leading components from patch file names. Integer optional 0
patches A mapping from Flex versions to lists of patch files to apply, relative to the root of the Flex source repository. Each patch should be in standard unified diff format. Dictionary: String -> List of strings optional {"2.6.4": ["//flex/patches:0001-fix-noline-for-top-directives.patch"]}
version A supported version of Flex. String required

flex_toolchain_repository

load("@rules_flex//flex:flex.bzl", "flex_toolchain_repository")

flex_toolchain_repository(name, flex_repository)

Toolchain repository rule for Flex toolchains.

Toolchain repositories add a layer of indirection so that Bazel can resolve toolchains without downloading additional dependencies.

The resulting repository will have the following targets:

  • //bin:flex (an alias into the underlying [flex_repository] (#flex_repository))
  • //:toolchain, which can be registered with Bazel.

Example

load(
    "@rules_flex//flex:flex.bzl",
    "flex_repository",
    "flex_toolchain_repository",
)

flex_repository(
    name = "flex_v2.6.4",
    version = "2.6.4",
)

flex_toolchain_repository(
    name = "flex",
    flex_repository = "@flex_v2.6.4",
)

register_toolchains("@flex//:toolchain")

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
flex_repository The name of a flex_repository. String required

flex_repository_ext

flex_repository_ext = use_extension("@rules_flex//flex/extensions:flex_repository_ext.bzl", "flex_repository_ext")
flex_repository_ext.repository(name, extra_copts, extra_linkopts, version)

Module extension for declaring dependencies on Flex.

The resulting repository will have the following targets:

  • //bin:flex (an alias into the underlying [flex_repository] (#flex_repository))
  • //:toolchain, which can be registered with Bazel.

Example

flex = use_extension(
    "@rules_flex//flex/extensions:flex_repository_ext.bzl",
    "flex_repository_ext",
)

flex.repository(name = "flex", version = "2.6.4")
use_repo(flex, "flex")
register_toolchains("@flex//:toolchain")

TAG CLASSES

repository

Attributes

Name Description Type Mandatory Default
name An optional name for the repository.

The name must be unique within the set of names registered by this extension. If unset, the repository name will default to "flex_v{version}".		 Name optional ""
extra_copts Additional C compiler options to use when building Flex. List of strings optional []
extra_linkopts Additional linker options to use when building Flex. List of strings optional []
version A supported version of Flex. String optional "2.6.4"

flex_toolchains_ext

flex_toolchains_ext = use_extension("@rules_flex//flex/extensions:flex_toolchains_ext.bzl", "flex_toolchains_ext")
flex_toolchains_ext.toolchain(name, flex_env, flex_lexer_h, flex_tool)

Module extension for declaring Flex toolchains with custom target binaries.

The resulting repository will have one subdirectory per named module tag, which contains a :toolchain target that can be registered with Bazel.

Example

flex_toolchains = use_extension(
    "@rules_flex//flex/extensions:flex_toolchains_ext.bzl",
    "flex_toolchain_ext",
)

flex_toolchains.toolchain(
    name = "custom",
    flex_tool = "//custom_flex:flex",
    flex_lexer_h = "//custom_flex:flex_lexer_h",
)
use_repo(flex_toolchains, "flex_toolchains")
register_toolchains("@flex_toolchains//custom:toolchain")

TAG CLASSES

toolchain

Attributes

Name Description Type Mandatory Default
name The name of the toolchain repository to create. Name required
flex_env Additional environment variables to set when running flex_tool. Dictionary: String -> String optional {}
flex_lexer_h Label of FlexLexer.h, used for generated C++ lexers. Label required
flex_tool The label of an flex executable target. Label required