cli: Add bundle subcommand.

1 files changed, 124 insertions, 0 deletions

diff --git a/doc/chickadee.texi b/doc/chickadee.texi
index 0585688..f561bae 100644
--- a/doc/chickadee.texi
+++ b/doc/chickadee.texi
@@ -182,6 +182,7 @@ line utility to make it easier to get started.
 
 @menu
 * Invoking chickadee play::     Run Chickadee programs
+* Invoking chickadee bundle::   Create redistributable binary bundles
 @end menu
 
 @node Invoking chickadee play
@@ -279,6 +280,129 @@ REPL server.
 
 @end table
 
+@node Invoking chickadee bundle
+@section Invoking @command{chickadee bundle}
+
+Distributing games is difficult.  While Chickadee games are free
+software, it would be far too burdensome on the player to ask them to
+compile a game from source in order to try it out.  Many potential
+players will simply not even try.  Players expect to be able to
+download a compressed archive, extract it, and play.  If there are any
+more steps than that then the chances of the game being played drop
+dramatically.  If you can't beat 'em, join 'em.  The
+@command{chickadee bundle} tool creates redistributable binary bundles
+by combining the game code and assets with shared libraries and
+executables from the host operating system.
+
+Bundling is currently only supported on Linux.  In the future, it may
+be possible to bundle on MacOS.  Patches very much welcome for that.
+
+It should be noted that bundling is a problematic way to distribute
+software.  All of the libraries that the bundled application includes
+are separated from the distribution that was so carefully making sure
+that they stay up-to-date with regard to security patches.  The
+bundled libraries are frozen in time, vulnerabilities and all.
+Unfortunately, the release model used by the most popular
+distributions, while wonderful for stable, mature software, does not
+fit the needs of game distribution at all.  So, we compromise, knowing
+that most games are only played for only a short amount of time before
+being disposed.  Perhaps, in time, the Linux world will shift to using
+more robust package management solutions such as
+@url{https://guix.gnu.org, GNU Guix} which support long-term
+maintenance of stable software as well as the ``fire and forget''
+nature of game releases.  And maybe a game made with Chickadee will
+become so popular that major distributions decide to package it, but
+let's get back to reality.
+
+To get started with bundling, simply add a @file{bundle.scm} file to
+the root of the project directory.  It could look something like this:
+
+@example
+'((asset-directories . ("images" "models"))
+  (bundle-name . "the-legend-of-emacs-1.0")
+  (code . "the-legend-of-emacs.scm")
+  (launcher-name . "the-legend-of-emacs"))
+@end example
+
+To create the bundle, simply run @command{chickadee bundle}.  Upon
+success, the file @file{the-legend-of-emacs-1.0.tar.gz} would be
+created in the current directory.
+
+To maximize the chances that the bundle will work on someone else's
+computer, it's best to build on the oldest supported Linux
+distribution available.  As of this writing, Ubuntu 18.04 LTS is a
+good choice.
+
+In addition to including system libraries and executables,
+@command{chickadee bundle} also includes the compiled Guile bytecode
+(the @file{.go} files) for all modules used by the game.  The module
+source files are @emph{not} included, so it's critical that all of the
+modules used by the game have been compiled.
+
+Available options:
+
+@itemize
+
+@item @code{asset-directories}
+
+A list of directories that hold static game assets such as images or
+audio.  Files in these directories will be copied into the bundle
+archive.
+
+@item @code{binary-directories}
+
+A list of directories to search for system binaries, such as
+@command{guile}.  By default, @file{/usr/bin} is searched.
+
+@item @code{bundle-name}
+
+The name of the bundle archive.  By default, the name is
+@code{"chickadee-bundle"}.
+
+@item @code{launcher-name}
+
+The name of the launcher script.  By default, the name is
+@code{"launch-game"}.
+
+@item @code{libraries}
+
+A list of shared libraries to include in the bundle.  By default, all
+of the libraries necessary for running Guile, Guile-SDL2, and
+Chickadee are included.  This list is compatible with the names given
+to the libraries on Ubuntu, which may be different than on other
+distributions.  In such cases, this list will need to be customized.
+See below for more information on the @code{%default-config} variable
+that can be of help.
+
+@item @code{library-directories}
+
+A list of directories to search for system shared libraries.  By
+default, the list contains common directories used by most
+distributions.
+
+@item @code{method}
+
+The method by which the game is launched.  Can be either @code{play}
+or @code{manual}.  The default is @code{play}, which means that
+@command{chickadee play} will be used to launch the game.  For games
+that do not use @command{chickadee play}, opting to start the game
+loop on their own, the @code{manual} method should be used.
+
+@item @code{play-args}
+
+A list of command line arguments to pass to @command{chickadee play}.
+Only used when the @code{method} option is set to @code{play}.
+
+@end itemize
+
+Default configuration options, such as the list of C shared libaries,
+can be found in the @code{%default-config} variable.  This way they
+can be programatically modified, if necessary.
+
+@defvar %default-config
+An association list of default configuration options.
+@end defvar
+
 @node Live Coding
 @chapter Live Coding