Sys::OsRelease::Lite - read operating system details from standard /etc/os-release file

# VERSION

version 0.4.6+lite

# SYNOPSIS

non-object-oriented (Perl 5.22 and later):

    use Sys::OsRelease;

    Sys::OsRelease->init();
    my $id = Sys::OsRelease->id();
    my $id_like = Sys::OsRelease->id_like();

object-oriented (Perl 5.22 and later):

    use Sys::OsRelease;

    my $osrelease = Sys::OsRelease->instance();
    my $id = $osrelease->id();
    my $id_like = $osrelease->id_like();

non-object-oriented (Perl up to 5.20):

    use Sys::OsRelease::Lite;

    Sys::OsRelease::Lite->init();
    my $id = Sys::OsRelease::Lite->id();
    my $id_like = Sys::OsRelease::Lite->id_like();

object-oriented (Perl up to 5.20):

    use Sys::OsRelease::Lite;

    my $osrelease = Sys::OsRelease::Lite->instance();
    my $id = $osrelease->id();
    my $id_like = $osrelease->id_like();

# DESCRIPTION

Sys::OsRelease is a helper library to read the /etc/os-release file, as defined by FreeDesktop.Org.
The os-release file is used to define an operating system environment.
It has been in widespread use among Linux distributions since 2017 and BSD variants since 2020.
It was started on Linux systems which use the systemd software, but then spread to other Linux, BSD and
Unix-based systems.
Its purpose is to identify the system to any software which needs to know.
It differentiates between Unix-based operating systems and even between Linux distributions.

Sys::OsRelease is implemented with a singleton model, meaning there is only one instance of the class.
Instead of instantiating an object with new(), the instance() class method returns the one and only instance.
The first time it's called, it instantiates it.
On following calls, it returns a reference to the singleton instance.

This module maintains minimal prerequisites, and only those which are usually included with Perl.
(Suggestions of new features and code will have to follow this rule.)
That is intended to be acceptable for establishing system or container environments which contain Perl programs.
It can also be used for installing or configuring software that needs to know about the system environment.

## The os-release Standard

FreeDesktop.Org's os-release standard is at [https://www.freedesktop.org/software/systemd/man/os-release.html](https://www.freedesktop.org/software/systemd/man/os-release.html).

Current attributes recognized by Sys::OsRelease are:
    NAME ID ID\_LIKE PRETTY\_NAME CPE\_NAME VARIANT VARIANT\_ID VERSION VERSION\_ID VERSION\_CODENAME
    BUILD\_ID IMAGE\_ID IMAGE\_VERSION RELEASE\_TYPE HOME\_URL DOCUMENTATION\_URL SUPPORT\_URL BUG\_REPORT\_URL
    PRIVACY\_POLICY\_URL SUPPORT\_END LOGO ANSI\_COLOR ANSI\_COLOR\_REVERSE VENDOR\_NAME VENDOR\_URL EXPERIMENT
    EXPERIMENT\_URL DEFAULT\_HOSTNAME ARCHITECTURE SYSEXT\_LEVEL CONFEXT\_LEVEL SYSEXT\_SCOPE CONFEXT\_SCOPE
    PORTABLE\_PREFIXES PORTABLE\_SCOPE

If other attributes are found in the os-release file, they will be accepted.
Folded to lower case, the attribute names are used as keys in an internal hash structure.

## Sys::OsRelease or Sys::OsRelease::Lite?

