Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "SMILA/Development Guidelines"
(General review on content and style) |
|||
Line 1: | Line 1: | ||
+ | This page covers a collection of development guidelines whose compliance should ensure that SMILA appears as a unified product rather than as a loose collection of parts worked on by a variety of individuals each with their own styles and ways of working. Furthermore it contains information on the used software components and requirements and provides descriptions (how-tos) of common tasks (e.g. setting up the development environment). | ||
+ | |||
== Development requirements == | == Development requirements == | ||
=== Official JVM === | === Official JVM === | ||
− | + | The official JVM for this project is Java 5. | |
− | === OSGi | + | === OSGi runtime === |
− | + | The OSGi implementation of Equinox of Eclipse 3.3 or later and the corresponding OSGi specification(s). | |
== Development conventions == | == Development conventions == | ||
− | === Project | + | === Project setup === |
The project folder setup is defined for this project at | The project folder setup is defined for this project at | ||
− | [[SMILA/Development_Guidelines/Brox Java Project Setup|Brox Java Project Setup]] | + | [[SMILA/Development_Guidelines/Brox Java Project Setup|Brox Java Project Setup]]. |
+ | === Description of make.xml === | ||
+ | For a description of the build file <tt>make.xml</tt> refer to [[SMILA/Development_Guidelines/Introduction to make.xml|Introduction to make.xml]]. | ||
− | === | + | === Continuous integration === |
− | + | ||
− | + | Everyone should be aware of the following workflow with Bamboo: | |
− | + | Bamboo should improve the source code quality but it should not be used as a (JUnit) test server. | |
− | + | ||
− | Bamboo should improve the source code quality but it should not be used as a ( | + | |
Therefore each developer should check his code before committing it to subversion regarding: | Therefore each developer should check his code before committing it to subversion regarding: | ||
− | * | + | * Compilation errors |
* Checkstyle (see Brox Coding Conventions) | * Checkstyle (see Brox Coding Conventions) | ||
− | * Tests: Run a local build with the build.xml to test all existing | + | * Tests: Run a local build with the <tt>build.xml</tt> to test all existing JUnit tests. |
*:(see [[SMILA/Development_Guidelines|Development Guidelines]] for the setup) | *:(see [[SMILA/Development_Guidelines|Development Guidelines]] for the setup) | ||
− | *:Be aware that running tests in | + | *:Be aware that running tests in Eclipse doesn't mean that they run with the pdebbuild. |
− | * Build | + | * Build process: Check if your bundles and your test bundle is fully integrated in the whole build process |
*:(see [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate new bundle into build process]] and [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate test bundle into build process]]) | *:(see [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate new bundle into build process]] and [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate test bundle into build process]]) | ||
− | We have added a feature to the build.xml: The failed | + | We have added a feature to the <tt>build.xml</tt>: The failed JUnit tests are reported at the end of the build output. |
− | Furthermore the full | + | Furthermore the full JUnit reports are generate under <tt>eclipse.build/reports/junit/</tt> and the |
− | error messages from the | + | error messages from the JUnit reports are stored under <tt>eclipse.build/reports_errors_txt/</tt>. |
− | Everyone should monitor the trunk at the build | + | Everyone should monitor the trunk at the build server and if there is a "red" build everyone should look if he has committed the error. |
− | If the error could not be solved within the next build the developer should inform the developer | + | If the error could not be solved within the next build, the developer should inform the developer team that there is a problem with the build and that he is working on the solution. |
=== File Header & Copyright Notice === | === File Header & Copyright Notice === | ||
− | see [[SMILA/Project Guidelines|Project Guidelines]] | + | For guidelines on file header and copyright notices see [[SMILA/Project Guidelines|Project Guidelines]]. |
+ | === Eclipse code formatter profile === | ||
− | + | The Eclipse code formatter file is available in trunk at <tt>EILF.builder/eclipse-formatter/Eclipse-formatter-Brox-3.2-3.3.xml</tt>. | |
− | + | To import the Eclipse code formatter profile: | |
− | + | # Download the profile configuration file. | |
− | To import Eclipse code formatter profile | + | # Select ''Window > Preferences'' in Eclipse and switch to the ''Java > Code Style > Formatter'' preferences page. |
− | Click | + | # Click the ''Import'' button and select the downloaded formatter file. |
=== Checkstyle === | === Checkstyle === | ||
− | Each Eclipse project ( | + | Each Eclipse project (bundles) should follow the Brox Coding Conventions. |
− | + | The file containing the Checkstyle rules is available in trunk at <tt>EILF.builder/checkstyle/brox_checks.xml</tt>. | |
'''Eclipse checkstyle plugin.''' | '''Eclipse checkstyle plugin.''' | ||
− | The eclipse-cs Checkstyle plugin integrates the source code analyzer Checkstyle into Eclipse IDE. | + | The eclipse-cs Checkstyle plugin integrates the source code analyzer Checkstyle into Eclipse IDE. By using this plugin your code is constantly inspected for problems. Within the Eclipse workbench you are notified of problems via the Eclipse ''Problems'' View and source code annotations just as you would see with compiler errors or warnings. The Checkstyle Eclipse plugin can be obtained from the update site: [http://eclipse-cs.sourceforge.net/update/]. Instructions about how to set up the Checkstyle plugin for your project can be obtained from [http://eclipse-cs.sourceforge.net/basic_setup_project.html]. |
− | + | ||
− | The Checkstyle Eclipse plugin can be obtained from the update site: http://eclipse-cs.sourceforge.net/update/ | + | |
− | Instructions about how to set up the Checkstyle plugin for your project can be obtained from http://eclipse-cs.sourceforge.net/basic_setup_project.html | + | |
− | + | ||
− | Checkstyle Configuration | + | To use the plugin for all projects: |
+ | # Click ''Window > Preferences'' in Eclipse. | ||
+ | # Select the ''Checkstyle'' preference page and click the ''New'' button. | ||
+ | # Select ''External Configuration File'' as ''Type'' and point to the location of the file <tt>brox_checks.xml</tt>. | ||
+ | # The Checkstyle configuration profile should be named (while importing): "Brox Coding Conventions 1.06". | ||
− | The complete manual and other information | + | The complete manual and other information on the plugin may be obtained from [http://eclipse-cs.sourceforge.net/]. |
+ | === Creation of bundles === | ||
+ | For information on creating and integrating bundles refer to the folowing pages: | ||
− | + | * [[SMILA/Development_Guidelines/Create a bundle (plug-in)|Create a bundle (plug-in)]] | |
− | + | * [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate a new bundle into the build process]] | |
− | + | * [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate a test bundle into the build process]] | |
− | + | ||
− | + | ||
− | + | ||
=== Version number === | === Version number === | ||
− | + | Until further notice, all own created bundles are V0.5. | |
− | + | ||
− | === XML | + | === XML schemas, namespace convention, and versioning === |
− | This subject is still very open to discussion right now, but | + | This subject is still very open to discussion right now, but I suggest to do the following: |
# when defining a schema a name space must be defined also | # when defining a schema a name space must be defined also | ||
## the URL of the namespace shall be like so: <nowiki>http://org.eclipse.eilf/<rest of bundle as path>/<version>##- <rest of bundle as path></nowiki> means that the '.' are converted to '/'. In case the bundle defines more than one schema then use the either packages or other properly identifying names (plz discuss this) to further qualify the name space. | ## the URL of the namespace shall be like so: <nowiki>http://org.eclipse.eilf/<rest of bundle as path>/<version>##- <rest of bundle as path></nowiki> means that the '.' are converted to '/'. In case the bundle defines more than one schema then use the either packages or other properly identifying names (plz discuss this) to further qualify the name space. | ||
Line 89: | Line 89: | ||
*:Further it is not clear how and when we will version a particular schema as those under development might be still very volatile. So the current *:idea is to version a schema on a milestone and releases. | *:Further it is not clear how and when we will version a particular schema as those under development might be still very volatile. So the current *:idea is to version a schema on a milestone and releases. | ||
*:Another idea is to integrate versioning in the daily build process where the version number may be constructed from | *:Another idea is to integrate versioning in the daily build process where the version number may be constructed from | ||
− | ** | + | **Date / time stamp |
− | ** | + | **Build number |
− | ** | + | **Revision number |
Example: <nowiki>http://org.eclipse.eilf/processing/bpel/xml/Record/0.7</nowiki> | Example: <nowiki>http://org.eclipse.eilf/processing/bpel/xml/Record/0.7</nowiki> | ||
− | === | + | === Naming conventions for launch files (.launch) === |
− | It is a good thing to share your launches and many do so already which helps greatly to run tests quickly from within Eclipse. However, in order that at least I don't get confused, we need to define a naming scheme for the . | + | It is a good thing to share your launches and many do so already which helps greatly to run tests quickly from within Eclipse. However, in order that at least I don't get confused, we need to define a naming scheme for the <tt>.launch</tt> files! |
− | ''' Preliminary | + | ''' Preliminary convention: ''' <tt><bundle name>[_config name].launch</tt> |
− | The | + | The <tt>[config name]</tt> part is optional and needed when several <tt>.launch</tt> files exist for the same bundle but with different settings. |
− | === Generated | + | === Generated source code goes into code/gen source folder (like Jaxb) === |
− | All generated source code (eg. JAXB) | + | All generated source code (eg. JAXB) goes into the distinct source code folder code/gen. |
Where possible all generated classes should also have their own package. | Where possible all generated classes should also have their own package. | ||
Reasons: | Reasons: | ||
− | * | + | * Separate generated source code from handwritten code |
− | * | + | * Easier filtering for Checkstyle |
− | (see previous | + | (see previous description in [[SMILA/Documentation/How_to_implement_a_Crawler|How to implement a crawler]]) |
=== Sources of third party bundles === | === Sources of third party bundles === | ||
− | If you have to implement third party bundles into the | + | If you have to implement third party bundles into the SMILA project, please insert the sources into the <tt>3rdPartySources</tt> folder, not into the new bundle folder. |
− | Each third party bundle should have an own folder | + | Each third party bundle should have an own folder suffixed by the corresponding version number, e.g. <tt>3rdPartySources\org.apache.tomcat-6.0.16\apache-tomcat-6.0.16-src.zip</tt>. |
− | == Used | + | == Used technologies == |
=== OSGi related information === | === OSGi related information === | ||
− | * [[SMILA/Development Guidelines/Declarative Services|Declarative | + | * [[SMILA/Development Guidelines/Declarative Services|Declarative services]] |
=== Tuscany related information === | === Tuscany related information === | ||
− | * [[SMILA/Development Guidelines/Tuscany Integration|Tuscany | + | * [[SMILA/Development Guidelines/Tuscany Integration|Tuscany integration]] |
=== Launch configurations for OSGi wih SCA === | === Launch configurations for OSGi wih SCA === | ||
Line 137: | Line 137: | ||
I don't know if all these start levels are required, at least I got it working with these settings. Setting all to default does NOT work !!! | I don't know if all these start levels are required, at least I got it working with these settings. Setting all to default does NOT work !!! | ||
+ | == How-to manuals == | ||
+ | === How to set up the development environment === | ||
+ | Find this how-to manual at [[SMILA/Development Guidelines/Howto set up dev environment|How to set up the development environment]]. | ||
+ | === How to set up the test environment === | ||
+ | Find this how-to manual at [[SMILA/Development Guidelines/Howto set up test environment|How to set up the test environment]]. | ||
− | == | + | === Run and manage the connectivity framework === |
− | + | At the time of writing this there is the possibility to start EILF/SMILA as a separate application as described below: | |
− | + | # Update from SVN and refresh. | |
− | + | # Execute build and unzip <tt>eclipse.build/Application/ EILF-win32.win32.x86.zip</tt> to an arbitrary folder. | |
− | + | # Create the folder <tt>c:\data</tt> and add some TXT and/or HTML files (for file system crawler). | |
− | + | # Launch the application by calling <tt>eclipse.exe -console</tt> or <tt>launch.cmd</tt>. | |
− | + | # Run JConsole and connect to local. | |
− | + | # Open the ''EILF/org.eclipse.econnectivity...'' branch in JConsole. | |
− | + | # Switch to the the ''MBeans/Operations'' tab. | |
− | # Update from SVN and refresh | + | # Start the file system crawler by launching the "startCrawl()" operation and passing the "file" parameter. |
− | # | + | # Start the web crawler by launching the "startCrawl()" operation and passing the "web" parameter. |
− | # Create folder | + | # Have a look at the Eclipse console log and enjoy ;) |
− | # | + | |
− | # Run | + | |
− | # Open EILF/org.eclipse.econnectivity... branch in | + | |
− | # | + | |
− | # Start | + | |
− | # Start | + | |
− | # | + | |
[[Category:SMILA]] | [[Category:SMILA]] |
Revision as of 05:54, 29 September 2008
This page covers a collection of development guidelines whose compliance should ensure that SMILA appears as a unified product rather than as a loose collection of parts worked on by a variety of individuals each with their own styles and ways of working. Furthermore it contains information on the used software components and requirements and provides descriptions (how-tos) of common tasks (e.g. setting up the development environment).
Contents
- 1 Development requirements
- 2 Development conventions
- 2.1 Project setup
- 2.2 Description of make.xml
- 2.3 Continuous integration
- 2.4 File Header & Copyright Notice
- 2.5 Eclipse code formatter profile
- 2.6 Checkstyle
- 2.7 Creation of bundles
- 2.8 Version number
- 2.9 XML schemas, namespace convention, and versioning
- 2.10 Naming conventions for launch files (.launch)
- 2.11 Generated source code goes into code/gen source folder (like Jaxb)
- 2.12 Sources of third party bundles
- 3 Used technologies
- 4 How-to manuals
Development requirements
Official JVM
The official JVM for this project is Java 5.
OSGi runtime
The OSGi implementation of Equinox of Eclipse 3.3 or later and the corresponding OSGi specification(s).
Development conventions
Project setup
The project folder setup is defined for this project at Brox Java Project Setup.
Description of make.xml
For a description of the build file make.xml refer to Introduction to make.xml.
Continuous integration
Everyone should be aware of the following workflow with Bamboo:
Bamboo should improve the source code quality but it should not be used as a (JUnit) test server. Therefore each developer should check his code before committing it to subversion regarding:
- Compilation errors
- Checkstyle (see Brox Coding Conventions)
- Tests: Run a local build with the build.xml to test all existing JUnit tests.
- (see Development Guidelines for the setup)
- Be aware that running tests in Eclipse doesn't mean that they run with the pdebbuild.
- Build process: Check if your bundles and your test bundle is fully integrated in the whole build process
We have added a feature to the build.xml: The failed JUnit tests are reported at the end of the build output.
Furthermore the full JUnit reports are generate under eclipse.build/reports/junit/ and the error messages from the JUnit reports are stored under eclipse.build/reports_errors_txt/.
Everyone should monitor the trunk at the build server and if there is a "red" build everyone should look if he has committed the error.
If the error could not be solved within the next build, the developer should inform the developer team that there is a problem with the build and that he is working on the solution.
File Header & Copyright Notice
For guidelines on file header and copyright notices see Project Guidelines.
Eclipse code formatter profile
The Eclipse code formatter file is available in trunk at EILF.builder/eclipse-formatter/Eclipse-formatter-Brox-3.2-3.3.xml.
To import the Eclipse code formatter profile:
- Download the profile configuration file.
- Select Window > Preferences in Eclipse and switch to the Java > Code Style > Formatter preferences page.
- Click the Import button and select the downloaded formatter file.
Checkstyle
Each Eclipse project (bundles) should follow the Brox Coding Conventions.
The file containing the Checkstyle rules is available in trunk at EILF.builder/checkstyle/brox_checks.xml.
Eclipse checkstyle plugin.
The eclipse-cs Checkstyle plugin integrates the source code analyzer Checkstyle into Eclipse IDE. By using this plugin your code is constantly inspected for problems. Within the Eclipse workbench you are notified of problems via the Eclipse Problems View and source code annotations just as you would see with compiler errors or warnings. The Checkstyle Eclipse plugin can be obtained from the update site: [1]. Instructions about how to set up the Checkstyle plugin for your project can be obtained from [2].
To use the plugin for all projects:
- Click Window > Preferences in Eclipse.
- Select the Checkstyle preference page and click the New button.
- Select External Configuration File as Type and point to the location of the file brox_checks.xml.
- The Checkstyle configuration profile should be named (while importing): "Brox Coding Conventions 1.06".
The complete manual and other information on the plugin may be obtained from [3].
Creation of bundles
For information on creating and integrating bundles refer to the folowing pages:
- Create a bundle (plug-in)
- How to integrate a new bundle into the build process
- How to integrate a test bundle into the build process
Version number
Until further notice, all own created bundles are V0.5.
XML schemas, namespace convention, and versioning
This subject is still very open to discussion right now, but I suggest to do the following:
- when defining a schema a name space must be defined also
- the URL of the namespace shall be like so: http://org.eclipse.eilf/<rest of bundle as path>/<version>##- <rest of bundle as path> means that the '.' are converted to '/'. In case the bundle defines more than one schema then use the either packages or other properly identifying names (plz discuss this) to further qualify the name space.
- <version>
- As we continue to develop the application, schemas will change over time. there are basically two options here: either encode the version in the *:name space or have an extra well defined attribute that needs to be added to the XML messages to tell which schema version it conforms to. Doing *:this with an attribute seem to be much more error prone (likely to be forgotten) and less xml-natural. (subject needs further discussion).
- Further it is not clear how and when we will version a particular schema as those under development might be still very volatile. So the current *:idea is to version a schema on a milestone and releases.
- Another idea is to integrate versioning in the daily build process where the version number may be constructed from
- Date / time stamp
- Build number
- Revision number
Example: http://org.eclipse.eilf/processing/bpel/xml/Record/0.7
Naming conventions for launch files (.launch)
It is a good thing to share your launches and many do so already which helps greatly to run tests quickly from within Eclipse. However, in order that at least I don't get confused, we need to define a naming scheme for the .launch files!
Preliminary convention: <bundle name>[_config name].launch
The [config name] part is optional and needed when several .launch files exist for the same bundle but with different settings.
Generated source code goes into code/gen source folder (like Jaxb)
All generated source code (eg. JAXB) goes into the distinct source code folder code/gen. Where possible all generated classes should also have their own package. Reasons:
- Separate generated source code from handwritten code
- Easier filtering for Checkstyle
(see previous description in How to implement a crawler)
Sources of third party bundles
If you have to implement third party bundles into the SMILA project, please insert the sources into the 3rdPartySources folder, not into the new bundle folder. Each third party bundle should have an own folder suffixed by the corresponding version number, e.g. 3rdPartySources\org.apache.tomcat-6.0.16\apache-tomcat-6.0.16-src.zip.
Used technologies
Launch configurations for OSGi wih SCA
This information is outdated. It will be updated when Tuscany integration is stable Daniel Stucky: I had some trouble selecting the right Bundles that were required to execute my sample application (org.eclipse.eilf.framework.test). Don't use the "Add required Bundles" button in the launch configuration dialog. It adds additional bundles that are not needed and starts all bundles with the same start level. I selected the required bundles manually (through try and error) and assigned the following start levels:
- all org.eclipse bundles (except for the eilf bundles)
- all org.apache.tuscany bundles
- all other third party bundles
- (default) all org.eclipse.eilf bundles
- the bundle with the test application (org.eclipse.eilf.framework.test)
I don't know if all these start levels are required, at least I got it working with these settings. Setting all to default does NOT work !!!
How-to manuals
How to set up the development environment
Find this how-to manual at How to set up the development environment.
How to set up the test environment
Find this how-to manual at How to set up the test environment.
Run and manage the connectivity framework
At the time of writing this there is the possibility to start EILF/SMILA as a separate application as described below:
- Update from SVN and refresh.
- Execute build and unzip eclipse.build/Application/ EILF-win32.win32.x86.zip to an arbitrary folder.
- Create the folder c:\data and add some TXT and/or HTML files (for file system crawler).
- Launch the application by calling eclipse.exe -console or launch.cmd.
- Run JConsole and connect to local.
- Open the EILF/org.eclipse.econnectivity... branch in JConsole.
- Switch to the the MBeans/Operations tab.
- Start the file system crawler by launching the "startCrawl()" operation and passing the "file" parameter.
- Start the web crawler by launching the "startCrawl()" operation and passing the "web" parameter.
- Have a look at the Eclipse console log and enjoy ;)