rebar3_lfe

A modern rebar3 plugin for LFE projects

✨ Why rebar3_lfe?

• 🚀 Fast: Incremental compilation is 10-30x faster than full rebuilds
• 🎯 Correct: Header changes automatically trigger recompilation
• 🛡️ Reliable: >90% test coverage, tested on Erlang/OTP 25-29
• 📦 Powerful: Nested module packages with proper cleanup
• 💬 Clear: Professional error messages that help you fix issues
• 🔧 Modern: Uses rebar3's latest compiler infrastructure

Quick Start

%% rebar.config
{plugins, [
    {rebar3_lfe, "~> 0.5"}
]}.

{deps, [
    {lfe, "2.2.0"}
]}.

rebar3 lfe compile    # Compile your code
rebar3 lfe repl       # Start REPL
rebar3 lfe eval '(+ 1 2 3)'  # Evaluate LFE expressions
rebar3 lfe ltest      # Run tests
rebar3 lfe format     # Format your source

See Full Quick Start →

Features

🔥 Smart Compilation

$ rebar3 lfe compile
Compiling 10 LFE files...
Progress: 10/10 (100%)
Compiled 10 files in 1.25s

$ touch include/records.lfe
$ rebar3 lfe compile
Compiling 3 LFE files...  # Only files using the header
Compiled 3 files in 0.3s

🤖 Updated REPL

REPL support in rebar3_lfe has changed slightly in 0.5.0:

• Easier support for customising the LFE REPL prompt
• rlwrap for more consistent experience with readline support (dedicated LFE history file, etc.)

There is a new Makefile target that is included with all generated projects (rebar3 new lfe-*) which makes it easier for projects to use rlwrap and prompt customisations:

make repl

Autocompletion support is currently in progress; when complete, example usage will be shown here.

📦 Package System

Optional!

Organize your code by directories:

src/
├── myapp.lfe           → myapp module
└── myapp/
    ├── core.lfe        → myapp.core module
    └── utils/
        └── helpers.lfe → myapp.utils.helpers module

🎨 Great Errors

src/myapp.lfe:10: error: undefined function foo/1
  Did you mean: bar/1?

📐 Consistent Formatting

rebar3 lfe format reformats your LFE source to the LFE style conventions (80-column width, 2-space indentation, the lfe-indent.el-derived special-form table), preserving every comment. It is idempotent and token-preserving. export/import entries are sorted alphabetically one-per-line (sort suppressed when an entry carries a comment). By default it edits files in place; --dry-run prints the result to stdout instead, and --check makes it a CI gate.

Format in place (the default — files are rewritten):

rebar3 lfe format                     # every .lfe file in the configured source dirs
rebar3 lfe format --path src/sub      # only this directory (recursively)
rebar3 lfe format --path src/foo.lfe  # only this file

Dry run (no files changed — formatted output goes to stdout; over multiple files, each is preceded by a ;; ==> <path> header):

rebar3 lfe format --dry-run                     # whole project, to stdout
rebar3 lfe format --dry-run --path src/sub      # one directory, to stdout
rebar3 lfe format --dry-run --path src/foo.lfe  # one file, to stdout

Check (no files changed — exits non-zero and lists any files that are not already formatted; ideal for CI):

rebar3 lfe format --check

Without --path, format operates on the source directories configured in rebar.config (src_dirs), defaulting to src/.

⚡ All the Commands

Core:

• compile - Smart, incremental compilation
• clean - Remove build artifacts
• format - Format LFE source (in place, --dry-run, or --check)
• repl - Interactive LFE shell
• eval - Evaluate LFE expressions
• ltest - Run tests
• versions - Version information

Scripts & Escripts:

• run - Execute LFE scripts (main/1)
• escriptize - Build standalone executables
• run-escript - Execute built escripts

Releases:

• release - Build OTP releases
• run-release - Manage releases (start/stop/console/etc)

Utilities:

• confabulate - Convert Erlang data to LFE format
• defabulate - Convert LFE data to Erlang format

See All Commands →

Documentation

• Quick Start - Get started in 5 minutes
• Commands - Complete command reference
• Troubleshooting - Common issues
• Migration Guide - Upgrade from 0.4.x

Compatibility

Breaking Changes from 0.4.x

Version 0.5.0 is a complete rewrite with breaking changes:

• Module prefix: rebar3_lfe_* → r3lfe_*
• Faster, more reliable compilation
• Better error messages

Migration Guide →

Contributing

See contributing.

git clone https://github.com/lfe/rebar3.git rebar3_lfe
cd rebar3_lfe
rebar3 compile
make check

Support

• Documentation: lfe.github.io/rebar3
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Chat: #tooling in LFE Discord

License

Apache 2.0 - See LICENSE