summaryrefslogtreecommitdiff
path: root/docs/examples/plugintemplate/doc/README
blob: 958f71282b6785aaebe8b4a1ac33433d4d3c700a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
Scala compiler plugin template
------------------------------

This project is a template that can be used for creating compiler
plugins for the Scala compiler.


Installation
------------
To install the compiler plugin, run "ant install". This will create
an sbaz package for the template plugin and install it in the scala
installation available in your PATH.
The install command will also create a script for running the plugin
as standalone application. The command is called "runplugintemplate"
and available in your scala installation as well.
To uninstall the plugin again, run "and uninstall".

Alternatively, copy the file build/pack/plugintemplate.jar, generated
by "ant pack", to the directory misc/scala-devel/plugins of your
scala distribution. The scala compiler will then find and integrate
the new plugin.

Customization
-------------
The following files need to be edited when creating a new plugin
- plugin.properties
- misc/scalac-plugin.xml
- src / test / doc/examples: The source files of the template plugin
  are located a package called "plugintemplate". This will most likely
  be changed for new plugins.

When using eclipse for development, make sure "scala-compiler.jar" is
in the Java Build Path: Right-Click the project and select "Properties".
Then go to "Java Build Path" -> "Libraries" and add the jar file
"eclipse/plugins/ch.epfl.lamp.sdt.core[..]/lib/scala-compiler.jar".

Traverse, Transform, Check
--------------------------
There are several pre-defined components that can be used to code
the behavior of a plugin:
- TemplateTraverseComponent: a template for tree traversers. Used
  to analyze and collect data about compiler trees.
  -> implement the "check" method

- TemplateTransformComponent: a template for tree transformers.
  -> implement "preTransform" and / or "postTransform"

- TemplateInfoTransformComponent: also a tree transformer, which
  additionally is an InfoTransformer. Allows changing the type
  of some symbols for later phases.
  -> implement "preTransform" and / or "postTransform", and the
     "apply" method of the "infoTransformer".

- TemplateAnnotationChecker: a plugin for the typechecker, useful
  for pluggable type systems. Computes the subtyping between two
  annotated types, and allows providing inferred type information.
  -> implement "annotationsConform" and optionally "addAnnotations"

- TemplateComponent: the most general component. Can do anything it
  likes with the CompilationUnits.
  -> implement the "run" method

Ant tasks
---------
"build.xml" defines Ant tasks for building, testing and packing a
plugin. The tests are written using the ScalaTest framework
(http://www.artima.com/scalatest/).
Run the tests using "ant test", or "ant guitest".