-
Notifications
You must be signed in to change notification settings - Fork 15
Analysis of tar_git
Jolla's OBS tar_git source service
Note that this README is not an exhaustive description or even a specification. It is merely a user contributed write-up providing some guidance how tar_git works. This write-up may have flaws or be fully erroneous at places; if you want to know something for sure, please read tar_git's interface definition and its shell script, which provides all its functionality.
Side note: This is not about the regular OBS (Open Build Service) services (plug-in modules) tar_scm or git_tar. The only publicly visible place where tar_git runs is the SailfishOS-OBS at build.sailfishos.org (= build.merproject.org), where it is the primary and mandatory service.
See tar_git's interface definition, its usage output for descriptions of the parameters and an exemplary _service file.
I went through its state as of 2020-12-14 to (at least) 2023-03-15 until I fully understood the parsing of tags:
- A valid tag for
tar_gitmay be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"), see first part of the functionget_tagver_from_tag: Both are cut out, a "v" is discarded, but a "vendor string" is prepended (without the slash) to the release field in the spec file (but see 6.). - A valid tag for
tar_gitmay contain at most a single dash ("-"). If the sub-string starting with the dash conforms to the extended regular expression (ERE)\-[[:alnum:]]+$, it is put into the release field (without the dash and directly appended to a "vendor string") and the part up to the dash into the version field bytar_git. Hence a valid tag can be used to fully rewrite the version and release fields in the spec file, before OBS builds this package (but see 6.), see second part of the functionget_tagver_from_tag. - The resulting, stripped tag must conform to the extended regular expression (ERE)
^[[:digit:]]+\.[[:alnum:].~+]*$(but is actually written much more complicated) and originate from the branch provided by thebranchparameter, otherwise it is discarded. - If there is no valid tag or if a commit ID (short-hash) was provided, or if a
branchparameter is set and either norevisionis set or in this Git branch commits exist newer than the tag referenced by therevisionparameter,tar_gitlooks for the "closest" tag in the functionset_vershawhich fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by thebranchparameter (i.e., it searches in all branches). Still, it uses the value of thebranchparameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a+, the branch name, a., a date-time string (YYYYMMDDhhmmss), the number of commits since the "closest" tag in the branch it resides enclosed in dots.<n>., agif newer commits exist in the branch referenced bybranchthan the tag referenced byrevision, and the short-hash of the latest commit, resulting in, e.g.,0.5.2+main.20230129011931.6.g584263awith0.5.2-3as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by thebranchparameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. - The result of this processing replaces the original
Version:string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. - Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a
1., the package revision at OBS and.1.jolla. This is not visible in the processed RPM spec file of a package, because it is done while building a package.
Once understood how tar_git's parsing of Git tags works, one can play with it: For 1.2.3+git1, 1.2.3~git1 and 1.2.3.git1 the whole string will be used as the processed<version> string and become part of the RPM file-name; for 1.2.3-git4, git4/1.2.3 and git/1.2.3-4 only the 1.2.3 and the release field will be initially set to git4 for the latter three examples (which is later substituted by 1.I.1).
As an "real life" example, when using sfos4.2/0.3.0-5 as a tag name for the harbour-storeman app, this results in, e.g., harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm as a final package name.
Counter-examples
Because older release tags for harbour-storeman always contained two dashes, they were discarded and the alternate code path found v0.2.12-master as the newest "valid" tag (although referring to the master branch instead one of the release branches the branch parameter was set to) and used by tar_git.
When the token parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the harbour-storeman app, sfos would be a suitable token. Or when marking release versions with the string release in Git tags (e.g., 1.2.3-release2), the string release is a suitable token to filter for.
tar_git always renames the source archive to <name>-<version>.<extension>, using the processed Git tag as <version>. While retaining the name and the extension, there is no way to achieve <name>-<version>-<release>.<extension> as its source archive, because the processing prevents any hyphens ("dashes": "-") to be retained in the processed <version> string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above.
Hence the %prep section of a spec file must contain %autosetup or %setup [-q] [-n %{name}-%{version}], but no other -n parameter can be used (which might as well be omitted)!
<ToDo>
- A slightly shortened version of this document was submitted as
tar_git's README.md.