Difference between revisions of "Equinox/p2/Engine/Touchpoint Instructions"

From Eclipsepedia

< Equinox‎ | p2‎ | Engine
Jump to: navigation, search
 
(38 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{CommentBox|Under update for 3.5}}
+
The information from this page is now in the formal platform documentation:
=Introduction=
+
A p2 Installable Unit (IU) is installed using the facilities provided by a ''touchpoint''. The IU metadata consists of a reference to the touchpoint (Touchpoint Type) which also defines the version of the touchpoint (i.e an expectancy that it supports a certain set of operations),  and describes instructions to execute in various p2 engine phases. The instructions are named after the phases - the phases "install", "uninstall", "configure", "unconfigure" are of interest when authoring, but there are also some internal phases  such as "collect" and "checktrust" executed by the engine. Each instruction (e.g. "install") describes a sequence of actions to execute on the referenced touchpoint. Examples of actions are create and remove directories, change permissons, install and remove bundles. Currently, two touchpoints (native, and eclipse) have been implemented. The native touchpoint has approximately 5 different actions, and the eclipse touchpoint has approximately 20. Most of these actions take parameters. This wiki page describes these actions in detail.
+
  
The instructions are grouped and described in a Touchpoint Data Element. The touchpoint data element uses a Map where the key is the name of a p2 engine phase (such as "install"), and the
+
http://help.eclipse.org/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_actions_touchpoints.html
value is a string representation of a sequence of actions. Using multiple touchpoint data elements is useful as it allows separation between sets of actions for install/uninstall/configure/unconfigure which makes it easier to maintain the meta data.  
+
  
This wiki page describes the two touchpoints, the instructions they understand, and the format used to represent an action sequence.
+
This page has been deleted to avoid duplication.
 
+
=Actions=
+
 
