-
Notifications
You must be signed in to change notification settings - Fork 126
Distribution
Because Fennel can be used in so many different contexts, it can be difficult to know how to prepare your code so it can be used by others. Here is a selection of different methods and tips for how to work with them:
For certain kinds of programs, you don't need any fancy distribution
mechanism beyond simply running from a source checkout. In this case
it's best to simply include a copy of the standalone fennel Lua
script (from running make fennel in the Fennel codebase) in your
repository.
For instance, the pengbot IRC bot can be run just by
executing make run in a source checkout:
run:
./fennel pengbot.fnl $(SERVER) $(PORT) $(NICK) $(CHANNEL)
If you have a standalone Fennel script that doesn't use any C
libraries, the easiest way to distribute it for others to use is to
compile it to Lua and put a #!/usr/bin/env lua shebang at the top of
the file output. This will run on any system that already has Lua
installed.
$ echo "#!/usr/bin/env lua" > myprogram
$ fennel --require-as-include --compile myprogram.fnl >> myprogram
$ chmod 755 myprogram
The --require-as-include flag will make it so your compiled program
includes any files required directly. It will not include transitive
requires from Lua, so you may need to directly require some of those
modules which you wouldn't otherwise need.
If you want to distribute something that works on systems that don't
already have Lua, you can compile a binary that includes Lua along
with your program using the --compile-binary flag. You will have to
compile a separate binary for every OS+architecture you want to
support, but this can be completely standalone.
You can include a Makefile rule which fetches and compiles the version
of Lua you want to use, and cross-compiles it by setting CC:
LUA_VERSION=5.4.2
LUA_DIR=lua-$(LUA_VERSION)
$(LUA_DIR): ; curl http://www.lua.org/ftp/lua-$(LUA_VERSION).tar.gz | tar xzf /dev/stdin
$(LUA_DIR)/src/liblua.a: $(LUA_DIR) ; make -C $^
myprogram: myprogram.fnl $(LUA_DIR)/src/liblua.a
./fennel --compile-binary $< $@ lua-$(LUA_VERSION)/src/liblua.a $(LUA_DIR)/src
myprogram.exe: myprogram.fnl $(LUA_DIR)/src/liblua-mingw.a
CC=i686-w64-mingw32-gcc ./fennel --compile-binary $< myprogram \
$(LUA_DIR)/src/liblua-mingw.a $(LUA_DIR)/src
$(LUA_DIR)/src/liblua-mingw.a: $(LUA_DIR)
$(MAKE) -C $(LUA_DIR)/src CC=i686-w64-mingw32-gcc \
"AR=i686-w64-mingw32-gcc -shared -o" \
"RANLIB=i686-w64-mingw32-strip --strip-unneeded" clean liblua.a
mv $(LUA_DIR)/src/liblua.a $@
On a Debian-based system, the gcc-mingw-w64-i686 package must be
installed to cross-compile Windows binaries; other OSes may provide it
under a different name.
The --compile-binary method can also be used to distribute standalone
programs that use C libraries, but it's more complicated and doesn't
always work with all libraries; see the HTTP page for details.
One of the most popular uses of Fennel is to create games with the LÖVE framework. The min-love2d-fennel project skeleton provides everything you need to get started.
The included Makefile can create executables for Windows, Mac OS, and
Linux-based systems as well as .love files which are portable to any
system if you install the LÖVE framework manually. It also supports
automating publishing to itch.io, the fabulous game hosting
web site.
In this case, all the Fennel code is loaded from .fnl files during
development, but then precompiled into .lua code for
distribution. This allows a nice tight feedback loop during
development but doesn't involve the compiler unnecessarily later on.
TODO: someone should write this who uses luarocks!