This document will guide you through setting up Fennel on your computer. This document assumes you know how to run shell commands and edit configuration files in a UNIX-like environment.
Note: Fennel can be used in non-UNIX environments, but those environments will mostly not be covered in this document.
Fennel does not contain any telemetry/spyware and never will.
Downloading Fennel on your computer allows you to run Fennel code and compile to Lua. You have a few options for how to install Fennel.
Depending on what package manager you use on your system, you may be
able to use it to install Fennel. See the wiki for a list of
packaging systems which offer Fennel. Packaged versions of Fennel may
lag behind the official releases and often only support one version at a
time, but they tend to be the most convenient. For instance, if you use
Fedora, it should be as easy as running
sudo dnf install fennel.
This method assumes you have Lua 5.1, 5.2, 5.3, 5.4, or LuaJIT installed on your system.
This method requires you to manually update the fennel
script when you want to use a newer version that has come out.
chmod +x fennel-1.4.2 to make it executablegpg --verify fennel-1.4.2*.asc
(optional but recommended).fennel-1.4.2 to a directory on your
$PATH, such as /usr/local/binNote: You can rename the script to
fennel for convenience. Or you can leave the version in the
name, which makes it easy to keep many versions of Fennel installed at
once.
Downloading a Fennel binary allows you to run Fennel on your computer without having to download Lua, if you are on a supported platform. If you already have Lua installed, it's better to use the script above.
This method requires you to manually update the fennel
binary when you want to use a newer version that has come out.
chmod +x fennel-1.4.2* to make it executablegpg --verify fennel-1.4.2*.asc (optional but
recommended).$PATH, such as /usr/local/binFennel code can be embedded inside of applications that support Lua either by including the Fennel compiler inside of the application, or by performing ahead-of-time compilation. Embedding Fennel in a program that doesn't already support Lua is possible but outside the scope of this document.
Note: Embedding the Fennel compiler in an application is the more flexible option, and is recommended. By embedding the Fennel compiler in an application, users can write their own extension scripts in Fennel to interact with the application, and you can reload during development. If the application is more restricted, (for instance, if you can only embed one Lua file into the application and it cannot access the disk to load further files) then compiling Fennel code to Lua during the build process and including the Lua output in the application may be easier.
There are so many ways to distribute your code that we can't cover them all here; please see the wiki page on distribution for details.
The Fennel compiler can be added to your code repository, and then loaded from Lua.
fennel.lua library. You can get this from a release
tarball or by running make in a source checkout.fennel.lua to your code repository.require("fennel").install().dofile("main.fnl")You can pass options to the fennel compiler by
passing a table to the install function.
Be sure to use the fennel.lua library and not the file
for the entire fennel executable.
If the target system of your application does not make it easy to add
the Fennel compiler but has Lua installed, Fennel offers ahead-of-time
(AOT) compilation. This allows you to compile .fnl files to
.lua files before shipping an application.
This section will guide you through updating a Makefile
to perform this compilation for you; if you use a different build system
you can adapt it.
Add the following lines to your Makefile:
%.lua: %.fnl fennel
./fennel --compile $< > $@Ensure your build target depends on the .lua files
you need, for example, if every .fnl file has a
corresponding .lua file:
SRC := $(wildcard *.fnl)
OUT := $(patsubst %.fnl,%.lua,$(SRC))
myprogram: $(OUT)
[...]Note 1: Ahead-of-time compilation is also useful if what you are working with requires optimal startup time. "Fennel compiles fast, but not as fast as not having to compile." -- jaawerth
Note 2: It's recommended you include the
fennel script in your repository to get consistent results
rather than relying on an arbitrary version of Fennel that is installed
on your machine at the time of building.
You can write Fennel code in any editor, but some editors make it more comfortable than others. Most people find support for syntax highlighting, automatic indentation, and delimiter matching convenient, as working without these features can feel tedious.
Other editors support advanced features like an integrated REPL, live reloading while you edit the program, documentation lookups, and jumping to source definitions.
See the wiki for a list of editors that have Fennel support.
If your editor supports the Language Server Protocol (LSP) then you can install fennel-ls to get highlighting of errors and improved navigation.
The command-line REPL that comes with the fennel script
works out of the box, but the built-in line-reader is very limited in
user experience. Adding GNU
Readline support enables user-friendly features, such as:
ctrl+r), and optionally persisted to disk so you can
search input from previous REPL sessions~/.inputrc, such as blinking on matched parentheses or
color output (described below)See the wiki page on readline for details of how to install and configure it on your system.
The two main platforms for making games with Fennel are TIC-80 and LÖVE.
TIC-80 is software that acts as a simulated computer in which you can write code, design art, compose music, and lay out maps for games. TIC-80 also makes it easy for you to publish and share the games you make with others. TIC-80 introduces restrictions such as low resolution and limited memory to emulate retro game styles.
LÖVE is a game-making framework for the Lua programming language. LÖVE is more flexible than TIC-80 in that it allows you to import from external resources and use any resolution or memory you like, but at a cost in that it is more complicated to make games in and more difficult to run in the browser.
Both TIC-80 and LÖVE offer cross-platform support across Windows, Mac, and Linux systems, but TIC-80 games can be played in the browser and LÖVE games cannot without more complex 3rd-party tools.
The Fennel wiki links to many games made in both systems you can study.
Support for Fennel is built into TIC-80. If you want to use the
built-in text editor, you don't need any other tools, just launch TIC-80
and run new fennel in its console to get started.
The TIC-80 wiki documents the functions to use and important concepts.
All TIC-80 games allow you to view and edit the source and assets. Try loading this Conway's Life game to see how it's made:
LÖVE has no built-in support for Fennel, so you will need to setup support yourself, similar to Embedding Fennel above.
This project skeleton for LÖVE shows you how to setup support for Fennel and how to setup a console-based REPL for debugging your game while it runs.
You can reference the LÖVE wiki for Lua-specific documentation. Use See Fennel to see how any given Lua snippet would look translated to Fennel.