Index

Plug-in Development Reference

1998-07-01


Introduction
------------
 This document describes the general procedures for developing a plug-in. 
 The final chapter details how to bootstrap the EPP source code.



Development Environment
-----------------------
 Currently, only the following two development environments are supported.
( only shell scripts for sh and bash are available. )

	Solaris/Linux, JDK1.1 and later
	Windows, bash from gnu-win32, JDK1.1 and later

 However, I guess you can use JavaVMs and Java compilers other than those
provided with JDK (for exaple, fastjavac, jvc, jview) by modifying the
shell scripts.



Design
------
  • In order to develop a plug-in, you must begin with designing it.
  • Determine a name for your plug-in. Here, we assume that the plug-in name is "Foo".
  • Determine the grammar of your extended feature. When determining the grammar, make sure it does not conflict with the Java grammar and other plug-ins and does not confuse editors. It preferable not to extend grammar. Consider implementing it as normal Java class libraries or implementing it using InvokeStyleMacro.
  • Determine the macro expansion policy Write code before expansion and after expansion and see if there are any potential problems. Implementation --------------
  • The file epp/sample/Sample/PlugIn.java is a template source code for plug-ins. First, under the current directory, create a directory with the name of the plug-in you are going to create, and copy the template file into that directory. % mkdir Foo % cp epp/sample/Sample/PlugIn.java Foo
  • Edit PlugIn.java.
  • Begin with implementing the grammar extension portion. For example if you want to add a new statement, extend the method named "statementTop".
  • Implement your macro expansion function. In order to do so, begin with translating the code after expansion into an S-expression. epp -tree -logfile Test.tree Test.java Then, cut and paste from Tree.tree and embed it into PlugIn.java using the back quote macro. After that, embed any code with commas.
  • When complete implementing, make sure of the following. "package Foo;" is specified. "import epp.*;" is specified. The macro expansion function is registered properly.
  • Make sure that your node name does not conflict with any other existing names. The name of SystemMixin should also not conflict with any other existing names. Testing -------
  • Testing a plug-in involves the following five steps. 1. Expanding the plug-in source code with EPP. 2. Compile the expanded *.java file into a *.class file. 3. Expand the test program using the plug-in. 4. Compile the expanded test program into a *.class file. 5. Execute the compiled test program. For each step, you will have to specify an appropriate CLASSPATH and execute java or javac in an appropriate directory. The tryplugin command executes all of the above steps automatically, while setting up the appropriate environment. ( Currently, only sh and bash scripts are available. ) The usage of tryplugin is described below.
  • First, assume that the following files and directories are under the current directory. Foo/PlugIn.java // source file of the plug-in test/TestFoo.java // test program. Must have #epp Foo specified. eppout/ // output directory of the translated Foo/PlugIn.java test/eppout/ // output directory of the translated test/TestFoo.java If you execute the following, tryplugin will automatically perform the five steps. % tryplugin Foo If any error occurs, execution will stop. The solutions for errors occuring at each step are detailed below. 1. Syntax error when expanding Foo/PlugIn.java with EPP. Fix the syntax error using the line number in the error message as a clue. 2. Compilation error when compiling the EPP expanded source code. Fix the source file according to the error message. Since you are using the SystemMixin plug-in, the error message produced may be misleading. However, you may be able to guess the actual cause by reading the "Error Message Reference" in epp/doc/SystemMixin.txt. 3. Error during expansion test of the plug-in. If a NullPointerException error occurs because of a bug in Foo/PlugIn.java, invoke the debugger and identify the exact location of the error. In order to do so, execute the following in the current directory. % jdbplugin TestFoo.java You do not need to change directories. When the debugger starts, just enter "run". You should be able to determine the cause of the error. 4. Complilation error when compiling the test program source code expanded using the plug-in. If the test program has a bug, fix it. If it does not seem to have any bugs, try debugging Foo/PlugIn.java using methods such as including print statements. 5. Execution error of the test program expanded using the plug-in. As with step 4, fix the test program or debug Foo/PlugIn.java.
  • If no errors occur but the behavior does not seem to be right, identify the wrong place using methods such as insering tree.print(), or specifying the -tree option. % testplugin -tree -logfile tree.log Foo I plan to enhance plug-in debugging features in future versions. Installation ------------
  • After you complete debugging, you must install the plug-in so it can be used from other locations. To do so, copy the eppout/Foo/*.class files that are under the current directory to a location included in the path designated by CLASSPATH. For example if ~/lib/epp is included in CLASSPATH, do the following. % mkdir ~/lib/epp/Foo cp eppout/Foo/*.class ~/lib/epp/Foo You would be able to use the plug-in. Sample Plug-in -------------- The following plug-ins are relatively easy implementations which are provided for your reference. Under epp/src/level0, Math/PlugIn.java enum/PlugIn.java assert/PlugIn.java defmacro/PlugIn.java UserOp/PlugIn.java How to the EPP source code -------------------------- In order to compile the EPP source code (which is also written using the EPP plug-in), do as follows. 1. Preperation -------------- First, create the eppout directory under epp/src directory of the distribution package. % cd epp/src % mkdir eppout (Note: A large amount of small files will be generated when compiling EPP. Note that file generation and deletion on Unix operationg systems is slow. For example if you create eppout under /tmp and not under the usual file system, compilation time may decrease significantlly. In order to do so, do as follows. % mkdir /tmp/tmpeppout % cd epp/src % ln -s /tmp/tmpeppout eppout j 2. Source Translation --------------------- Next, translate the EPP source code into normal Java code. You will have specify the -plug-in-package-prefix jp.go.etl.epp option. If you want to change the package name of translated EPP, specify the -plug-in RenamePackage option. % epp -plug-in-package-prefix jp.go.etl.epp -r level0 Process files under level0 Process files under level0/epp Translating level0/epp/Symbol.java Translating level0/epp/CompUnit.java ... 37 Java files were translated. % 3. Compilation of the Translated Source Code -------------------------------------------- Compile the translated source code. You do not need to set the CLASSPATH. The default heap size of javac will not be sufficient, so increase it by specifying appropriate options. If you use fastjavac of JavaWorkshop2.0 you do not need to specify any options. % cd eppout/level0 % javac -J-mx32m */*.java % 4. Execution of the compiled EPP -------------------------------- You can try out the compiled EPP. Here too, you do not have to set the CLASSPATH. % mkdir eppout % java epp.Epp epp/Tree.java Translating epp/Tree.java 1 Java files were translated. % By examining the first line of the expanded file, you will be able to identify the version of EPP used to build it. % head -1 eppout/epp/Tree.java /* Generated by EPP 1.1.0 (by 1.1.0 (by 1.1.0 (by lisp-epp1.1.0))) */ %

  • Index