Skip to content

Latest commit

 

History

History
300 lines (195 loc) · 14.4 KB

rules_flex.md

File metadata and controls

300 lines (195 loc) · 14.4 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)

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 ""

flex_cc_library

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

flex_cc_library(name, deps, src, flex_options, include_prefix, language, linkstatic,
                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 to depend on. 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
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
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 ""

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, patches, repo_mapping, 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 []
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": ["//patches:0001-fix-noline-for-top-directives.patch"]}
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).		 Dictionary: String -> String optional
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, repo_mapping)

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
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).		 Dictionary: String -> String optional

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"