Forge Home


Utility module for FreeBSD ports


6,970 latest version

4.5 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.1.3 (latest)
  • 0.1.2
  • 0.1.1
  • 0.1.0
  • 0.0.11
  • 0.0.10
  • 0.0.9
  • 0.0.8 (deleted)
  • 0.0.7
  • 0.0.6
  • 0.0.5
  • 0.0.3
  • 0.0.2
  • 0.0.1
released Sep 18th 2016
This version is compatible with:
  • FreeBSD

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'ptomulik-portsutil', '0.1.3'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add ptomulik-portsutil
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install ptomulik-portsutil --version 0.1.3

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



ptomulik/portsutil — version 0.1.3 Sep 18th 2016


Build Status Coverage Status Code Climate

Table of Contents

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


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' is referred to as a pkgname
  • a string in form 'www/apache22' or 'lang/ruby18' is referred to as a port origin or portorigin



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.


See 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.


Nothing that could be currently mentioned.


The project is held at github: