Package: oscfs
OSC File SystemIntroductionoscfsis a FUSE based user space file system that allows to access
open build service (OBS) instances. It is based on theosc(openSUSE
Commander) Python package for interfacing with OBS. At the moment it
provides read-only access for inspecting packages and their metadata.Dependenciesoscfsitself is implemented in Python and uses thefusepymodule to
implement the file system portion. There is another Python Fuse package
calledpython-fusewhichis not compatiblewithoscfs.For accessing OBS instances the Pythonoscmodule is required. Theoscmodule by now is working with Python3, thereforeoscfsis no
longer supporting Python2 since version 0.8.0.FeaturesRepresentation of all OBS projects and packages in a hierarchical
file system.Access to individual package files including old revisions.Access to project and package metadata via pseudo files.Access to package buildlogs and artifacts.Configurable runtime caching of cached data.Usageoscfsships a main script calledoscfs. It supports a couple of
command line parameters to influence its behaviour. It should only be
called by a regular user and never by therootuser.For mounting the file system simply provide themountpointargument to
theoscfsmain script. By default the openSUSE build service is
accessed. For authentication at the OBS instance, the configuration file
in the home directory in~/.config/osc/oscrc(or~/.oscrcon
older installations) needs to be setup. This file is part of theoscPython module for which you can find more documentation in theopenSUSE
wiki.To access a different OBS instance, provide the URL via the--apiurlparameter. For example to mount the SUSE internal build service (IBS)
under use a command line like this:$oscfs--apiurlhttps://api.suse.de~/ibsBy defaultoscfsdetaches and runs in the background as a daemon.
For testing purposes it can be run in the foreground by passing the-fparameter.Certain special OBS projects are excluded by default like the users’home:projects, maintenance incident projects or PTF (Program
Temporary Fix) projects. This is the case, because a lot of these
projects can exist in an OBS instance which would clutter the file
system contents.If you want to include these types of projects you can pass the
according command line parameter like--homes,--maintenanceor--ptfrespectively. Your user account’s own home projects will
always be included in the file system independently of the--homesswitch.Content that has been fetched from the OBS instance will be cached
locally for a certain time to improve response times. The time before
content will be refreshed can be tuned via the--cache-timeparameter.File System StructureOn the first level of the file system, a directory for each OBS project
is found. When accessing the openSUSE OBS instance you can find theopenSUSE:Factorydirectory, for example. On the second level the
packages within a project are found. WithinopenSUSE:Factoryall
packages that make up the openSUSE Tumbleweed rolling release codebase
are found. For example you can find the package bash withinopenSUSE:Factory/bash.Within each package directory you can find a list of flat files that
make up the package’s data like RPM spec file, patches, source tarballs
and so on. You can read the file contents like every other file with
your editor or tools likecatandless. There are no regular
subdirectories found in a package.Each project and package directory contains a hidden.oscfsdirectory which contains metadata and pseudo files provided byoscfs. These files are not actually existing in OBS.The following is a list of pseudo files provided in each project’s.oscfsdirectory:bugowners: contains a list of the usernames of the bugowners of
the project, one per line. If the name starts with an ‘@’ then the
name refers to a group of users.maintainers: just likebugownersbut contains a list of the
project’s maintainers.debuginfo: returns a boolean “0” or “1”, indicating whether
debuginfo generation is enabled.locked: returns a boolean “0” or “1”, indicating whether the
project is in the locked state.meta: returns the complete XML metadata for the project as
provided by the OBS instance.refresh: this is a control file. When you write the value of “1”
into the file then the cache for the project will be flushed. This
can be used to force regeneration of cached content.repositories: this file returns a list of all the repositories
defined for the project. Each new repository starts with a line# <name>. Following are a number of lines providing additional
information about the repository likearchs:<...>, defining the
architectures used in the repository.The following is a list of pseudo files provided in each package’s.oscfsdirectory:bugowners: the same as for projects above.maintainers: the same as for projects above.description: contains the human readable description of the
package.log: contains the commit changelog of the package.meta: returns the complete XML metadata for the package as
provided by the OBS instance.num_revisions: returns an integer denoting the number of commit
revisions that are available for the package.commits: a directory that contains one file for each commit
available for the package. Each file is named after the commit
revision number. Each file returns a description of the commit user,
date and description.requests: a directory that contains one file for each OBS request
that exists for the package. Each file is named in the format<num>:<state>, where<num>is the submit request ID and<state>is the current state of the request. Upon reading each
file returns the description and history of the submit request it
represents.revisions: a directory that contains a subdirectory for each
commit available for the package. Each directory is named after the
commit revision number. Each directory contains the state of the
package’s files as of that revision.buildresults: A file that contains the current package build
results for each repository/architecture combination.buildlogs: a directory below which a hierarchy of
repository/architecture files can be found. The architecture files
are regular files that return the build log of the package for the
repository/architecture combination it represents.binaries: a directory below which a hierarchy of
repository/architecture directories can be found. Within the
architecture directory the binary artifacts can be found that have
been produced in the package for the repository/architecture
combination it represents.incident: a symlink only present in package updates that
originate from a maintenance incident. In this case this symlink
points to the maintenance project where the package was built. For
this to work the file system needs to be mounted with the--maintenanceparameter.Usage HintsHow the Runtime Caching WorksEach operation performed on the file system in some way needs to talk to
the remote OBS instance. This is a slow process and needs to be
minimized. Theoscfsperforms lazy evaluation of directory contents.
This means that only when you access a certain path for the first time
will the actual contents be determined by communicating with the OBS
instance. This will take a noticeable amount of time. The second time
you will access the same path a locally cached version of the file or
directory will be served. This will take considerably less time.Caching also means that the state of files shown in the file system may
not correspond to the state on the remote server any more. Thereforeoscfsrefetches the contents of files and directories after the
cache has reached a certain age as is determined by the--cache-timeparameter. This only happens when a cached path is accessed after the
configured cache time has passed since the last retrieval of data from
the remote server. You can also explicitly invalidate the caching for a
complete package by writing to therefreshcontrol file documented
above.Whenoscfsis restarted then any previously cached contents are
lost. This means that the cache is not written to the local disk in any
form. Fetching a lot amount of data from the remote server should be
avoided (e.g. don’t callfindfor the complete file system). This
would be a kind of denial of service attack on the remote server.In a future version ofoscfsevaluation of remote server
modification times could be used to transparently update cached data
when necessary.Sorting of Directory ContentsListing directories withlscan feel a bit on the slow side, even if
data is cached byoscfs. This results fromlssorting the
directory contents by name. Since e.g.openSUSE:Factorycontains
more than 10.000 entries this can take about a second to complete. When
listing without sorting i.e. by runningls-fthen the time required
is considerably lower. Similar considerations need to be made when
accessing the file system by other means like from programming languages
that could sort directory contents by default.Metadata of Pseudo FilesThe pseudo files contained in the.oscfsdirectory of a package
start out with a size of zero bytes, although they may actually contain
data. The reason for this is that for determining the size of the
content, the content would need to be accessed right away. This would
slow down e.g. recursive searching for file names considerably.
Therefore some metadata like the size of pseudo files is only calculated
after it is accessed the first time. Since some of the pseudo files may
return dynamic data the displayed file size is also subject to change at
any time i.e. it only reflects a snapshot of the data as it was last
seen byoscfs.Usage ExamplesFinding PackagesYou can find packages by using tools likefindor shell wildcards
expansion. To find all Fuse related packages you do this for example:$cdopenSUSE:Factory$ls-d*fuse*enblend-enfusefusefuse-exfatfuseisofusepodfusesmbifuseldapfuselibconfuse0python-defusedxmlpython-fusepython-fusepyunionfs-fuseMatching Lines from RPM SpecsYou can query for packages containing certain RPM spec statements. For
example to find packages that require some Perl package by using grep
like this:$cdopenSUSE:Factory$grep-H"^Requires:.*perl"*/*.specNote that this is going to take a long time, because each package needs
to be queried on OBS.Comparing Two Package RevisionsYou can check two package revisions for differences by taking this
approach:$cdopenSUSE:Factory/bash/.oscfs/revisions$diff-r12<diffoutput...>