# rebar3_lfe

[![Build Status][gh-actions-badge]][gh-actions] [![LFE Versions][lfe badge]][lfe] [![Erlang Versions][erlang badge]][versions] [![Tag][github tag badge]][github tag]

*A comprehensive LFE rebar3 plugin for all your LFE tooling needs*

[![Project Logo][logo]][logo-large]

#### Contents

* [About](#about-)
* [Features](#features-)
* [Setup](#setup-)
* [Documentation](#documentation-)

## About [↟](#contents)

This plugin originally started life as a shell script (`lfetool` -- there's
even a T-shirt for it!), then it toyed with integrating with `rebar` (the
original). Around that time, though, `rebar3` was under initial development,
and LFE took a chance on it as an early adopter. This lead to a whole series of
LFE plugins, but after a few years momentum was lost. 

Those early `rebar3` efforts have been combined into a single plugin in this
project, with many updates and using all the latest approaches developed in
`rebar3`'s now mature ecosystem.

## Features [↟](#contents)

* Create new LFE projects:
  * `rebar3 new lfe-lib`
  * `rebar3 new lfe-main`
  * `rebar3 new lfe-escript`
  * `rebar3 new lfe-app`
  * `rebar3 new lfe-release`
* Create new LFE behaviour files:
  * `rebar3 new lfe-sup name=my-sup`
  * `rebar3 new lfe-server name=my-server`
  * `rebar3 new lfe-statem-handle-event name=my-statem`
  * `rebar3 new lfe-statem-state-functions name=my-statem`
* Start up an LFE REPL:
  * `rebar3 lfe repl`
* Compile LFE source code:
  * `rebar3 lfe compile`
* Run tests using the LFE testing library (wrapper for eunit)
  * `rebar3 lfe ltest`
  * `rebar3 lfe ltest -tunit`
  * `rebar3 lfe ltest -tsystem`
  * `rebar3 lfe ltest -tintegration`
  * `rebar3 lfe ltest -tall`
* Run an LFE project's `main/1` function as an lfescript (run `rebar3 new lfe-main` to see an example):
  * `rebar3 lfe run`
  * `rebar3 lfe run -- 1 2 5`
  * `rebar3 lfe run -main some/path/main.lfe`
* Escriptize an LFE escript project:
  * `rebar3 ecsriptize`
* Run an escriptized LFE escript project:
  * `rebar3 lfe run-ecsript`
* Generate an LFE/OTP release
  * `rebar3 release`
* Run an LFE/OTP release project's release script (`COMMAND` can be `start` , `stop` , `status`, `ping`, etc.):
  * `rebar3 lfe run-release COMMAND`
* Convert LFE data files to Erlang data file
  * `rebar3 lfe confabulate lfe-data.lfe erl_data.erl`
* Cleanup
  * `rebar3 lfe clean`
  * `rebar3 lfe clean-build`
  * `rebar3 lfe clean-cache`
  * `rebar3 lfe clean-all`
* Metadata
  * `rebar3 lfe versions`

[More coming soon!](

## Setup [↟](#contents)

Add the plugin to your ``rebar.config`` (stable):

{plugins, [
    {rebar3_lfe, "0.3.1"}

Or, if you want to use the current development branch (unstable):

{plugins, [
        {git, "", {branch, "release/0.4.x"}}}

### Upgrading `rebar3_lfe` Globally

You may need to upgrade `rebar3_lfe` at some point, as older versions will not work with newer versions of `rebar3`.

In order to successfully upgrade the plugin globally, first edit `~/.config/rebar3/rebar.config` (replace `release/0.4.x` with the desired branch):

{plugins, [
  {rebar3_lfe, {git, "", {branch, "release/0.4.x"}}}

Then clear the rebar3 plugin cache:

$ rm -rf ~/.cache/rebar3/plugins/*lfe*

Finally, run:

$ rebar3 plugins upgrade rebar3_lfe

You can check whether the version upgrade was successful with:

$ rebar3 lfe versions
(#(apps ())
   (#(lfe "2.1.1") #(erlang "25") #(emulator "13.0") #(driver_version "3.3")))
 #(tooling (#(rebar "3.18.0") #(rebar3_lfe "0.4.3"))))

## Documentation [↟](#contents)

Detailed usage is provided in the [project documentation](

[//]: ---Named-Links---

[lfe badge]:
[erlang badge]:
[github tag]:
[github tag badge]:
[github downloads]:
[hex badge]:
[hex package]:
[hex downloads]:

<!-- Unused badges:
[![Downloads][hex downloads]][hex package]