engine: resources: exec: Add a bit of documentation to exec res

engine/resources/exec.go

@@ -56,6 +56,12 @@ func init() {
 }
 
 // ExecRes is an exec resource for running commands.
+//
+// This resource attempts to minimise the effects of the execution environment,
+// and, in particular, will start the new process with an empty environment (as
+// would `execve` with an empty `envp` array). If you want the environment to
+// inherit the mgmt process' environment, you can import it from "sys" and use
+// it with `env => sys.env()` in your exec resource.
 type ExecRes struct {
 	traits.Base // add the base methods without re-implementation
 	traits.Edgeable
@@ -90,7 +96,9 @@ type ExecRes struct {
 	Cwd string `lang:"cwd" yaml:"cwd"`
 
 	// Shell is the (optional) shell to use to run the cmd. If you specify
-	// this, then you can't use the Args parameter.
+	// this, then you can't use the Args parameter. Note that unless you
+	// use absolute paths, or set the PATH variable, the shell might not be
+	// able to find the program you're trying to run.
 	Shell string `lang:"shell" yaml:"shell"`
 
 	// Timeout is the number of seconds to wait before sending a Kill to the
@@ -99,7 +107,9 @@ type ExecRes struct {
 	Timeout uint64 `lang:"timeout" yaml:"timeout"`
 
 	// Env allows the user to specify environment variables for script
-	// execution. These are taken using a map of format of VAR_NAME -> value.
+	// execution. These are taken using a map of format of VAR_KEY -> value.
+	// Omitting this value or setting it to an empty array will cause the
+	// program to be run with an empty environment.
 	Env map[string]string `lang:"env" yaml:"env"`
 
 	// WatchCmd is the command to run to detect event changes. Each line of