Howl development
In this page, we’ll introduce Howl development and talk about some things you need to know when developing for Howl.
Running Howl for development
First off, you need to make sure that you’re building and running Howl directly
from the latest source. Chances are that you’re already doing so, but if you
currently run Howl from a binary package you want to clone the Howl
repo and build Howl from there (see the
instructions here for more details).
You can keep up with the latest changes for Howl by tracking the master
branch. While there’s no guarantee that you’ll never experience problems while
tracking the latest, the master
branch is intended to be stable at all times,
and is used as the base branch by the developers themselves on a daily basis.
As mentioned on the previously linked page, once Howl has been built from
source, there is two possible ways one might run it; you can either run it by
installing it and running it from the installed location (/usr/local/
by
default), or you can run it directly from the checkout directory. When
developing for, and making changes to Howl itself, the easiest option is to run
Howl directly from the checkout directory.
Rebuilding after changes
Howl has a minimal C core, and has some dependencies written in C as well, all
of which is compiled as you type make
. Nearly all of Howl is actually written
in Moonscript (and some Lua) however. While neither Moonscript or Lua is
compiled in the traditional sense, for Howl they are both compiled down to
LuaJIT byte code. This is done for performance reasons, as we are mindful of the
startup time for Howl.
While the use of byte code does not present a problem for end users who simply
install Howl once, it must be accounted for when making changes, or when trying
out others' changes. The most straight forward way of making sure that byte
code, etc., is updated after sources have changed is to remake again (i.e. cd
src && make
). While this will always work (and is required for the rare changes
to the C core), it’s also slow. For the typical workflow where you edit a source
file and save it, only the byte code needs to be updated. Fortunately, Howl
automatically updates this for you when it can, so it’s something that you
shouldn’t have to consider. This will work out of the box as long as you run
Howl directly from within the checkout directory - any Moonscript or Lua files
below the checkout directoy will have their byte code versions updated
automatically as you save them.
While the recommended way of developing for Howl is to simply run it from within
the checkout directory, it’s also possible to explicitly instruct Howl to update
byte code for files within another directory. In this scenario one might for
instance run Howl from an installed stable version, and do development in the
ordinary checkout directory. Since Howl cannot reasonably be expected to try and
save byte code for arbitrary files scattered all over your file system, you have
to specify the Howl source directory explicitly in this case. The configuration
variable howl_src_dir
can be used for this. For instance, you can set it like
this in your Howl configuration (example using ~/.howl/init.moon
):
{:config} = howl {:File} = howl.io config.howl_src_dir = File.expand_path('~/code/howl')
Running the specs (tests)
Howl has a whole lot of specs that verify different aspects of its behaviour.
These are written using the busted testing
framework (the stable 1.* version, not the unstable pre-2.* version). Starting
with the 0.5 release, Howl bundles all dependencies needed for running the
specs, so you don’t have to worry about manually installing busted
, or
luarocks
, etc. Instead, simply run the howl-spec
script (located in the
bin/
directory), specifying the spec or specs you want to run. You can either
specify individual files to run, or specify the path to a directory, in which
case all specs below that directory will be run. Note that you’ll need to run
the howl-spec
script from within the project root, like so:
[howl-dir] $ ./bin/howl-spec <path-to-file-or-directory>
Since running specs manually can get quite tedious, e.g. when doing test driven development, you can run a watcher of some sort that will automatically run the right specs as files are changed. Howl ships with a ready-made Spookfile that can be used with the spook utility (a Lua based file watcher). If you install spook, then simply run it in the project root in order to run specs as files are changed.