Skip to content

Commit

Permalink
Correct formating in the p2 source blocks of metadata docs page
Browse files Browse the repository at this point in the history
  • Loading branch information
vogella committed Oct 7, 2024
1 parent ec65256 commit b160eeb
Showing 1 changed file with 36 additions and 1 deletion.
37 changes: 36 additions & 1 deletion docs/Customizing_Metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,13 @@ For the 3.5 release the p2.inf file can be used to augment Installable Units: ca

Properties in this file often contain <#> index segments. These index segments serve to separate groups of similar properties from each other. The actual value of these indexes are not important, only that a given set of properties which all refer to the same logical item all use the same index. The following example is talking about two seperate properties, each uses a different index to distinguish it from the other.


```
properties.0.name = testName1
properties.0.value = testValue1
properties.1.name = testName2
properties.1.value = testValue2
```

Capability Advice:
------------------
Expand All @@ -54,6 +57,7 @@ There are three different type of capability advice:

Capability advice will "replace" an existing capability of the same type on the IU if the name/namespace match.

```
provides.<#>.namespace = <namespace>
provides.<#>.name = <name>
provides.<#>.version = <version> _(optional / default: 1.0.0)_
Expand All @@ -66,9 +70,11 @@ Capability advice will "replace" an existing capability of the same type on the
requires.<#>.optional = <true|false> _(optional / default: false)_
requires.<#>.multiple = <true|false> _(optional / default: false)_
requires.<#>.filter = <ldap filter> _(optional)_
```

Negative requirements can be published by setting min and max values on the requirement to 0. For example

```
requires.<#>.namespace = org.eclipse.equinox.p2.iu
requires.<#>.name = some.feature.feature.group
requires.<#>.min = 0
Expand All @@ -81,11 +87,13 @@ Negative requirements can be published by setting min and max values on the requ
metaRequirements.<#>.greedy = <true|false> _(optional / default: true)_
metaRequirements.<#>.optional = <true|false> _(optional / default: false)_
metaRequirements.<#>.multiple = <true|false> _(optional / default: false)_
```

Where <#> is an index for the property, <namespace>, and <name> are the associated named strings, <version> and <range> are version and version range strings respectively.

For example:

```
provides.0.namespace = testNamespace1
provides.0.name = testName1
provides.0.version = 1.2.3.$qualifier$
Expand Down Expand Up @@ -114,46 +122,61 @@ For example:
metaRequirements.1.name = testName2
metaRequirements.1.range = $version$
metaRequirements.1.greedy = false
```



Update descriptor advice:
-------------------------

The update descriptor advice allows to override the default update descriptor generated by p2. Typically this is useful if an IU has been renamed and automatic update detection is still desired.

```
update.id = <id of IU>
update.range = <range of the IU being updated>
update.matchExp = {a match expression identifying the IU being updated}. (When this is specified the values of id and range are ignored)
update.severity = <0|1>
```

To allow updating a renamed artifact, you must provide a matchExp that matches both the old and new artifact names. For example, when renaming \*old\* feature to \*new\*:

```
update.matchExp = providedCapabilities.exists(pc | \
pc.namespace == 'org.eclipse.equinox.p2.iu' && \
(pc.name == 'old.feature.group' || \
(pc.name == 'new.feature.group' && pc.version ~= range('\[0.0.0,$version$)'))))
```

These match expressions are written in the [p2 Query Language p2ql](/Equinox/p2/Query_Language_for_p2 "Equinox/p2/Query Language for p2").

Property Advice:
----------------

```
properties.<#>.name = <propertyName>
properties.<#>.value = <propertyValue>
```

Where <#> is an index for the property, <propertyName>, and <propertyValue> hold the name and value strings for the property.

For example:

```
properties.0.name = testName1
properties.0.value = testValue1
properties.1.name = testName2
properties.1.value = testValue2
```


Touchpoint Instruction Advice:
------------------------------

```
instructions.<phase> = <raw actions>
instructions.<phase>.import = <qualified action name> \[,<qualified action name>\]* _(optional)_
```


Where <phase> is a p2 phases (collect, configure, install, uninstall, unconfigure, etc).

Expand All @@ -164,12 +187,14 @@ Where <phase> is a p2 phases (collect, configure, install, uninstall, unconfigur

For example:

```
instructions.install = \
ln(targetDir:@artifact,linkTarget:foo/lib.1.so,linkName:lib.so);\
chmod(targetDir:${artifact.location},targetFile:lib/lib.so,permissions:755);
instructions.install.import= \
org.eclipse.equinox.p2.touchpoint.natives.ln,\
org.eclipse.equinox.p2.touchpoint.natives.chmod
```

### Variable Substitutions

Expand All @@ -188,11 +213,14 @@ Additional Installable Unit Advice:

In addition to customizing attributes of the containing IU one can also author addtional installable units that work with the container IU. Typically this mechanism is used to author an IUFragment that customizes the containing IU or one of it's dependencies.

```
iu.<#>.id= <identifier>
iu.<#>.version= <version> _(optional)_
```

Where <#> is an index for the Installable Unit, so multiple Installable Units can be declared. A fairly full range of IU customizations are supported including:

```
id
version
singleton
Expand All @@ -208,9 +236,11 @@ Where <#> is an index for the Installable Unit, so multiple Installable Units ca
metaRequirements
hostRequirements
instructions
```

To illustrate all the various settings for these customizations here's a more complete example of: (unit.0) a minimal IU and (unit.1) a full featured IU:

```
units.0.id = testid0
units.0.version = 1.2.3
Expand Down Expand Up @@ -276,6 +306,7 @@ To illustrate all the various settings for these customizations here's a more co
units.1.hostRequirements.0.greedy = true
units.1.hostRequirements.0.optional = true
units.1.hostRequirements.0.multiple = true
```

Category Generation Using p2.inf
================================
Expand All @@ -284,11 +315,14 @@ The p2 UI allows for hierarchical organization of Installable Units based on the

To support this we can tag a feature as a category as follows:

```
properties.1.name=org.eclipse.equinox.p2.type.category
properties.1.value=true
```

Another possibility is to use "additional IU advice" to create a specialized category IU like this:

```
units.1.id=my.product.category
units.1.version=1.0.0
units.1.provides.1.namespace=org.eclipse.equinox.p2.iu
Expand All @@ -302,6 +336,7 @@ Another possibility is to use "additional IU advice" to create a specialized cat
requires.1.name=my.product
requires.1.range=\[1.0.0,1.0.0\]
requires.1.greedy=true
```

Categorizing plug-ins
---------------------
Expand All @@ -316,5 +351,5 @@ Nested categories
* p2 parser and publisher for category.xml to support nested categories: [https://bugs.eclipse.org/bugs/show_bug.cgi?id=406902](https://bugs.eclipse.org/bugs/show_bug.cgi?id=406902)
* PDE category editor to support nested categories: [https://bugs.eclipse.org/bugs/show_bug.cgi?id=296392](https://bugs.eclipse.org/bugs/show_bug.cgi?id=296392)

**Current workaround** The following file containss a number of projects showing how to create nested categories [File:NestedCategories.zip](/File:NestedCategories.zip "File:NestedCategories.zip").
**Current workaround** The following file contains a number of projects showing how to create nested categories [File:NestedCategories.zip](/File:NestedCategories.zip "File:NestedCategories.zip").

0 comments on commit b160eeb

Please sign in to comment.