|
| 1 | +# Customizable Phase |
| 2 | + |
| 3 | +## Contents |
| 4 | +* [Overview](#overview) |
| 5 | +* [Who needs customizable phase](#who-needs-customizable-phase) |
| 6 | +* [As a consumer](#as-a-consumer) |
| 7 | +* [As a contributor](#as-a-contributor) |
| 8 | + * [Phase naming convention](#phase-naming-convention) |
| 9 | + |
| 10 | +## Overview |
| 11 | +Phases increase configurability. Rule implementations are defined as a list of phases. Each phase defines a specific step, which helps breaking up implementation into smaller and more readable groups. Some phases are independent from others, which means the order doesn't matter. However, some phases depend on outputs of previous phases, in this case, we should make sure it meets all the prerequisites before executing phases. |
| 12 | + |
| 13 | +The biggest benefit of phases is that it is customizable. If default phase A is not doing what you expect, you may switch it with your self-defined phase A. One use case is to write your own compilation phase with your favorite Scala compiler. You may also extend the default phase list for more functionalities. One use case is to check the Scala format. |
| 14 | + |
| 15 | +## Who needs customizable phase |
| 16 | +Customizable phase is an advanced feature for people who want the rules to do more. If you are an experienced Bazel rules developer, we make this powerful API public for you to do custom work without impacting other consumers. If you have no experience on writing Bazel rules, we are happy to help but be aware it may be frustrating at first. |
| 17 | + |
| 18 | +If you don't need to customize your rules and just need the default setup to work correctly, then just load the following file for default rules: |
| 19 | +``` |
| 20 | +load("@io_bazel_rules_scala//scala:scala.bzl") |
| 21 | +``` |
| 22 | +Otherwise read on: |
| 23 | + |
| 24 | +## As a consumer |
| 25 | +You need to load the following 2 files: |
| 26 | +``` |
| 27 | +load("@io_bazel_rules_scala//scala:advanced_usage/providers.bzl", "ScalaRulePhase") |
| 28 | +load("@io_bazel_rules_scala//scala:advanced_usage/scala.bzl", "make_scala_binary") |
| 29 | +``` |
| 30 | +`ScalaRulePhase` is a phase provider to pass in custom phases. Rules with `make_` prefix, like `make_scala_binary`, are customizable rules. `make_<RULE_NAME>`s take a dictionary as input. It currently supports appending `attrs` and `outputs` to default rules, as well as modifying the phase list. |
| 31 | + |
| 32 | +For example: |
| 33 | +``` |
| 34 | +ext_add_custom_phase = { |
| 35 | + "attrs": { |
| 36 | + "custom_content": attr.string( |
| 37 | + default = "This is custom content", |
| 38 | + ), |
| 39 | + }, |
| 40 | + "outputs": { |
| 41 | + "custom_output": "%{name}.custom-output", |
| 42 | + }, |
| 43 | + "phase_providers": [ |
| 44 | + "//custom/phase:phase_custom_write_extra_file", |
| 45 | + ], |
| 46 | +} |
| 47 | +
|
| 48 | +custom_scala_binary = make_scala_binary(ext_add_custom_phase) |
| 49 | +``` |
| 50 | +`make_<RULE_NAME>`s append `attrs` and `outputs` to the default rule definitions. All items in `attrs` can be accessed by `ctx.attr`, and all items in `outputs` can be accessed by `ctx.outputs`. `phase_providers` takes a list of targets which define how you want to modify phase list. |
| 51 | +``` |
| 52 | +def _add_custom_phase_singleton_implementation(ctx): |
| 53 | + return [ |
| 54 | + ScalaRulePhase( |
| 55 | + custom_phases = [ |
| 56 | + ("last", "", "custom_write_extra_file", phase_custom_write_extra_file), |
| 57 | + ], |
| 58 | + ), |
| 59 | + ] |
| 60 | +
|
| 61 | +add_custom_phase_singleton = rule( |
| 62 | + implementation = _add_custom_phase_singleton_implementation, |
| 63 | +) |
| 64 | +``` |
| 65 | +`add_custom_phase_singleton` is a rule solely to pass in custom phases using `ScalaRulePhase`. The `custom_phases` field in `ScalaRulePhase` takes a list of tuples. Each tuple has 4 elements: |
| 66 | +``` |
| 67 | +(relation, peer_name, phase_name, phase_function) |
| 68 | +``` |
| 69 | + - relation: the position to add a new phase |
| 70 | + - peer_name: the existing phase to compare the position with |
| 71 | + - phase_name: the name of the new phase, also used to access phase information |
| 72 | + - phase_function: the function of the new phase |
| 73 | + |
| 74 | +There are 5 possible relations: |
| 75 | + - `^` or `first` |
| 76 | + - `$` or `last` |
| 77 | + - `-` or `before` |
| 78 | + - `+` or `after` |
| 79 | + - `=` or `replace` |
| 80 | + |
| 81 | +The symbols and words are interchangable. If `first` or `last` is used, it puts your custom phase at the beginning or the end of the phase list, `peer_name` is not needed. |
| 82 | + |
| 83 | +Then you have to call the rule in a `BUILD` |
| 84 | +``` |
| 85 | +add_custom_phase_singleton( |
| 86 | + name = "phase_custom_write_extra_file", |
| 87 | + visibility = ["//visibility:public"], |
| 88 | +) |
| 89 | +``` |
| 90 | + |
| 91 | +You may now see `phase_providers` in `ext_add_custom_phase` is pointing to this target. |
| 92 | + |
| 93 | +The last step is to write the function of the phase. For example: |
| 94 | +``` |
| 95 | +def phase_custom_write_extra_file(ctx, p): |
| 96 | + ctx.actions.write( |
| 97 | + output = ctx.outputs.custom_output, |
| 98 | + content = ctx.attr.custom_content, |
| 99 | + ) |
| 100 | +``` |
| 101 | +Every phase has 2 arguments, `ctx` and `p`. `ctx` gives you access to the fields defined in rules. `p` is the global provider, which contains information from initial state as well as all the previous phases. You may access the information from previous phases by `p.<PHASE_NAME>.<FIELD_NAME>`. For example, if the previous phase, said `phase_jar` with phase name `jar`, returns a struct |
| 102 | +``` |
| 103 | +def phase_jar(ctx, p): |
| 104 | + # Some works to get the jars |
| 105 | + return struct( |
| 106 | + class_jar = class_jar, |
| 107 | + ijar = ijar, |
| 108 | + ) |
| 109 | +``` |
| 110 | +You are able to access information like `p.jar.class_jar` in `phase_custom_write_extra_file`. You can provide the information for later phases in the same way, then they can access it by `p.custom_write_extra_file.<FIELD_NAME>`. |
| 111 | + |
| 112 | +You should be able to define the files above entirely in your own workspace without making change to the [bazelbuild/rules_scala](https://github.com/bazelbuild/rules_scala). If you believe your custom phase will be valuable to the community, please refer to [As a contributor](#as-a-contributor). Pull requests are welcome. |
| 113 | + |
| 114 | +## As a contributor |
| 115 | +Besides the basics in [As a consumer](#as-a-consumer), the followings help you understand how phases are setup if you plan to contribute to [bazelbuild/rules_scala](https://github.com/bazelbuild/rules_scala). |
| 116 | + |
| 117 | +These are the relevant files |
| 118 | + - `scala/private/phases/api.bzl`: the API of executing and modifying the phase list |
| 119 | + - `scala/private/phases/phases.bzl`: re-expose phases for convenience |
| 120 | + - `scala/private/phases/phase_<PHASE_NAME>.bzl`: all the phase definitions |
| 121 | + |
| 122 | +Currently phase architecture is used by 7 rules: |
| 123 | + - scala_library |
| 124 | + - scala_macro_library |
| 125 | + - scala_library_for_plugin_bootstrapping |
| 126 | + - scala_binary |
| 127 | + - scala_test |
| 128 | + - scala_junit_test |
| 129 | + - scala_repl |
| 130 | + |
| 131 | +In each of the rule implementation, it calls `run_phases` and returns the information from `phase_final`, which groups the final returns of the rule. To prevent consumers from accidently removing `phase_final` from the list, we make it a non-customizable phase. |
| 132 | + |
| 133 | +To make a new phase, you have to define a new `phase_<PHASE_NAME>.bzl` in `scala/private/phases/`. Function definition should have 2 arguments, `ctx` and `p`. You may expose the information for later phases by returning a `struct`. In some phases, there are multiple phase functions since different rules may take slightly different input arguemnts. You may want to re-expose the phase definition in `scala/private/phases/phases.bzl`, so it's more convenient to access in rule files. |
| 134 | + |
| 135 | +In the rule implementations, put your new phase in `builtin_customizable_phases` list. The phases are executed sequentially, the order matters if the new phase depends on previous phases. |
| 136 | + |
| 137 | +If you are making new return fields of the rule, remember to modify `phase_final`. |
| 138 | + |
| 139 | +### Phase naming convention |
| 140 | +Files in `scala/private/phases/` |
| 141 | + - `phase_<PHASE_NAME>.bzl`: phase definition file |
| 142 | + |
| 143 | +Function names in `phase_<PHASE_NAME>.bzl` |
| 144 | + - `phase_<RULE_NAME>_<PHASE_NAME>`: function with custom inputs of specific rule |
| 145 | + - `phase_common_<PHASE_NAME>`: function without custom inputs |
| 146 | + - `_phase_default_<PHASE_NAME>`: private function that takes `_args` for custom inputs |
| 147 | + - `_phase_<PHASE_NAME>`: private function with the actual logic |
| 148 | + |
| 149 | +See `phase_compile.bzl` for example. |
0 commit comments