Merge pull request #51 from grafana/update-documentation

Update documentation

README.md

@@ -1,8 +1,32 @@
 # k6build
 
-k6build builds custom k6 binaries with extensions
+k6build builds custom k6 binaries with extensions.
 
-## Examples
+
+## API
+
+`k6build` defines an [API](build.go) for building custom k6 binaries.
+
+The API returns the metadata of the custom binary, including an URL for downloading it,
+but does not return the binary itself.
+
+The request for building a binary specifies the target platform (required) and the dependencies,
+including k6.
+
+The dependencies specify the import path (as used in the k6 script) and the semantic version 
+constrains.
+
+Dependencies are mapped by a catalog to the corresponding go module that implements it. The catalog
+also defines the available versions.
+
+If a dependency doesn't specify a constrains, the latest version (according to the catalog) is used.
+
+See [k6catalog](http://github.com/grafana/k6catalog) for more details on defining a catalog.
+
+The default catalog is defined at https://registry.k6.io/catalog.json
+
+
+## Usage scenarios
 
 The following sections describe different usage scenarios.
 
@@ -17,9 +41,7 @@ TODO: use [k6-operator](https://github.com/grafana/k6-operator) for running the
 <!-- #region cli -->
 # k6build
 
-**Build k6 with various builders.**
-
-Build k6 using one of the supported builders.
+**Build custom k6 binaries with extensions**
 
 ## Commands
 
@@ -77,15 +99,16 @@ curl http://external.url:9000/cache/objectID/download
 
 ```
   -c, --cache-dir string      cache directory (default "/tmp/cache/objectstore")
-  -d, --download-url string   base url used for downloading objects. If not specified http://localhost:<port> is used
+  -d, --download-url string   base url used for downloading objects.
+                              If not specified http://localhost:<port>/cache is used
   -h, --help                  help for cache
   -l, --log-level string      log level (default "INFO")
   -p, --port int              port server will listen (default 9000)
 ```
 
 ## SEE ALSO
 
-* [k6build](#k6build)	 - Build k6 with various builders.
+* [k6build](#k6build)	 - Build custom k6 binaries with extensions
 
 ---
 # k6build local
@@ -154,7 +177,7 @@ k6build local -k v0.50.0 -e GOPROXY=http://localhost:80 -q
 
 ## SEE ALSO
 
-* [k6build](#k6build)	 - Build k6 with various builders.
+* [k6build](#k6build)	 - Build custom k6 binaries with extensions
 
 ---
 # k6build remote
@@ -212,15 +235,16 @@ Extensions:
   -d, --dependency stringArray   list of dependencies in form package:constrains
   -h, --help                     help for remote
   -k, --k6 string                k6 version constrains (default "*")
-  -o, --output string            path to download the custom binary as an executable. If not specified, the artifact is not downloaded.
+  -o, --output string            path to download the custom binary as an executable.
+                                 If not specified, the artifact is not downloaded.
   -p, --platform string          target platform (default GOOS/GOARCH)
   -q, --quiet                    don't print artifact's details
   -s, --server string            url for build server (default "http://localhost:8000")
 ```
 
 ## SEE ALSO
 
-* [k6build](#k6build)	 - Build k6 with various builders.
+* [k6build](#k6build)	 - Build custom k6 binaries with extensions
 
 ---
 # k6build server
@@ -230,7 +254,43 @@ k6 build service
 ## Synopsis
 
 
-starts a k6build server
+Starts a k6build server
+
+The server exposes an API for building custom k6 binaries.
+
+The API returns the metadata of the custom binary, including an URL for downloading it,
+but does not return the binary itself.
+
+For example
+
+	curl http://localhost:8000/build/ -d \
+	'{
+	  "k6":"v0.50.0",
+	  "dependencies":[
+	    {
+		"name":"k6/x/kubernetes",
+		"constraints":">v0.8.0"
+	    }
+	  ],
+	  "platform":"linux/amd64"
+	}' | jq .
+
+	{
+	  "artifact": {
+	  "id": "5a241ba6ff643075caadbd06d5a326e5e74f6f10",
+	  "url": "http://localhost:9000/cache/5a241ba6ff643075caadbd06d5a326e5e74f6f10/download",
+	  "dependencies": {
+	    "k6": "v0.50.0",
+	    "k6/x/kubernetes": "v0.10.0"
+	  },
+	  "platform": "linux/amd64",
+	  "checksum": "bfdf51ec9279e6d7f91df0a342d0c90ab4990ff1fb0215938505a6894edaf913"
+	  }
+	}
+
+Note: The build server does not support CGO_ENABLE when building binaries
+      due to this issue: https://github.com/grafana/k6build/issues/37
+      use --enable-cgo=true to enable CGO support
 
 
 ```
@@ -241,19 +301,23 @@ k6build server [flags]
 
 ```
 
-# start the build server using a custom catalog
+# start the build server using a custom local catalog
 k6build server -c /path/to/catalog.json
 
-# start the server the build server using a custom GOPROXY
+# start the build server using a custom GOPROXY
 k6build server -e GOPROXY=http://localhost:80
+
 ```
 
 ## Flags
 
 ```
-      --cache-url string     cache server url (default "http://localhost:9000")
-  -c, --catalog string       dependencies catalog. Can be path to a local file or an URL (default "https://registry.k6.io/catalog.json")
+      --allow-prereleases    allow building pre-releases.
+      --cache-url string     cache server url (default "http://localhost:9000/cache")
+  -c, --catalog string       dependencies catalog. Can be path to a local file or an URL.
+                              (default "https://registry.k6.io/catalog.json")
   -g, --copy-go-env          copy go environment (default true)
+      --enable-cgo           enable CGO for building binaries.
   -e, --env stringToString   build environment variables (default [])
   -h, --help                 help for server
   -l, --log-level string     log level (default "INFO")
@@ -263,6 +327,6 @@ k6build server -e GOPROXY=http://localhost:80
 
 ## SEE ALSO
 
-* [k6build](#k6build)	 - Build k6 with various builders.
+* [k6build](#k6build)	 - Build custom k6 binaries with extensions
 
 <!-- #endregion cli -->

build.go

@@ -10,27 +10,30 @@ import (
 
 var ErrBuildFailed = errors.New("build failed") //nolint:revive
 
-// Dependency contains the properties of a k6 dependency.
+// Dependency defines a dependency and its semantic version constrains
 type Dependency struct {
 	// Name is the name of the dependency.
 	Name string `json:"name,omitempty"`
-	// Constraints contains the version constraints of the dependency.
+	// Constraints specifies the semantic version constraints. E.g. >v0.2.0
 	Constraints string `json:"constraints,omitempty"`
 }
 
-// Module defines an artifact dependency
+// Module defines the mapping of a Dependency to a go module that satisfies it
 type Module struct {
-	Path    string `json:"path,omitempty"`
+	// Path is the go module path
+	Path string `json:"path,omitempty"`
+	// Version is the go module version
 	Version string `json:"version,omitempty"`
 }
 
-// Artifact defines a binary that can be downloaded
-// TODO: add metadata (e.g. list of dependencies, checksum, date compiled)
+// Artifact defines the metadata of binary that satisfies a set of dependencies
+// including a URL for downloading it.
 type Artifact struct {
+	// Unique id. Binaries satisfying the same set of dependencies have the same ID
 	ID string `json:"id,omitempty"`
 	// URL to fetch the artifact's binary
 	URL string `json:"url,omitempty"`
-	// list of dependencies
+	// List of dependencies that the artifact provides
 	Dependencies map[string]string `json:"dependencies,omitempty"`
 	// platform
 	Platform string `json:"platform,omitempty"`
@@ -70,8 +73,8 @@ func (a Artifact) toString(details bool, sep string) string {
 	return buffer.String()
 }
 
-// BuildService defines the interface of a build service
+// BuildService defines the interface for building custom k6 binaries
 type BuildService interface {
-	// Build returns a k6 Artifact given its dependencies and version constrain
+	// Build returns a k6 Artifact that satisfies a set dependencies and version constrains.
 	Build(ctx context.Context, platform string, k6Constrains string, deps []Dependency) (Artifact, error)
 }

cmd/cache/cache.go

@@ -28,7 +28,7 @@ downloading the objects from different machines.
 
 	example = `
 # start the cache server serving an external url
-k6build cache --download0url http://external.url
+k6build cache --download-url http://external.url
 
 # store object from same host
 curl -x POST http://localhost:9000/cache/objectID -d "object content" | jq .
@@ -114,10 +114,8 @@ func New() *cobra.Command {
 	cmd.Flags().StringVarP(&cacheDir, "cache-dir", "c", "/tmp/cache/objectstore", "cache directory")
 	cmd.Flags().IntVarP(&port, "port", "p", 9000, "port server will listen")
 	cmd.Flags().StringVarP(&cacheSrvURL,
-		"download-url",
-		"d",
-		"",
-		"base url used for downloading objects. If not specified http://localhost:<port> is used",
+		"download-url", "d", "", "base url used for downloading objects."+
+			"\nIf not specified http://localhost:<port>/cache is used",
 	)
 	cmd.Flags().StringVarP(&logLevel, "log-level", "l", "INFO", "log level")
 

cmd/cmd.go

@@ -14,8 +14,7 @@ import (
 func New() *cobra.Command {
 	root := &cobra.Command{
 		Use:               "k6build",
-		Short:             "Build k6 with various builders.",
-		Long:              "Build k6 using one of the supported builders.",
+		Short:             "Build custom k6 binaries with extensions",
 		SilenceUsage:      true,
 		SilenceErrors:     true,
 		DisableAutoGenTag: true,

cmd/remote/remote.go

@@ -128,7 +128,7 @@ func New() *cobra.Command {
 	cmd.Flags().StringVarP(&k6, "k6", "k", "*", "k6 version constrains")
 	cmd.Flags().StringVarP(&platform, "platform", "p", "", "target platform (default GOOS/GOARCH)")
 	cmd.Flags().StringVarP(&output, "output", "o", "", "path to download the custom binary as an executable."+
-		" If not specified, the artifact is not downloaded.")
+		"\nIf not specified, the artifact is not downloaded.")
 	cmd.Flags().BoolVarP(&quiet, "quiet", "q", false, "don't print artifact's details")
 
 	return cmd

cmd/server/server.go

@@ -17,7 +17,39 @@ import (
 
 const (
 	long = `
-starts a k6build server
+Starts a k6build server
+
+The server exposes an API for building custom k6 binaries.
+
+The API returns the metadata of the custom binary, including an URL for downloading it,
+but does not return the binary itself.
+
+For example
+
+	curl http://localhost:8000/build/ -d \
+	'{
+	  "k6":"v0.50.0",
+	  "dependencies":[
+	    {
+		"name":"k6/x/kubernetes",
+		"constraints":">v0.8.0"
+	    }
+	  ],
+	  "platform":"linux/amd64"
+	}' | jq .
+
+	{
+	  "artifact": {
+	  "id": "5a241ba6ff643075caadbd06d5a326e5e74f6f10",
+	  "url": "http://localhost:9000/cache/5a241ba6ff643075caadbd06d5a326e5e74f6f10/download",
+	  "dependencies": {
+	    "k6": "v0.50.0",
+	    "k6/x/kubernetes": "v0.10.0"
+	  },
+	  "platform": "linux/amd64",
+	  "checksum": "bfdf51ec9279e6d7f91df0a342d0c90ab4990ff1fb0215938505a6894edaf913"
+	  }
+	}
 
 Note: The build server does not support CGO_ENABLE when building binaries
       due to this issue: https://github.com/grafana/k6build/issues/37
@@ -28,8 +60,9 @@ Note: The build server does not support CGO_ENABLE when building binaries
 # start the build server using a custom local catalog
 k6build server -c /path/to/catalog.json
 
-# start the server the build server using a custom GOPROXY
-k6build server -e GOPROXY=http://localhost:80`
+# start the build server using a custom GOPROXY
+k6build server -e GOPROXY=http://localhost:80
+`
 )
 
 // New creates new cobra command for the server command.
@@ -106,7 +139,8 @@ func New() *cobra.Command { //nolint:funlen
 		"catalog",
 		"c",
 		k6catalog.DefaultCatalogURL,
-		"dependencies catalog. Can be path to a local file or an URL",
+		"dependencies catalog. Can be path to a local file or an URL."+
+			"\n",
 	)
 	cmd.Flags().StringVar(&config.CacheURL, "cache-url", "http://localhost:9000/cache", "cache server url")
 	cmd.Flags().BoolVarP(&config.Verbose, "verbose", "v", false, "print build process output")