|
|
| (54 intermediate revisions by 12 users not shown) |
| Line 1: |
Line 1: |
| − | == Setting up CVS for the new bundle==
| + | {{warning|Note: The contents of this page has been migrated. Please see https://github.com/eclipse/orbit/blob/master/Add-bundle.md for current information, or page history for historical versions. }} |
| − | === Creating a new project for an Orbit bundle ===
| + | |
| − | When adding an entirely new library to Orbit, you have to create a project in CVS to house the content. Follow these steps to set this up the first time.
| + | |
| − | # In your workspace, create a project with the desired name (see [[Bundle Naming]]). For this example we'll use com.example.foo.
| + | |
| − | # In the project, create a readme.txt file that alerts users to the fact that the real content of the project is maintained in CVS branches. Something like <pre>Work in this project happens in various branches according to the version of the library being maintained. For example, if you are looking for javax.servlet version 2.3, check out the v2_3 branch of the javax.servlet project.</pre>
| + | |
| − | # Share the project into the Orbit repository using the '''Team > Share Project...''' wizard. There select '''CVS''' then the "dev.eclipse.org/cvsroot/tools" repository. In the following page, choose '''Use specified module name''' and enter "org.eclipse.orbit/com.example.foo" (remember to fill-in your bundle name). Finish off the wizard steps.
| + | |
| − | # Immediately create a new branch of the newly created project following the steps in [[#newBranch|Creating a new branch]].
| + | |
| − | | + | |
| − | === Creating a new branch of an existing Orbit project ===
| + | |
| − | Since all real content in Orbit is maintained in branches, HEAD never contains any real content (just the readme.txt file described above). Follow these steps to create a new branch.
| + | |
| − | # Check out HEAD of the desired project, or '''Replace with...''' HEAD if HEAD of the project is not currently in the workspace.
| + | |
| − | # Create a new branch using the '''Team > Branch...''' wizard. You will be asked to enter a branch name. The typical pattern for that is "v<version number>" where the version number is that which was assigned by the original library producers with the '.' (period) characters replaced with '_' (underscore) characters. So a library whose version is 2.3 would go in the v2_3 branch. Ensure that the "Work with this branch" option is selected and and finish off the wizard.
| + | |
| − | # Delete the readme.txt file
| + | |
| − | # Proceed to add the desired content and eventually commit the changes into the branch.
| + | |
| − | | + | |
| − | == Moving an existing bundle to Orbit ==
| + | |
| − | Taking a library that is already bundled in another Eclipse project and adding it to Orbit is quite straightforward.
| + | |
| − | # Create a [[#newProject|new project]] or [[#newBranch|new branch]] of an existing project to hold the bundle's content.
| + | |
| − | # Check out the existing version of the library into a project using a temporary name. You need to do this if the new and old projects have the same name. Use the '''Team > Check Out As...''' wizard from the repository navigator. Pick any name you like for the new project. For example, com.example.foo.old helps keep things clear. This project will only be in your workspace for a few minutes.
| + | |
| − | # Once the original project is checked out, copy and paste all content from the old project into the project you created at the beginning of these steps and delete the old project. '''Note that you should use the Resource Navigator to ensure you get all the content.'''
| + | |
| − | # Commit the changes to the destination project to create an exact copy of the original bundle project in a branch in the Orbit repository.
| + | |
| − | | + | |
| − | == Adding a library for the first time ==
| + | |
| − | Use this approach when you have a library (i.e., JAR) that you want to convert into a bundle.
| + | |
| − | # Create a [[#newProject|new project]] or [[#newBranch|new branch]] of an existing project to hold the bundle's content.
| + | |
| − | # Start the '''New > Project > Plugin Development > Plug-in from existing JAR''' wizard to effectively import the library into a new project.
| + | |
| − | # Enter the new bundle name etc.
| + | |
| − | # Ensure that the '''Analyze library contents and add dependencies''' checkbox is selected.
| + | |
| − | # Ensure that the '''Unzip the JAR into the project''' checkbox is selected.
| + | |
| − | # Click '''Finish'''
| + | |
| − | | + | |
| − | == Adding a library that is already a bundle ==
| + | |
| − | TBD
| + | |
| − | | + | |
| − | == Adding source for Orbit bundles ==
| + | |
| − | See [[Orbit Bundle Checklist#Create a Source Bundle]]
| + | |
| − | | + | |
| − | == Project setup ==
| + | |
| − | No matter how you created your bundle in Orbit, the following outlines how the project itself should be configured. Remember, it is often simpler to use the Resource Navigator rather than the Project Explorer since you really need to see all the files in your project and you aren't really compiling or building anything.
| + | |
| − | | + | |
| − | * In general Orbit projects have the original JAR exploded into the root of the project. This results in a directory structure such as <project root>org/apache/commons/logging/foo.class.
| + | |
| − | * Using the '''Project properties > Java Build Path > Source''' tab remove all source folders. Check the '''Libraries''' tab to ensure that that project itself is listed as a library (since the class files are directly in the root of the project)
| + | |
| − | * In the MANIFEST.MF, ensure that the '''Bundle-Classpath:''' header is either missing or has only '.' as a value.
| + | |
| − | * For most cases there is no need to have '''Eclipse-Autostart: true''' or such headers since this library is generic and will not have an OSGi bundle activator.
| + | |
| − | * Similarly, for most bundles there is no need to set the '''singleton:=true''' on the '''Bundle-SymbolicName''' header.
| + | |
| − | * Of course, you should set the '''Bundle-RequiredExecutionEnvironment''' header to the absolute minimum JRE required by the library. That can often be difficult to figure out. Look for some tools in PDE to help with this...
| + | |
| − | * Where possible use '''Import-Package''' instead of '''Require-Bundle'''. This reduces sensitivity to different bundlings of the same library.
| + | |
| − | * The Orbit community has agreed that '''Bundle-Version''' numbers should be the original library version number followed by .qualifier in the fourth segment. In the event that the original number is already four segments, that version number should be used and then followed by "_qualifier". ''Note that this versioning scheme differs from the normal Eclipse plug-in [[Version Numbering]] if the external library does not follow the Eclipse rules.''
| + | |
| − | * It is suggested that a 3 part version number be included in the project name, in the ''.project'' file. This is to enable those that use the Eclipse IDE preference (under Team, CVS) to "Use .project project name instead of module name on check out". This makes it easier to check out multiple versions of a bundle (project) from its various branches. For example,
| + | |
| − | <pre><nowiki>
| + | |
| − | <projectDescription>
| + | |
| − | <name>javax.xml 1.3.4</name>
| + | |
| − | <comment></comment>
| + | |
| − | <projects>
| + | |
| − | </projects>
| + | |
| − | .
| + | |
| − | .
| + | |
| − | .
| + | |
| − | | + | |
| − | </nowiki></pre>
| + | |
| − | | + | |
| − | === Special Detailed Notes on the four segment case ===
| + | |
| − | | + | |
| − | As documented above, in the event that the original package number is already four segments, that version number should be used and then followed by "_qualifier". These leads to a few differences in exactly how the final qualifier is computed and referred to in features and map files. The following example are taken from [https://bugs.eclipse.org/bugs/show_bug.cgi?id=152588 bug 152588].
| + | |
| − | | + | |
| − | For example, for the junit version 4.1.0.01, the manifest.mf file specifies
| + | |
| − | | + | |
| − | Bundle-Version: 4.1.0.01_qualifier
| + | |
| − | | + | |
| − | But, the feature.xml file specifies
| + | |
| − | | + | |
| − | <plugin
| + | |
| − | id="org.junit"
| + | |
| − | download-size="0"
| + | |
| − | install-size="0"
| + | |
| − | version="4.1.0.qualifier" />
| + | |
| − | | + | |
| − | And, the (multiversion) map file specifies
| + | |
| − | | + | |
| − | plugin@org.junit,4.1.0=v200701261101,:pserver:anonymous....
| + | |
| − | | + | |
| − | The resulting zip file is named as follows (zip, in this case, since it is not a jarred bundle).
| + | |
| − | | + | |
| − | org.junit_4.1.0.01_200704231307.zip
| + | |
| − | | + | |
| − | And, the resulting bundle version matches the file name, for example,
| + | |
| − |
| + | |
| − | Bundle-Version: 4.1.0.01_200704231307
| + | |
| − | | + | |
| − | Note, the final qualifier in this case does not "match" the cvs version tag, as the
| + | |
| − | usual case, but, is "translated" into current date/time to append to the
| + | |
| − | provided 4th segment prefix.
| + | |
| − | | + | |
| − | === Special Detailed Notes on the RC case ===
| + | |
| − | | + | |
| − | Sometimes bundles need to be added that aren't full releases, but 'release candidates.' These release candidate plug-ins should share the same branch as their full release cousins.
| + | |
| − | | + | |
| − | For example, let's say we have a plug-in ch.ethz.iks.slp 1.0.0 RC2, the manifest.mf file specifies
| + | |
| − | | + | |
| − | Bundle-Version: 1.0.0.RC2_qualifier
| + | |
| − | | + | |
| − | The branch the plug-in would be created in is v1_0_0 even though it's an RC2 release. Once 1.0.0 came out or say RC3, the branch would be updated with the info code. This essentially limits us to one "1.0.0" release at a time, but it's an acceptable workaround for the time being.
| + | |
| − | | + | |
| − | The feature.xml file specifies
| + | |
| − | | + | |
| − | <plugin
| + | |
| − | id="ch.ethz.iks.slp"
| + | |
| − | download-size="0"
| + | |
| − | install-size="0"
| + | |
| − | version="1.0.0.qualifier" />
| + | |
| − | | + | |
| − | And, the (multiversion) map file specifies
| + | |
| − | | + | |
| − | plugin@ch.ethz.iks.slp,1.0.0=v200701261101,:pserver:anonymous....
| + | |
| − | | + | |
| − | The resulting zip file is named as follows (zip, in this case, since it is not a jarred bundle).
| + | |
| − | | + | |
| − | ch.ethz.iks.slp_1.0.0.RC2_200704231307.zip
| + | |
| − | | + | |
| − | And, the resulting bundle version matches the file name, for example,
| + | |
| − |
| + | |
| − | Bundle-Version: 1.0.0.RC2_200704231307
| + | |
| − | | + | |
| − | Note: It's incredibly important that the final release is lexicographically greater than the release candidate so it can be updated properly. For example, ch.ethz.iks.slp_1.0.0.RC2_v200801291200 is > than ch.ethz.iks.slp.1.0.0_v200801291200 because "R" is considered greater than "v"
| + | |
| − | | + | |
| − | == Packaging licensing information ==
| + | |
| − | When packaging a third party library we have to ensure that the licensing information is present and correctly used.
| + | |
| − | # Create an '''about_files''' directory and add a copy of the licensing text.
| + | |
| − | # Create an '''about.html''' file at the root of the third party bundle based on the '''template''' [http://nowhere here]... ''(eventually)''.
| + | |
| − | # Open your project's '''build.properties''' and switch to the PDE Build tab.
| + | |
| − | # Select and check the '''about_files''' directory and '''about.html''' under both your '''Binary Build''' and '''Source Build''' and then save your changes.
| + | |
| − | | + | |
| − | == National Language Considerations ==
| + | |
| − | | + | |
| − | The following are some tips to help make sure any text in the bundle
| + | |
| − | is not "garbled" during network or storage transfers and it is capable of
| + | |
| − | being properly translated to languages other than English.
| + | |
| − | | + | |
| − | * As I think is true for all projects in an Eclipse repository, it is recommend you set the project's default encoding preference to ISO-8859-1. This project encoding applies to files that do not otherwise have any ability to specify their encoding (such as ".txt" or ".java" files). This is a good "single byte" encoding in general, and I think the CVS Repository Server assumes ISO-8859-1 as the default. Having it set as a project setting is good, so that, for example, if someone on windows checks it out and makes changes, and someone on Linux checks it out and makes changes, the default encoding for that project will be the same, no matter what the default encodings are on those different OS platforms.
| + | |
| − | | + | |
| − | * Be sure to "externalize" all the string in your manifest.mf files, and plugin.xml files, if you have any. There is usually at least two: the Provider (and, yes, even 'Eclipse.org' should be externalized) and the bundle's name.
| + | |
| − | | + | |
| − | == Remember to retain important aspect of original jar manifest ==
| + | |
| − | | + | |
| − | Part of the goal of creating Orbit bundles, is that when ever possible, the Orbit bundle can continue to be used as a jar, just as it would have been originally.
| + | |
| − | | + | |
| − | In some cases, this means there may be aspects in the original jar's manifest that should be carried over to the manifest in the bundle.
| + | |
| − | | + | |
| − | One example, if the original jar's manifest contains a ''Main-Class'' directive, then the bundle's manifest should contain the same ''Main-Class'' directives. One case of this is the Rhino bundle (org.mozilla.javascript). It originally contained
| + | |
| − | Main-Class: org.mozilla.javascript.tools.shell.Main
| + | |
| − | which prints the version and starts up an interpreter "shell". It's best to maintain that sort of functionality whenever possible.
| + | |
| − | | + | |
| − | == Adding your bundle to the Orbit Build ==
| + | |
| − | See [[Orbit_Builds#Orbit_Builds_for_Orbit_Committers | Orbit Builds for Orbit Committers]].
| + | |
| − | | + | |
| − | [[Category: Orbit]]
| + | |
