Wiki source code of Naming and Metadata

Version 10.1 by mkr on 2015/08/18 14:04
Show last authors
1 So you want to add a new package, plugin or feature to KIELER, eh? Well, then there's some stuff you should know. First, there's some general remarks applying to all kinds of stuff. Then, there's more details specific to certain kinds of stuff.
2
3 **Content**
4
5
6
7 {{toc/}}
8
9 = General Advice =
10
11 These remarks apply to all, packages, namespaces, plug-in projects, and features.
12
13 == Naming Conventions ==
14
15 Follow the [[Eclipse naming conventions>>url:http://wiki.eclipse.org/index.php/Naming_Conventions||shape="rect"]]; basically, projects are named after their base packages, who in turn should follow [[Oracle's naming conventions>>url:http://www.oracle.com/technetwork/java/codeconventions-135099.html||shape="rect"]].
16
17 = Packages and Namespaces =
18
19 == Naming Conventions ==
20
21 Packages and namespaces may use the university internal domain: [[http:~~/~~/kieler.cs.cau.de>>url:http://kieler.cs.cau.de||shape="rect"]]. In fact, that domain forwards to the KIELER project website, although it is not the official domain. Package names should begin with de.cau.cs.kieler, following Oracle's naming conventions.
22
23 = Plug-In Projects =
24
25 == Naming Conventions ==
26
27 When a project consists of several plug-ins, all of them should share the same prefix. For example, all KIML plug-ins start with de.cau.cs.kieler.kiml. Plug-ins containing examples should begin with de.cau.cs.kieler.example. The project name, project ID and project folder should be the same.
28
29 == Project Settings ==
30
31 * //Java Build Path//
32 ** On the //Libraries// tab, remove the default JRE System Library and click //Add Library//. Choose //JRE System Library// and click //Next//. Select //Execution environment//, ensure that Workspace defualt JRE is //jdk1.8.0//.
33 * //Checkstyle//
34 ** If your plug-in only contains generated code, disable Checkstyle.
35 ** Otherwise, activate Checkstyle.
36 *** In the //Exclude from checking...// list, select //all file types except//, click //Change...// and remove //properties//. Checkstyle usually gives wrong warnings for property files.
37 *** If there are packages containing generated code, select //files from packages// from the //Exclude from checking...// list and add the packages to it.
38
39 == Version Numbering ==
40
41 See the [[Eclipse guidelines on version numbering>>url:http://wiki.eclipse.org/index.php/Version_Numbering||shape="rect"]] for general advice on choosing version numbers for projects. All our projects start with version 0.1.0, which is increased after each new release where the project content or its dependencies have changes. Append the string .qualifierto all version numbers to avoid problems with the build system. (if that part is omitted, the build system won't realize that it has to build the project)
42
43 == Metadata ==
44
45 In the plug-in manifest editor, be sure to follow these settings:
46
47 * Tab //Overview//
48 ** ID: start with de.cau.cs.kieler as prefix, except for plugins that contain third-party code
49 ** Version: 0.1.0.qualifier, increase with each release according to changes in the plugin
50 ** Name: start with //KIELER//, e.g. //KIELER Core UI//
51 ** Provider: //Christian-Albrechts-Universität zu Kiel//
52 ** Check //Activate this plug-in when one of its classes is loaded// and //This plug-in is a singleton//, except if you know what you're doing
53 ** Execution Environment: J2SE-1.5
54 ** Activator: Set the name of your Activator class (this represents the entry point of you plug-in). By default it is named "Activator.java". **Rename this class to <Name>Plugin.java** (e.g. {{code language="none"}}CorePlugin.java{{/code}}).
55 * Tab //Dependencies//
56 ** For Eclipse plugins: set your current version with 0 as third digit for //Minimum Version//, e.g. //org.eclipse.core.runtime (3.5.0)//
57 ** For our own plugins: if you know that you really need a specific version of the plugin, do the same as for Eclipse plugins, else leave the minimum version empty
58 ** Don't reexport dependencies, except in one case: UI plug-ins may reexport their dependencies on plug-ins that are part of the same project. (de.cau.cs.kieler.kiml.ui could reexport a dependency on de.cau.cs.kieler.kiml)
59 ** Collect all KIELER internal dependencies on the bottom of the list to increase readability.
60 * Tab //Runtime//
61 ** Add all Java packages that must be visible for other plugins, e.g. if they contain classes or interfaces that must be referenced elsewhere
62 * Tab Extensions
63 ** Add extensions to other extension points as needed
64 * Tab //Build//
65 ** Binary Build
66 *** Include epl-v10.html (copy into plugin from one of the other plugins)
67 *** Include META-INF folder, plugin.xml and plugin.properties if present
68 *** Do **not** include src or bin folder
69 *** Include all icons, models etc. that are in your plugin
70 ** Source Build
71 *** Include epl-v10.html (copy into plugin from one of the other plugins)
72 *** Do **not** include src or bin folder
73 *** Include files that you explicitly want to be present in the source project
74
75 == Metadata for Extension Points ==
76
77 * plugin.xml (//Extension Points//tab)
78 ** ID and name of schema file shall be equal, starting with a lower case character, e.g. diagramConnectors and schema/diagramConnectors.exsd
79 ** Name shall be equal to ID, but starting with an upper case character, e.g. DiagramConnectors
80 ** Do not prefix the ID with the plugin ID
81 * Extension point schema (*.exsdfiles)
82 ** //Overview//tab
83 *** Point ID and Name: same as in plugin.xml
84 *** Description: write general information on the extension point
85 *** Since: enter the version number of the host plugin, without .qualifier
86 *** Examples: write example XML code for plugin.xml that uses the extension point
87 *** API Information: write useful information for developers that want to use the extension point
88 *** (((
89 Copyright:
90
91 {{code}}
92 Copyright 2010 by<br>
93 &nbsp;+ Christian-Albrechts-University of Kiel<br>
94 &nbsp;&nbsp;&nbsp;+ Department of Computer Science<br>
95 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+ Real-Time and Embedded Systems Group<br>
96 This program and the accompanying materials are made available under the terms of the Eclipse Public License (EPL) which accompanies this distribution, and is available at
97 <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
98 {{/code}}
99 )))
100 ** //Definition//tab:
101 *** Create new elements that can be added to the extension point and give them attributes (do not change the extension element)
102 *** Create a //Sequence// in the extension element and drag the top-level elements into it, set their //Max Occurrences// to //Unbounded//
103
104 == Automatic Build Integration ==
105
106 * (((
107 New plugin
108 * (((
109 New plugins need a {{code language="none"}}pom.xml{{/code}} in the plugin's root folder
110
111 {{code title="plugin pom.xml" language="html/xml" collapse="true"}}
112  <?xml version="1.0" encoding="UTF-8"?>
113 <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
114 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
115 <modelVersion>4.0.0</modelVersion>
116 <parent>
117 <groupId>de.cau.cs.kieler</groupId>
118 <artifactId>plugins</artifactId>
119 <version>0.0.1-SNAPSHOT</version>
120 </parent>
121 <groupId>de.cau.cs.kieler</groupId>
122 <artifactId>YOUR.NEW.PLUGIN.NAME</artifactId>
123 <version>0.7.0-SNAPSHOT</version>
124 <packaging>eclipse-plugin</packaging>
125 </project>
126
127
128 {{/code}}
129 )))
130 * Make sure that {{code language="none"}}<version>{{/code}} is in sync with {{code language="none"}}Bundle-Version{{/code}} in {{code language="none"}}META-INF/MANIFEST.MF{{/code}}
131 * Add a {{code language="none"}}<module>{{/code}} entry in the corresponding parent POM i.e. {{code language="none"}}plugins/pom.xml{{/code}}
132 * (((
133 If your plugin uses xtend, tell maven to run the xtend compiler in {{code language="none"}}pom.xml{{/code}}(% style="font-family: monospace;" %)
134
135
136 {{code language="html/xml" collapse="true"}}
137 <build>
138 <sourceDirectory>src</sourceDirectory>
139 <plugins>
140 <plugin>
141 <groupId>org.eclipse.xtend2</groupId>
142 <artifactId>xtend-maven-plugin</artifactId>
143 <executions>
144 <execution>
145 <goals>
146 <goal>compile</goal>
147 </goals>
148 </execution>
149 </executions>
150 </plugin>
151 </plugins>
152 </build>
153
154
155 {{/code}}
156 )))
157 )))
158 * New JUnit test plugin\\
159 ** Basically the same steps as for plugins except {{code language="none"}}<packaging>{{/code}} is {{code language="none"}}eclipse-test-plugin{{/code}}
160 * New features\\
161 ** The same steps as for plugins except {{code language="none"}}<packaging>{{/code}} is {{code language="none"}}eclipse-feature{{/code}}
162 ** Additionally if sources are to be distributed a separate source feature with the corresponding source-bundles must be created
163
164 = Features =
165
166 == Naming Conventions ==
167
168 If <name> is the name of a feature's base plug-in, then the feature project and its directory are named <name>.feature, and the feature is assigned the ID <name>.feature. For example, the plug-in de.cau.cs.kieler.core is contained in the feature de.cau.cs.kieler.core.feature, and this feature is located in the feature project de.cau.cs.kieler.core.feature in the directory features/de.cau.cs.kieler.core.feature.
169
170 == Version Numbering ==
171
172 The version numbering conventions for plug-ins apply to features as well.
173
174 == Metadata ==
175
176 * Project name: same as project folder, use the feature ID with .feature as suffix
177 * feature.xml (//Overview //tab)
178 ** ID: start with de.cau.cs.kieler as prefix, use .feature as suffix
179 ** Version: 0.1.0.qualifier, increase with each release according to changes in one of the contained plugins
180 ** Name: start with //KIELER//, e.g. //KIELER Core//
181 ** Provider: //Christian-Albrechts-Universität zu Kiel//
182 ** Update Site URL: [[http:~~/~~/rtsys.informatik.uni-kiel.de/~~~~kieler/updatesite/nightly/>>url:http://rtsys.informatik.uni-kiel.de/%7Ekieler/updatesite/nightly/||shape="rect"]]
183 ** Update Site Name: //KIELER Nightly Builds//
184 * feature.xml (//Information //tab)
185 ** Feature Description: enter URL of the Wiki page of your project and write a general description as text
186 ** Copyright Notice:
187
188 {{{Copyright 2010 by Real-Time and Embedded Systems Group, Department
189 of Computer Science, Christian-Albrechts-University of Kiel
190 }}}
191 ** License Agreement: enter [[http:~~/~~/www.eclipse.org/legal/epl-v10.html>>url:http://www.eclipse.org/legal/epl-v10.html||shape="rect"]] as URL and copy-paste the complete content of that page as text
192 ** Sites to Visit: add update sites of features that are not part of the official Eclipse distribution and are needed by the plugins contained in your feature
193 * feature.xml (//Dependencies //tab)
194 ** Add other KIELER features that contain plugins that are needed by your plugins, e.g. de.cau.cs.kieler.core.feature feature
195 ** Add single plugins if you do not want to depend on a whole feature, use //Compute// to automatically compute these plugins and remove duplicate entries
196 * build.properties (//Build//tab)
197 ** Include epl-v10.html in binary and source build (copy into plugin from one of the other plugins)
198 ** Include feature.xml in binary build
199 ** Manually add the following line to build.properties, replace <feature>by the suffix of your feature ID
200
201 {{{generate.feature@de.cau.cs.kieler.&#x3c;feature&#x3e;.source = de.cau.cs.kieler.&#x3c;feature&#x3e;}}}
202
203 == Source Features ==
204
205 {{warning}}
206 This section hasn't been written yet.
207 {{/warning}}