Wiki source code of Naming and Metadata

Version 6.1 by tig on 2012/05/24 13:20
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//, select the one beginning with //J2SE-1.5// and click //Finish//.
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 * New plugin\\
107 ** (((
108 New plugins need a {{code language="none"}}pom.xml{{/code}} in the plugin's root folder
109
110 {{code title="plugin pom.xml" language="html/xml" collapse="true"}}
111  <?xml version="1.0" encoding="UTF-8"?>
112 <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"
113 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
114 <modelVersion>4.0.0</modelVersion>
115 <parent>
116 <groupId>de.cau.cs.kieler</groupId>
117 <artifactId>plugins</artifactId>
118 <version>0.0.1-SNAPSHOT</version>
119 </parent>
120 <groupId>de.cau.cs.kieler</groupId>
121 <artifactId>YOUR.NEW.PLUGIN.NAME</artifactId>
122 <version>0.7.0-SNAPSHOT</version>
123 <packaging>eclipse-plugin</packaging>
124 </project>
125
126
127 {{/code}}
128 )))
129 ** 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}}
130 ** Add a {{code language="none"}}<module>{{/code}} entry in the corresponding parent POM i.e. {{code language="none"}}plugins/pom.xml{{/code}}
131 ** If your plugin uses xtend, tell maven to run the xtend compiler in {{code language="none"}}pom.xml{{/code}}(% style="font-family: monospace;" %)
132
133
134 {{code}}
135 <build>
136 <sourceDirectory>src</sourceDirectory>
137 <plugins>
138 <plugin>
139 <groupId>org.eclipse.xtend2</groupId>
140 <artifactId>xtend-maven-plugin</artifactId>
141 <executions>
142 <execution>
143 <goals>
144 <goal>compile</goal>
145 </goals>
146 </execution>
147 </executions>
148 </plugin>
149 </plugins>
150 </build>
151
152
153 {{/code}}
154
155 {{warning}}
156 This section hasn't been written yet.
157 {{/warning}}
158
159 = Features =
160
161 == Naming Conventions ==
162
163 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.
164
165 == Version Numbering ==
166
167 The version numbering conventions for plug-ins apply to features as well.
168
169 == Metadata ==
170
171 * Project name: same as project folder, use the feature ID with .feature as suffix
172 * feature.xml (//Overview //tab)
173 ** ID: start with de.cau.cs.kieler as prefix, use .feature as suffix
174 ** Version: 0.1.0.qualifier, increase with each release according to changes in one of the contained plugins
175 ** Name: start with //KIELER//, e.g. //KIELER Core//
176 ** Provider: //Christian-Albrechts-Universität zu Kiel//
177 ** Update Site URL: [[http:~~/~~/rtsys.informatik.uni-kiel.de/~~~~kieler/updatesite/nightly/>>url:http://rtsys.informatik.uni-kiel.de/%7Ekieler/updatesite/nightly/||shape="rect"]]
178 ** Update Site Name: //KIELER Nightly Builds//
179 * feature.xml (//Information //tab)
180 ** Feature Description: enter URL of the Wiki page of your project and write a general description as text
181 ** Copyright Notice:
182
183 {{{Copyright 2010 by Real-Time and Embedded Systems Group, Department
184 of Computer Science, Christian-Albrechts-University of Kiel
185 }}}
186 ** 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
187 ** 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
188 * feature.xml (//Dependencies //tab)
189 ** Add other KIELER features that contain plugins that are needed by your plugins, e.g. de.cau.cs.kieler.core.feature feature
190 ** 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
191 * build.properties (//Build//tab)
192 ** Include epl-v10.html in binary and source build (copy into plugin from one of the other plugins)
193 ** Include feature.xml in binary build
194 ** Manually add the following line to build.properties, replace <feature>by the suffix of your feature ID
195
196 {{{generate.feature@de.cau.cs.kieler.&#x3c;feature&#x3e;.source = de.cau.cs.kieler.&#x3c;feature&#x3e;}}}
197
198 == Source Features ==
199
200 {{warning}}
201 This section hasn't been written yet.
202 {{/warning}}

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage