tidy up toolchain.bzl and jvm.bzl. These files are no longer skydoc compatible.
diff --git a/kotlin/BUILD b/kotlin/BUILD
index b6a5992..f8db35a 100644
--- a/kotlin/BUILD
+++ b/kotlin/BUILD
@@ -13,11 +13,7 @@
# limitations under the License.
package(default_visibility = ["//visibility:public"])
-load("//kotlin/internal:toolchains.bzl", "kt_toolchain_ide_info")
-
toolchain_type(
name = "kt_toolchain_type",
visibility = ["//visibility:public"],
)
-
-kt_toolchain_ide_info(name = "kt_toolchain_ide_info")
diff --git a/kotlin/internal/jvm/jvm.bzl b/kotlin/internal/jvm/jvm.bzl
index 55f8b9e..d155c1b 100644
--- a/kotlin/internal/jvm/jvm.bzl
+++ b/kotlin/internal/jvm/jvm.bzl
@@ -89,20 +89,12 @@
)
```
"""
-# This file is the main import -- it shouldn't grow out of hand the reason it contains so much allready is due to the limitations of skydoc.
-########################################################################################################################
-# Common Definitions
-########################################################################################################################
load("//kotlin/internal:defs.bzl", _KtJvmInfo = "KtJvmInfo", _TOOLCHAIN_TYPE = "TOOLCHAIN_TYPE")
-
-# struct can't be used till skydoc is removed
load(
"//kotlin/internal/jvm:plugins.bzl",
_kt_jvm_plugin_aspect = "kt_jvm_plugin_aspect",
)
-
-# struct can't be used till skydoc is removed
load(
"//kotlin/internal/jvm:impl.bzl",
_kt_jvm_binary_impl = "kt_jvm_binary_impl",
@@ -111,17 +103,7 @@
_kt_jvm_library_impl = "kt_jvm_library_impl",
)
-########################################################################################################################
-# Rule Attributes
-########################################################################################################################
_implicit_deps = {
- "_kotlin_toolchain": attr.label_list(
- default = [
- Label("@io_bazel_rules_kotlin//kotlin:kt_toolchain_ide_info"),
- ],
- cfg = "host",
- allow_files = False,
- ),
"_singlejar": attr.label(
executable = True,
cfg = "host",
@@ -146,26 +128,46 @@
),
}
-_common_attr = dict(_implicit_deps.items() + {
+_common_attr = _implicit_deps + {
"srcs": attr.label_list(
+ doc = """The list of source files that are processed to create the target, this can contain both Java and Kotlin
+ files. Java analysis occurs first so Kotlin classes may depend on Java classes in the same compilation unit.""",
default = [],
allow_files = [".srcjar", ".kt", ".java"],
),
"deps": attr.label_list(
+ doc = """A list of dependencies of this rule.See general comments about `deps` at
+ [Attributes common to all build rules](https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).""",
aspects = [_kt_jvm_plugin_aspect],
providers = [
[JavaInfo],
],
allow_files = False,
),
- "runtime_deps": attr.label_list(default = [], allow_files = False),
+ "runtime_deps": attr.label_list(
+ doc = """Libraries to make available to the final binary or test at runtime only. Like ordinary deps, these will
+ appear on the runtime classpath, but unlike them, not on the compile-time classpath.""",
+ default = [],
+ allow_files = False,
+ ),
"resources": attr.label_list(
+ doc = """A list of files that should be include in a Java jar.""",
default = [],
allow_files = True,
),
- "resource_strip_prefix": attr.string(default = ""),
- "resource_jars": attr.label_list(default = []),
+ "resource_strip_prefix": attr.string(
+ doc = """The path prefix to strip from Java resources, files residing under common prefix such as
+ `src/main/resources` or `src/test/resources` will have stripping applied by convention.""",
+ default = "",
+ ),
+ "resource_jars": attr.label_list(
+ doc = """Set of archives containing Java resources. If specified, the contents of these jars are merged into
+ the output jar.""",
+ default = [],
+ ),
"data": attr.label_list(
+ doc = """The list of files needed by this rule at runtime. See general comments about `data` at
+ [Attributes common to all build rules](https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).""",
allow_files = True,
cfg = "data",
),
@@ -174,19 +176,21 @@
aspects = [_kt_jvm_plugin_aspect],
),
"module_name": attr.string(
+ doc = """The name of the module, if not provided the module name is derived from the label. --e.g.,
+ `//some/package/path:label_name` is translated to
+ `some_package_path-label_name`.""",
mandatory = False,
),
-}.items())
+}
-_runnable_common_attr = dict(_common_attr.items() + {
+_runnable_common_attr = _common_attr + {
"jvm_flags": attr.string_list(
+ doc = """A list of flags to embed in the wrapper script generated for running this binary. Note: does not yet
+ support make variable substitution.""",
default = [],
),
-}.items())
+}
-########################################################################################################################
-# Outputs: All the outputs produced by the various rules are modelled here.
-########################################################################################################################
_common_outputs = dict(
jar = "%{name}.jar",
jdeps = "%{name}.jdeps",
@@ -195,108 +199,129 @@
srcjar = "%{name}-sources.jar",
)
-_binary_outputs = dict(_common_outputs.items() + {
-}.items())
-
-########################################################################################################################
-# Simple Rules:
-########################################################################################################################
kt_jvm_library = rule(
- attrs = dict(_common_attr.items() + {
- "exports": attr.label_list(default = [], providers = [JavaInfo]),
- "neverlink": attr.bool(default = False),
- }.items()),
+ doc = """This rule compiles and links Kotlin and Java sources into a .jar file.""",
+ attrs = _common_attr + {
+ "exports": attr.label_list(
+ doc = """Exported libraries.
+
+ Deps listed here will be made available to other rules, as if the parents explicitly depended on
+ these deps. This is not true for regular (non-exported) deps.""",
+ default = [],
+ providers = [JavaInfo],
+ ),
+ "neverlink": attr.bool(
+ doc = """If true only use this library for compilation and not at runtime.""",
+ default = False,
+ ),
+ },
outputs = _common_outputs,
toolchains = [_TOOLCHAIN_TYPE],
implementation = _kt_jvm_library_impl,
provides = [JavaInfo, _KtJvmInfo],
)
-"""This rule compiles and links Kotlin and Java sources into a .jar file.
-Args:
- srcs: The list of source files that are processed to create the target, this can contain both Java and Kotlin files. Java analysis occurs first so Kotlin
- classes may depend on Java classes in the same compilation unit.
- exports: Exported libraries.
-
- Deps listed here will be made available to other rules, as if the parents explicitly depended on these deps.
- This is not true for regular (non-exported) deps.
- resources: A list of data files to include in a Java jar.
- resource_strip_prefix: The path prefix to strip from Java resources, files residing under common prefix such as `src/main/resources` or `src/test/resources`
- will have stripping applied by convention.
- resource_jars: Set of archives containing Java resources. If specified, the contents of these jars are merged into the output jar.
- runtime_deps: Libraries to make available to the final binary or test at runtime only. Like ordinary deps, these will appear on the runtime classpath, but
- unlike them, not on the compile-time classpath.
- data: The list of files needed by this rule at runtime. See general comments about `data` at [Attributes common to all build rules](https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).
- deps: A list of dependencies of this rule.See general comments about `deps` at [Attributes common to all build rules](https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).
- module_name: The name of the module, if not provided the module name is derived from the label. --e.g., `//some/package/path:label_name` is translated to
- `some_package_path-label_name`.
- neverlink: If true only use this library for compilation and not at runtime.
-"""
-
kt_jvm_binary = rule(
+ doc = """Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. The wrapper
+ shell script uses a classpath that includes, among other things, a jar file for each library on which the binary
+ depends.
+
+ **Note:** This rule does not have all of the features found in [`java_binary`](https://docs.bazel.build/versions/master/be/java.html#java_binary).
+ It is appropriate for building workspace utilities. `java_binary` should be preferred for release artefacts.
+ """,
attrs = dict(_runnable_common_attr.items() + {
- "main_class": attr.string(mandatory = True),
+ "main_class": attr.string(
+ doc = """Name of class with main() method to use as entry point.""",
+ mandatory = True,
+ ),
}.items()),
executable = True,
- outputs = _binary_outputs,
+ outputs = _common_outputs,
toolchains = [_TOOLCHAIN_TYPE],
implementation = _kt_jvm_binary_impl,
)
-"""Builds a Java archive ("jar file"), plus a wrapper shell script with the same name as the rule. The wrapper shell script uses a classpath that includes,
-among other things, a jar file for each library on which the binary depends.
-
-**Note:** This rule does not have all of the features found in [`java_binary`](https://docs.bazel.build/versions/master/be/java.html#java_binary). It is
-appropriate for building workspace utilities. `java_binary` should be preferred for release artefacts.
-
-Args:
- main_class: Name of class with main() method to use as entry point.
- jvm_flags: A list of flags to embed in the wrapper script generated for running this binary. Note: does not yet support make variable substitution.
-"""
-
kt_jvm_test = rule(
- attrs = dict(_runnable_common_attr.items() + {
+ doc = """Setup a simple kotlin_test.
+
+ **Notes:**
+ * The kotlin test library is not added implicitly, it is available with the label
+ `@com_github_jetbrains_kotlin//:kotlin-test`.
+ """,
+ attrs = _runnable_common_attr + {
"_bazel_test_runner": attr.label(
default = Label("@bazel_tools//tools/jdk:TestRunner_deploy.jar"),
allow_files = True,
),
"friends": attr.label_list(
+ doc = """A single Kotlin dep which allows the test code access to internal members. Currently uses the output
+ jar of the module -- i.e., exported deps won't be included.""",
default = [],
providers = [JavaInfo, _KtJvmInfo],
),
- "test_class": attr.string(),
+ "test_class": attr.string(
+ doc = "The Java class to be loaded by the test runner.",
+ default = "",
+ ),
"main_class": attr.string(default = "com.google.testing.junit.runner.BazelTestRunner"),
- }.items()),
+ },
executable = True,
- outputs = _binary_outputs,
+ outputs = _common_outputs,
test = True,
toolchains = [_TOOLCHAIN_TYPE],
implementation = _kt_jvm_junit_test_impl,
)
-"""Setup a simple kotlin_test.
-
-**Notes:**
-* The kotlin test library is not added implicitly, it is available with the label `@com_github_jetbrains_kotlin//:kotlin-test`.
-
-Args:
- test_class: The Java class to be loaded by the test runner.
- friends: A single Kotlin dep which allows the test code access to internal members. Currently uses the output jar of
- the module -- i.e., exported deps won't be included.
-"""
-
kt_jvm_import = rule(
+ doc = """Import Kotlin jars.
+
+ ## examples
+
+ ```bzl
+ # Old style usage -- reference file groups, do not used this.
+ kt_jvm_import(
+ name = "kodein",
+ jars = [
+ "@com_github_salomonbrys_kodein_kodein//jar:file",
+ "@com_github_salomonbrys_kodein_kodein_core//jar:file"
+ ]
+ )
+
+ # This style will pull in the transitive runtime dependencies of the targets as well.
+ kt_jvm_import(
+ name = "kodein",
+ jars = [
+ "@com_github_salomonbrys_kodein_kodein//jar",
+ "@com_github_salomonbrys_kodein_kodein_core//jar"
+ ]
+ )
+
+ # Import a single kotlin jar.
+ kt_jvm_import(
+ name = "kotlin-runtime",
+ jars = ["lib/kotlin-runtime.jar"],
+ srcjar = "lib/kotlin-runtime-sources.jar"
+ )
+ ```
+ """,
attrs = {
"jars": attr.label_list(
+ doc = """The jars listed here are equavalent to an export attribute. The label should be either to a single
+ class jar, or multiple filegroup labels. When the labels is a file_provider it should follow the conventions
+ used in repositories generated by the maven_jar rule --i.e., the rule expects a file_provider with a single
+ class jar and a single source jar. a source jar is recognized by the suffix `-sources.jar`.""",
allow_files = True,
mandatory = True,
cfg = "target",
),
"srcjar": attr.label(
+ doc = """The sources for the class jar. This should generally be provided especially when importing a single
+ jar.""",
allow_single_file = True,
cfg = "target",
),
"runtime_deps": attr.label_list(
+ doc = """Additional runtime deps.""",
default = [],
mandatory = False,
providers = [JavaInfo],
@@ -305,52 +330,3 @@
implementation = _kt_jvm_import_impl,
provides = [JavaInfo, _KtJvmInfo],
)
-
-# The pairing of src and class is used by intellij to attatch sources, this is picked up via the kt provider attribute.
-#
-# once current format and semantics are finalized add runtime_deps, exports, data, neverlink, testonly.
-# * runtime_deps should accept JavaInfo's (this includes KotlinInfo) and maven_jar filegroups.
-# * exports should only accept JavaInfo's (this include KotlinInfo) but not filegroup. The jars attribute takes care of importing the jars without generating
-# ijars.
-"""(experimental) Import Kotlin jars.
-
-**Status:** This rule is not a counterpart to `java_import`. The current purpose for this rule is to import a kotlin jar without creating ijars. It will
-eventually [be replaced](https://github.com/bazelbuild/rules_kotlin/issues/4) with `java_import`. If there is a need for expanding this rule we can instead
-create a utility macro that delegates to this.
-
-## examples
-
-```bzl
-# Old style usage -- reference file groups, do not used this.
-kt_jvm_import(
- name = "kodein",
- jars = [
- "@com_github_salomonbrys_kodein_kodein//jar:file",
- "@com_github_salomonbrys_kodein_kodein_core//jar:file"
- ]
-)
-
-# This style will pull in the transitive runtime dependencies of the targets as well.
-kt_jvm_import(
- name = "kodein",
- jars = [
- "@com_github_salomonbrys_kodein_kodein//jar",
- "@com_github_salomonbrys_kodein_kodein_core//jar"
- ]
-)
-
-# Import a single kotlin jar.
-kt_jvm_import(
- name = "kotlin-runtime",
- jars = ["lib/kotlin-runtime.jar"],
- srcjar = "lib/kotlin-runtime-sources.jar"
-)
-```
-
-Args:
- jars: The jars listed here are equavalent to an export attribute. The label should be either to a single class jar, or multiple filegroup labels. When the
- labels is a file_provider it should follow the conventions used in repositories generated by the maven_jar rule --i.e., the rule expects a file_provider
- with a single class jar and a single source jar. a source jar is recognized by the suffix `-sources.jar`.
- srcjar: The sources for the class jar. This should be set when importing a single class jar.
- runtime_deps: Additional runtime deps.
-"""
diff --git a/kotlin/internal/toolchains.bzl b/kotlin/internal/toolchains.bzl
index aeae3e8..32e0477 100644
--- a/kotlin/internal/toolchains.bzl
+++ b/kotlin/internal/toolchains.bzl
@@ -38,73 +38,6 @@
```
"""
-# The toolchain rules are not made private, at least the jvm ones so that they may be introspected in Intelij.
-_common_attrs = {
- "kotlin_home": attr.label(
- default = Label("@" + _KT_COMPILER_REPO + "//:home"),
- allow_files = True,
- ),
- "kotlinbuilder": attr.label(
- default = Label("//kotlin/builder"),
- executable = True,
- allow_files = True,
- cfg = "host",
- ),
- "language_version": attr.string(
- default = "1.2",
- values = [
- "1.1",
- "1.2",
- ],
- ),
- "api_version": attr.string(
- default = "1.2",
- values = [
- "1.1",
- "1.2",
- ],
- ),
- "debug": attr.string_list(
- allow_empty = True,
- doc = """Debugging tags passed to the builder. Two tags are supported. `timings` will cause the builder to print
-timing information. `trace` will cause the builder to print tracing messages. These tags can be enabled via the default
-toolchain via the defines `kt_timings=1` and `kt_trace=1`. The tags may also be picked up via the `tags` attribute
-defined directly on the rules.""",
- ),
- "coroutines": attr.string(
- default = "enable",
- values = [
- "enable",
- "warn",
- "error",
- ],
- ),
-}
-
-_kt_jvm_attrs = dict(_common_attrs.items() + {
- "jvm_runtime": attr.label(
- default = Label("@" + _KT_COMPILER_REPO + "//:kotlin-runtime"),
- providers = [JavaInfo],
- cfg = "target",
- ),
- "jvm_stdlibs": attr.label_list(
- default = [
- Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib"),
- Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib-jdk7"),
- Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib-jdk8"),
- ],
- providers = [JavaInfo],
- cfg = "target",
- ),
- "jvm_target": attr.string(
- default = "1.8",
- values = [
- "1.6",
- "1.8",
- ],
- ),
-}.items())
-
def _kotlin_toolchain_impl(ctx):
toolchain = dict(
label = _common.restore_label(ctx.label),
@@ -126,19 +59,84 @@
]
kt_toolchain = rule(
- attrs = _kt_jvm_attrs,
+ doc = """The kotlin toolchain. This should not be created directly `define_kt_toolchain` should be used. The
+ rules themselves define the toolchain using that macro.""",
+ attrs = {
+ "kotlin_home": attr.label(
+ doc = "the filegroup defining the kotlin home",
+ default = Label("@" + _KT_COMPILER_REPO + "//:home"),
+ allow_files = True,
+ ),
+ "kotlinbuilder": attr.label(
+ doc = "the kotlin builder executable",
+ default = Label("//kotlin/builder"),
+ executable = True,
+ allow_files = True,
+ cfg = "host",
+ ),
+ "language_version": attr.string(
+ doc = "this is the -languag_version flag [see](https://kotlinlang.org/docs/reference/compatibility.html)",
+ default = "1.2",
+ values = [
+ "1.1",
+ "1.2",
+ ],
+ ),
+ "api_version": attr.string(
+ doc = "this is the -api_version flag [see](https://kotlinlang.org/docs/reference/compatibility.html).",
+ default = "1.2",
+ values = [
+ "1.1",
+ "1.2",
+ ],
+ ),
+ "debug": attr.string_list(
+ doc = """Debugging tags passed to the builder. Two tags are supported. `timings` will cause the builder to
+ print timing information. `trace` will cause the builder to print tracing messages. These tags can be
+ enabled via the defines `kt_timings=1` and `kt_trace=1`. These can also be enabled on a per target bases by
+ using `tags` attribute defined directly on the rules.""",
+ allow_empty = True,
+ ),
+ "coroutines": attr.string(
+ doc = "the -Xcoroutines flag, enabled by default as it's considered production ready 1.2.0 onward.",
+ default = "enable",
+ values = [
+ "enable",
+ "warn",
+ "error",
+ ],
+ ),
+ "jvm_runtime": attr.label(
+ doc = "The implicit jvm runtime libraries. This is internal.",
+ default = Label("@" + _KT_COMPILER_REPO + "//:kotlin-runtime"),
+ providers = [JavaInfo],
+ cfg = "target",
+ ),
+ "jvm_stdlibs": attr.label_list(
+ doc = "The jvm stdlibs. This is internal.",
+ default = [
+ Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib"),
+ Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib-jdk7"),
+ # JDK8 is being added blindly but I think we will probably not support bytecode levels 1.6 when the
+ # repo stabelizes so this should be fine.
+ Label("@" + _KT_COMPILER_REPO + "//:kotlin-stdlib-jdk8"),
+ ],
+ providers = [JavaInfo],
+ cfg = "target",
+ ),
+ "jvm_target": attr.string(
+ doc = "the -jvm_target flag. This is only tested at 1.8.",
+ default = "1.8",
+ values = [
+ "1.6",
+ "1.8",
+ ],
+ ),
+ },
implementation = _kotlin_toolchain_impl,
provides = [platform_common.ToolchainInfo],
)
-"""The kotlin jvm toolchain
-Args:
- language_version: the -languag_version flag [see](https://kotlinlang.org/docs/reference/compatibility.html).
- api_version: the -api_version flag [see](https://kotlinlang.org/docs/reference/compatibility.html).
- jvm_target: the -jvm_target flag.
- coroutines: the -Xcoroutines flag, enabled by default as it's considered production ready 1.2.0 onward.
-"""
-
def kt_register_toolchains():
"""This macro registers all of the default toolchains."""
native.register_toolchains("@io_bazel_rules_kotlin//kotlin/internal:default_toolchain")
@@ -169,25 +167,3 @@
toolchain = impl_name,
visibility = ["//visibility:public"],
)
-
-def _kt_toolchain_ide_info_impl(ctx):
- tc = ctx.toolchains[_TOOLCHAIN_TYPE]
- info = struct(
- label = tc.label,
- common = struct(
- language_version = tc.language_version,
- api_version = tc.api_version,
- coroutines = tc.coroutines,
- ),
- jvm = struct(
- jvm_target = tc.jvm_target,
- ),
- )
- ctx.actions.write(ctx.outputs.ide_info, info.to_json())
- return [DefaultInfo(files = depset([ctx.outputs.ide_info]))]
-
-kt_toolchain_ide_info = rule(
- outputs = {"ide_info": "kt_toolchain_ide_info.json"},
- toolchains = [_TOOLCHAIN_TYPE],
- implementation = _kt_toolchain_ide_info_impl,
-)
