Skip to content

Commit

Permalink
Migrating Category wiki page
Browse files Browse the repository at this point in the history
Moves an improved version of https://wiki.eclipse.org/Tycho/category.xml
to the Tycho documentation

See #2564
  • Loading branch information
vogella committed Nov 21, 2023
1 parent d76d71c commit 92bd0e7
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 0 deletions.
64 changes: 64 additions & 0 deletions src/site/markdown/Category.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Category

A category.xml file can be used to define which content is placed into a p2 repository.
It can also specify how to display the content in the p2 installation dialog.
For Tycho to use it, it must to be placed into the root of an project with the packaging type 'eclipse-repository'.

The 'category.xml' format was originally defined by the Eclipse PDE project.
There are extensions to the format only supported by p2 and Tycho.

The following listing is a simple category file listing only one feature and one plug-in.


```
<?xml version="1.0" encoding="UTF-8"?>
<site>
<feature id="com.example.feature">
<category name="com.example.category.update"/>
</feature>
<category-def name="com.example.category.update" label="Example update site"/>
</site>
```
The following is an example, demonstrating a complex category definition.

```
<?xml version="1.0" encoding="UTF-8"?>
<site>
<!-- Include features -->
<feature id="feature.id" version="1.4.100.v2009"/>
<!-- Since Tycho 1.1.0 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=407273#c18), features can declare platform-specific compatibility for multi-platform builds -->
<!-- Examples: https://github.com/mickaelistria/org.eclipse.simrel.build/blob/master/categories/category.xml#L581 -->
<feature id="linux.specific.feature.id" version="0.0.0" os="linux"/>
<!-- Directly include bundles, without a feature -->
<bundle id="bundle.id" version="1.3.1.v2023"/>
<!-- Directly include any iu -->
<iu id="unit.id"/>
<!-- Include all IUs matching an expression -->
<iu>
<query>
<expression type="match">
<![CDATA[
id == $0
]]>
</expression>
<param>another.unit.id</param>
</query>
</iu>
<!-- Categories -->
<feature id="feature.in.category">
<category name="category.id"/>
</feature>
<category-def name="category.id" label="Category Label">
<description>Details on the category</description>
</category-def>
<!-- example for a dynamic category -->
<category-def name="javax" label="Bundles starting with javax."/>
<iu>
<category name="javax"/>
<query><expression type="match">id ~= /javax.*/</expression></query>
</iu>
</site>
```
1 change: 1 addition & 0 deletions src/site/site.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
<item name="Packaging Types" href="PackagingTypes.html" />
<item name="Testing Bundles" href="TestingBundles.html" />
<item name="Tycho CI Friendly Versions" href="TychoCiFriendly.html" />
<item name="Creating update sites using category.xml" href="Category.html" />
<item name="Target Platform Configuration" href="target-platform-configuration/plugin-info.html" />
<item name="Compiler Plugin" href="tycho-compiler-plugin/plugin-info.html" />
<item name="Declarative Services Plugin" href="tycho-ds-plugin/plugin-info.html" />
Expand Down

0 comments on commit 92bd0e7

Please sign in to comment.