clone url: git://git.m455.casa/fa
esperbuild/espersrc/fennel-0.7.0/setup.md
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 not be covered in this document.
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.
Downloading the fennel
script allows you to place the script in
convenient locations for running Fennel code.
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-0.7.0
to make it executablegpg --verify fennel-0.7.0.asc
to verify that the fennel
script is from the Fennel creators (optional but recommended)fennel-0.7.0
to a directory on your $PATH
, such as /usr/local/bin
Note: 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.
chmod +x fennel-0.7.0*
to make it executable (not needed on Windows).gpg --verify fennel-0.7.0*.asc
(optional but recommended).$PATH
, such as /usr/local/bin
LuaRocks contains a repository of Lua software packages. LuaRocks is convenient because it automates the downloading, installation, updating, and uninstallation of Lua software packages.
luarocks
package is installed on your system.~/.luarocks/bin
directory is added to your shell's $PATH
.luarocks --local install fennel
to install locally (recommended)luarocks install fennel
to install globally (requires root or admin)fennel --help
to confirm the installation succeeded.Note: When using luarocks
with --local
, you'll need to ensure
you have a $PATH
which contains the LuaRocks bin/
directory. You can add
eval $(luarocks path --bin)
to your shell's init file to do this. See the
LuaRocks path docs
for more information.
Homebrew aims to be the missing package manager for macOS (and Linux). Its primary goal is to be useful to as many people as possible, while remaining maintainable to a professional, high standard by a small group of volunteers.
To download Fennel using Homebrew:
brew
package is installed on your systembrew install fennel
to install fennel
fennel --help
to confirm the installation succeededFennel 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 load further files) 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.
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.lua
local fennel = require("fennel")
table.insert(package.loaders or package.searchers, fennel.searcher)
local mylib = require("mylib") -- will compile and load code in mylib.fnl
Be sure to use the library and not the file for the entire fennel
compiler.
Note: Optionally, if you want the Fennel REPL to print tables
in a more readable format, you can add fennelview.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 .lua
files 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.
Installing fennel-mode gives you syntax highlighting, indentation, paren-matching, a repl, reloading, documentation lookup, and jumping to source definitions.
For more information, see the fennel-mode readme.
The fennel.vim plugin offers syntax highlighting and indentation support.
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 highlighting.
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)Note: 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.
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.
Tip: If you don't want to use LuaRocks, you can manually install readline.lua by following the guide here.
To install readline.lua with LuaRocks:
luarocks install --local readline
(recommended)luarocks install --lua-version=5.1 readline
(for a non-default Lua version)luarocks install readline
(requires root or admin)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.
You can configure readline.lua using one of the following options:
fennelrc
~/.inputrc
filefennelrc
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.
fennel
; persist repl history
(match package.loaded.readline
rl (rl.set_options {:histfile "~/.fennel_history" ; default:"" (don't save)
:keeplines 1000})) ; default:1000
~/.inputrc
See the documentation on the readline init file for the full set of options and a sample inputrc.
The following example adds these behaviors:
)
. Useful in a Lisp REPL, where
the parens are plentiful!<tab>
Create a ~/.inputrc
file with the following contents:
inputrc
set enable-bracketed-paste on
set blink-matching-paren on
set show-all-if-ambiguous on
As of Fennel 0.4.0 and readline.lua 2.6, you can make use of a conditional
directive your inputrc
if you would like certain settings to only apply to Fennel.
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. 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.
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.
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.