jvm_common.bzl

# 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", "AbiGenerationMode", "UnusedDependenciesAction")

def _test_env():
    return {
        "env": attrs.dict(key = attrs.string(), value = attrs.arg(), sorted = False, default = {}, doc = """
    A map of environment names and values to set when running the test.
"""),
    }

def _resources_arg():
    return {
        "resources": attrs.list(attrs.source(), default = [], doc = """
    Static files to include with the compiled `.class` files.
     These files can be loaded
     via [Class.getResource()](http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html#getResource(java.lang.String)).


    **Note:** If `resources_root` isn't set,
     Buck uses the ``.buckconfig``
     property in `.buckconfig` to
     determine where resources should be placed within the generated JAR
     file.
"""),
        "resources_root": attrs.option(attrs.source(), default = None, doc = """
    The path that resources are resolved against. For example, if `resources_root` is `"res"` and
     `resources` contains the file `"res/com/example/foo.txt"`, that file will end up as `"com/example/foo.txt"` in the output JAR. This parameter
     overrides the ``.buckconfig`` property in `.buckconfig`.
"""),
    }

def _remove_classes_arg():
    return {
        "remove_classes": attrs.list(attrs.regex(), default = [], doc = """
    Specifies a list of `Patterns` that are used to exclude
     `classes` from the `JAR`. The pattern matching is
     based on the name of the class. This can be used to exclude a member
     class or delete a local view of a class that will be replaced during
     a later stage of the build.
"""),
    }

def _provided_deps():
    return {
        "provided_deps": attrs.list(attrs.dep(), default = [], doc = """
    These represent dependencies that are known to be provided at run
     time, but are required in order for the code to compile. Examples of
     `provided_deps` include the JEE servlet APIs. When this
     rule is included in a , the
     `provided_deps` will not be packaged into the output.
"""),
    }

def _exported_deps():
    return {
        "exported_deps": attrs.list(attrs.dep(), default = [], doc = """
    Other  rules that depend on this rule will also
     include its `exported_deps` in their classpaths. This is useful
     when the public API of a rule has return types or checked exceptions that are
     defined in another rule, which would otherwise require callers to add an
     extra dependency. It's also useful for exposing e.g. a collection of
     `prebuilt_jar` rules as a single target for callers to depend
     on. Targets in `exported_deps` are implicitly included in the
     `deps` of this rule, so they don't need to be repeated there.
"""),
    }

def _exported_provided_deps():
    return {
        "exported_provided_deps": attrs.list(attrs.dep(), default = [], doc = """
    This is a combination of `provided_deps` and `exported_deps`. Rules listed
     in this parameter will be added to classpath of rules that depend on this rule, but they will not
     be included in a binary if binary depends on a such target.
"""),
    }

def _source_only_abi_deps():
    return {
        "source_only_abi_deps": attrs.list(attrs.dep(), default = [], doc = """
    These are dependencies that must be present during
     `source-only ABI generation`.
     Typically such dependencies are added when some property of the code in this rule prevents source-only ABI
     generation from being correct without these dependencies being present.


     Having `source_only_abi_deps` prevents Buck from
     completely flattening the build graph, thus reducing the performance win from source-only
     ABI generation. They should be avoided when possible. Often only a small code change is needed to avoid them.
     For more information on such code changes, read about
     `source-only ABI generation`.
"""),
    }

def _abi_generation_mode():
    return {
        "abi_generation_mode": attrs.option(attrs.enum(AbiGenerationMode), default = None, doc = """
    Overrides `.buckconfig`
    for this rule.
"""),
    }

def _required_for_source_only_abi():
    return {
        "required_for_source_only_abi": attrs.bool(default = False, doc = """
    Indicates that this rule must be present on the classpath during
     `source-only ABI generation`
     of any rule that depends on it. Typically this is done when a rule contains annotations,
     enums, constants, or interfaces.


     Having rules present on the classpath during source-only ABI generation prevents Buck from
     completely flattening the build graph, thus reducing the performance win from source-only
     ABI generation. These rules should be kept small (ideally just containing annotations,
     constants, enums, and interfaces) and with minimal dependencies of their own.
"""),
    }

def _on_unused_dependencies():
    return {
        "on_unused_dependencies": attrs.option(attrs.enum(UnusedDependenciesAction), default = None, doc = """
    Action performed when Buck detects that some dependencies are not used during Java compilation.


    Note that this feature is experimental and does not handle runtime dependencies.


    The valid values are:
     * `ignore` (default): ignore unused dependencies,
    * `warn`: emit a warning to the console,
    * `fail`: fail the compilation.



    This option overrides the default value from
    .
"""),
    }