+
==Native Touchpoint Actions==
+
The native touchpoint is used to install things "outside of eclipse".
+
 
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''instruction'''
+
| '''parameters'''
+
| '''description'''
+
|- valign="top"
+
| style="font-weight:bold;font-family:monospace"|cleanupzip
+
| <code>source, target</code>
+
| removes unzipped files and directories that where unzipped from ''source'' into ''target'' - i.e. an "undo operation" of an ''unzip'' instruction.
+
|- valign="top"
+
{{Command|unzip}}
+
{{Parameters|source, target}}
+
| unzips the ''source'' into the ''target'' directory. The ''source'' can be the special <code>@artifact</code> source path, which denotes the download cache location for the first artifact key in the IU. ''Comments in code indicates that the use of <code>@artifact</code> may be deprecated.''
+
|-valign="top"
+
{{Command|mkdir}}
+
{{Parameters|path}}
+
| Creates the directory specified by the parameter ''path''.
+
|-valign="top"
+
{{Command|rmdir}}
+
{{Parameters|path}}
+
| Removes the directory specified by the parameter ''path''. Action has no effect if the referenced directory contains files. Use the ''remove'' action for a forced recursive remove.
+
|- valign="top"
+
{{Command|link}}
+
{{Parameters|targetDir, linkTarget, linkName, force}}
+
| Performs the system action <code>ln -s</code> with the parameters ''linkTarget'' being the source-file, ''targetDir'' is the directory where the symbolic link will be created, and ''linkName'' is the name of the resulting link in the ''targetDir''. The ''force'' parameter is a boolean in string form (i.e. "true"/"false") and indicates if an existing link with the same name should be removed before the new link is created. {{CommentBox|the parameter names are quite confusing}}  {{CommentBox|This action executes the system command ''ln -s'', and is not available on platforms that does not have this (i.e. Windows)}}
+
|-valign="top"
+
{{Command|chmod}}
+
{{Parameters|targetDir, targetFile, permissions, options}}
+
| Changes permission on a file using the system chmod command. The ''targetDir'' parameter is either a path, or the special <code>@artifact</code> which is a reference to the directory where the first artifact included in the installable unit is located. The parameter ''targetFile'' is the name of a file, and ''permissions'' is written like for the ''chmod'' system command. The options parameter is new since [https://bugs.eclipse.org/bugs/show_bug.cgi?id=240728 3.5M6] and allows passing additional options like "-R" for recursive operation. If multiple parameters are needed separate them with a space (like on the command line). {{CommentBox|This action executes the system command ''chmod'', and is not available on platforms that does not have this (i.e. Windows)}}
+
|- valign="top"
+
{{Command|remove}}
+
{{Parameters|path}}
+
| Removes a file, or a directory (and all files under this directory) as referenced by the parameter ''path''. <br/>(Since 3.5 M7)
+
|- valign="top"
+
{{Command|copy}}
+
{{Parameters|source, target, overwrite}}
+
| Copies a file or a directory (and all of its content) denoted by ''source'' path to the ''target'' path.
+
The boolean flag ''overwrite'' should be set to ''true'' if the copy action should overwrite existing files. If overwrite is
+
''false'' the operation will fail with an IO error in the files already exists.
+
<br/>(Since 3.5 M7)
+
|- valign="top"
+
{{Command|cleanupcopy}}
+
{{Parameters|source, target}}
+
| Cleans up what was installed earlier with a ''copy'' from ''source'' to ''target''. I.e. this is an "undo" of a ''copy'' operation.
+
<br/>(Since 3.5 M7)
+
|- valign="top"
+
{{Command|collect|style=color:#626262}}
+
{{Parameters|-}}
+
|collects all associated artifacts for an IU and places them in a local touchpoint addressable cache. This action is not meant to be called directly and is used as part of the main Collect and Sizing phases.
+
|}
+
 
+
==Eclipse Touchpoint Actions==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''instruction'''
+
| '''parameters'''
+
| '''description'''
+
|- valign="top"
+
{{Command|collect|style=color:#626262}}
+
{{Parameters|-}}
+
|collects all associated artifacts for an IU and places them in a local touchpoint addressable cache. This action is not meant to be called directly and is used as part of the main Collect and Sizing phases.
+
|-valign="top"
+
{{Command|installBundle}}
+
{{Parameters|bundle}}
+
| Installs a bundle artifact specified by the parameter ''bundle''
+
|-valign="top"
+
{{Command|uninstallBundle}}
+
{{Parameters|bundle}}
+
| Uninstalls a bundle artifact with a bundle-id specified by the paramter ''bundle''
+
|-valign="top"
+
{{Command|addSourceBundle}}
+
{{Parameters|bundle}}
+
| Installs a source bundle artifact with the bundle-id specified by the parameter ''bundle''
+
|-valign="top"
+
{{Command|removeSourceBundle}}
+
{{Parameters|bundle}}
+
| Removes/uninstalls the source bundle artifact with the bundle-id specified by the parameter ''bundle''
+
|-valign="top"
+
{{Command|installFeature}}
+
{{Parameters|feature, featureId, version}}
+
| Installs the feature referenced by the parameter ''feature'' (matched against artifacts in the iu). The feature is installed with the id specified by the parameter ''featureId'', or if this parameter has the value <code>default</code>, with the id specified in the artifact referenced by ''feature''. The features is installed with the version specified in ''version'', or with the version specified in the artifact referenced by the ''feature'' parameter if the ''version'' parameter has the value <code>default</code>
+
|-valign="top"
+
{{Command|uninstallFeature}}
+
{{Parameters|feature, featureId, version}}
+
| Uninstalls a feature. Parameters have the same meaning as for the command <code>installFeature</code>
+
|-valign="top"
+
{{Command|setLauncherName}}
+
{{Parameters|name}}
+
| Sets the name of the launcher to <code>name</code>. The launcher name is used to configure launcher name specific ini files.
+
|-valign="top"
+
{{Command|addProgramArg}}
+
{{Parameters|programArg}}
+
| Adds the string specified in the parameter ''programArg'' as an argument to the program. If the parameters is the special value <code>@artifact</code>, the location of the artifact referenced by the first artifact key in the IU is used as the parameter value.
+
|-valign="top"
+
{{Command|removeProgramArg}}
+
{{Parameters|programArg}}
+
| Removes the program argument specified in the string ''programArg'' - if the parameters is the special value <code>@artifact</code>, the location of the artifact referenced by the first artifact key in the IU is used as the parameter value.
+
|-valign="top"
+
{{Command|setStartLevel}}
+
{{Parameters|startLevel}}
+
| Sets the start level to the integer value specified in the parameter ''startValue''
+
|-valign="top"
+
{{Command|markStarted}}
+
{{Parameters|started}}
+
| Marks the bundle referenced by the first artifact key in the IU as started / not started, as controlled by the boolean parameter ''started'' (in string form i.e. "true"/"false").
+
|-valign="top"
+
{{Command|setFrameworkDependentProperty}}
+
{{Parameters|propName, propValue}}
+
| Sets the framework dependant property named ''propName'' to the value specified in ''propValue''. Framework dependent properties are properties specific to the Equinox implementation of the OSGi framework.
+
|-valign="top"
+
{{Command|setFrameworkIndependentProperty}}
+
{{Parameters|propName, propValue}}
+
| Sets the framework independant property named ''propName'' to the value specified in ''propValue''. Framework independent properties do not specifically target Eclipse and are generally applicable to other OSGi frameworks.
+
|-valign="top"
+
{{Command|setProgramProperty}}
+
{{Parameters|propName, propValue}}
+
| Sets the program property named ''propName'' to the value specified in ''propValue''. Program properties are used by the executable program to among other things locate the jars needed to start Eclipse.
+
|-valign="top"
+
{{Command|addJVMArg}}
+
{{Parameters|jvmArg}}
+
| Adds the string specified in the parameter ''jvmArg'' to the arguments passed to the JVM.
+
|-valign="top"
+
{{Command|removeJVMArg}}
+
{{Parameters|jvmArg}}
+
| Removes the string specified in the parameter ''jvmArg'' from the arguments passed to the JVM.
+
|-valign="top"
+
{{Command|checkTrust|style=color:#626262}}
+
{{Parameters|-}}
+
|collects the set of bundle files on which the signature trust check should be performed. The checkTrust action is not meant to be user callable and is done as part of the CheckTrust phase.
+
|-valign="top"
+
{{Command|addRepository}}
+
{{Parameters|location, type, enabled}}
+
| Adds the repository at ''location'' of type ''type'' to the list of known repositories. The repository will then be available when installing or updating the profile in the future. The ''enabled'' parameter takes a boolean value ("true" or "false") indicating whether the add repository should be enabled. The value of the ''location'' parameter must be a well-formed URI. The ''type'' parameter value must be the value of one of the IRepository.TYPE_* constants, Specifically, type "0" indicates a metadata repository, and type "1" indicates an artifact repository.
+
|-valign="top"
+
{{Command|removeRepository}}
+
{{Parameters|location, type}}
+
| Removes the repository at ''location'' of type ''type'' from the list of known
+
repositories. The value of the ''location'' parameter must be a well-formed URI. The ''type'' parameter value must be the value of one of the IRepository.TYPE_* constants, Specifically, type "0" indicates a metadata repository, and type "1" indicates an artifact repository.
+
|}
+
 
+
=Action Format=
+
The Touchpoint Data Element has a Map that describes the actions to execute in the various p2 engine phases (e.g. "install", "uninstall", "configure", "unconfigure", "collect" and "checktrust"). The key of the Map entry is the name of a phase (i.e. when the actions should be executed), and the value is a ''statement-sequence'':
+
  statement-sequence :
+
      | statement ';'
+
      | statement-sequence statement
+
      ;
+
 
+
Where a statement is of the  format:
+
  statement :
+
      | actionName '(' parameters ')'
+
      ;
+
 
+
  parameters :
+
      | // empty
+
      | parameter
+
      | parameters ',' parameter
+
      ;
+
 
+
    parameter :
+
      | paramName ':' paramValue
+
      ;
+
+
  actionName, paramName, paramValue :
+
      | String
+
      ;
+
 
+
In the p2 engine, the Phase will lookup the "actionName" using it's own phase specific actions (e.g. "collect") and also those made available by the associated touchpoint (e.g. "mkdir" in the native touchpoint, and "installBundle" in the Eclipse touchpoint) .
+
 
+
As an example - an "install" instruction for a bundle might consist of the following statement:
+
 
+
  installBundle(bundle:${artifact});
+
 
+
* ''installBundle'' is the action name
+
* ''bundle'' is the parameter name
+
* ''${artifact}'' is the parameter value. The value ${artifact} signifies the use of a pre-defined variable named "artifact".
+
 
+
=Built-in Action Variables=
+
What follows is a catalog of the variables made available by the phases and touchpoints. Many of these are mostly useful to the implementor of new actions and touchpoint types.
+
 
+
==Variables Available in all phases==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|#nnnn}}
+
|the unicode value of a character.
+
''[[Note:]] This is especially important for the six characters that require escaping.''
+
# $ = ${#36}
+
# , = ${#44}
+
# : = ${#58}
+
# ; = ${#59}
+
# { = ${#123}
+
# } = ${#125}
+
|- valign="top"
+
{{Command|profile }}
+
|the profile being modified.
+
|- valign="top"
+
{{Command|phaseId }}
+
|the name of the phase e.g. collect, install, etc.
+
|- valign="top"
+
{{Command|operand }}
+
|the actions operand (e.g. IU pair)
+
|- valign="top"
+
{{Command|touchpoint }}
+
|the touchpoint associated with the IUs in the operand
+
|}
+
 
+
==Variables Available in all installable unit phases==
+
''e.g. collect, unconfigure, uninstall, install, configure, ...''
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|installFolder }}
+
|the root folder for this profile.
+
|}
+
 
