Merge pull request #1723 from monopole/renaming

Improved plugin loading docs.

api/pgmconfig/pluginconfig.go

@@ -15,7 +15,15 @@ const (
 	// Symbol that must be used inside Go plugins.
 	PluginSymbol = "KustomizePlugin"
 
-	// Location of builtins.
+	// Name of environment variable used to set AbsPluginHome.
+	// See that variable for an explanation.
+	KustomizePluginHomeEnv = "KUSTOMIZE_PLUGIN_HOME"
+
+	// Relative path below XDG_CONFIG_HOME/kustomize to find plugins.
+	// e.g. AbsPluginHome = XDG_CONFIG_HOME/kustomize/plugin
+	RelPluginHome = "plugin"
+
+	// Location of builtin plugins below AbsPluginHome.
 	BuiltinPluginPackage = "builtin"
 
 	// The value of kubernetes ApiVersion to use in configuration
@@ -26,9 +34,6 @@ const (
 	// Domain from which kustomize code is imported, for locating
 	// plugin source code under $GOPATH when GOPATH is defined.
 	DomainName = "sigs.k8s.io"
-
-	// Name of directory housing all plugins.
-	PluginRoot = "plugin"
 )
 
 func ActivePluginConfig() *types.PluginConfig {
@@ -40,10 +45,14 @@ func ActivePluginConfig() *types.PluginConfig {
 func DefaultPluginConfig() *types.PluginConfig {
 	return &types.PluginConfig{
 		PluginRestrictions: types.PluginRestrictionsBuiltinsOnly,
-		DirectoryPath:      filepath.Join(configRoot(), PluginRoot),
+		AbsPluginHome:      DefaultAbsPluginHome(),
 	}
 }
 
+func DefaultAbsPluginHome() string {
+	return filepath.Join(configRoot(), RelPluginHome)
+}
+
 // Use https://github.com/kirsle/configdir instead?
 func configRoot() string {
 	dir := os.Getenv(XdgConfigHomeEnv)
@@ -68,3 +77,19 @@ func homeEnv() string {
 	}
 	return "HOME"
 }
+
+func CurrentWorkingDir() string {
+	// Try for full path first to be explicit.
+	pwd := os.Getenv(pwdEnv())
+	if len(pwd) > 0 {
+		return pwd
+	}
+	return "."
+}
+
+func pwdEnv() string {
+	if runtime.GOOS == "windows" {
+		return "CD"
+	}
+	return "PWD"
+}

api/plugins/compiler/compiler.go

@@ -35,20 +35,20 @@ func DefaultSrcRoot() (string, error) {
 
 	root = filepath.Join(
 		os.Getenv("GOPATH"), "src",
-		pgmconfig.DomainName, pgmconfig.ProgramName, pgmconfig.PluginRoot)
+		pgmconfig.DomainName, pgmconfig.ProgramName, pgmconfig.RelPluginHome)
 	if FileExists(root) {
 		return root, nil
 	}
 	nope = append(nope, root)
 
-	root = pgmconfig.DefaultPluginConfig().DirectoryPath
+	root = pgmconfig.DefaultPluginConfig().AbsPluginHome
 	if FileExists(root) {
 		return root, nil
 	}
 	nope = append(nope, root)
 
 	root = filepath.Join(
-		pgmconfig.HomeDir(), pgmconfig.ProgramName, pgmconfig.PluginRoot)
+		pgmconfig.HomeDir(), pgmconfig.ProgramName, pgmconfig.RelPluginHome)
 	if FileExists(root) {
 		return root, nil
 	}

api/plugins/loader/loader.go

@@ -93,7 +93,7 @@ func relativePluginPath(id resid.ResId) string {
 
 func AbsolutePluginPath(pc *types.PluginConfig, id resid.ResId) string {
 	return filepath.Join(
-		pc.DirectoryPath, relativePluginPath(id), id.Kind)
+		pc.AbsPluginHome, relativePluginPath(id), id.Kind)
 }
 
 func (l *Loader) absolutePluginPath(id resid.ResId) string {

api/testutils/kusttest/plugintestenv.go

@@ -70,7 +70,7 @@ func (x *PluginTestEnv) makeCompiler() *compiler.Compiler {
 	//    $objRoot
 	// so set things up accordingly.
 	objRoot := filepath.Join(
-		x.workDir, pgmconfig.ProgramName, pgmconfig.PluginRoot)
+		x.workDir, pgmconfig.ProgramName, pgmconfig.RelPluginHome)
 	err := os.MkdirAll(objRoot, os.ModePerm)
 	if err != nil {
 		x.t.Error(err)

api/types/pluginconfig.go

@@ -5,11 +5,25 @@ package types
 
 // PluginConfig holds plugin configuration.
 type PluginConfig struct {
-	// DirectoryPath is an absolute path to a
-	// directory containing kustomize plugins.
-	// This directory may contain subdirectories
-	// further categorizing plugins.
-	DirectoryPath string
+	// AbsPluginHome is the home of kustomize plugins.
+	// Kustomize plugin configuration files are k8s-style objects
+	// containing the fields 'apiVersion' and 'kind', e.g.
+	//   apiVersion: apps/v1
+	//   kind: Deployment
+	// When kustomize reads a plugin configuration file (as as result
+	// of seeing the file name in the 'generators:' or 'transformers:'
+	// field in a kustomization file), it must then locate the plugin
+	// code (Go plugin or exec plugin).
+	// Every kustomize plugin (its code, its tests, supporting data
+	// files, etc.) must be housed in its own directory at
+	//   ${AbsPluginHome}/${pluginApiVersion}/LOWERCASE(${pluginKind})
+	// where
+	//   - ${AbsPluginHome} is an absolute path, defined below.
+	//   - ${pluginApiVersion} is taken from the plugin config file.
+	//   - ${pluginKind} is taken from the plugin config file.
+	// The value of AbsPluginHome can be any absolute path, but might
+	// default to $XDG_CONFIG_HOME/kustomize/plugin.
+	AbsPluginHome string
 
 	// PluginRestrictions defines the plugin restriction state.
 	// See type for more information.