# salt.modules.mac_portspkg

Support for MacPorts under macOS.

This module has some caveats.

1. Updating the database of available ports is quite resource-intensive. However, refresh=True is the default for all operations that need an up-to-date copy of available ports. Consider refresh=False when you are sure no db update is needed.

2. In some cases MacPorts doesn't always realize when another copy of itself is running and will gleefully tromp all over the available ports database. This makes MacPorts behave in undefined ways until a fresh complete copy is retrieved.

Because of 1 and 2 it is possible to get the salt-minion into a state where salt mac-machine pkg./something/ won't want to return. Use

salt-run jobs.active

on the master to check for potentially long-running calls to port.

Finally, ports database updates are always handled with port selfupdate as opposed to port sync. This makes sense in the MacPorts user community but may confuse experienced Linux admins as Linux package managers don't upgrade the packaging software when doing a package database update. In other words salt mac-machine pkg.refresh_db is more like apt-get update; apt-get upgrade dpkg apt-get than simply apt-get update.

salt.modules.mac_portspkg.available_version(*names, **kwargs)

  This function is an alias of `latest_version`.

  > Return the latest version of the named package available for upgrade or installation

  > Options:

  > refresh

  >   Update ports with `port selfupdate`

  > CLI Example:

  >     salt '*' pkg.latest_version <package name>
  >     salt '*' pkg.latest_version <package1> <package2> <package3>

salt.modules.mac_portspkg.install(name=None, refresh=False, pkgs=None, **kwargs)

  Install the passed package(s) with `port install`

  name

    The name of the formula to be installed. Note that this parameter is ignored if "pkgs" is passed.

    CLI Example:

        salt '*' pkg.install <package name>

  version

    Specify a version to pkg to install. Ignored if pkgs is specified.

    CLI Example:

        salt '*' pkg.install <package name>
        salt '*' pkg.install git-core version='1.8.5.5'

  variant

    Specify a variant to pkg to install. Ignored if pkgs is specified.

    CLI Example:

        salt '*' pkg.install <package name>
        salt '*' pkg.install git-core version='1.8.5.5' variant='+credential_osxkeychain+doc+pcre'

  Multiple Package Installation Options:

  pkgs

    A list of formulas to install. Must be passed as a python list.

    CLI Example:

        salt '*' pkg.install pkgs='["foo","bar"]'
        salt '*' pkg.install pkgs='["foo@1.2","bar"]'
        salt '*' pkg.install pkgs='["foo@1.2+ssl","bar@2.3"]'

  Returns a dict containing the new package names and versions:

      {'<package>': {'old': '<old-version>',
                     'new': '<new-version>'}}

  CLI Example:

      salt '*' pkg.install 'package package package'

salt.modules.mac_portspkg.latest_version(*names, **kwargs)

  Return the latest version of the named package available for upgrade or installation

  Options:

  refresh

    Update ports with `port selfupdate`

  CLI Example:

      salt '*' pkg.latest_version <package name>
      salt '*' pkg.latest_version <package1> <package2> <package3>

salt.modules.mac_portspkg.list_pkgs(versions_as_list=False, **kwargs)

  List the packages currently installed in a dict:

      {'<package_name>': '<version>'}

  CLI Example:

      salt '*' pkg.list_pkgs

salt.modules.mac_portspkg.list_upgrades(refresh=True, **kwargs)

  Check whether or not an upgrade is available for all packages

  Options:

  refresh

    Update ports with `port selfupdate`

  CLI Example:

      salt '*' pkg.list_upgrades

salt.modules.mac_portspkg.refresh_db(**kwargs)

  Update ports with `port selfupdate`

  CLI Example:

      salt mac pkg.refresh_db

salt.modules.mac_portspkg.remove(name=None, pkgs=None, **kwargs)

  Removes packages with `port uninstall`.

  name

    The name of the package to be deleted.

  Multiple Package Options:

  pkgs

    A list of packages to delete. Must be passed as a python list. The `name` parameter will be ignored if this option is passed.

  New in version 0.16.0.

  Returns a dict containing the changes.

  CLI Example:

      salt '*' pkg.remove <package name>
      salt '*' pkg.remove <package1>,<package2>,<package3>
      salt '*' pkg.remove pkgs='["foo", "bar"]'

salt.modules.mac_portspkg.upgrade(refresh=True, **kwargs)

  Run a full upgrade using MacPorts 'port upgrade outdated'

  Options:

  refresh

    Update ports with `port selfupdate`

  Returns a dictionary containing the changes:

      {'<package>':  {'old': '<old-version>',
                      'new': '<new-version>'}}

  CLI Example:

      salt '*' pkg.upgrade

salt.modules.mac_portspkg.upgrade_available(pkg, refresh=True, **kwargs)

  Check whether or not an upgrade is available for a given package

  CLI Example:

      salt '*' pkg.upgrade_available <package name>

salt.modules.mac_portspkg.version(*names, **kwargs)

  Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

  CLI Example:

      salt '*' pkg.version <package name>
      salt '*' pkg.version <package1> <package2> <package3>