RPMGet
======

RPMGet uses an ini-style config file to manage an arbitrary set of
development dependencies or releases as RPM packages. Either install
these packages in RHEL development environment or create a local
package repo.

|ci| |wheels| |bandit| |release|

|pre| |cov| |pylint|

|tag| |license| |reuse| |python|

Things you can do now:

* validate configuration files and URLs
* download configured rpm files to a single directory or rpm tree
* dump a sample config file
* create an rpm repository from rpm tree (Not Implemented Yet)

As stated above, the intended use cases (in the `user experience sense`_)
are geared towards managing/using a set of RPMs in development workflows
intended for older-but-still-supported Enterprise Linux environments, eg,
RHEL9 or similar. That said, the initial packaging for RPMGet itself is
not quite compatible (yet) with el9 packaging tools when using the newer
pyproject macros.

.. _user experience sense: https://en.wikipedia.org/wiki/Use_case#Definition

Quick Start
~~~~~~~~~~~

* Install from GH release page, eg in a Tox file or venv
* Clone from GH and install in a venv

See the Tox_ section below *and* the ``tox.ini`` file for more details.

Command Interface
-----------------

The minimum usage requirement is an INI-style configuration file with URLs
pointing to RPM_ files. Use the ``--dump`` argument shown below for a small
example config. Note each of the rpm URLs in the example point to GitHub
release pages. The CLI uses the standard Python ``argparse`` module::

  $ tox -e dev
  $ source .venv/bin/activate
  $ rpmget -h
  usage: rpmget [-h] [--version] [-S] [-t] [-v] [-d] [-D] [-c FILE]

  Download manager for rpm files

  options:
    -h, --help            show this help message and exit
    --version             show program's version number and exit
    -S, --show            display user config (default: False)
    -t, --test            run sanity checks (default: False)
    -v, --validate        run schema validation on active config (default:
                          False)
    -d, --debug           display more processing info (default: False)
    -D, --dump-config     dump active configuration to stdout (default: False)
    -c, --configfile FILE
                          path to ini-style configuration file (default: None)

The example config uses extended interpolation using ${VAR} style notation
but the simplest example config requires only an option with a URL string.

A simple example might look something like this::

  [rpmget]
  top_dir = rpms
  layout = flat
  pkg_tool = yum

  [stuff]
  files =
      https://github.com/VCTLabs/el9-rpm-toolbox/releases/download/procman-0.6.2/python3-procman-0.6.2-1.el9.noarch.rpm
      https://github.com/VCTLabs/el9-rpm-toolbox/releases/download/honcho-2.0.0.2/python3-honcho-2.0.0.2-1.el9.noarch.rpm
      https://github.com/VCTLabs/el9-rpm-toolbox/releases/download/hexdump-3.5.3/python3-hexdump-3.5.3-1.el9.noarch.rpm
      https://github.com/VCTLabs/el9-rpm-toolbox/releases/download/diskcache-5.6.3/python3-diskcache-5.6.3-2.el9.noarch.rpm