+
==Collect Phase Variables==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|artifactRequests }}
+
|A list that a touchpoints "collect" action will use to add mirroring requests to.
+
|}
+
 
+
==Unconfigure Phase Variables==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|iu }}
+
|The IU being unconfigured. This is set from the first IU of the operand pair.
+
|- valign="top"
+
{{Command|artifact}}
+
|The artifact id of the first artifact listed in the IU.
+
|}
+
 
+
==Uninstall Phase Variables==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|iu }}
+
|The IU being uninstalled. This is set from the first IU of the operand pair.
+
|- valign="top"
+
{{Command|artifact}}
+
|The artifact id of the first artifact listed in the IU.
+
|}
+
 
+
==Install Phase Variables==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|iu }}
+
|The IU being installed. This is set from the second IU of the operand pair.
+
|- valign="top"
+
{{Command|artifact}}
+
|The artifact id of the first artifact listed in the IU.
+
|}
+
 
+
==Configure Phase Variables==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|iu }}
+
|The IU being configured. This is set from the second IU of the operand pair.
+
|- valign="top"
+
{{Command|artifact}}
+
|The artifact id of the first artifact listed in the IU.
+
|}
+
 
+
==Eclipse Touchpoint Variables==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|manipulator }}
+
|an instance of the Manipulator class used to alter the configuration of an Eclipse install.
+
|}
+
 
