flake-fennel-tools

Nix flake of Fennel development tools.

Description

There are a number of good development tools for Fennel programming: Faith for testing, Fennel Format for formatting code, Fenneldoc for generating documentation, fennel-ls for linting, etc. (find more in Fennel wiki).

Some of these tools are missing in nixpkgs¹. This flake aims to help Fennel developers using Nix by providing Fennel development tools en masse, including those missing ones.

Moreover, it provides Fennel development version (i.e., main branch), which is updated once every day. It would help you test your Fennel application/library against the cutting edge.

Usage

Overlay

Add the default overlay of this flake to your flake.nix. It could look like:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    fennel-tools.url = "github:m15a/flake-fennel-tools";
  };
  outputs = { self, nixpkgs, flake-utils, fennel-tools, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ fennel-tools.overlays.default ];
        };
      in {
        devShells.default =
          let
            fennel = pkgs.fennel-unstable-luajit;
          in
          pkgs.mkShell {
            packages = [
              fennel
              pkgs.faith
              pkgs.fnlfmt
              pkgs.fenneldoc
            ] ++ (with fennel.lua.pkgs; [ readline ]);
            FENNEL_PATH = "${pkgs.faith}/bin/?;./src/?.fnl;./src/?/init.fnl";
            FENNEL_MACRO_PATH = "./src/?.fnl;./src/?/init-macros.fnl";

            shellHook = ''
              # if you want to read man pages
              export MANPATH="${fennel.man}/share/man''${MANPATH:+:''${MANPATH}}"
            '';
          };
      });
}

Alternatively, you can use this flake via FlakeHub. See instructions at the FlakeHub page.

Run applications on the fly

Executable programs contained in the packages are accessible via nix run command. For example,

$ nix run github:m15a/flake-fennel-tools#fennel-unstable-luajit
Welcome to Fennel 1.4.2-dev-f0e3412 on LuaJIT 2.1.1693350652 Linux/x64!
Use ,help to see available commands.
Try installing readline via luarocks for a better repl experience.
>>

Notes on each package

Fennel

This flake exposes a number of Fennel variants, each being different in Fennel version, stable (1.4.1 as of Feb 2024) or unstable (main branch), and Lua version/implementation, PUC Lua from 5.1 to 5.4 or LuaJIT.

You can access them via attributes

pkgs."fennel-${LUA}" # stable version
# or
pkgs."fennel-unstable-${LUA}" # main branch
# and man pages
pkgs."fennel-${LUA}".man
pkgs."fennel-unstable-${LUA}".man

where ${LUA} is either one of lua5_1, lua5_2, lua5_3, lua5_4, and luajit.

If you want to derive Fennel with additional Lua packages, you can do like so:

pkgs.fennel-luajit.withLuaPackages (ps: with ps; [ cjson ])

Faith

A testing library. Attributes:

pkgs.faith # stable version (0.1.2 as of Feb 2024)
# or
pkgs.faith-unstable # main branch

In this flake, the package contains a runnable script of Faith, bin/faith. The script begins with shebang line #!/usr/bin/env fennel, thus enabling you to test your code against different Fennel variants.

Don't forget to add the Faith script path to environment variable $FENNEL_PATH, so that you can require Faith module in your test code. It could be set in devShell:

  pkgs.mkShell {
    buildInputs = [
      pkgs.fennel-unstable-lua5_2
      pkgs.faith
      ...
    ];
    FENNEL_PATH = "${pkgs.faith}/bin/?";
  };
  ...

or in console shell (below is a Bash example):

export FENNEL_PATH="$(dirname $(which faith))/?"

For more information, take a look at Faith's repository.

Fennel Format

A Fennel formatter. Attributes:

pkgs.fnlfmt # stable version (0.3.1 as of Feb 2024)
# or
pkgs.fnlfmt-unstable # main branch

Nothing special has been done for Nix usage. Install it and format code as usual. For more information, read the document in Fennel Format's repository.

Fenneldoc

A Fennel API documentation generator. Attribute:

pkgs.fenneldoc # development version (1.0.1-dev as of Feb 2024)

Again, once installed, you can just use it. For more information, read the document in Fenneldoc's repository.

fennel-ls

A language server for Fennel. Attributes:

pkgs.fennel-ls # stable version (0.1.1 as of Feb 2024)
# or
pkgs.fennel-ls-unstable # main branch
sk

Note that, regardless of this flake, you can use the official nixpkgs' package pkgs.fennel-ls or the Nix flake provided by fennel-ls itself:

inputs.fennel-ls.url = "sourcehut:~xerool/fennel-ls/main";

This flake provides its own fennel-ls package just for completeness.

Licenses

Unless otherwise stated, this software is licensed under the BSD 3-clause license.

data/unstable-packages.json is collected from code hosting services (currently sourcehut only) by using their API. Each part of the data has respective copyright and permission to use. See sourcehut terms of service for more information about the permissible data use and content rights.

Footnotes

1. fnlfmt and fennel-ls are available in nixpkgs as of Feb 2024. ↩