Add Getting Started, update readme

Getting Started.md

@@ -0,0 +1,148 @@
+As I've been getting a lot of questions on how to actually use the scripts in
+this repository, here is some more information to get you started.
+
+## Building a portable love distribution using the docker container ##
+By far the easiest way to build a portable tarball, AppImage and Snap is by
+using the docker container. You can build the container yourself (see `docker
+build`) but I recommend saving yourself some time and effort and using the
+container from DockerHub. A (complete!) example of how to use this is as
+follows:
+
+```sh
+docker run --rm -v /path/to/repo:/build/love-linux-builder bartbes/love-linux-builder:x86_64 0.10.2
+```
+
+The docker container runs the script located in `docker/build.sh`, but here's a
+brief overview:
+
+ - The existing repo is used. Both so you can customise the scripts, or the
+   resulting builds see [building portable game distributions][]. The path is
+   set using the `-v /path/to/repo:/build/love-linux-builder` argument, as seen
+   above. Here the first part is the path to this repo on your local machine,
+   and the second part is the destination path in the container. All resulting
+   build artifacts end up in the repo.
+
+ - The argument passed to the script (in the example `0.10.2`) is used to
+   determine the version for the scripts. If there is no matching tarball, the
+   container will build one.
+
+ - If building a tarball, it will first see if `/build/love` contains a
+   love(-like) repository. If not, it clones the main love repo. This is a
+   customisation point if you want to use a modified build of love. To specify
+   your own repo, you can specify an argument to `docker run` as follows:
+   `-v /path/to/love-repo:/build/love`
+
+ - The container will now build a Snap and an AppImage. Unfortunately, the
+   Flatpak script is not supported, as Flatpak does not run on a distro this
+   old.
+
+## Building a portable love distribution manually ##
+The first step in getting building portable binaries is getting a tarball. The
+rest of the scripts use the tarball as input.
+
+### Building a tarball ###
+This is the hardest step of them all. To build a tarball of (mostly) portable
+binaries, the key is to use the oldest distro you're willing to support. I, and
+the docker container, use Debian Wheezy (aka Debian 7 aka Debian oldoldstable),
+as binaries built for it will run on practically any machine reasonably used
+for running games.
+
+On said distro, build and install love. It is very likely the distro you
+selected does not have (recent) love packages and lacks some dependency, like
+SDL2 and LuaJIT. Unfortunately the steps for this are highly distro-specific
+(and version-specific), so you're on your own for this bit. If you're building
+from source, make sure to run `make install` to install love system-wide.
+
+Once you've got love installed on that machine, running the `build.sh` script
+in the tarball directory will extract the love binaries and its dependencies
+and copy them to a directory. It also adds a template desktop file, a love icon
+and a launcher script that sets up the correct library paths. Surprisingly, it
+doesn't actually tar the resulting directory.
+
+*NOTE: The build script also copies in a license.txt file if it exists. For
+legal reasons, don't forget to add it!*
+
+The rest of the scripts expect a tarball in the tarball directory, which you
+can now create like this:
+
+```sh
+tar czf "love-0.10.2-x86_64.tar.gz" dest
+```
+
+Substitute the relevant version number and architecture, of course.
+
+### Building an AppImage ###
+Now you've got the tarball, most of the hard work is done. Go to the AppImage
+directory and run the build script with as single argument the version number
+as specified in the tarball name. For example:
+
+```sh
+./build.sh 0.10.2
+```
+
+It will use the current system architecture as target architecture, so if you
+want to build 32-bit binaries on a 64-bit system you can use the `setarch`
+program.
+
+NOTE: The AppImage script automatically downloads some binaries if you don't
+already have them. In theory, you don't need to install anything to build an
+AppImage.
+
+### Building a Flatpak ###
+Like the AppImage script, building a Flatpak is as easy as running the script
+with the right version. For example:
+
+```sh
+./build.sh 0.10.2
+```
+
+It will push the resulting data to a Flatpak repo located in `flatpak/repo`
+(can be overridden by setting the `REPO` environment variable) and it then
+builds a bundle. To build a Flatpak, you will need to have the Flatpak tools
+installed.
+
+### Building a Snap ###
+The Snap script, surprisingly, works exactly the same as the others. For
+example:
+
+```sh
+./build.sh 0.10.2
+```
+
+Unfortunately, the Snap is the least complete. If you're looking to build a
+proper snap, you probably need to customise the YAML file `snap/snap.yaml`.
+Like the AppImage script, it requires no snap-specific dependencies, though it
+does require the SquashFS tools to be installed (in particular `mksquashfs`).
+Most distros provide the tools in their repos, and they're even commonly
+pre-installed.
+
+## Building portable game distributions ##
+The AppImage and Flatpak scripts provide customisation points so you can build
+distributions of your game instead. All these files need to go in the root
+directory of the repo.
+
+Both AppImage and Flatpak:
+
+ - `game.love`: A .love file of your game. Will be fused with the love binary
+   in the resulting AppImage/Flatpak.
+
+ - `game.desktop.in`: A [desktop file][] for your game. See
+   `tarball/love.desktop.in` for inspiration. Note that you want to specify
+   `%BINARY%` as application name and `%ICON%` as icon name, since the scripts
+   will override these with the relevant paths.
+
+ - `game.svg`: An icon for your game. Used both for the desktop file and for
+   the metadata.
+
+Flatpak only:
+
+ - `game.rdns`: A reverse domain name that identifies your game. Love itself
+   uses `org.love2d.love`. I *strongly discourage* using the love domain name.
+   Please be a nice citizen of the internet and use your own domain name.
+
+ - `game.version`: A version number to display in the application metadata.
+
+For Snap users there is no inbuilt customisation at the moment. You can modify `snap/snap.yaml`.
+
+[building portable game distributions]: #markdown-header-building-portable-game-distributions
+[desktop file]: https://standards.freedesktop.org/desktop-entry-spec/latest/

README.md

@@ -6,6 +6,8 @@ This project is split up into multiple parts, and each part is responsible for
 a different build. Note that the `tarball` build is used as a base for the
 other builds.
 
+See [Getting Started][] for more information on how to use these scripts.
+
 ## tarball ##
 `tarball` contains a build script that extracts the love version currently
 installed on the system together with its dependencies to form a portable
@@ -20,8 +22,9 @@ to do everything for you, why not just do it manually?! Seriously though, you
 can still use snapcraft to build this, but at that point it just acts like a
 fancy mksquashfs, and an extra dependency at that.
 
-NOTE: I haven't been able to run the built snaps yet, but that seems to be a
+NOTE: Due to nvidia driver issues I haven't been able to test these snaps yet.
-driver issue, possibly related to Arch Linux. Let me know if it works for you!
+From what I can tell these issues have been fixed since the last time I tried.
+Let me know if you get them working so I can remove this note.
 
 ## appimage ##
 `appimage` builds [AppImages][AppImage], unsurprisingly. It uses binaries from
@@ -33,9 +36,6 @@ this actually seems to work, too!
 command line tool. Of course flatpak has some kind of repo system, so you can't
 easily distribute a flatpak file. Useful.
 
-NOTE: Once again driver issues (blame nvidia) prevent me from testing this
-myself. If you get it working, let me know!
-
 ## docker ##
 `docker` does not build docker images. Instead it builds a docker image so you
 can build portable packages yourself!
@@ -54,3 +54,4 @@ branch or commit.
 [AppImage]: http://appimage.org/
 [AppImageKit]: https://github.com/probonopd/AppImageKit
 [flatpak]: http://flatpak.org/
+[Getting Started]: Getting%20Started.md