 This topic is depricated. Please see PluginANTScript for Pallada and Irida releases.
You can use WizardPlugin to create plugin project in IDEA.
The project plugin template is a preconfigured environment for plugin development. It is meant for plugin developers
who wish to start writing a plugin and want to setup an initial project. Now IDEA doesn't have any Project Wizards for
predefined projects, therefore you must manually extract this package into your development folder, before you can use it. Also read file HowToDeploy.txt after extract.
If you look at the structure of all of the plugins, you can find very different layouts with many installation types for them. It does not make it obvious to the plugin users how they should be installed. If all the plugins have the same structure and installation instructions, it will be more useful for others who wish to use them.
A project template for plugin development must:
- Be independent of local paths and work on every machine with few changes
- Be functional. This means that the project already must have prepared environment for ANT building, API docs generation, etc.
- Be documented.
-
 External ANT script properties file
- Generics compiler in ANT
- Generics JavaDoc tool in ANT script (sinjdoc)
- UI form compiler for UIDesigner forms (javac2)
- Native2ASCII tool in ANT script
-
 Uptodate task in ANT script for building
The template of the predefined project package consists of an ANT script for building and installing a plugin into IDEA during
development, the default Readme, Changes e.t.c text files for plugin user.
The ZIP archive contains follow files:
- ant folder, contains script for ANT and some util files
- Changes.txt, the change log of the plugin, for example see change log of IDEA
- KnownIssues.txt, the known bugs and issues in the current plugin build
- License.txt, the file containing the plugin's license
- Readme.txt, the file containing the installation/removal instructions for the plugin, along with some extra help information
- classes folder, will contain the output classes from IDEA and the ANT script. This folder is deleted each time the ANT script is executed. Do not place any files into this directory or they will be lost.
- docs folder, contains the documentation for the plugin. The ANT script will also generate javadocs. Javadocs should be placed into an build/docs/api folder. The ANT 'docs' tack is started then it copy all documents from it directory to build/docs folder
- lib folder, the library folder for any jars used by your project. You should also setup IDEA project classpath to include these jars. ANT automatically includes all jars from this directory, you not to need to specify them explicitly in the ANT script.
- src folder, this folder contains your sources. By default in this folder includes a sample plugin, you can safety remove it. But is not recommended to remove the META-INF directory, because it contains your plugin.xml descriptior template.
- template.ipr, template.iws files contain the project settings. Before using the template, please rename these files as
YourPluginName.ipr, YourPluginName.iws. The head of those filenames (the part before the '.') must be equal.
- template.iml, file contains modules and libraries settings for Aurora. Do not rename it like IPR and IWS files before first opening this project in Aurora, becouse it will be erased.
- First, you must download it for your version of IDEA:
- Put ZIP distibution into your backup folder.
- Extract all files into your new empty plugin development folder. Or extract folder template from the ZIP archive into
your development root folder, then rename the folder "template" with your plugin name.
- Rename files template.ipr, template.iws with your plugin name. For example, if plugin name called "==YourPluginName==", then files must be renamed to
YourPluginName.ipr, YourPluginName.iws, YourPluginName.iml. On a windows system it may be doing by command:
ren template.* YourPluginName.*
- If you're using Aurora, then start IDEA and open the IPR file, then close it, do not try change anything. After IDEA is closed, overwrite the IML file with the renaming (replacing) IML file from template.iml to
YourPluginName.iml, this restores valid settings the next time you run IDEA.
- Start IDEA and open IPR file with the Open Project command.
- Go to Project Properties and check the JDK settings. If it shows in red, please choose a valid JDK.
- Go to the Ant Build tab, select the build.xml file and choose Properties from the context menu. In the "Execution" tab check the JDK, if it is not valid, please choose a valid JDK.
- Find package
org.intellij.template and rename it by refactoring (Shift+F6) to org.intellij.YourPluginName.
- Open file ant/build.properties and set up properties for ANT script by you wish. See section about build.properties file for more information.
- Try to run the "all" task from Ant panel. If this task is successful, then the installation of plugin template is successful too.
The plugin descriptor, called "plugin.xml", is located in the src/META-INF folder. This file contains blank fields.
Please, read the comments and fill in the blanks with correct values. You can see how it's defined in the sample.
Please remember, that tokens that look like @project.name@ or @build.number@ will automatically be changed
during the ANT script building process. These tokens provide a way to automatically version number and name the project, please, do not remove it without knowing exactly what you are doing.
In the ant folder is the file build. This file contains only one string - the build number, whichever
you wish. It will authomatical increment since each ANT building.
Ant scripts have the following tasks for building a plugin:
- binaries, build the plugin directory, and compress this directory into a ZIP archive. The ZIP placed into project
build folder. The structure of output ZIP file:
- docs folder, to copy documentation into plugin folder. Here copy all documents from project docs folder.
- lib folder, this will contain a jar file of all the classes compiled in the project, also all jars from project folder
lib will be copied into this folder.
- build, is the build number for the ZIP (when build is complite in build folder will created file build.txt with build number of distribution)
- Changes.txt, is the change history for build
- KnownIssues.txt, contains the list of known issues in this build
- License.txt, is the plugin license
- Readme.txt, is the plugin readme file
- stylesheet.css, is the Default stylesheet CSS file for javadocs
- install, this task copies the built binaries into the IDEA plugins folder for testing. If you are using Aurora build, the plugines folder may change. If this is the case please correct the directory in this target.
- sources, this task creates a ZIP arhive of all the sources of the plugin. This ZIP is then placed into the project
build folder. The structure of output ZIP file is same as the project directory structure.
- docs, this task generates the javadocs for the plugin sources and places it to project build/docs/api directory. Also it copy all docs from docs folder into build/docs.
- native2ascii, this task converts all your native properties files to ascii format. The native file look like
myproperties_RU.native.properties. This file will be converted into an ascii file named myproperties_RU.properties.
- all, meta-task for "binaries", "sources" and "javadoc"
You can control ANT script by setting some properties. There are:
- build.generics.javac, if this property is setted the generics compilers will be used.
- generics.home, folder path of JSR-14 jars. In this folder must exists files collect.jar and gjc-rt.jar. By default this folder is
${idea.home}/lib/generics.
- build.generics.javadoc, if this property is setted the generics javadocs doclet will be used.
- sinjdoc.home, home path of sinjdoc. In this folder must exists files sinjdoc.jar and lib/cup.jar. By default this folder is
${idea.home}/lib/sinjdoc.
- build.uidesigner.javac, if this property is setted the ui form compiler for *.form files will used.
- idea.uidesigner.home, location path of UI Designer plugin. In this folder must exists file javac2.jar. By default this folder is
${idea.home}/plugins/uiDesigner.
- build.native2ascii, if this property is setted the task native2ascii will enabled.
- build.native2ascii.pattern, this property is patern to recognise native properties files. For example,
*.native.properties.
- build.version.class, this property hold the class name within ANT will find @project.name@, @build.number@ etc tokens and replace it before compilation. After compilation file restored back.
- build.version, this property keep plugin version (not build).
- project.author, this property keep author of plugin.
- idea.plugins.home, this property used for task install to copy plugin into directory named by value.
- build.prefix, then ANT script build ZIP files, then it will use follow prefix to construct file name. For example,
${project.name}-${build.number}.
- build.binaries.docs, if this property is setted then binaries ZIP will contains docs.
Any documentation must be placed into the project's docs folder. Then all files from this directory will put into the plugin
distribution.
The ant folder contains files Changes.txt, KnownIssues.txt, License.txt, Readme.txt. You may edit those files
directly, but please remember, that a token looks like @project.name@ will automatically be changed by the ANT script, so
please do not remove it without being sure of what you are doing.
Please also see the topic IntelliJPluginPackage about TWiki recommendations for IntelliJ plugins.
4.2
- Added sinjdoc support (generics JavaDocs generation)
- Added UI designer compilation support
- Bug fixes in generics support and filtering tokens
4.1
Since this version the template will only for Aurora builds, becose too hard to track all new features in this templates in Aurora and Ariadna too. So version 3.04 is final template for plugin development for Ariadna.
- ANT script now may controled by build.properties file
- Support for generics compilation
- Autoincrement for build number
- Default example of "About plugin" with plugin version and other info already included in package. You just setup version and name of plugin.
- Fixes in file coping issues
4.04 and 3.04
- Ant native2acsii task
- Improvements in documentation packaging
- CSS for javadocs
- Fixed issue with copieng jars from project lib into plugin distributive.
- Putting versions and build info into jar file manifest
-- AlexeyEfimov - 03 Nov 2004
|
|
