Metadata-Version: 2.4
Name: pycargoebuild
Version: 0.15.0
Summary: A generator for Rust/Cargo ebuilds written in Python
Author-email: Michał Górny <mgorny@gentoo.org>
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
License-File: COPYING
Requires-Dist: jinja2
Requires-Dist: license_expression
Requires-Dist: tomli >= 1.2.3; python_version < '3.11'
Requires-Dist: rich ; extra == "pretty-log"
Requires-Dist: pytest ; extra == "test"
Project-URL: Homepage, https://github.com/projg2/pycargoebuild/
Provides-Extra: pretty-log
Provides-Extra: test

=============
pycargoebuild
=============
:Author: Michał Górny
:License: GPL-2.0-or-later
:Homepage: https://github.com/projg2/pycargoebuild/


pycargoebuild is a generator for ebuilds using the Cargo infrastructure
of Rust language.  It is primarily meant to aid in keeping the list
of ``CRATES`` and their ``LICENSE`` up-to-date.  It is a rewrite
of the `cargo-ebuild`_ tool in Python, with no actual dependency
on Rust.

pycargoebuild reads ``Cargo.toml`` and ``Cargo.lock`` files in order
to obtain the package's metadata and dependency list, respectively.
Then it fetches all dependent crates into ``DISTDIR`` and reads their
``Cargo.toml`` files to construct the complete list of licenses.
The resulting data can either be used to construct a new ebuild from
a template or to update the values of ``CRATES`` and ``LICENSE``
in an existing ebuild.


Why not cargo-ebuild?
=====================
pycargoebuild has the following features that cargo-ebuild 0.5.2
is missing:

- small size (cargo-ebuild compiles to 5.5M on my system)

- full support for SPDX-2.0 license expressions with boolean
  simplification (whereas cargo-ebuild just dumps all licenses it finds)

- pretty-printing with line wrapping for license expressions

- support for updating ``CRATES`` and crate ``LICENSE`` in existing
  ebuilds (whereas cargo-ebuild can only generate new ebuilds)

- support for combining the data from multiple subpackages (useful
  e.g. in setuptools-rust)

- support for fast crate fetching if ``aria2c`` is installed

- support for skipping crate licenses (e.g. for when Crates are used
  at build/test time only)


Usage
=====
To create a new ebuild, run::

    pycargoebuild <package-directory>

where *package-directory* is the directory containing ``Cargo.toml``.
This creates an ebuild file named after the package name and version
in the current directory, and outputs its name.

To update an existing ebuild, use instead::

    pycargoebuild -i <current-file>.ebuild <package-directory>

Note that the existing file must contain both ``CRATES`` variable
and ``LICENSE+=`` assignment like the following::

    # Dependent crate licenses
    LICENSE+="..."

It is also possible to explicitly specify the output filename using
the ``-o`` option.


Configuration file
==================
pycargoebuild can additionally be configured using
``pycargoebuild.toml`` in one of the XDG config directories
(usually ``~/.config``).  The following example provides a quick summary
of configuration options available::

    [paths]
    # default --distdir, Portage config is used if not set
    distdir = "/var/cache/portage/distfiles"
    # default --license-mapping, "metadata/license-mapping.conf" from
    # ::gentoo repo (via Portage API) is used if not set
    license-mapping = "/var/db/repos/gentoo/metadata/license-mapping.conf"

    [license-overrides]
    # provide an SPDX license string for packages missing the metadata
    nihav_codec_support = "MIT"
    nihav_core = "MIT"
    nihav_duck = "MIT"

    [license-mapping]
    # additional mappings from SPDX licenses to Gentoo licenses
    "LicenseRef-UFL-1.0" = "UbuntuFontLicense-1.0"


.. _cargo-ebuild: https://github.com/gentoo/cargo-ebuild/