def _k2():
    return {
        "k2": attrs.bool(default = False, doc = """
    Enables the Kotlin K2 compiler.
    """),
    }

def _incremental():
    return {
        "incremental": attrs.bool(default = False, doc = """
    Enables Kotlin incremental compilation.
    """),
    }

def _enable_used_classes():
    return {
        "enable_used_classes": attrs.bool(default = True, doc = """
    Deprecated: for an experiment only, will be removed
    """),
    }

def _plugins():
    return {
        "plugins": attrs.list(
            attrs.one_of(
                attrs.dep(),
                attrs.tuple(attrs.dep(), attrs.list(attrs.string())),
            ),
            default = [],
        ),
    }

def _kotlin_compiler_plugins():
    return {
        "kotlin_compiler_plugins": attrs.dict(key = attrs.source(), value = attrs.dict(key = attrs.string(), value = attrs.string(), sorted = False), sorted = False, default = {}, doc = """
                Use this to specify [Kotlin compiler plugins](https://kotlinlang.org/docs/reference/compiler-plugins.html) to use when compiling this library.
                 This takes a map, with each entry specify one plugin. Entry's key is plugin source path,
                 and value is a map of plugin option key value pair. Unlike `extra_kotlinc_arguments`,
                 these can be *source paths*, not just strings.

                 A special option value is
                 `__codegen_dir__`, in which case Buck will provide a default codegen folder's path as
                 option value instead.
                 E.g.

                ```
fbcode/buck2/prelude/decls/jvm_common.bzl
                kotlin_compiler_plugins = {
                    "somePluginSourcePath": {
                        "plugin:somePluginId:somePluginOptionKey": "somePluginOptionValue",
                        "plugin:somePluginId:someDirectoryRelatedOptionKey": "__codegen_dir__",
                    },
                },

                ```
                Each plugin source path will be prefixed with `-Xplugin=` and passed as extra
                 arguments to the compiler. Plugin options will be appended after its plugin with `-P`.

                 A specific example is, if you want to use [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization)
                 with `kotlin_library()`, you need to specify `kotlinx-serialization-compiler-plugin.jar` under `kotlin_compiler_plugins` and `kotlinx-serialization-runtime.jar` (which you may have to fetch from Maven) in your `deps`:

                ```

                kotlin_library(
                    name = "example",
                    srcs = glob(["*.kt"]),
                    deps = [
                        ":kotlinx-serialization-runtime",
                    ],
                    kotlin_compiler_plugins = {
                        # Likely copied from your $KOTLIN_HOME directory.
                        "kotlinx-serialization-compiler-plugin.jar": {},
                    },
                )

                prebuilt_jar(
                    name = "kotlinx-serialization-runtime",
                    binary_jar = ":kotlinx-serialization-runtime-0.10.0",
                )

                # Note you probably want to set
                # maven_repo=http://jcenter.bintray.com/ in your .buckconfig until
                # https://github.com/Kotlin/kotlinx.serialization/issues/64
                # is closed.
                remote_file(
                    name = "kotlinx-serialization-runtime-0.10.0",
                    out = "kotlinx-serialization-runtime-0.10.0.jar",
                    url = "mvn:org.jetbrains.kotlinx:kotlinx-serialization-runtime:jar:0.10.0",
                    sha1 = "23d777a5282c1957c7ce35946374fff0adab114c"
                )

                ```
            """),
    }

def _javac():
    return {
        "javac": attrs.option(attrs.one_of(attrs.exec_dep(), attrs.source()), default = None, doc = """
            Specifies the Java compiler program to use for this rule.
                The value is a source path or an execution dep (e.g., //foo/bar:bar).
                Overrides the value in "javac" in the "tools" section
                of `.buckconfig`.
            """),
    }

jvm_common = struct(
    test_env = _test_env,
    resources_arg = _resources_arg,
    remove_classes_arg = _remove_classes_arg,
    provided_deps = _provided_deps,
    exported_deps = _exported_deps,
    exported_provided_deps = _exported_provided_deps,
    source_only_abi_deps = _source_only_abi_deps,
    abi_generation_mode = _abi_generation_mode,
    required_for_source_only_abi = _required_for_source_only_abi,
    on_unused_dependencies = _on_unused_dependencies,
    k2 = _k2,
    incremental = _incremental,
    plugins = _plugins,
    kotlin_compiler_plugins = _kotlin_compiler_plugins,
    javac = _javac,
    enable_used_classes = _enable_used_classes,
)