Documentation
¶
Overview ¶
Package static is a library that helps automate creating the static directory of files for the webapp to function. It, along with lib/build/api, is one half of the build process to produce a functioning webapp given a config.json
All of the steps it does could be done by hand, but they are finicky and error prone, so this library helps take the guess work out of them.
Build() is the primary entrypoint for this package, which composes all of the build steps, which are themselves exposed as public methods int his package, in the right order.
All build methods in this package take a dir parameter. This is the directory to produce the build into. In particular, these methods will create a `static` subdirectory in dir and work inside of that. dir may be "", which will create the static sub-folder within the current directory. Tools like `boardgame-util serve` create a temporary directory and use that, so it's easy to clean up later.
Various steps of the build symlink other files and folders into the created static build directory, for example when we symlink in the client directories of each game into game_src. These symlinks use relative paths, not absolute paths. This means that if all of the packages (including the current repo) are in the canonical location in $GOPATH (and modules are not enabled), then these relative symlinks are OK to check in to a source control repo because they should work reasonably on other systems. However, typically you don't check in the results of the static build into source control, and instead use `boardgame-util serve`, which creates a temporary directory for the build each time.
The steps of the build process, at a high level, are as follows:
First, create the `static` sub directory, if it doesn't already exist. All following steps create files and directories within that static subfolder.
Next, it copies over all of the static resources (no directories) from `github.com/jkomoros/boardgame/server/static`, skipping a handful of files that will be generated later. These files are symlinked by default, but can also be copied. This step is encapsulated by CopyStaticResources.
Next, it creates a node_modules folder that contains up to date dependencies given the contents of `github.com/jkomoros/boardgame/server/static/package.json`. Checking out this whole directory is expensive, so this package creates a node_modules in a central cache, re-upping it each time this command is run (unless skipUpdate is true), and then symlinks it into the static directory. This step is encapsulated by LinkNodeModules.
Next, it generates a `client_config.js`, which encodes the global configuration for the client webapp. It calls config.Client(false) and saves the result to static/client-config.js, which index.html will look for when booting up. This step is encapsulated by CreateClientConfigJs.
Next, it copies in the client folders (containing boardgame-render-game- GAMENAME.js, and optionally boardgame-render-player-info-GAMENAME.js) into static/game-src. It does this by locating the on-disk location of each gameImport given by gameImports (typically this is configMode.Games), then symlinking its client folder into `static/game-src/GAMENAME`. In a modules context, game packages that do not yet exist on disk will be downloaded automatically; if you are not using modules and you have not yet `go get` the given game imports or a containg package, it will error. This step is encapsulated by LinkGameClientFolders.
Next, it generates a `static/polymer.json`, which contains fragments entries for each dynamic import--specifically, the `game-src/GAMENAME /boardgame-render-game-GAMENAME.js` and `game-src/GAMENAME/boardgame- render-player-info-GAMENAME.js`, if it exists. It identifes the fragments to include by walking through all of the game directories in `game-src`, meaning it relies on the output of the previous step. It then saves this generated file to `static/polymer.json`. This step is encapsulated by CreatePolymerJson.
The static build is now mostly complete. Optionally, BuildPolymer can be called to run `polymer build` on the generated static dir. This step is encapsulated by BuildPolymer.
Typically direct users of this package use Build(), which automatically runs these steps in the proper order.
Clean() removes the static build contents from the given build directory (specifically, it removes the `static` subdirectory and all of its contents). LinkNodeModules also might create (or update) a shared cache directory of node_modules on the system, and CleanCache() removes that cache.
Server() is a simple development server that makes the static resources available at `localhost:PORT`. Polymer requires that imports use bare module specifiers, which means that a naive local serve is not sufficient because the import URLs must be lightly rewritten, so this Server() is necessary. Under the covers it uses `polymer serve`.
Typically you don't use this package directly, but use `boardgame-util build static` or `boardgame-util serve`.
Index ¶
- func Build(directory string, pkgs []*gamepkg.Pkg, c *config.ClientConfig, prodBuild bool, ...) (assetRoot string, err error)
- func BuildPolymer(dir string) error
- func Clean(directory string) error
- func CleanCache() error
- func CopyStaticResources(dir string, copyFiles bool) error
- func CreateClientConfigJs(dir string, c *config.ClientConfig) error
- func CreatePolymerJSON(dir string, missingFragmentsErrors bool) error
- func LinkGameClientFolders(dir string, pkgs []*gamepkg.Pkg) error
- func LinkNodeModules(dir string, skipUpdate bool) error
- func Server(directory string, port string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Build ¶
func Build(directory string, pkgs []*gamepkg.Pkg, c *config.ClientConfig, prodBuild bool, copyFiles bool, skipNodeUpdate bool) (assetRoot string, err error)
Build creates a folder of static resources for a server in the given directory. It is the primary entrypoint for this package. It has no logic of its own but serves to call all of the build steps in the correct order.
Specificlaly, it calls: CopyStaticResources, passing copyFiles; LinkNodeModules, passing skipNodeUpdate; CreateClientConfigJs, passing c; LinkGameClientFolders, passing gameImports; CreatePolymerJson, passing false. If prodBuild is true, also calls BuildPolymer.
See the package doc for more about the specific build steps and what they do.
func BuildPolymer ¶
BuildPolymer calls `polymer build` to build the bundled version within a given build directory. Will error if the build directory doesn't include polymer.json (which CreatePolymerJson will have created).
func CleanCache ¶
func CleanCache() error
CleanCache clears the central cache the build system uses (currently just node_modules). If that cache doesn't exist, is a no op.
func CopyStaticResources ¶
CopyStaticResources copies all of the top-level files into the build directory given by dir. If copyFiles is true, it copies them, otherwise it symlinks them.
func CreateClientConfigJs ¶
func CreateClientConfigJs(dir string, c *config.ClientConfig) error
CreateClientConfigJs creates and saves a client_config.js corresponding to the given Clientconfig object, into the given build directory. You should use config.Client() to generate the ClientConfig.
func CreatePolymerJSON ¶
CreatePolymerJSON outputs a polymer.json in the given build folder that includes fragments for all of the valid game directories that exist in the build folder's game-src directory. If missingFragmentsError is true, then if there are missing fragments we will return an error. Otherwise, will print a message for missing fragments but not error.
func LinkGameClientFolders ¶
LinkGameClientFolders creates a game-src directory and for each import listed in pkgs, finds a copy of that game on disk and symlinks its client directory into game-src.
func LinkNodeModules ¶
LinkNodeModules symlinks a node_modules folder into the build directory given by dir, that is fully up to date based on the resources required. node_modules is cached in a known cache on the system, and only topped up as necessary, so only the first call to this on a given system should be particularly expensive (or after CleanCache()) has been called. Returns an error if node_modules can't be updated or if it can't be linked in. If skipUpdate is true, then if node_modules exists we won't try to update. Useful if you're in an offline context.
Types ¶
This section is empty.
Source Files