Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Version Selector (Buckminster)
< To: Buckminster Project
Definition
A Version Selector is reference to a version of a component's state as found in a particular type of repository. It typically refers to a branch/tag combination but can also include changenumber and timestamp.
Description
Contrast the Version Selector with a plain version is a version string like "4.5.0" (as described in Which Version of Version where a particular logical version is requested without consideration of how a version is represented in the repository where the component will be fetched. This is important as a component could be materialized from different repositories depending on what is requested (binary prebuilt, with source, with possibility to modify/mutate, etc.) and the component could be materialized from an archive of zip files, or from a CM system.
Version Selector format
A version selector is qualified in one of four ways:
| Selector type | Notation | Comment |
|---|---|---|
| Latest | <branch>/LATEST | Denotes the latest revision on the branch. |
| Tag | <branch>/<tag> | Denotes a specific tag on the branch. |
| Change number | <branch>#<number> | Denotes a specific change number on the branch. |
| Timestamp | <branch>@yyyy-MM-dd[THH:mm:ss] | Denotes a specific point in time (UTC) on the branch. Note that the delimiters are all optional except for the 'T' e.g. "<branch>@20030102T111213" is a valid timestamp. |
A plain version string may not contain the characters '/', '#', or '@' as the precense of these indicates that it is a Version Selector and not a plain version, as in a version string like "4.5.0". The version string is further restricted to not include the version designator delimiters '[' ']' '(' ')' or ','.
Fixed Selector
It is often necessary to have a "fixed selector", i.e. a branch selector that, when applied, is guaranteed to yield the same result. A tag, a change-number, or a timestamp applied on a branch are considered 'fixed'. The tag might be moved though, so it might be beneficial to translate it into a change-number or timestamp if possible. We don't do this at present (we trust that tags are stable). Buckminster will always augment the request with a fixed selector during resolve unless it is qualified with a tag, a change-number, or a timestamp.
How this is done is repository specific, so check the documentation for the Component Reader for the respository you are using. For instance, in case of P4 or SVN, it will be a change-number. In case of CVS, it's a timestamp that reflects the last change on the given branch.