How do I associate a launchd 2 plist with its domain and service targets?

What exactly are these "domain" and "service targets" and how do I associate them with plists for use by launchd?

OS X 10.10 introduces a new launchctl API for managing LaunchDaemons and launching plists. Log messages and man pages suggest that keys like KeepAlive and RunAtLoad should no longer be used and that subcommands enable; bootstrap; and kickstart should be used in preference to load -w and unload -w

However it is not clear from the man pages how to associate a plist with the "domain" and "service target" it talks about and without which these commands cannot be used with existing plists that seemingly were quite sufficient for OS X 10.9

For example [updated]: A basic plist we are trying to "launch"; seemingly bootstrapped into "system" domain but subsequently not recognised in "system"

# pwd
/Library/LaunchDaemons
# cat com.iainhouston.django.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC -//Apple Computer//DTD PLIST 1.0//EN
http://www.apple.com/DTDs/PropertyList-1.0.dtd >
<plist version="1.0">
<dict>
     <key>Label</key>
     <string>com.iainhouston.django</string>
     <key>ProgramArguments</key>
     <array>
          <string>/usr/local/virtualenvs/django.iainhouston.com/bin/gunicorn</string>
          <string>--bind=127.0.0.1:49202</string>
          <string>--workers=2</string>
          <string>superlists.wsgi:application</string>
     </array>
     <key>Disabled</key><false/>
</dict>
</plist> 
# launchctl bootstrap system com.iainhouston.django.plist
/Library/LaunchDaemons/com.iainhouston.django.plist: Service is disabled 
# launchctl enable system/com.iainhouston.django.plist 
# launchctl kickstart system/com.iainhouston.django.plist
Could not find service "com.iainhouston.django.plist" in domain for system  

Motivation

The system log records that launchctl -w load ... complains when we use KeepAlive with RunAtLoad that This service is defined to be constantly running and is inherently inefficient. so we are motivated to use the new interface.
Not only that, we have significant problems with excessive processor usage that we want to control by providing the appropriate on-demand keywords so, again, we are motivated to understand how to interact with the new launchd .... not easy with the docs as they stand!

Solution 1:

If you can, file a bug with Apple regarding incomplete or unclear documentation.

launchd appears to have been rewritten for OS X 10.10 and is likely still in flux for a few minor versions yet.

Domains and service targets appear to be an abstraction of the various folders available for launchd job tickets. They also allow a means for launchctl commands to target specific sessions; a feature that should allow a launchctl command to affect other user sessions.

However, as of OS X 10.10.1, the launchd.plist man page makes no mention of deprecated KeepAlive or RunAtLoad keys.

Apple suggest avoiding KeepAlive and RunAtLoad because the intention is to avoid ever launching a process without a guarantee of work to be done. Both keys remain and are required for many tasks.

The best reference document remains Technical Note TN2083, Daemons and Agents. This document provides a great insight into launchd and Apple's intentions towards how background processes should be implemented.

Solution 2:

You are close, but you should not have the .plist part in the enable and kickstart commands. Here is some code we use to associate it to a domain and service target for a user. $UID is basically your userid.

launchctl bootstrap gui/$UID /Library/LaunchAgents/com.yourcompany.yourapp.plist
launchctl enable gui/$UID/com.yourcompany.yourapp
launchctl kickstart -k gui/$UID/com.yourcompany.yourapp