From 3efdc7a5e66b10a0297b9aed21c233cf60d5f41f Mon Sep 17 00:00:00 2001 From: "C. R. Oldham" Date: Tue, 23 Sep 2014 13:39:16 -0600 Subject: [PATCH] Add documentation. --- salt/modules/macports.py | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/salt/modules/macports.py b/salt/modules/macports.py index 039eda69a3..7a540def59 100644 --- a/salt/modules/macports.py +++ b/salt/modules/macports.py @@ -1,6 +1,33 @@ # -*- coding: utf-8 -*- ''' -Support for MacPorts under MacOSX +Support for MacPorts under Mac OSX. + +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 commmunity +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`. + ''' # Import python libs @@ -14,7 +41,6 @@ import salt.utils log = logging.getLogger(__name__) LIST_ACTIVE_ONLY = True - __virtualname__ = 'pkg'