Documentation

Overview

    Package devutil has tooling to make Vugu development simpler.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var DefaultAutoReloadIndex = DefaultIndex.Replace(
    	"<!-- scripts -->",
    	"<script src=\"http://localhost:8324/auto-reload.js\"></script>\n<!-- scripts -->")

      DefaultAutoReloadIndex is like DefaultIndex but also includes a script tag to load auto-reload.js from the default URL.

      View Source
      var DefaultIndex = StaticContent(`<!doctype html>
      <html>
      <head>
      <title>Vugu App</title>
      <meta charset="utf-8"/>
      <!-- styles -->
      </head>
      <body>
      <div id="vugu_mount_point">
      <img style="position: absolute; top: 50%; left: 50%;" src="https://cdnjs.cloudflare.com/ajax/libs/galleriffic/2.0.1/css/loader.gif">
      </div>
      <script src="https://cdn.jsdelivr.net/npm/text-encoding@0.7.0/lib/encoding.min.js"></script> <!-- MS Edge polyfill -->
      <script src="/wasm_exec.js"></script>
      <!-- scripts -->
      <script>
      var wasmSupported = (typeof WebAssembly === "object");
      if (wasmSupported) {
      	if (!WebAssembly.instantiateStreaming) { // polyfill
      		WebAssembly.instantiateStreaming = async (resp, importObject) => {
      			const source = await (await resp).arrayBuffer();
      			return await WebAssembly.instantiate(source, importObject);
      		};
      	}
      	var mainWasmReq = fetch("/main.wasm").then(function(res) {
      		if (res.ok) {
      			const go = new Go();
      			WebAssembly.instantiateStreaming(res, go.importObject).then((result) => {
      				go.run(result.instance);
      			});		
      		} else {
      			res.text().then(function(txt) {
      				var el = document.getElementById("vugu_mount_point");
      				el.style = 'font-family: monospace; background: black; color: red; padding: 10px';
      				el.innerText = txt;
      			})
      		}
      	})
      } else {
      	document.getElementById("vugu_mount_point").innerHTML = 'This application requires WebAssembly support.  Please upgrade your browser.';
      }
      </script>
      </body>
      </html>
      `)

        DefaultIndex is the default index.html content for a development Vugu app. The exact text `<title>Vugu App</title>`, `<!-- styles -->` and `<!-- scripts -->` are meant to be replaced as needed if you quickly need to hack in CSS or JS references for a development Vugu application. If you need more control than that, just copy it into your application.

        View Source
        var DefaultTinygoDockerImage = "vugu/tinygo-dev:latest" // this is temporary until we can smooth things out with tinygo/tinygo:latest
        

          DefaultTinygoDockerImage is used as the docker image for Tinygo unless overridden.

          View Source
          var NoFileExt = RequestMatcherFunc(func(r *http.Request) bool {
          	return path.Ext(path.Clean("/"+r.URL.Path)) == ""
          })

            NoFileExt is a RequestMatcher that will return true for all paths which do not have a file extension.

            Functions

            This section is empty.

            Types

            type Compiler

            type Compiler interface {
            	Execute() (outpath string, err error)
            }

              Compiler is implemented by WasmCompiler and TinygoCompiler.

              type FileServer

              type FileServer struct {
              	// contains filtered or unexported fields
              }

                FileServer is similar to http.FileServer but has some options and behavior differences more useful for Vugu programs. The following rules apply when serving http responses:

                If the path is a directory but does not end with a slash it is redirected to be with a slash.

                If the path is a directory and ends with a slash then if it contains an index.html file that is served.

                If the path is a directory and ends with a slash and has no index.html, if listings are enabled a listing will be returned.

                If the path does not exist but exists when .html is appended to it then that file is served.

                For anything else the handler for the not-found case is called, or if not set then a 404.html will be searched for and if that's not present http.NotFound is called.

                Directory listings are disabled by default due to security concerns but can be enabled with SetListings.

                func NewFileServer

                func NewFileServer() *FileServer

                  NewFileServer returns a FileServer instance. Before using you must set FileSystem to serve from by calling SetFileSystem or SetDir.

                  func (*FileServer) ServeHTTP

                  func (fs *FileServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

                    ServeHTTP implements http.Handler with the appropriate behavior.

                    func (*FileServer) SetDir

                    func (fs *FileServer) SetDir(dir string) *FileServer

                      SetDir is short for SetFileSystem(http.Dir(dir))

                      func (*FileServer) SetFileSystem

                      func (fs *FileServer) SetFileSystem(fsys http.FileSystem) *FileServer

                        SetFileSystem sets the FileSystem to use when serving files.

                        func (*FileServer) SetListings

                        func (fs *FileServer) SetListings(v bool) *FileServer

                          SetListings enables or disables automatic directory listings when a directory is indicated in the URL path.

                          func (*FileServer) SetNotFoundHandler

                          func (fs *FileServer) SetNotFoundHandler(h http.Handler) *FileServer

                            SetNotFoundHandler sets the handle used when no applicable file can be found.

                            type MainWasmHandler

                            type MainWasmHandler struct {
                            	// contains filtered or unexported fields
                            }

                              MainWasmHandler calls WasmCompiler.Build and responds with the resulting .wasm file.

                              func NewMainWasmHandler

                              func NewMainWasmHandler(wc Compiler) *MainWasmHandler

                                NewMainWasmHandler returns an initialized MainWasmHandler.

                                func (*MainWasmHandler) ServeHTTP

                                func (h *MainWasmHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

                                  ServeHTTP implements http.Handler.

                                  type Mux

                                  type Mux struct {
                                  	// contains filtered or unexported fields
                                  }

                                    Mux is simple HTTP request multiplexer that has more generally useful behavior for Vugu development than http.ServeMux. Routes are considered in the order they are added.

                                    func NewMux

                                    func NewMux() *Mux

                                      NewMux returns a new Mux.

                                      func (*Mux) Default

                                      func (m *Mux) Default(h http.Handler) *Mux

                                        Default sets the defualt handler to be called if no other matches were found.

                                        func (*Mux) Exact

                                        func (m *Mux) Exact(name string, h http.Handler) *Mux

                                          Exact adds an exact route match. If path.Clean("/"+r.URL.Path)==name then h is called to handle the request.

                                          func (*Mux) Match

                                          func (m *Mux) Match(rm RequestMatcher, h http.Handler) *Mux

                                            Match adds a route that is used if the provided RequestMatcher returns true.

                                            func (*Mux) ServeHTTP

                                            func (m *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

                                              ServeHTTP implements http.Handler.

                                              type RequestMatcher

                                              type RequestMatcher interface {
                                              	RequestMatch(r *http.Request) bool
                                              }

                                                RequestMatcher describes something that can say yes/no if a request matches. We use it here to mean "should this path be followed in order to answer this request".

                                                type RequestMatcherFunc

                                                type RequestMatcherFunc func(r *http.Request) bool

                                                  RequestMatcherFunc implements RequestMatcher as a function.

                                                  func (RequestMatcherFunc) RequestMatch

                                                  func (f RequestMatcherFunc) RequestMatch(r *http.Request) bool

                                                    RequestMatch implements RequestMatcher.

                                                    type StaticContent

                                                    type StaticContent string

                                                      StaticContent implements http.Handler and serves the HTML content in this string.

                                                      func (StaticContent) Replace

                                                      func (sc StaticContent) Replace(old, new string) StaticContent

                                                        Replace performs a single string replacement on this StaticContent and returns the new value.

                                                        func (StaticContent) ServeHTTP

                                                        func (sc StaticContent) ServeHTTP(w http.ResponseWriter, r *http.Request)

                                                          ServeHTTP implements http.Handler

                                                          type StaticFilePath

                                                          type StaticFilePath string

                                                            StaticFilePath implements http.Handler and serves the file at this path.

                                                            func (StaticFilePath) ServeHTTP

                                                            func (sfp StaticFilePath) ServeHTTP(w http.ResponseWriter, r *http.Request)

                                                              ServeHTTP implements http.Handler

                                                              type TinygoCompiler

                                                              type TinygoCompiler struct {
                                                              	// contains filtered or unexported fields
                                                              }

                                                                TinygoCompiler provides a convenient way to build a program via Tinygo into Wasm. This implementation by default uses Docker to download and run Tinygo, and provides methods to handle mapping local directories into the Tinygo docker filesystem and for making other dependencies available by calling `go get` on them. This approach might change once Tinygo has module support, but for now the idea is it makes it reasonably convenient to integration Tinygo into the workflow for Vugu app.

                                                                func MustNewTinygoCompiler

                                                                func MustNewTinygoCompiler() *TinygoCompiler

                                                                  MustNewTinygoCompiler is like NewTinygoCompiler but panics upon error.

                                                                  func NewTinygoCompiler

                                                                  func NewTinygoCompiler() (*TinygoCompiler, error)

                                                                    NewTinygoCompiler returns a new TinygoCompiler instance.

                                                                    func (*TinygoCompiler) AddGoGet

                                                                    func (c *TinygoCompiler) AddGoGet(goGetCmdLine string) *TinygoCompiler

                                                                      AddGoGet adds a go get command to the list of dependencies. Arguments are separated by whitespace.

                                                                      func (*TinygoCompiler) AddGoGetArgs

                                                                      func (c *TinygoCompiler) AddGoGetArgs(goGetCmdParts []string) *TinygoCompiler

                                                                        AddGoGetArgs is like AddGoGet but the args are explicitly separated in a string slice.

                                                                        func (*TinygoCompiler) AddPkgReplace

                                                                        func (c *TinygoCompiler) AddPkgReplace(pkgName, dir string) *TinygoCompiler

                                                                          AddPkgReplace adds a directory mapping for a package. It provides similar functionality to go.mod's replace statement, but is implemented with a docker volume mapping. The dir will be run through filepath.Abs before adding it and will panic if that fails.

                                                                          func (*TinygoCompiler) Close

                                                                          func (c *TinygoCompiler) Close() error

                                                                            Close performs any cleanup. For now it removes the temporary directory created by NewTinygoCompiler.

                                                                            func (*TinygoCompiler) Execute

                                                                            func (c *TinygoCompiler) Execute() (outpath string, err error)

                                                                              Execute runs the generate command (if any) and then invokes the Tinygo compiler and produces a wasm executable (or an error). The value of outpath is the absolute path to the output file on disk. It will be created with a temporary name and if no error is returned it is the caller's responsibility to delete the file when it is no longer needed. If an error occurs during any of the steps it will be returned with (possibly multi-line) descriptive output in it's error message, as produced by the underlying tool.

                                                                              func (*TinygoCompiler) NoDocker

                                                                              func (c *TinygoCompiler) NoDocker() *TinygoCompiler

                                                                                NoDocker is an alias for SetTinygoDockerImage("") and will result in the tinygo executable being run on the local system instead of via docker image.

                                                                                func (*TinygoCompiler) SetAfterFunc

                                                                                func (c *TinygoCompiler) SetAfterFunc(f func(outpath string, err error) error) *TinygoCompiler

                                                                                  SetAfterFunc specifies a function to be executed after everthing else during Execute().

                                                                                  func (*TinygoCompiler) SetBeforeFunc

                                                                                  func (c *TinygoCompiler) SetBeforeFunc(f func() error) *TinygoCompiler

                                                                                    SetBeforeFunc specifies a function to be executed before anything else during Execute().

                                                                                    func (*TinygoCompiler) SetBuildDir

                                                                                    func (c *TinygoCompiler) SetBuildDir(dir string) *TinygoCompiler

                                                                                      SetBuildDir sets the directory of the main package, where `go build` will be run. Relative paths are okay and will be resolved with filepath.Abs.

                                                                                      func (*TinygoCompiler) SetDir

                                                                                      func (c *TinygoCompiler) SetDir(dir string) *TinygoCompiler

                                                                                        SetDir sets both the build and generate directories.

                                                                                        func (*TinygoCompiler) SetGenerateCmdFunc

                                                                                        func (c *TinygoCompiler) SetGenerateCmdFunc(cmdf func() *exec.Cmd) *TinygoCompiler

                                                                                          SetGenerateCmdFunc provides a function to create the exec.Cmd used when running `go generate`. It overrides any other generate-related setting.

                                                                                          func (*TinygoCompiler) SetGenerateDir

                                                                                          func (c *TinygoCompiler) SetGenerateDir(dir string) *TinygoCompiler

                                                                                            SetGenerateDir sets the directory of where `go generate` will be run. Relative paths are okay and will be resolved with filepath.Abs.

                                                                                            func (*TinygoCompiler) SetLogWriter

                                                                                            func (c *TinygoCompiler) SetLogWriter(w io.Writer) *TinygoCompiler

                                                                                              SetLogWriter sets the writer to use for logging output. Setting it to nil disables logging. The default from NewCompiler is os.Stderr

                                                                                              func (*TinygoCompiler) SetTinygoArgs

                                                                                              func (c *TinygoCompiler) SetTinygoArgs(tinygoArgs ...string) *TinygoCompiler

                                                                                                SetTinygoArgs sets arguments to be passed to tinygo, e.g. -no-debug

                                                                                                func (*TinygoCompiler) SetTinygoDockerImage

                                                                                                func (c *TinygoCompiler) SetTinygoDockerImage(img string) *TinygoCompiler

                                                                                                  SetTinygoDockerImage will specify the docker image to use when invoking Tinygo. The default value is the value of when NewTinygoCompiler was called. If you specify an empty string then the "tinygo" command will be run directly on the local system.

                                                                                                  func (*TinygoCompiler) WasmExecJS

                                                                                                  func (c *TinygoCompiler) WasmExecJS() (r io.Reader, err error)

                                                                                                    WasmExecJS returns the contents of the wasm_exec.js file bundled with Tinygo.

                                                                                                    type WasmCompiler

                                                                                                    type WasmCompiler struct {
                                                                                                    	// contains filtered or unexported fields
                                                                                                    }

                                                                                                      WasmCompiler provides a convenient way to call `go generate` and `go build` and produce Wasm executables for your system.

                                                                                                      func NewWasmCompiler

                                                                                                      func NewWasmCompiler() *WasmCompiler

                                                                                                        NewWasmCompiler returns a WasmCompiler instance.

                                                                                                        func (*WasmCompiler) Execute

                                                                                                        func (c *WasmCompiler) Execute() (outpath string, err error)

                                                                                                          Execute runs the generate command (if any) and then invokes the Go compiler and produces a wasm executable (or an error). The value of outpath is the absolute path to the output file on disk. It will be created with a temporary name and if no error is returned it is the caller's responsibility to delete the file when it is no longer needed. If an error occurs during any of the steps it will be returned with (possibly multi-line) descriptive output in it's error message, as produced by the underlying tool.

                                                                                                          func (*WasmCompiler) SetAfterFunc

                                                                                                          func (c *WasmCompiler) SetAfterFunc(f func(outpath string, err error) error) *WasmCompiler

                                                                                                            SetAfterFunc specifies a function to be executed after everthing else during Execute().

                                                                                                            func (*WasmCompiler) SetBeforeFunc

                                                                                                            func (c *WasmCompiler) SetBeforeFunc(f func() error) *WasmCompiler

                                                                                                              SetBeforeFunc specifies a function to be executed before anything else during Execute().

                                                                                                              func (*WasmCompiler) SetBuildCmdFunc

                                                                                                              func (c *WasmCompiler) SetBuildCmdFunc(cmdf func(outpath string) *exec.Cmd) *WasmCompiler

                                                                                                                SetBuildCmdFunc provides a function to create the exec.Cmd used when running `go build`. It overrides any other build-related setting.

                                                                                                                func (*WasmCompiler) SetBuildDir

                                                                                                                func (c *WasmCompiler) SetBuildDir(dir string) *WasmCompiler

                                                                                                                  SetBuildDir sets the directory of the main package, where `go build` will be run. Relative paths are okay and will be resolved with filepath.Abs.

                                                                                                                  func (*WasmCompiler) SetDir

                                                                                                                  func (c *WasmCompiler) SetDir(dir string) *WasmCompiler

                                                                                                                    SetDir sets both the build and generate directories.

                                                                                                                    func (*WasmCompiler) SetGenerateCmdFunc

                                                                                                                    func (c *WasmCompiler) SetGenerateCmdFunc(cmdf func() *exec.Cmd) *WasmCompiler

                                                                                                                      SetGenerateCmdFunc provides a function to create the exec.Cmd used when running `go generate`. It overrides any other generate-related setting.

                                                                                                                      func (*WasmCompiler) SetGenerateDir

                                                                                                                      func (c *WasmCompiler) SetGenerateDir(dir string) *WasmCompiler

                                                                                                                        SetGenerateDir sets the directory of where `go generate` will be run. Relative paths are okay and will be resolved with filepath.Abs.

                                                                                                                        func (*WasmCompiler) SetLogWriter

                                                                                                                        func (c *WasmCompiler) SetLogWriter(w io.Writer) *WasmCompiler

                                                                                                                          SetLogWriter sets the writer to use for logging output. Setting it to nil disables logging. The default from NewWasmCompiler is os.Stderr

                                                                                                                          func (*WasmCompiler) WasmExecJS

                                                                                                                          func (c *WasmCompiler) WasmExecJS() (r io.Reader, err error)

                                                                                                                            WasmExecJS returns the contents of the wasm_exec.js file bundled with the Go compiler.

                                                                                                                            type WasmExecJSHandler

                                                                                                                            type WasmExecJSHandler struct {
                                                                                                                            	// contains filtered or unexported fields
                                                                                                                            }

                                                                                                                              WasmExecJSHandler calls WasmCompiler.WasmExecJS and responds with the resulting .js file. WasmCompiler.WasmExecJS will only be called the first time and subsequent times will return the same result from memory. (We're going to assume that you'll restart whatever process this is running in when upgrading your Go version.)

                                                                                                                              func NewWasmExecJSHandler

                                                                                                                              func NewWasmExecJSHandler(wc WasmExecJSer) *WasmExecJSHandler

                                                                                                                                NewWasmExecJSHandler returns an initialized WasmExecJSHandler.

                                                                                                                                func (*WasmExecJSHandler) ServeHTTP

                                                                                                                                func (h *WasmExecJSHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

                                                                                                                                  ServeHTTP implements http.Handler.

                                                                                                                                  type WasmExecJSer

                                                                                                                                  type WasmExecJSer interface {
                                                                                                                                  	WasmExecJS() (contents io.Reader, err error)
                                                                                                                                  }

                                                                                                                                    WasmExecJSer is implemented by WasmCompiler and TinygoCompiler.