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

(cherry picked from commit 0b01f24)
  • Loading branch information
vogella authored and laeubi committed Nov 22, 2023
1 parent d45b6a3 commit a92daad
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 a92daad

Please sign in to comment.