From df9b52e5430ffbc8e48e60c61d541ff9346cc496 Mon Sep 17 00:00:00 2001 From: Liu Fengyun Date: Thu, 14 Jun 2018 15:43:42 +0200 Subject: [PATCH 1/8] add documentation for compiler plugin --- .../reference/changed/compiler-plugins.md | 133 ++++++++++++++++++ docs/sidebar.yml | 2 + .../compiler-plugin/plugin/DivideZero.scala | 2 +- .../neg/divideZero-research/plugin_1.scala | 4 +- tests/plugins/pos/divideZero/plugin_1.scala | 41 ------ 5 files changed, 138 insertions(+), 44 deletions(-) create mode 100644 docs/docs/reference/changed/compiler-plugins.md delete mode 100644 tests/plugins/pos/divideZero/plugin_1.scala diff --git a/docs/docs/reference/changed/compiler-plugins.md b/docs/docs/reference/changed/compiler-plugins.md new file mode 100644 index 000000000000..e86064983d5e --- /dev/null +++ b/docs/docs/reference/changed/compiler-plugins.md @@ -0,0 +1,133 @@ +--- +layout: doc-page +title: "Changes in Compiler Plugins" +--- + +Compiler plugins are supported by Dotty since 0.9. Compared to Scalac, there are +two notable changes: + +- No more support for analyzer plugins +- Added support for research plugins + +[Analyzer plugins][1] in Scalac are executed during type checking to change the +normal type checking. This is a nice feature for doing research, but for +production usage, a predictable and consistent type checker is more important. + +For experiments and researches that depend on analyzer plugins in Scalac, +_research plugin_ can be used for the same purpose in Dotty. Research plugins +are more powerful than Scalac analyzers as it enables plugin authors to +customize the whole compiler pipeline. That means, you can easily use your +customized typer to replace the standard typer, or roll your own parser for +your domain-specific language. Research plugins are only enabled for nightly or +snaphot releases of Dotty. + +The common plugins that add a new phase to the compiler pipeline are called +_standard plugins_ in Dotty. In terms of features, they are similar to +Scalac plugins, despite minor changes in the API. + +## Physical Interface + +Both research plugins and standard plugins share the same command line options +as Scalac plugins. You may manually specify a plugin as a compiler option as follows: + +```shell +dotc -Xplugin:pluginA.jar -Xplugin:pluginB.jar Test.scala +``` + +The compiler will examine the jar provided, and look for a property file +`plugin.properties` in the root directory of the jar. The property file +specifies the fully qualified plugin class name. The format of a property file +looks like the following: + +``` +pluginClass=dividezero.DivideZero +``` + +The above is a change from Scalac, which depends on an XML file +`scalac-plugin.xml`. Since SBT 1.1.5, SBT also supports Dotty compiler plugins: + +```Scala +addCompilerPlugin("org.divbyzero" % "divbyzero" % "1.0") +``` + +## Standard Plugin + +The following code example shows the template for a standard plugin: + +```Scala +package dividezero + +import dotty.tools.dotc._ +import core._ +import Contexts.Context +import plugins._ +import Phases.Phase +import ast.tpd +import transform.{LinkAll, Pickler} + +class DivideZero extends StandardPlugin { + val name: String = "divideZero" + override val description: String = "divide zero check" + + def init(options: List[String]): List[PluginPhase] = (new DivideZeroPhase) :: Nil +} + +class DivideZeroPhase extends PluginPhase { + val phaseName = "divideZero" + + override val runsAfter = Set(Pickler.name) + override val runsBefore = Set(LinkAll.name) + + override def transformApply(tree: tpd.Apply)(implicit ctx: Context): tpd.Tree = { + // check whether divide by zero here + tree + } +} +``` + +As you can see from the code above, the plugin main class `DivideZero` +extends the trait `StandardPlugin`. It implements the method `init` which +takes the options for the plugin and return a list of `PluginPhase`s to be +inserted into the compilation pipeline. + +The plugin `DivideZero` only adds one compiler phase, `DivideZeroPhase`, +to the compiler pipeline. The compiler phase has to extend the trait +`PluginPhase`. It also needs to tell the compiler the place where it wants to be +in the pipeline by specifying `runsAfter` and `runsBefore` relative to standard +compiler phases. Finally, it can transform the trees of interest by overriding +methods like `transformXXX`. + +Usually a compiler plugin requires significant compiler knowledge in order to +maintain invariants of the compiler. It is a good practice to enable +the compiler option `-Ycheck:all` in the test set of your plugin. + +## Research Plugin + +Research plugins extend the trait `ResearchPlugin` as the following code shows: + +```Scala +import dotty.tools.dotc._ +import core._ +import Contexts.Context +import plugins._ +import Phases.Phase + +class DummyResearchPlugin extends ResearchPlugin { + val name: String = "dummy" + override val description: String = "dummy research plugin" + + def init(options: List[String], phases: List[List[Phase]])(implicit ctx: Context): List[List[Phase]] = + phases +} +``` + +Research plugins also define a method `init`, but the signature is different. +Research plugins receive options for the plugin and the whole compiler pipeline as parameters. +Usually, the `init` method replaces some standard phase of the compiler pipeline +with a custom phase, e.g. use a custom frontend. Finally, `init` returns the +updated compiler pipeline. + +Note that research plugins are only enabled for nightly or snaphot release of Dotty. + + +[1]: https://github.com/scala/scala/blob/2.13.x/src/compiler/scala/tools/nsc/typechecker/AnalyzerPlugins.scala diff --git a/docs/sidebar.yml b/docs/sidebar.yml index 8fab86dd4bea..1b46769168c9 100644 --- a/docs/sidebar.yml +++ b/docs/sidebar.yml @@ -79,6 +79,8 @@ sidebar: url: docs/reference/changed/pattern-matching.html - title: Eta Expansion url: docs/reference/changed/eta-expansion.html + - title: Compiler Plugins + url: docs/reference/changed/compiler-plugins.html - title: Dropped Features subsection: - title: DelayedInit diff --git a/sbt-dotty/sbt-test/sbt-dotty/compiler-plugin/plugin/DivideZero.scala b/sbt-dotty/sbt-test/sbt-dotty/compiler-plugin/plugin/DivideZero.scala index 5942d236a079..a69adf32d81e 100644 --- a/sbt-dotty/sbt-test/sbt-dotty/compiler-plugin/plugin/DivideZero.scala +++ b/sbt-dotty/sbt-test/sbt-dotty/compiler-plugin/plugin/DivideZero.scala @@ -22,7 +22,7 @@ class DivideZero extends PluginPhase with StandardPlugin { override val runsAfter = Set(Pickler.name) override val runsBefore = Set(LinkAll.name) - override def init(options: List[String]): List[PluginPhase] = this :: Nil + def init(options: List[String]): List[PluginPhase] = this :: Nil private def isNumericDivide(sym: Symbol)(implicit ctx: Context): Boolean = { def test(tpe: String): Boolean = diff --git a/tests/plugins/neg/divideZero-research/plugin_1.scala b/tests/plugins/neg/divideZero-research/plugin_1.scala index f7f4efbda87b..7b5c61003931 100644 --- a/tests/plugins/neg/divideZero-research/plugin_1.scala +++ b/tests/plugins/neg/divideZero-research/plugin_1.scala @@ -10,13 +10,13 @@ import Symbols.Symbol import Constants.Constant import StdNames._ -class DivideZero extends MiniPhase with ResearchPlugin { +class DivideZero extends PluginPhase with ResearchPlugin { val name: String = "divideZero" override val description: String = "divide zero check" val phaseName = name - override def init(options: List[String], phases: List[List[Phase]])(implicit ctx: Context): List[List[Phase]] = { + def init(options: List[String], phases: List[List[Phase]])(implicit ctx: Context): List[List[Phase]] = { val (before, after) = phases.span(ps => !ps.exists(_.phaseName == "pickler")) before ++ (List(this) :: after) } diff --git a/tests/plugins/pos/divideZero/plugin_1.scala b/tests/plugins/pos/divideZero/plugin_1.scala deleted file mode 100644 index eca2e6fdf53b..000000000000 --- a/tests/plugins/pos/divideZero/plugin_1.scala +++ /dev/null @@ -1,41 +0,0 @@ -import dotty.tools.dotc._ -import core._ -import Contexts.Context -import plugins.Plugin -import Phases.Phase -import ast.tpd -import transform.MegaPhase.MiniPhase -import Decorators._ -import Symbols.Symbol -import Constants.Constant -import StdNames._ - - -class DivideZero extends MiniPhase with Plugin { - val name: String = "divideZero" - override val description: String = "divide by zero check" - - val phaseName = name - - override val research = true - - override def init(options: List[String], phases: List[List[Phase]])(implicit ctx: Context): List[List[Phase]] = { - val (before, after) = phases.span(ps => !ps.exists(_.phaseName == "pickler")) - before ++ (List(this) :: after) - } - - private def isNumericDivide(sym: Symbol)(implicit ctx: Context): Boolean = { - def test(tpe: String): Boolean = - (sym.owner eq ctx.requiredClass(tpe.toTermName)) && sym.name == nme.DIV - - test("scala.Int") || test("scala.Long") || test("scala.Short") || test("scala.Float") || test("scala.Double") - } - - override def transformApply(tree: tpd.Apply)(implicit ctx: Context): tpd.Tree = tree match { - case tpd.Apply(fun, tpd.Literal(Constants.Constant(v)) :: Nil) if isNumericDivide(fun.symbol) && v == 0 => - ctx.warning("divide by zero", tree.pos) - tree - case _ => - tree - } -} From bf19080fce3baf72da8ef94cf23aeaa2de1333c5 Mon Sep 17 00:00:00 2001 From: Liu Fengyun Date: Thu, 14 Jun 2018 16:22:20 +0200 Subject: [PATCH 2/8] address review --- docs/docs/reference/changed/compiler-plugins.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/reference/changed/compiler-plugins.md b/docs/docs/reference/changed/compiler-plugins.md index e86064983d5e..e5dd650f3e07 100644 --- a/docs/docs/reference/changed/compiler-plugins.md +++ b/docs/docs/reference/changed/compiler-plugins.md @@ -13,7 +13,7 @@ two notable changes: normal type checking. This is a nice feature for doing research, but for production usage, a predictable and consistent type checker is more important. -For experiments and researches that depend on analyzer plugins in Scalac, +For experiments and researches that rely on analyzer plugins in Scalac, _research plugin_ can be used for the same purpose in Dotty. Research plugins are more powerful than Scalac analyzers as it enables plugin authors to customize the whole compiler pipeline. That means, you can easily use your @@ -21,7 +21,7 @@ customized typer to replace the standard typer, or roll your own parser for your domain-specific language. Research plugins are only enabled for nightly or snaphot releases of Dotty. -The common plugins that add a new phase to the compiler pipeline are called +The common plugins that add new phases to the compiler pipeline are called _standard plugins_ in Dotty. In terms of features, they are similar to Scalac plugins, despite minor changes in the API. @@ -44,7 +44,7 @@ pluginClass=dividezero.DivideZero ``` The above is a change from Scalac, which depends on an XML file -`scalac-plugin.xml`. Since SBT 1.1.5, SBT also supports Dotty compiler plugins: +`scalac-plugin.xml`. Starting from 1.1.5, SBT also supports Dotty compiler plugins: ```Scala addCompilerPlugin("org.divbyzero" % "divbyzero" % "1.0") From 27f10abf28ec2b2f950e53b4908daa9a5121589b Mon Sep 17 00:00:00 2001 From: Liu Fengyun Date: Thu, 14 Jun 2018 16:31:42 +0200 Subject: [PATCH 3/8] revert the change in research plugin test --- tests/plugins/neg/divideZero-research/plugin_1.scala | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/plugins/neg/divideZero-research/plugin_1.scala b/tests/plugins/neg/divideZero-research/plugin_1.scala index 7b5c61003931..f3056496e080 100644 --- a/tests/plugins/neg/divideZero-research/plugin_1.scala +++ b/tests/plugins/neg/divideZero-research/plugin_1.scala @@ -10,7 +10,7 @@ import Symbols.Symbol import Constants.Constant import StdNames._ -class DivideZero extends PluginPhase with ResearchPlugin { +class DivideZero extends MiniPhase with ResearchPlugin { val name: String = "divideZero" override val description: String = "divide zero check" From 074a5dce06b7da1afb71170ba698c21fc1cf4536 Mon Sep 17 00:00:00 2001 From: Liu Fengyun Date: Thu, 14 Jun 2018 17:43:01 +0200 Subject: [PATCH 4/8] address review --- docs/docs/reference/changed/compiler-plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/reference/changed/compiler-plugins.md b/docs/docs/reference/changed/compiler-plugins.md index e5dd650f3e07..f7878784f160 100644 --- a/docs/docs/reference/changed/compiler-plugins.md +++ b/docs/docs/reference/changed/compiler-plugins.md @@ -15,7 +15,7 @@ production usage, a predictable and consistent type checker is more important. For experiments and researches that rely on analyzer plugins in Scalac, _research plugin_ can be used for the same purpose in Dotty. Research plugins -are more powerful than Scalac analyzers as it enables plugin authors to +are more powerful than Scalac analyzer plugins as they enable plugin authors to customize the whole compiler pipeline. That means, you can easily use your customized typer to replace the standard typer, or roll your own parser for your domain-specific language. Research plugins are only enabled for nightly or From 19d3c161677213588591b8e6bd1b2e75e261d99c Mon Sep 17 00:00:00 2001 From: Liu Fengyun Date: Tue, 19 Jun 2018 10:05:20 +0200 Subject: [PATCH 5/8] rename physical interface to artifact interface --- docs/docs/reference/changed/compiler-plugins.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/docs/reference/changed/compiler-plugins.md b/docs/docs/reference/changed/compiler-plugins.md index f7878784f160..af028c87290b 100644 --- a/docs/docs/reference/changed/compiler-plugins.md +++ b/docs/docs/reference/changed/compiler-plugins.md @@ -25,10 +25,10 @@ The common plugins that add new phases to the compiler pipeline are called _standard plugins_ in Dotty. In terms of features, they are similar to Scalac plugins, despite minor changes in the API. -## Physical Interface +## Artifact Interface Both research plugins and standard plugins share the same command line options -as Scalac plugins. You may manually specify a plugin as a compiler option as follows: +as Scalac plugins. You may integrate a plugin in the Dotty compiler as follows: ```shell dotc -Xplugin:pluginA.jar -Xplugin:pluginB.jar Test.scala @@ -44,12 +44,16 @@ pluginClass=dividezero.DivideZero ``` The above is a change from Scalac, which depends on an XML file -`scalac-plugin.xml`. Starting from 1.1.5, SBT also supports Dotty compiler plugins: +`scalac-plugin.xml`. + +Starting from 1.1.5, SBT also supports Dotty compiler plugins: ```Scala addCompilerPlugin("org.divbyzero" % "divbyzero" % "1.0") ``` +With the code above, SBT will prepare the correct options to the compiler. + ## Standard Plugin The following code example shows the template for a standard plugin: From c495b83592646e5721de1e37a787fab1966b7598 Mon Sep 17 00:00:00 2001 From: Allan Renucci Date: Tue, 3 Jul 2018 16:55:39 +0200 Subject: [PATCH 6/8] Polishing --- .../reference/changed/compiler-plugins.md | 134 ++++++++---------- 1 file changed, 63 insertions(+), 71 deletions(-) diff --git a/docs/docs/reference/changed/compiler-plugins.md b/docs/docs/reference/changed/compiler-plugins.md index af028c87290b..249dcab1a4fc 100644 --- a/docs/docs/reference/changed/compiler-plugins.md +++ b/docs/docs/reference/changed/compiler-plugins.md @@ -3,71 +3,64 @@ layout: doc-page title: "Changes in Compiler Plugins" --- -Compiler plugins are supported by Dotty since 0.9. Compared to Scalac, there are -two notable changes: +Compiler plugins are supported by Dotty since 0.9. There are two notable changes +compared to `scalac`: -- No more support for analyzer plugins +- No support for analyzer plugins - Added support for research plugins -[Analyzer plugins][1] in Scalac are executed during type checking to change the -normal type checking. This is a nice feature for doing research, but for -production usage, a predictable and consistent type checker is more important. +[Analyzer plugins][1] in `scalac` run during type checking and may influence +normal type checking. This is a very powerful feature but for production usages, +a predictable and consistent type checker is more important. -For experiments and researches that rely on analyzer plugins in Scalac, -_research plugin_ can be used for the same purpose in Dotty. Research plugins -are more powerful than Scalac analyzer plugins as they enable plugin authors to -customize the whole compiler pipeline. That means, you can easily use your -customized typer to replace the standard typer, or roll your own parser for -your domain-specific language. Research plugins are only enabled for nightly or -snaphot releases of Dotty. +For experimentation and research, Dotty introduces _research plugin_. Research plugins +are more powerful than `scalac` analyzer plugins as they let plugin authors customize +the whole compiler pipeline. One can easily replace the standard typer by a custom one or +roll its own parser for domain-specific language. However, research plugins are only +enabled for nightly or snaphot releases of Dotty. -The common plugins that add new phases to the compiler pipeline are called +Common plugins that add new phases to the compiler pipeline are called _standard plugins_ in Dotty. In terms of features, they are similar to Scalac plugins, despite minor changes in the API. -## Artifact Interface +## Using Compiler Plugins -Both research plugins and standard plugins share the same command line options -as Scalac plugins. You may integrate a plugin in the Dotty compiler as follows: +Both standard and research plugins can be used with `dotc` by adding the `-Xplugin:` option: ```shell dotc -Xplugin:pluginA.jar -Xplugin:pluginB.jar Test.scala ``` -The compiler will examine the jar provided, and look for a property file -`plugin.properties` in the root directory of the jar. The property file -specifies the fully qualified plugin class name. The format of a property file -looks like the following: +The compiler will examine the jar provided, and look for a property file named +`plugin.properties` in the root directory of the jar. The property file specifies +the fully qualified plugin class name. The format of a property file is as follow: -``` +```properties pluginClass=dividezero.DivideZero ``` -The above is a change from Scalac, which depends on an XML file -`scalac-plugin.xml`. - -Starting from 1.1.5, SBT also supports Dotty compiler plugins: - -```Scala -addCompilerPlugin("org.divbyzero" % "divbyzero" % "1.0") -``` +This is different from `scalac` plugins that required a `scalac-plugin.xml` file. -With the code above, SBT will prepare the correct options to the compiler. +Starting from 1.1.5, `sbt` also supports Dotty compiler plugins. Please refer to the +`sbt` [documentation][2] for more information. -## Standard Plugin +## Writing a Standard Compiler Plugin -The following code example shows the template for a standard plugin: +Here is the source code for a simple compiler plugin that reports integer divisions by +zero as errors. -```Scala +```scala package dividezero -import dotty.tools.dotc._ -import core._ -import Contexts.Context -import plugins._ -import Phases.Phase -import ast.tpd -import transform.{LinkAll, Pickler} +import dotty.tools.dotc.ast.Trees._ +import dotty.tools.dotc.ast.tpd +import dotty.tools.dotc.core.Constants.Constant +import dotty.tools.dotc.core.Contexts.Context +import dotty.tools.dotc.core.Decorators._ +import dotty.tools.dotc.core.StdNames._ +import dotty.tools.dotc.core.Symbols._ +import dotty.tools.dotc.plugins.{PluginPhase, StandardPlugin} +import dotty.tools.dotc.transform.{LinkAll, Pickler} class DivideZero extends StandardPlugin { val name: String = "divideZero" @@ -77,44 +70,45 @@ class DivideZero extends StandardPlugin { } class DivideZeroPhase extends PluginPhase { + import tpd._ + val phaseName = "divideZero" override val runsAfter = Set(Pickler.name) override val runsBefore = Set(LinkAll.name) - override def transformApply(tree: tpd.Apply)(implicit ctx: Context): tpd.Tree = { - // check whether divide by zero here + override def transformApply(tree: Apply)(implicit ctx: Context): Tree = { + tree match { + case Apply(Select(rcvr, nme.DIV), List(Literal(Constant(0)))) + if rcvr.tpe <:< defn.IntType => + ctx.error("dividing by zero", tree.pos) + case _ => + () + } tree } } ``` -As you can see from the code above, the plugin main class `DivideZero` -extends the trait `StandardPlugin`. It implements the method `init` which -takes the options for the plugin and return a list of `PluginPhase`s to be -inserted into the compilation pipeline. +The plugin main class (`DivideZero`) must extends the `StandardPlugin` trait +and implement the method `init` that takes the plugin's options as argument +and return a list of `PluginPhase`s to be inserted into the compilation pipeline. -The plugin `DivideZero` only adds one compiler phase, `DivideZeroPhase`, -to the compiler pipeline. The compiler phase has to extend the trait -`PluginPhase`. It also needs to tell the compiler the place where it wants to be -in the pipeline by specifying `runsAfter` and `runsBefore` relative to standard -compiler phases. Finally, it can transform the trees of interest by overriding -methods like `transformXXX`. +Our plugin adds one compiler phase to the pipeline. A compiler phase must extend +the `PluginPhase` trait. In order to specify when the phase is executed, we also +need to specify a `runsBefore` and `runsAfter` constraints that are list of phase +names. -Usually a compiler plugin requires significant compiler knowledge in order to -maintain invariants of the compiler. It is a good practice to enable -the compiler option `-Ycheck:all` in the test set of your plugin. +We can now transform trees by by overriding methods like `transformXXX`. -## Research Plugin +## Writing a Research Compiler Plugin -Research plugins extend the trait `ResearchPlugin` as the following code shows: +Here is a template for research plugins. -```Scala -import dotty.tools.dotc._ -import core._ -import Contexts.Context -import plugins._ -import Phases.Phase +```scala +import dotty.tools.dotc.core.Contexts.Context +import dotty.tools.dotc.core.Phases.Phase +import dotty.tools.dotc.plugins.ResearchPlugin class DummyResearchPlugin extends ResearchPlugin { val name: String = "dummy" @@ -125,13 +119,11 @@ class DummyResearchPlugin extends ResearchPlugin { } ``` -Research plugins also define a method `init`, but the signature is different. -Research plugins receive options for the plugin and the whole compiler pipeline as parameters. -Usually, the `init` method replaces some standard phase of the compiler pipeline -with a custom phase, e.g. use a custom frontend. Finally, `init` returns the -updated compiler pipeline. - -Note that research plugins are only enabled for nightly or snaphot release of Dotty. +A research plugins must extend the `ResearchPlugin` trait and implements the +method `init` that takes the plugin's options as argument as well as the list of +default compiler phases. We can return an updated version of this list that may +replace, remove or add any phases to the pipeline. [1]: https://github.com/scala/scala/blob/2.13.x/src/compiler/scala/tools/nsc/typechecker/AnalyzerPlugins.scala +[2]: https://www.scala-sbt.org/1.x/docs/Compiler-Plugins.html \ No newline at end of file From 109568a4b31d73b2363ff2000270ad996e875410 Mon Sep 17 00:00:00 2001 From: Fengyun Liu Date: Tue, 3 Jul 2018 17:22:34 +0200 Subject: [PATCH 7/8] small fixes --- .../reference/changed/compiler-plugins.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/docs/reference/changed/compiler-plugins.md b/docs/docs/reference/changed/compiler-plugins.md index 249dcab1a4fc..a55ddc09ceec 100644 --- a/docs/docs/reference/changed/compiler-plugins.md +++ b/docs/docs/reference/changed/compiler-plugins.md @@ -4,19 +4,19 @@ title: "Changes in Compiler Plugins" --- Compiler plugins are supported by Dotty since 0.9. There are two notable changes -compared to `scalac`: +compared to scalac: - No support for analyzer plugins - Added support for research plugins -[Analyzer plugins][1] in `scalac` run during type checking and may influence +[Analyzer plugins][1] in scalac run during type checking and may influence normal type checking. This is a very powerful feature but for production usages, a predictable and consistent type checker is more important. For experimentation and research, Dotty introduces _research plugin_. Research plugins -are more powerful than `scalac` analyzer plugins as they let plugin authors customize +are more powerful than scalac analyzer plugins as they let plugin authors customize the whole compiler pipeline. One can easily replace the standard typer by a custom one or -roll its own parser for domain-specific language. However, research plugins are only +create a parser for a domain-specific language. However, research plugins are only enabled for nightly or snaphot releases of Dotty. Common plugins that add new phases to the compiler pipeline are called @@ -25,7 +25,7 @@ Scalac plugins, despite minor changes in the API. ## Using Compiler Plugins -Both standard and research plugins can be used with `dotc` by adding the `-Xplugin:` option: +Both standard and research plugins can be used with dotc by adding the `-Xplugin:` option: ```shell dotc -Xplugin:pluginA.jar -Xplugin:pluginB.jar Test.scala @@ -90,9 +90,9 @@ class DivideZeroPhase extends PluginPhase { } ``` -The plugin main class (`DivideZero`) must extends the `StandardPlugin` trait +The plugin main class (`DivideZero`) must extend the trait `StandardPlugin` and implement the method `init` that takes the plugin's options as argument -and return a list of `PluginPhase`s to be inserted into the compilation pipeline. +and returns a list of `PluginPhase`s to be inserted into the compilation pipeline. Our plugin adds one compiler phase to the pipeline. A compiler phase must extend the `PluginPhase` trait. In order to specify when the phase is executed, we also @@ -119,11 +119,11 @@ class DummyResearchPlugin extends ResearchPlugin { } ``` -A research plugins must extend the `ResearchPlugin` trait and implements the -method `init` that takes the plugin's options as argument as well as the list of -default compiler phases. We can return an updated version of this list that may -replace, remove or add any phases to the pipeline. +A research plugin must extend the trait `ResearchPlugin` and implement the +method `init` that takes the plugin's options as argument as well as the compiler +pipeline in the form of a list of compiler phases. The method can replace, remove +or add any phases to the pipeline and return the updated pipeline. [1]: https://github.com/scala/scala/blob/2.13.x/src/compiler/scala/tools/nsc/typechecker/AnalyzerPlugins.scala -[2]: https://www.scala-sbt.org/1.x/docs/Compiler-Plugins.html \ No newline at end of file +[2]: https://www.scala-sbt.org/1.x/docs/Compiler-Plugins.html From ae44d177dea1c3df3fb068956d474ae3955dfafd Mon Sep 17 00:00:00 2001 From: Fengyun Liu Date: Tue, 3 Jul 2018 17:25:24 +0200 Subject: [PATCH 8/8] add back inline code for scalac and dotc --- docs/docs/reference/changed/compiler-plugins.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/reference/changed/compiler-plugins.md b/docs/docs/reference/changed/compiler-plugins.md index a55ddc09ceec..6abda9f69a39 100644 --- a/docs/docs/reference/changed/compiler-plugins.md +++ b/docs/docs/reference/changed/compiler-plugins.md @@ -4,28 +4,28 @@ title: "Changes in Compiler Plugins" --- Compiler plugins are supported by Dotty since 0.9. There are two notable changes -compared to scalac: +compared to `scalac`: - No support for analyzer plugins - Added support for research plugins -[Analyzer plugins][1] in scalac run during type checking and may influence +[Analyzer plugins][1] in `scalac` run during type checking and may influence normal type checking. This is a very powerful feature but for production usages, a predictable and consistent type checker is more important. For experimentation and research, Dotty introduces _research plugin_. Research plugins -are more powerful than scalac analyzer plugins as they let plugin authors customize +are more powerful than `scalac` analyzer plugins as they let plugin authors customize the whole compiler pipeline. One can easily replace the standard typer by a custom one or create a parser for a domain-specific language. However, research plugins are only enabled for nightly or snaphot releases of Dotty. Common plugins that add new phases to the compiler pipeline are called _standard plugins_ in Dotty. In terms of features, they are similar to -Scalac plugins, despite minor changes in the API. +`scalac` plugins, despite minor changes in the API. ## Using Compiler Plugins -Both standard and research plugins can be used with dotc by adding the `-Xplugin:` option: +Both standard and research plugins can be used with `dotc` by adding the `-Xplugin:` option: ```shell dotc -Xplugin:pluginA.jar -Xplugin:pluginB.jar Test.scala