Maintenance tools

Makefile.py is used for many of the repetitive and maintenance-related tasks in this overlay. The custom code was chosen over make as the original Makefile was simply becoming too unwieldy, and as many of the support tools were already written in Python this trade felt like a good choice.

Repository level support

all

This task performs all building tasks for the repository. It is purely a wrapper that executes any tasks whose name begins with gen-, and doesn’t need to be manually updated for new generators.

check

This task runs all the defined checks for the repository. It is simply a wrapper that executes any task whose name ends with -check, and doesn’t need to be manually updated for new checks.

clean

This task removes generated files, such as HTML generated from reST sources.

distclean

In addition to the files removed by the clean target this task also removes all the Manifest files in the repository.

eclass-doc-check

Check the syntax of eclass documentation using the awk script from app-portage/eclass-manpages.

task-doc-check

Check all tasks are documented here.

cupage support

gen-cupage-conf

This task recreates the support/cupage.conf file for this repository, see watch files.

cupage-check

This task checks that a watch file exists for every package in the repository, see watch files.

layman support

layman-check

This task performs a XML validation check on the layman support files.

Maintenance support tasks

gen-stable

This task creates a support/stabilisation.rem snippet to use a stabilisation reminder. It requires a full <category>/<package>-<version> string as its only argument. See the stabilisation.rem documentation.

keyword-check

This task is used to check whether packages have stable, or at least unstable, keywords available on amd64 and x86. These are the only supported archs in this repository, and packages should be available on both where possible.

Previously arm was also supported, but this is no longer the case as the packages that were most useful on arm have moved to another overlay.

open-bug

This task will open a bug in the GitHub repository’s issue tracker. It requires one argument, which will be used as the bug’s title. If you give a second argument it will be used for the bug’s body. A third argument, if given, will be used for the initial label for the bug.

The examples below should make the usage clear:

$ ./Makefile.py open-bug 'new title'
$ ./Makefile.py open-bug 'title' 'with extended body content'
$ ./Makefile.py open-bug 'title' 'body' 'initial label'
$ ./Makefile.py open-bug 'title' '' 'initial label'

It reads your GitHub authentication data using git config, see the setup help page on GitHub for more information.

Note

This task fetches the repository identifier from the remote.origin.url setting. See git-config(1).

bump-pkg

This task is a special case of the open-bug task whose sole purpose is to file bump requests with the minimum of fuss. It requires a full <category>/<package>-<version> string as its only argument.

It reads your GitHub authentication data using git config, see the setup help page on GitHub for more information.

Note

This task fetches the repository identifier from the remote.origin.url setting. See git-config(1).

portage support

gen-categories

This task recreates the overlay’s categories list in profiles/categories.

gen-manifests

This task will regenerate any missing, or stale, Manifest files in the repository.

Note

If you have a PORTAGE_GPG_KEY setting in /etc/portage/make.conf it will use that key to sign the created files. See make.conf(5) for more information on Manifest signing.

gen-news-sigs

This task is used regenerate any missing, or stale, signatures for news files. See the GLEP 42 documentation for more information.

This task requires you have PORTAGE_GPG_KEY set in /etc/portage/make.conf to function, see make.conf(5) for details.

gen-use-local-desc

This task generates the profiles/use.local.desc file using the USE flag information in each package’s metadata.xml definitions. See egencache(1) and the devmanual’s metadata.xml documentation for more information.

remind support

gen-removals

This task is used to generate removals.rem, see the package.mask documentation for more information.

reminders

This task is just a shortcut for using remind to display the currently active stabilisation and removal records.

reStructuredText support

gen-html

This task generates HTML from all files ending in .rst. It uses the equivalent of the rst2html.py command’s --strict flag, and will fail if any errors or warnings are issued.

gen-sphinx-html

This task rebuilds the documentation contained in doc/ using Sphinx.

gen-thanks

This task is used to create doc/thanks.rst from README.rst, its purpose is to remove the error-prone manual edits of both files when adding contributor information.

rst-check

This task parses all files ending in .rst for conformity. It uses the equivalent of the rst2html.py command’s --strict flag, and will fail if any errors or warnings are issued.

tasks.utils

This module is used to provide support functionality for use in other tasks. The few developer facing functions are described below.

newer(file1, file2) → Bool

This function returns True if file1 is newer than file2. It handles the case of file arguments that don’t yet exist.

dep(targets, sources[, mapping=False]) → function

dep is to be used for checking whether a target needs executing. If the target is up to date the task is not run.

If the mappings argument is True then rebuilds are only performed if a source is newer than a target when the arguments are paired. If False a rebuild is performed if any source is a newer than a target.

Args:

targets (list): Targets to check against sources (list): Sources to check against mapping (bool): Whether targets map directly to sources

cmd_output(command) → str

A simple wrapper for check_output() that call commands and returns the result with any whitespace padding removed

Args:

command (str): Command to execute