Due to restrictions of the Dist::Zilla build environment and its dependencies,
[Sys::OsRelease](https://metacpan.org/pod/Sys%3A%3AOsRelease) 0.4.0 had to follow an increase in the minimum Perl version from 5.10 to 5.22.
For systems with Perl older than 5.22, see below about [Sys::OsRelease::Lite](https://metacpan.org/pod/Sys%3A%3AOsRelease%3A%3ALite)
which repackages Sys::OsRelease without the Dist::Zilla version limitation
in order to retain support for legacy Perl installations.

Sys::OsRelease::Lite is the same module in all but name. A release script filters the source code of Sys::OsRelease to change its name. Then Sys::OsRelease::Lite is built with ExtUtils::MakeMaker to maintain compatibility back to Perl 5.10. The two are released in parallel with the same version number.

# METHODS

## Class methods

_Sys::OsRelease_ uses a singleton model. So there is only one instance.
Class methods manage the singleton instance, or import those methods to another cooperating class' namespace.

Class methods must be called using the class name, like `Sys::OsRelease-`instance()> .

- init(\[key => value, ...\])

    initializes the singleton instance without returning a value.
    Parameters are passed to the instance() method.
    This method is for cases where method calls will be via the class name, and the program
    doesn't need a reference to the instance.

    Under normal circumstances no parameters are needed. See instance() for possible parameters.

- new(\[key => value, ...\])

    initializes the singleton instance and returns a reference to it.
    Parameters are passed to the instance() method.
    This is equivalent to using the instance() method, made available if new() sounds more comfortable.

    Under normal circumstances no parameters are needed. See instance() for possible parameters.

- instance(\[key => value, ...\])

    initializes the singleton instance and returns a reference to it.

    Under normal circumstances no parameters are needed. Possible optional parameters are as follows:

    - common\_id

        supplies an arrayref to use as a list of additional common strings which should be recognized by the platform()
        method, if they occur in the ID\_LIKE attribute in the os-release file. By default, "debian" and "fedora" are
        regonized by platform() as common names and it will return them instead of the system's ID attribute.

    - search\_path

        supplies an arrayref of strings with directories to use as the search path for the os-release file.

    - file\_name

        supplies a string with the basename of the file to look for the os-release file.
        Obviously the default file name is "os-release".
        Under normal circumstances there is no need to set this.
        Currently this is only used for testing, where suffixes are added for copies of various different systems'
        os-release files, to indicate which system they came from.

- defined\_instance()

    returns true if the singleton instance is defined, false if it is not yet defined or has been cleared.

- clear\_instance()

    removes the singleton instance of the class if it was defined.
    Under normal circumstances it is not necessary to call this since the class destructor will call it automatically.
    It is currently only used for testing, where it is necessary to clear the instance before loading a new one with
    different parameters.

    Since this class is based on the singleton model, there is only one instance.
    The instance(), new() and init() methods will only initialize the instance if it is not already initialized.

- import\_singleton()

    The singleton-management methods _init_, _new_, _instance_, _defined\_instance_ and _clear\_instance_
    can be imported by another class by using the import\_singleton() method.
    That was done for [Sys::OsPackage](https://metacpan.org/pod/Sys%3A%3AOsPackage), to allow it to avoid copying those methods.
    But other classes with a similar need to minimize module dependencies which already
    use _Sys::OsRelease_ can do this too.
    This helps maintain minimal prerequisites among modules working to set up Perl on containers or new systems.

## Instance methods

Object methods, including auto-generated accessors described above, access the data from the singleton instance,
either read from an os-release file or empty to indicate no os-release file was found on the system.

Instance methods may be called either via the class name or a reference to the singleton instance.
Each of these functions can determine whether they were called as a class or object method, and obtain the
reference to the singleton instance if needed.

- platform()

    returns a string with the platform type. On systems with /etc/os-release (or os-release in any location
    from the standard) this is usually from the ID field.
    On systems that use the ID\_LIKE field, systems that claim to be like "debian" or "fedora" (always in lower case)
    will return those names for the platform.

    The list of recognized common platforms can be modified by passing a "common\_id" parameter to instance()/new()
    with an arrayref containing additional names to recognize as common. For example, "centos" is another possibility. 
    It was not included in the default because CentOS is discontinued. Both Rocky Linux and Alma Linux have
    ID\_LIKE fields of "rhel centos fedora", which will match "fedora" with the default setting, but could be configured
    via "common\_id" to recognize "centos" since it's listed first in ID\_LIKE.

    On systems where an os-release file doesn't exist or isn't found, the platform string will fall back to Perl's
    $Config{osname} setting for the system.

- osrelease\_path()

    returns the path where os-release was found.

    The default search path is /etc, /usr/lib and /run/host as defined by the standard.
    The search path can be replaced by providing a "search\_path" parameter to instance()/new() with an arrayref
    containing the directories to search. This feature is currently only used for testing purposes.

- found\_attrs()

    returns a list of attribute names found in the os-release file, empty if os-release doesn't exist on the platform.

- has\_attr(name)

    returns a boolean which is true if the attribute named by the string parameter exists in the os-release data for the
    current system.
    The attribute name is case insensitive.

- get(name)

    is a read-only accessor which returns the value of the os-release attribute named by the string parameter,
    or undef if it doesn't exist.

- has\_config(name)

    returns a boolean which is true if Sys::OsRelease contains a configuration setting named by the string parameter.

- config(name, \[value\])

    is a read/write accessor for the configuration setting named by the string parameter "name".
    If no value parameter is provided, it returns the value of the parameter, or undef if it doesn't exist.
    If a value parameter is provided, it assigns that to the configuration setting and returns the same value.

## Auto-generated Accessor Methods

For convenience, _Sys::OsRelease_ generates read-only accessor methods for each of the standard 
attribute names, converted to lower case. For example, from the list above they are _name()_, _id()_,
_id\_like()_, etc. The auto-generated methods do not require any parameters, and ignore any if provided.

Accessor methods are not generated for non-standard atttributes because it would be unreliable to try to
call methods named for transient data that may or may not exist on a given platform, and for the possibility
they could conflict with existing functions in the _Sys::OsRelease_ namespace.  Use the _found\_attrs()_,
_has\_attr()_ and _get()_ methods to detect and access non-standard attributes.

The current full list is at the os-release standard
[https://www.freedesktop.org/software/systemd/man/latest/os-release.html](https://www.freedesktop.org/software/systemd/man/latest/os-release.html)
which includes descriptions of each attribute.

- name()
- id()
- id\_like()
- pretty\_name()
- cpe\_name()
- variant()
- variant\_id()
- version()
- version\_id()
- version\_codename()
- build\_id()
- image\_id()
- image\_version()
- release\_type()
- home\_url()
- documentation\_url()
- support\_url()
- bug\_report\_url()
- privacy\_policy\_url()
- support\_end()
- logo()
- ansi\_color()
- ansi\_color\_reverse()
- vendor\_name()
- vendor\_url()
- experiment()
- experiment\_url()
- default\_hostname()
- architecture()
- sysext\_level()
- confext\_level()
- sysext\_scope()
- confext\_scope()
- portable\_prefixes()
- portable\_scope()

# SEE ALSO

FreeDesktop.Org's os-release standard: [https://www.freedesktop.org/software/systemd/man/os-release.html](https://www.freedesktop.org/software/systemd/man/os-release.html)

GitHub repository for Sys::OsRelease: [https://github.com/ikluft/Sys-OsRelease](https://github.com/ikluft/Sys-OsRelease)

Related modules:

- [Sys::OsPackage](https://metacpan.org/pod/Sys%3A%3AOsPackage)

    installs Perl modules, for example as dependencies of a script, via OS packages if available or otherwise via CPAN -
    uses Sys::OsRelease to determine OS type

- [System::Info](https://metacpan.org/pod/System%3A%3AInfo)

    system information collected from multiple sources including system architecture, hardware, OS release data

- [Sys::OsRelease::Lite](https://metacpan.org/pod/Sys%3A%3AOsRelease%3A%3ALite)

    This is a repackaging of Sys::OsRelease for older versions of Perl before 5.22.
    This was made because dependencies of Dist::Zilla forced it to bump its minimum Perl version to 5.22,
    which in turn forced Sys::OsRelease to follow.
    Sys::OsRelease::Lite provides Sys::OsRelease with the same source code,
    implemented with a filter on the source code changing the name of the module.
    The name change is just to prevent a namespace collision in CPAN, but is otherwise the same module.
    It is packaged with [ExtUtils::MakeMaker](https://metacpan.org/pod/ExtUtils%3A%3AMakeMaker) to maintain availability back to Perl 5.10.
    Compatibility was at the time still being maintained via CPAN testing back to 5.10.
    The use case was systems with RHEL 6 on Perl 5.10.1 and RHEL 7 on Perl 5.16,
    or similar variations on enterprise or other infrastructure installations.

# BUGS AND LIMITATIONS

Please report bugs via GitHub at [https://github.com/ikluft/Sys-OsRelease/issues](https://github.com/ikluft/Sys-OsRelease/issues)

Patches and enhancements may be submitted via a pull request at [https://github.com/ikluft/Sys-OsRelease/pulls](https://github.com/ikluft/Sys-OsRelease/pulls)

# LICENSE INFORMATION

This module is distributed in the hope that it will be useful, but it is provided “as is” and without any express or implied warranties. For details, see the full text of the license in the file LICENSE or at [https://www.perlfoundation.org/artistic-license-20.html](https://www.perlfoundation.org/artistic-license-20.html).

# AUTHOR

Ian Kluft &lt;https://github.com/ikluft>
