rrthomas / slingshot

Slingshot releases rocks!

SLINGSHOT

Slingshot releases rocks!

The files shipped with this project form the common foundation I use to manage LuaRocks releases from github for all my other projects. This promotes the good programming trait of laziness by saving me from having to manually propagate improvements to my release process between them all every-time I update.

Installation

Incorporating Slingshot into your project involves copying the Slingshot bootstrap script into your project root directory and checking it in. You should probably write and check in a project bootstrap.conf with a list of files you want slingshot to manage for you in the slingshot_files variable.

Running bootstrap after that will set up a Slingshot git submodule, along with requisite .gitmodules file, and link any slingshot managed files nominated into your project tree.

• bootstrap:

  a complete rewrite of the GNU Gnulib bootstrap script, for figuring out what autotools need to be run, in what order, and with what arguments to bootstrap a newly checked out working copy. This version is much more robust, a lot more user friendly, slightly faster, and a little more portable than the GNU version. It's also quite a lot larger than the GNU implementation.

  Note that the Slingshot bootstrap script has extra functions compared to the Libtool bootstrap on which it is based, and the two are not interchangable!

• docs/bootstrap.texi:

  texinfo documentation for bootstrap.

Alternatively, pick and choose whichever of the following files you want to make use of into your project, and either list them in a slingshot_files variable in your bootstrap.conf (or just copy them to your project and check them in, as long as you don't care about automatically keeping them in sync with future releases):

• gitlog-to-changelog, do-release-commit-and-tag:

  adapted from the GNU Gnulib project, with changes for portability and applicability to a Lua based project.

• ax_lua.m4:

  taken from the GNU Autoconf Archive, to help autoconf discover where Lua and its files are installed on your system.

• configure.ac:

  wrapper for the macros above, currently generates a configure that turns mkrockspecs.in into mkrockspecs, and generates a manual page for the same - though you can use it as the basis for your own configure.ac with a little editing.

• merge-sections:

  given a list of files with section headers in boxes like this:

  -------------

  Section Name.

  -------------

  this script merges those sections into identically named sections from standard input. This script is used by Slingshot itself to merge additional functions into the upstream bootstrap script.

• mkrockspecs:

  take a set of defaults (see slingshot's own rockspec.conf) from a YAML format specification, fill in the missing entries, and output a full LuaRocks rockspec file.

• rockspecs.mk:

  a portable make fragment to drive the mkrockspecs script, which you can include in your Makefile.am.

• release.mk:

  a set of GNU make maintainer rules to run pre-release checks, build a distribution tarball, and then switch to the git release branch and check-in the unpacked distribution files. Finally, the resulting release check-in is tagged so that the rockspecs files generated by mkrockspecs can fetch the associated github generated zipball attached to that tag.

• sanity.mk:

  a port of the gnulib sanity check rules hooked into the pre-release process by default.

• GNUmakefile:

  a wrapper for release.mk, along with auto-rebootstrap rules.

• Makefile.am:

  a wrapper for rockspecs.mk, as a starter for your own Makefile.am.

• travis.yml.in:

  configuration for the free gitub Travis CI service.

• .autom4te.cfg:

  some autotools configuration to avoid the annoying autom4te.cache directory that gets dropped everywhere. You can copy this to ~/.autom4te.cfg to turn off the cache globally.

In addition to the files above, slingshot expects you to maintain your release notes in a GNU format NEWS file, such as the one used by slingshot itself, and a revision controlled .prev-version file with the previous release version number. release.mk will maintain these files for you once you have them in place.

You'll also need a rockspec.conf file to feed the mkrockspecs script, and probably a local.mk with your project specific build rules.

Usage

Use ./bootstrap to run autotools (you can customize the behaviour of this script with a bootstrap.conf file, as described in the bootstrap.texi documentation).

GNUmakefile will run bootstrap for you, even in a freshly checked out tree, provided you pass it a target to build.

Use make rockspecs to trigger the rules in rockspecs.mk which will use the values from AC_INIT in configure.ac and rockspec.conf to build project specific rockspec files, suitable for uploading to luarocks.org.

Use make stable (or make alpha, or make beta if appropriate) to locally run the pre-release sanity checks, the release itself, and some post-release administration. These rules only affect your local git repository, and don't push the changes back to origin.

Use make release RELEASE_TYPE=stable to perform a full release process, including pushing changes back to origin, and mailing an announcement taken from the NEWS file. You can override the mail addresses by setting announce_emails and rockspec_emails in your local.mk fragment.