+
==Native Touchpoint Variables==
+
{| {{Greytable}}
+
|-valign="top" style="background-color:#eeeeee;color:#444444;"
+
| '''variable'''
+
| '''description'''
+
|- valign="top"
+
{{Command|backup }}
+
|the BackupStore used to save transaction state during native file operations.
+
|}
+
 
+
= Authoring touchpoint data =
+
== Touchpoint advice file format ==
+
Touchpoint instructions can be added to an installable unit at development time by writing a touchpoint advice file (p2.inf). The format of this file is key=value pairs as follow:
+
 
+
  instructions.<phase> = <raw actions>
+
 
+
Where <phase> is one of the p2 phases (collect, configure, install, uninstall, unconfigure, etc). The <raw actions> will be appended to the end of any instructions already being generated.
+
 
+
As a concrete example chmod/ln would look something like
+
 
+
  instructions.install = \
+
    ln(targetDir:@artifact,linkTarget:foo/lib.1.so,linkName:lib.so);\
+
    chmod(targetDir:@artifact,targetFile:lib/lib.so,permissions:755);
+
 
+
== Where the touchpoint advice file can be used ==
+
In Eclipse 3.4, touchpoint advice files were only supported in bundles. An advice file placed in the bundle at META-INF/p2.inf would be processed at PDE build time to add the instructions to the installable unit corresponding to the bundle.  In Eclipse 3.5, touchpoint advice files can be placed:
+
* In bundles (META-INF/p2.inf): The instructions are added to the installable unit for the bundle
+
* In features (a p2.inf file co-located with the feature.xml): The instructions are added to the installable unit for the feature group
+
* In products (a p2.inf file co-located with the .product file): The instructions are added to the root installable unit for that product.
+
 
+
The p2.inf format in 3.5 has been enhanced to allow greater control of the metadata of an IU. This section needs [https://bugs.eclipse.org/bugs/show_bug.cgi?id=266481 updating] but for now see:
+
* https://bugs.eclipse.org/bugs/show_bug.cgi?id=265217
+
* https://bugs.eclipse.org/bugs/show_bug.cgi?id=268541
+
* https://bugs.eclipse.org/bugs/show_bug.cgi?id=271342
+
 
+
=Backup=
+
Since 3.5 M7.<br/>
+
The Native Touchpoint stores a temporary backup of files that are deleted or overwritten during the installation process. If an installation succeeds the backup is simply removed. If however the installation fails, the files in backup are restored to their original location. If the restore works as expected, the backup copy is also removed. Two "disaster" cases remains:
+
* It was not possible to restore files (probably because of faulty hardware, running of out disk, or manual tampering with files during the installation).
+
* The system crashed during the install
+
 
+
The backup is placed in a directory under the directory referenced by the system property "java.io.tmpdir".
+
The backup directory has a name with the prefix ".p2bu" which is followed by a unique key per running backup instance.
+
Under the ".p2bu..." directory files are stored in a hierarchy that reflects their original location.
+
 
+
In both of the disaster cases, the backup store under java.io.tempdir will contain copies of all files that were not automatically restored. If a restore is wanted, this can be performed manually by copying the content back to their original position (which is evident from the structure under ".p2bu"). This can be made with tools like zip (simply zip everything relative to .p2bu, and the then unzip it from the real file system root).
+
 
+
In case something goes wrong during restore of a backup, the event is logged with details of what needs to be manually restored. (In case or a system crash, you are on your own though....)
+
 
+
[[Category:Equinox p2|Touchpoint Instructions]]
+

Latest revision as of 12:18, 14 December 2012

The information from this page is now in the formal platform documentation:

http://help.eclipse.org/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/p2_actions_touchpoints.html

This page has been deleted to avoid duplication.