Wiki source code of Naming and Metadata

Version 4.1 by cds on 2012/04/03 18:04
Hide last authors
cds 3.1 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
cds 1.1 106 {{warning}}
cds 3.1 107 This section hasn't been written yet.
cds 1.1 108 {{/warning}}
cds 3.1 109
110 = Features =
111
112 == Naming Conventions ==
113
114 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.
115
116 == Version Numbering ==
117
118 The version numbering conventions for plug-ins apply to features as well.
119
120 == Metadata ==
121
122 * Project name: same as project folder, use the feature ID with .feature as suffix
123 * feature.xml (//Overview //tab)
124 ** ID: start with de.cau.cs.kieler as prefix, use .feature as suffix
125 ** Version: 0.1.0.qualifier, increase with each release according to changes in one of the contained plugins
126 ** Name: start with //KIELER//, e.g. //KIELER Core//
127 ** Provider: //Christian-Albrechts-Universität zu Kiel//
128 ** Update Site URL: [[http:~~/~~/rtsys.informatik.uni-kiel.de/~~~~kieler/updatesite/nightly/>>url:http://rtsys.informatik.uni-kiel.de/%7Ekieler/updatesite/nightly/||shape="rect"]]
129 ** Update Site Name: //KIELER Nightly Builds//
130 * feature.xml (//Information //tab)
131 ** Feature Description: enter URL of the Wiki page of your project and write a general description as text
132 ** Copyright Notice:
133
134 {{{Copyright 2010 by Real-Time and Embedded Systems Group, Department
135 of Computer Science, Christian-Albrechts-University of Kiel
136 }}}
137 ** 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
138 ** 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
139 * feature.xml (//Dependencies //tab)
140 ** Add other KIELER features that contain plugins that are needed by your plugins, e.g. de.cau.cs.kieler.core.feature feature
141 ** 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
142 * build.properties (//Build//tab)
143 ** Include epl-v10.html in binary and source build (copy into plugin from one of the other plugins)
144 ** Include feature.xml in binary build
145 ** Manually add the following line to build.properties, replace <feature>by the suffix of your feature ID
146
cds 4.1 147 {{{generate.feature@de.cau.cs.kieler.&#x3c;feature&#x3e;.source = de.cau.cs.kieler.&#x3c;feature&#x3e;}}}
148
149 == Source Features ==
150
151 {{warning}}
152 This section hasn't been written yet.
153 {{/warning}}

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage