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.
Fennel can be used in non-UNIX environments, but those environments will not be covered in this document.
- Access to a UNIX-like environment, such as Ubuntu, Debian, Arch Linux, Windows Subsystem for Linux, Homebrew, scoop.sh, etc.
- Lua version 5.1, 5.2, 5.3, or LuaJIT
- LuaRocks or Git and Make
Downloading and installing Fennel on your system allows you to run Fennel scripts. Currently, you can download and install Fennel using Git or LuaRocks.
Depending on which method you want to use, choose a subsection below:
Tip: If you are using software that supports Fennel, such as TIC-80, you do not need to download Fennel, because you can use it inside of TIC-80.
Downloading and installing Fennel using Git allows you to use versions of Fennel that haven't been released yet and makes contributions to Fennel easier.
cdto a directory in which you want to download Fennel, such as~/src- Run
git clone https://github.com/bakpakin/Fennel
- Run
cd Fennel - Run
make fennel - Copy or link the
fennelscript to a directory on your$PATH, such as/usr/local/bin
Note 1: Step 2 above will compile Fennel into a standalone script
called fennel.
Note 2: If the fennel script exists in one of the directories on
your $PATH , you can run fennel filename.fnl to run a Fennel file.
LuaRocks contains a repository of Lua software packages. LuaRocks is convenient because it automates the downloading, installation, and uninstallation of Lua software packages.
- Ensure the
luarockspackage is installed on your system - Ensure the
~/.luarocks/bindirectory is added to your shell's$PATH - Run one of
luarocks install fennelto install globally (requires admin or sudo)luarocks --local install fennelto install locally (see the note below about paths)
Note: When using luarocks with --local, you'll need to ensure you have
the correct lua path values. You can run eval $(luarocks path --bin) from
your shell to set this correctly; see LuaRocks path docs
for details.
You can try running fennel --help to confirm the
installation succeeded.
Fennel code can be embedded inside of Lua applications by including the Fennel compiler inside of a Lua application, or by performing ahead-of-time compilation.
This section consists of the following subsections:
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, then compiling Fennel code to Lua during the build process and including the Lua output in the application may be easier.
The Fennel compiler can be added to your code repository, and then loaded from Lua.
- Add
fennel.luato your code repository - Add the following lines to your Lua code:
local fennel = require("fennel")
table.insert(package.loaders or package.searchers, fennel.searcher)
local mylib = require("mylib") -- will compile and load code in mylib.fnlNote: Optionally, if you want the Fennel REPL to print tables
in a more readable format, you can add fennelview.fnl to
your code repository. For more helpful compiler errors, you can add
fennelfriend.fnl to your code repository.
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
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.
- Add the following lines to your
Makefile:
%.lua: %.fnl fennel
./fennel --compile $< > $@
- Ensure your build target depends on the
.luafiles you need.
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.
If your favorite editor isn't listed here, that's OK; stick with what you're most comfortable. You can usually get decent results by telling your editor to treat Fennel files as if they were Clojure or Scheme files.
This section consists of the following subections:
- Adding Fennel support to Emacs
- Adding Fennel support to Vim
- Adding Fennel support to Neovim
- Adding Fennel support to Visual Studio Code
- Adding readline support to Fennel
Installing fennel-mode gives you syntax highlighting, indentation, paren-matching, a repl, reloading, documentation lookup, and jumping to source definitions.
See the Readme.md
here
for details.
The fennel.vim plugin offers syntax highlighting and indentation support.
- For syntax highlighting and indentation, install fennel.vim
- To spin up a REPL in the terminal buffer, you can install a REPL plugin like iron.nvim and follow the documentation to add fennel as an executable REPL command.
Search in the built-in extension manager for "Fennel" to install the vsc-fennel extension. At the time of this writing it only provides syntax support.
The command-line REPL that comes with the fennel works out of the box, but
the built-in line-reader is very limited in user experience. Adding
GNU Readline support
enables such user-friendly features as
- Tab completion on the REPL that can complete on all locals, macros, and special forms
- A rolling history buffer, which can be navigated, searched (
ctrl+r), and optionally persisted to disk so you can search input from previous REPL sessions. - emacs (default) or vi emulation via readline's custom support for better line navigation
- Optional use of additional readline features in
~/.inputrc, such as blinking on matched parentheses or color color output (described below)
All you need to enable readline support is:
- GNU Readline installed on your system (installation steps vary for different operating systems, but you may already have it!)
- readline.lua lua bindings to libreadline
The stock Fennel REPL will automatically load and use the readline bindings when
it can resolve the readline module, so that's all you need to get started.
For the official support on getting readline.lua, see the official docs.
The easiest way to get readline.lua is to install it with Luarocks, which will fetch the package and automatically compile the native bindings for you. If you don't want to use LuaRocks, you can do a manual install.
# to install globally on the system (requires admin privileges or sudo)
$ luarocks install readline
# to install to the user's local tree
$ luarocks install --local readline
# install for Lua 5.1 (including LuaJIT)
$ luarocks install --lua-version=5.1 readlineBecause the readline Lua module contains native bindings to libreadline, be sure it's installed for the Lua version you intend to use.
Note: If you've installed with the --local flag, you may need to ensure your package.path
and package.cpath contain its location. See the
note on LuaRocks installation for details.
Readline itself has a number of configuration options, which can be set either
via the readline.lua API in fennelrc, or in readline's own ~/.inputrc config file.
To configure the REPL to save the rolling history to file at the end of every
session, add the following to your fennelrc with your desired filename:
See the readline.lua documentation for information on its API, most notably other parameters that can be set via rl.set_options.
; persist repl history
(match package.loaded.readline
rl (rl.set_options {:histfile "~/.fennel_history" ; default:"" (don't save)
:keeplines 1000})) ; default:1000See the documentation on the readline init file for the full set of options and a sample inputrc.
As of Fennel 0.4.0 and readline.lua 2.6, you can make use of a conditional
directive your inputrc
for fennel-only configuration options.
The following example adds these behaviors:
- Blink on a matching parenthesis when entering
). Useful in a Lisp REPL, where the parens are plentiful! - Enable bracketed paste mode for more reliable pasting from clipboard
- When tab-completing on a term with more than one possible match, display all
candidates immediately instead of ringing the bell + requiring a second
<tab>
# requires Fennel >= 0.4.0 and readline.lua >= 2.6
$if fennel
set enable-bracketed-paste on
set blink-matching-paren on
set show-all-if-ambiguous on
$endifThe two main platforms for making games with Fennel are TIC-80 and LÖVE.
TIC-80 is software that acts as a 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. Because Fennel compiles to Lua, you can reference the LÖVE wiki when making games with Fennel. 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.
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.
This section consists of the following subsections:
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 to get started.
- The TIC-80 wiki documents the functions to use and important concepts.
- See this project skeleton repo for information on using external editors, instead of the built-in TIC-80 editor.
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:
- Click "start" to begin
- Press the Esc key to open a menu
- Use the arrow keys to navigate the menu
- Press the Z key to open the console, followed by Esc to see the source code.
LÖVE has no built-in support for Fennel, so you will need to setup support yourself.
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.