To install the above downloaded rpms in a RockyLinux9 environment, run
something like the following::

  $ sudo dnf install -y rpms/*.rpm

Note the above example could easily use a separate option-key for each URL
but the default configparser allows multiline strings, so we take advantage
of that.

.. _RPM: https://en.wikipedia.org/wiki/RPM_Package_Manager#Binary_format


Dev tools
~~~~~~~~~

Local tool dependencies to aid in development; install them for
maximum enjoyment.

Doorstop
--------

Document configurations and corresponding YAML or markdown items are
maintained in the following directory structure::

  $ tree reqs/ docs/swd/ tests/docs/
  reqs/
  ├── .doorstop.yml
  └── REQ001.yml
  docs/swd/
  ├── assets
  │   ├── .gitkeep
  │   └── rpmget_dependency_graph.svg
  ├── .doorstop.yml
  └── SDD001.md
  tests/docs/
  ├── .doorstop.yml
  └── TST001.yml

The doorstop_ tool has been added to project [dev] "extras" as well as the
tox dev and docs environments. If a doorstop package is not available for
your environment, then use the "dev" environment for working with doorstop_
documents, eg::

  tox -e dev
  source .venv/bin/activate
  (.venv) doorstop
  building tree...
  loading documents...
  validating items...

  REQ
  │
  ├── TST
  │
  └── SDD

Please see the `doorstop Quick Start`_ for an overview of the relevant
doorstop commands.

.. _doorstop Quick Start: https://doorstop.readthedocs.io/en/latest/getting-started/quickstart.html
.. _doorstop: https://doorstop.readthedocs.io/en/latest/index.html

Tox
---

As long as you have git and at least Python 3.8, then you can install
and use tox_.  After cloning the repository, you can run the repo
checks with the ``tox`` command.  It will build a virtual python
environment for each installed version of python with all the python
dependencies and run the specified commands, eg:

::

  $ git clone https://github.com/sarnold/rpmget
  $ cd rpmget/
  $ tox -e py

The above will run the default test command using the (local) default
Python version.  To specify the Python version and host OS type, run
something like::

  $ tox -e py311-linux

To build and check the Python package, run::

  $ tox -e build,check

Full list of additional ``tox`` commands:

* ``tox -e dev`` build a python venv and install in editable mode
* ``tox -e build`` build the python packages and run package checks
* ``tox -e check`` install the wheel package from above
* ``tox -e lint`` run ``pylint`` (somewhat less permissive than PEP8/flake8 checks)
* ``tox -e mypy`` run mypy import and type checking
* ``tox -e style`` run flake8 style checks
* ``tox -e reuse`` run the ``reuse lint`` command and install sbom4python
* ``tox -e changes`` generate a new changelog file

To build/lint the api docs, use the following tox commands:

* ``tox -e docs`` build the documentation using sphinx and the api-doc plugin
* ``tox -e ldocs`` run the Sphinx doc-link checking
* ``tox -e cdocs`` run ``make clean`` in the docs build


Gitchangelog
------------

We use gitchangelog_  to generate a changelog and/or release notes, as
well as the gitchangelog message format to help it categorize/filter
commits for tidier output.  Please use the appropriate ACTION modifiers
for important changes in Pull Requests.

Pre-commit
----------

This repo is also pre-commit_ enabled for various linting and format
checks.  The checks run automatically on commit and will fail the
commit (if not clean) with some checks performing simple file corrections.

If other checks fail on commit, the failure display should explain the error
types and line numbers. Note you must fix any fatal errors for the
commit to succeed; some errors should be fixed automatically (use
``git status`` and ``git diff`` to review any changes).

See the following sections in the built docs for more information on
gitchangelog and pre-commit.

You will need to install pre-commit before contributing any changes;
installing it using your system's package manager is recommended,
otherwise install with pip into your usual virtual environment using
something like::

  $ sudo emerge pre-commit  --or--
  $ pip install pre-commit

then install it into the repo you just cloned::

  $ git clone git@github.com:sarnold/rpmget.git
  $ cd rpmget/
  $ pre-commit install

It's usually a good idea to update the hooks to the latest version::

    pre-commit autoupdate


SBOM and license info
~~~~~~~~~~~~~~~~~~~~~

This project is now compliant with the REUSE Specification Version 3.3, so the
corresponding license information for all files can be found in the ``REUSE.toml``
configuration file with license text(s) in the ``LICENSES/`` folder.

Related metadata can be (re)generated with the following tools and command
examples.

* reuse-tool_ - REUSE_ compliance linting and sdist (source files) SBOM generation
* sbom4python_ - generate SBOM with full dependency chain

Commands
--------

Use tox to create the environment and run the lint command::

  $ tox -e reuse                      # --or--
  $ tox -e reuse -- spdx > sbom.txt   # generate sdist files sbom

Note you can pass any of the other reuse commands after the ``--`` above.

Use the above environment to generate the full SBOM in text format::

  $ source .tox/reuse/bin/activate
  $ sbom4python --system --use-pip -o <file_name>.txt

Be patient; the last command above may take several minutes. See the
doc links above for more detailed information on the tools and
specifications.

.. _Tox: https://github.com/tox-dev/tox
.. _reuse-tool: https://github.com/fsfe/reuse-tool
.. _REUSE: https://reuse.software/spec-3.3/
.. _sbom4python: https://github.com/anthonyharrison/sbom4python
.. _gitchangelog: https://github.com/sarnold/gitchangelog
.. _pre-commit: http://pre-commit.com/
.. _setuptools_scm: https://setuptools-scm.readthedocs.io/en/stable/


.. |ci| image:: https://github.com/sarnold/rpmget/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/sarnold/rpmget/actions/workflows/ci.yml
    :alt: CI Status

.. |wheels| image:: https://github.com/sarnold/rpmget/actions/workflows/wheels.yml/badge.svg
    :target: https://github.com/sarnold/rpmget/actions/workflows/wheels.yml
    :alt: Wheel Status

.. |badge| image:: https://github.com/sarnold/rpmget/actions/workflows/pylint.yml/badge.svg
    :target: https://github.com/sarnold/rpmget/actions/workflows/pylint.yml
    :alt: Pylint Status

.. |release| image:: https://github.com/sarnold/rpmget/actions/workflows/release.yml/badge.svg
    :target: https://github.com/sarnold/rpmget/actions/workflows/release.yml
    :alt: Release Status

.. |bandit| image:: https://github.com/sarnold/rpmget/actions/workflows/bandit.yml/badge.svg
    :target: https://github.com/sarnold/rpmget/actions/workflows/bandit.yml
    :alt: Security check - Bandit

.. |cov| image:: https://raw.githubusercontent.com/sarnold/rpmget/badges/main/test-coverage.svg
    :target: https://github.com/sarnold/rpmget/actions/workflows/coverage.yml
    :alt: Test coverage

.. |pylint| image:: https://raw.githubusercontent.com/sarnold/rpmget/badges/main/pylint-score.svg
    :target: https://github.com/sarnold/rpmget/actions/workflows/pylint.yml
    :alt: Pylint Score

.. |license| image:: https://img.shields.io/badge/license-MIT-blue
    :target: https://github.com/sarnold/rpmget/blob/main/LICENSE
    :alt: License

.. |tag| image:: https://img.shields.io/github/v/tag/sarnold/rpmget?color=green&include_prereleases&label=latest%20release
    :target: https://github.com/sarnold/rpmget/releases
    :alt: GitHub tag

.. |python| image:: https://img.shields.io/badge/python-3.9+-blue.svg
    :target: https://www.python.org/downloads/
    :alt: Python

.. |reuse| image:: https://api.reuse.software/badge/git.fsfe.org/reuse/api
    :target: https://api.reuse.software/info/git.fsfe.org/reuse/api
    :alt: REUSE status

.. |pre| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
   :target: https://github.com/pre-commit/pre-commit
   :alt: pre-commit