Skip to content
This repository was archived by the owner on Aug 13, 2025. It is now read-only.

rules.md

Latest commit

 

History

History
executable file
·
205 lines (161 loc) · 25.1 KB

rules.md

File metadata and controls

executable file
·
205 lines (161 loc) · 25.1 KB

Bazelisp - Common Lisp Build Rules for Bazel

lisp_binary

lisp_binary(name, deps, srcs, data, add_features, allow_save_lisp, block_compile,
            block_compile_specified_only, cdeps, compile_data, helper_script, image,
            instrument_coverage, main, malloc, nowarn, order, precompile_generics, runtime,
            save_runtime_options, stamp, verbose)

Supports all of the same attributes as lisp_library, plus additional attributes governing the behavior of the completed binary. The main attribute defines behavior (generally specifying a function to run with no arguments) when the binary is started. By default, it runs (cl-user::main).

Example:

lisp_binary(
    name = "binary"
    srcs = ["binary.lisp"],
    main = "binary:main",
    deps = [":library"],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Common Lisp dependencies (generally lisp_library, but you can put lisp_binary in deps for testing). List of labels optional []
srcs Common Lisp (.lisp or .lsp) source files. If there are multiple files in srcs, which other files in srcs are loaded before each file is compiled depends on the order attr. List of labels optional []
data Data available to this target and its consumers in the runfiles directory at runtime. List of labels optional []
add_features Names of symbols (by default in the keyword package) to be added to \*features\* of this library and its consumers, at compile time and in the resulting binary. Note that this differs from the features attribute common to all build rules which controls toolchain features. List of strings optional []
allow_save_lisp Whether to preserve the ability to run save-lisp-and-die instead of altering the binary format to be more compatible with C++ debugging tools (which, for example, allows you to get combined stacktraces of C/C++ and Lisp code). Must be True for targets used as a compilation image. Boolean optional False
block_compile Whether to block-compile the sources. By default, this will cause sources to be block-compiled together as a single block, that behavior can be overridden by block_compile_specified_only. Boolean optional False
block_compile_specified_only If true, block compilation only considers multiple top-level forms together if those are between explicit (START-BLOCK) and (END-BLOCK). Boolean optional False
cdeps C++ dependencies (generally cc_library). List of labels optional []
compile_data Data available to this target and its consumers at build time, added to the inputs of LispCompile and LispCore actions. List of labels optional []
helper_script - Label optional None
image Lisp binary used as Bazel compilation image. This should be a binary with the main function #'bazel:main defined in main.lisp. Label optional "//third_party/lisp/bazel:image"
instrument_coverage Force coverage instrumentation. Possible values:

0: Never instrument this target. Should be used if thetarget compiles generated source files or does not compilewith coverage instrumentation.

1: Always instrument this target. Generally should not be used outside of tests for the coverage implementation.

-1 (default): If coverage data collection is enabled, instrument this target per [--instrumentation_filter](https://docs.bazel.build/versions/master/command-line-reference.html#flag--instrumentation_filter).		 Integer optional -1
main Name of function (by default in the cl-user package) or snippet of Lisp code to run when starting the binary. "nil" or "t" to start the default REPL. Can be overridden by naming a function (or nil or t) in the LISP_MAIN environment variable. String optional "main"
malloc Target providing a custom malloc implementation. Same as cc_binary.malloc. Note that these rules do not respect --custom_malloc. Label optional "//third_party/tcmalloc"
nowarn Suppressed Lisp warning types or warning handlers. List of strings optional []
order Compilation order, one of:

"serial" (default) - Each source is compiled in an image with previous sources loaded. (Note that in this configuration you should put a comment at the top of the list of srcs if there is more than one, so that formatters like Buildozer do not change the order.)

"multipass" - Each source is compiled in an image with all sources loaded.

"parallel" - Each source is compiled independently.		 String optional "serial"
precompile_generics If False, skip precompiling generic functions. Boolean optional True
runtime SBCL C++ dependencies. Consumers should generally omit this attr and use the default value. Label optional "//third_party/lisp/sbcl:c-support"
save_runtime_options If False, process SBCL runtime options at the command-line on binary startup. Boolean optional True
stamp Same as cc_binary.stamp. Integer optional -1
verbose Enable verbose debugging output when analyzing and compiling this target (0 = none (default), 3 = max). Integer optional 0

lisp_library

lisp_library(name, deps, srcs, data, add_features, block_compile, block_compile_specified_only,
             cdeps, compile_data, image, instrument_coverage, nowarn, order, verbose)

The basic compilation unit for Lisp code. Can have Lisp dependencies (deps) and C/C++ dependencies (cdeps).

Example:

lisp_test(
    name = "library"
    srcs = ["library.lisp"],
    cdeps = [":cc-dependency-ci"],
    deps = [":dependency"],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Common Lisp dependencies (generally lisp_library, but you can put lisp_binary in deps for testing). List of labels optional []
srcs Common Lisp (.lisp or .lsp) source files. If there are multiple files in srcs, which other files in srcs are loaded before each file is compiled depends on the order attr. List of labels optional []
data Data available to this target and its consumers in the runfiles directory at runtime. List of labels optional []
add_features Names of symbols (by default in the keyword package) to be added to \*features\* of this library and its consumers, at compile time and in the resulting binary. Note that this differs from the features attribute common to all build rules which controls toolchain features. List of strings optional []
block_compile Whether to block-compile the sources. By default, this will cause sources to be block-compiled together as a single block, that behavior can be overridden by block_compile_specified_only. Boolean optional False
block_compile_specified_only If true, block compilation only considers multiple top-level forms together if those are between explicit (START-BLOCK) and (END-BLOCK). Boolean optional False
cdeps C++ dependencies (generally cc_library). List of labels optional []
compile_data Data available to this target and its consumers at build time, added to the inputs of LispCompile and LispCore actions. List of labels optional []
image Lisp binary used as Bazel compilation image. This should be a binary with the main function #'bazel:main defined in main.lisp. Label optional "//third_party/lisp/bazel:image"
instrument_coverage Force coverage instrumentation. Possible values:

0: Never instrument this target. Should be used if thetarget compiles generated source files or does not compilewith coverage instrumentation.

1: Always instrument this target. Generally should not be used outside of tests for the coverage implementation.

-1 (default): If coverage data collection is enabled, instrument this target per [--instrumentation_filter](https://docs.bazel.build/versions/master/command-line-reference.html#flag--instrumentation_filter).		 Integer optional -1
nowarn Suppressed Lisp warning types or warning handlers. List of strings optional []
order Compilation order, one of:

"serial" (default) - Each source is compiled in an image with previous sources loaded. (Note that in this configuration you should put a comment at the top of the list of srcs if there is more than one, so that formatters like Buildozer do not change the order.)

"multipass" - Each source is compiled in an image with all sources loaded.

"parallel" - Each source is compiled independently.		 String optional "serial"
verbose Enable verbose debugging output when analyzing and compiling this target (0 = none (default), 3 = max). Integer optional 0

lisp_test

lisp_test(name, deps, srcs, data, add_features, allow_save_lisp, block_compile,
          block_compile_specified_only, cdeps, compile_data, helper_script, image,
          instrument_coverage, main, malloc, nowarn, order, precompile_generics, runtime,
          save_runtime_options, stamp, verbose)

Like lisp_binary, for defining tests to be run with the test command. The main attribute should name a function which runs the tests, outputs information about failing assertions, and exits with a non-zero exit status if there are any failures.

Example:

lisp_test(
    name = "library-test"
    srcs = ["library-test.lisp"],
    main = "library-test:run-tests",
    deps = [
        ":library",
        "//path/to/unit-test:framework",
    ],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps Common Lisp dependencies (generally lisp_library, but you can put lisp_binary in deps for testing). List of labels optional []
srcs Common Lisp (.lisp or .lsp) source files. If there are multiple files in srcs, which other files in srcs are loaded before each file is compiled depends on the order attr. List of labels optional []
data Data available to this target and its consumers in the runfiles directory at runtime. List of labels optional []
add_features Names of symbols (by default in the keyword package) to be added to \*features\* of this library and its consumers, at compile time and in the resulting binary. Note that this differs from the features attribute common to all build rules which controls toolchain features. List of strings optional []
allow_save_lisp Whether to preserve the ability to run save-lisp-and-die instead of altering the binary format to be more compatible with C++ debugging tools (which, for example, allows you to get combined stacktraces of C/C++ and Lisp code). Must be True for targets used as a compilation image. Boolean optional False
block_compile Whether to block-compile the sources. By default, this will cause sources to be block-compiled together as a single block, that behavior can be overridden by block_compile_specified_only. Boolean optional False
block_compile_specified_only If true, block compilation only considers multiple top-level forms together if those are between explicit (START-BLOCK) and (END-BLOCK). Boolean optional False
cdeps C++ dependencies (generally cc_library). List of labels optional []
compile_data Data available to this target and its consumers at build time, added to the inputs of LispCompile and LispCore actions. List of labels optional []
helper_script - Label optional None
image Lisp binary used as Bazel compilation image. This should be a binary with the main function #'bazel:main defined in main.lisp. Label optional "//third_party/lisp/bazel:image"
instrument_coverage Force coverage instrumentation. Possible values:

0: Never instrument this target. Should be used if thetarget compiles generated source files or does not compilewith coverage instrumentation.

1: Always instrument this target. Generally should not be used outside of tests for the coverage implementation.

-1 (default): If coverage data collection is enabled, instrument this target per [--instrumentation_filter](https://docs.bazel.build/versions/master/command-line-reference.html#flag--instrumentation_filter).		 Integer optional -1
main Name of function (by default in the cl-user package) or snippet of Lisp code to run when starting the binary. "nil" or "t" to start the default REPL. Can be overridden by naming a function (or nil or t) in the LISP_MAIN environment variable. String optional "main"
malloc Target providing a custom malloc implementation. Same as cc_binary.malloc. Note that these rules do not respect --custom_malloc. Label optional "//third_party/tcmalloc"
nowarn Suppressed Lisp warning types or warning handlers. List of strings optional []
order Compilation order, one of:

"serial" (default) - Each source is compiled in an image with previous sources loaded. (Note that in this configuration you should put a comment at the top of the list of srcs if there is more than one, so that formatters like Buildozer do not change the order.)

"multipass" - Each source is compiled in an image with all sources loaded.

"parallel" - Each source is compiled independently.		 String optional "serial"
precompile_generics If False, skip precompiling generic functions. Boolean optional True
runtime SBCL C++ dependencies. Consumers should generally omit this attr and use the default value. Label optional "//third_party/lisp/sbcl:c-support"
save_runtime_options If False, process SBCL runtime options at the command-line on binary startup. Boolean optional True
stamp Same as cc_test.stamp. Build version stamping is disabled by default. Integer optional 0
verbose Enable verbose debugging output when analyzing and compiling this target (0 = none (default), 3 = max). Integer optional 0

lisp_compile_srcs

lisp_compile_srcs(ctx, srcs, deps, cdeps, block_compile, block_compile_specified_only, image,
                  add_features, nowarn, order, compile_data, verbose_level, instrument_coverage,
                  indexer_metadata)

Generate LispCompile actions, return LispInfo and FASL output.

This is the core functionality shared by the Lisp build rules.

PARAMETERS

Name Description Default Value
ctx The rule context. none
srcs list of src Files. []
deps list of immediate Lisp dependency Targets. []
cdeps list of immediate C++ dependency Targets. []
block_compile Whether to block-compile this target. False
block_compile_specified_only Whether to only combine top-level forms in blokcs that are in explicitly specified (with (start-block) and (end-block)) when block compiling. False
image Build image Target used to compile the sources. None
add_features list of Lisp feature strings added by this target. []
nowarn List of suppressed warning type strings. []
order Order in which to load sources, either "serial", "parallel", or "multipass". "serial"
compile_data list of data dependency Targets whose outputs and runfiles are made available at load/compile time for this target and its consumers. []
verbose_level int indicating level of debugging output. 0
instrument_coverage Controls coverage instrumentation, with the following values: -1 (default) - Instruments if coverage is enabled for this target. 0 - Instruments never. 1 - Instruments always (for testing purposes). -1
indexer_metadata Extra metadata files to be passed to the --deps flag of LispCompile when the Kythe indexer is run. Ignored by the build image itself, but this appears in the command-line for the LispCompile action which can be inspected by action_listener. []

RETURNS

struct with fields: - lisp_info: LispInfo for the target - output_fasl: Combined FASL for this target (which is also included in lisp_info.fasls if there are srcs) - build_flags: Args to pass to all LispCompile and LispCore actions