From f4c04f37757d1cda4fae9aa91ad72bc633b83094 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Sun, 26 Sep 2021 16:03:49 -0400 Subject: cli: Add bundle subcommand. --- doc/chickadee.texi | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) (limited to 'doc') 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 -- cgit v1.2.3