ptomulik-portsutil

Build Status Coverage Status Code Climate

Table of Contents

  1. Overview
  2. Module Description
  3. Setup
  4. Usage
  5. Reference
  6. Limitations
  7. Development

Overview

This library contains extension modules for searching FreeBSD ports(7) and packages. It uses make search command to search available ports and portversion(1) to query already installed packages. The portversion is a part of the port-maintenance-tools package, which may be installed with

pkg install port-maintenance-tools

Both, the old pkg and the new pkgng databases are supported. The library also allows manipulating build options (normally set with make config) and determining other characteristics of FreeBSD packaging system.

The library is developed primarily for ptomulik-portsng module, which implements ports provider for package resource.

Module Description

Library contents

The library contains the following ruby modules:

  • Puppet::Util::PTomulik::Package::Ports::PortSearch - methods for searching ports INDEX,
  • Puppet::Util::PTomulik::Package::Ports::PkgSearch - search installed packages,
  • Puppet::Util::PTomulik::Package::Ports::Functions - common stuff used by other modules,

and the following classes:

  • Puppet::Util::PTomulik::Package::Ports::Options - FreeBSD ports options (normally settable by make search),
  • Puppet::Util::PTomulik::Package::Ports::PortRecord - represents single record from ports INDEX,
  • Puppet::Util::PTomulik::Package::Ports::PkgRecord - single record from package database,
  • Puppet::Util::PTomulik::Package::Ports::Record - superclass for PkgRecord and PortRecord

The module Puppet::Util::PTomulik::Package::Ports includes both the PortSearch and PkgSearch, so it may be used if you wish to have the functionality of both modules in your class.

Library functionality

The PortSearch module provides methods that facilitate searching ports INDEX for information describing available ports. The PkgSearch module provides method that facilitate searching the database of installed packages. It supports the old pkg database format and the new pkgng. Search methods in both modules are designed such that they yield one record for each package found in database. The returned record is either PortRecord object (for PortSearch) or PkgRecord (for PkgSearch). The record is basically a {:field=>value} hash (the record classes inherit from Hash), but it also provides some additional methods (see API docs for details). Example fields that may be found in a record are :name, :pkgname, :portorigin, :path, etc..

Searches are customizable. You may, for example, specify what fields should be included in search results (in records).

You may search ports INDEX by pkgname, portname, by portorigin, or (with a little extra effort) perform a custom search by any key supported by the make search command (see ports(7)). You may also perform a heuristic search by name without stating whether the name represents pkgname, portname or portorigin (see API docs for search_ports method).

Installed packages may be searched by name (the list of names is passed directly portversion(1)). It's also easy to retrieve information about all installed packages.

When compiling FreeBSD ports, the user has possibility to set some build options with make config command. Here, the same build options may be easily manipulated with Options class. The Options object represents a set of options for a single port/package. The options are implemented as a hash with simple key/value validation and munging. They may be read from or written to options files - the ones that normally lay under /var/db/ports/.

Terms and definitions

This section explains few terms used across the documentation.

FreeBSD ports collection and its terminology

Ports and packages in FreeBSD may be identified by either portnames, pkgnames or portorigins. We use the following terminology when referring ports/packages:

  • a string in form 'apache22' or 'ruby' is referred to as portname
  • a string in form 'apache22-2.2.25' or 'ruby-1.8.7.371,1' is referred to as a pkgname
  • a string in form 'www/apache22' or 'lang/ruby18' is referred to as a port origin or portorigin

See http://www.freebsd.org/doc/en/books/porters-handbook/makefile-naming.html

Setup

What portsutil affects

This is just a library and shouldn't alter your system (it performs mostly read-only operations). The Options class writes ports options to options files, so the contents of options files may change if you save ones. The module uses Facter and some read-only shell commands to query information related to FreeBSD ports/packages.

Setup Requirements

You may need to enable pluginsync in your puppet.conf.

Usage

See Reference.

Reference

The complete API documentation may be generated with yard as follows:

bundle exec rake yard

The generated documentation is written to doc/. Note that this works only on ruby >= 1.9.

Limitations

Nothing that could be currently mentioned.

Development

The project is held at github: