Improved godoc Launch Agent for OS X

Sat, Dec 14, 2013

I recently found instructions from Dave Cheney on installing godoc as a launch agent in OS X. It’s really cool to have Go’s documentation running locally and to have the system ensure it’s always running for you, but I realized you can get it to display your own packages as well.

It’s insanely helpful to have documentation auto-generated for my packages that are consistent with and as nice as the documentation for the standard library.

This requires only a slight tweak in Dave’s file, adding your GOPATH as an environment variable (toward the bottom):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>Label</key>
   <string>org.golang.godoc</string>
   <key>ProgramArguments</key>
   <array>
      <!-- ensure this is the absolute path to your godoc install -->
      <string>/usr/local/go/bin/godoc</string>
      <string>-http=127.0.0.1:6060</string>
   </array>
   <key>Sockets</key>
   <dict>
      <key>Listeners</key>
      <dict>
         <key>SockServiceName</key>
         <string>6060</string>
      </dict>
   </dict>
   <key>KeepAlive</key>
   <true/>
   <key>EnvironmentVariables</key>
   <dict>
     <key>GOPATH</key>
     <!-- ensure this is your absolute gopath -->
     <string>/Users/Stephen/Code/go</string>
   </dict>
   </dict>
</plist>

Simply install that to ~/Library/LaunchAgents/org.golang.godoc.plist, and run:

launchctl load ~/Library/LaunchAgents/org.golang.godoc.plist

Now navigate to [http://127.0.0.1:6060][1] and see all of your own code alongside the standard library.

Searching

If you want to enable search, it’s just a small tweak to that file. Add this line just below the http flag:

<string>-index</string>

(You can also play with adding the index_throttle flag if you want that to use less cpu or finish quicker.)

I have found that once the index is created, it never gets updated. So to refresh the search index, kill the godoc process (launchd will restart it).

[1]: http://127.0.0.1:6060/