• Convert the existing LFE plugin to Erlang
• Bring that Erlang code into rebar3_lfe
• Stop using test runner's directly
  • use functions that accept options
  • set up the listener based upon parsed options
  • set up the runner based upon parsed options
  • set up the reporter based upon parsed options
• Ensure all options are being used
  • test types are properly limited by --test-type=
  • listeners can be switched out with --test-listener=
  • ANSI colors in output can be disabled with --color=false (accept --colour too)
  • eunit options are passed on to the appropriate listeners
• Test in LFE projects

I think we can actually dump this command and just use rebar3 escriptize ...

Todo items:

• Change the book title to the same thing that's on the cover page
• Add a custom css to oveeride in-lined <code> (too dark on light themes)
• Make the LFE PDP theme the default
• Split the "cleanup" commands into separate pages, just like the "run" commands
• Add css for waning and info sections
• Use those instead of blockquote
• Fix verb typo in opening sentence of "cleanup" section
• Split "setup" section into three pages
• Convert all intro.md files to README.md

My project:
https://github.com/prokopiy/aira

Environment

rebar3 compile
===> Verifying dependencies...
===> Fetching uuid (from {git,"https://github.com/prokopiy/lfe-uuid.git",{branch,"master"}})
===> Uncaught error in rebar_core. Run with DEBUG=1 to see stacktrace or consult rebar3.crashdump
===> When submitting a bug report, please include the output of rebar3 report "your command"

...

Rebar3 report
version 3.14.0-rc2+build.4690.ref60652e6f
generated at 2020-09-23T06:24:28+00:00

Please submit this along with your issue at https://github.com/erlang/rebar3/issues (and feel free to edit out private information, if any)

Task: rebar3
Entered as:
rebar3 compile

Operating System: x86_64-pc-linux-gnu
ERTS: Erlang/OTP 22 [erts-10.6.4] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1]
Root Directory: /usr/lib/erlang
Library directory: /usr/lib/erlang/lib

Loaded Applications:
bbmustache: 1.8.0
certifi: 2.5.2
cf: 0.2.2
common_test: 1.18.1
compiler: 7.5.2
crypto: 4.6.4
cth_readable: 1.4.8
dialyzer: 4.1.1
edoc: 0.11
erlware_commons: 1.3.1
eunit: 2.4
eunit_formatters: 0.5.0
getopt: 1.0.1
hipe: 3.19.2
inets: 7.1.2
kernel: 6.5.1
providers: 1.8.1
public_key: 1.7.1
relx: 4.0.0-rc2
sasl: 3.4.1
snmp: 5.4.5
ssl_verify_fun: 1.1.5
stdlib: 3.11.2
syntax_tools: 2.2.1
tools: 3.3

Escript path: /usr/bin/rebar3
Providers:
app_discovery as clean clean clean-all clean-build clean-cache compile compile compile cover ct deps dialyzer do edoc escriptize escriptize eunit get-deps help install install_deps list lock new path pkgs release release relup repl report repos run run-escript run-release shell state tar tree unlock update upgrade upgrade upgrade version versions xref

I am use plugin:
https://github.com/lfe-rebar3/rebar3_lfe

rebar3.crashdump:
Error: badarg
[{erlang,'++',
[{uuid,[]},
[cl,clj,lfe,lfe_abstract_code,lfe_bits,lfe_codegen,lfe_codelift,
lfe_comp,lfe_docs,lfe_edlin_expand,lfe_env,lfe_eval,lfe_gen,
lfe_init,lfe_internal,lfe_io,lfe_io_format,lfe_io_pretty,
lfe_io_write,lfe_lib,lfe_lint,lfe_macro,lfe_macro_export,
lfe_macro_include,lfe_macro_record,lfe_ms,lfe_parse,lfe_pmod,
lfe_qlc,lfe_scan,lfe_shell,lfe_trans,lfe_types,lfescript,scm,csv]],
[]},
{lists,append,1,[{file,"lists.erl"},{line,127}]},
{lists,append,1,[{file,"lists.erl"},{line,127}]},
{rebar_paths,purge_and_load,2,
[{file,"/usr/lib/rebar3/src/rebar_paths.erl"},{line,115}]},
{rebar_paths,set_paths,2,
[{file,"/usr/lib/rebar3/src/rebar_paths.erl"},{line,21}]},
{rebar_prv_compile,do,1,
[{file,"/usr/lib/rebar3/src/rebar_prv_compile.erl"},
{line,39}]},
{rebar_core,do,2,[{file,"/usr/lib/rebar3/src/rebar_core.erl"},{line,154}]},
{rebar3,run_aux,2,[{file,"/usr/lib/rebar3/src/rebar3.erl"},{line,181}]}]

Originally filed here: lfe-rebar3/compile#30

Originally filed here: lfe-rebar3/compile#23

And maybe them optionally? Maybe don't compile tests by default, but add a --compile-tests boolean flag?

What would it take to create a custom theme for LFE mdbooks? It would be nice to match the colors of the manual covers ...

Maybe using Slate for static page gen?

• lfe clean: Clean the project's ebin directory (this doesn't seem to be done by rebar3 clean ...?)
• lfe clean-build: Completely remove the project's directory under _build
• lfe clean-cache: Remove the project from the system level cache
• lfe clean-all: perform both clean-build and clean-cache, delete rebar*crashdump, delete rebar.lock

Tasks

• Examine latest compile support provided by a modern version of LFE
• Review lfe-rebar3/compile plugin and determine how much of that project's code may be reused
• Add the bare-minimum code needed to support LFE compilation by rebar3 rebar3 lfe compile

I think this will just be a simple wrapper around what LFE already supports?

Tasks:

• Add rebar.config to new "examples" directory
• Add make target to generate all project types
• Update regen target to call this target
• Add clean target to remove generated examples
• Update each project creation chapter to include pertinent files in the chapter

Does Gitub Actions support Erlang yet? If so, great. If not, set up for Travis CI ...

• Add config(s) for CI/CD infra
• Add badges to README to indicate build status
• Add support for testing against multiple versions of Erlang
• Explore ways of testing the plugin commands in CI/CD jobs

Copied from the 2015 ticket in the old repo: lfe-rebar3/compile#4

Note that this is not true package support, since Erlang/LFE don't have such a concept.

Instead, this is about finding modules in a directory structure and creating a beam file name that is composed of the path elements of the module files parent directories.

This will mean that you can have a path structure like src/a/b/c/d.lfe and, once compiled, there would be a .beam file in ./ebin created with the name a.b.c.d.beam. Calling this module's functions from LFE code would be done in the usual manner: (a.b.c.d:some-func ...). The onus will of course be on the developer to ensure that the module is given the proper name: (defmodule a.b.c.d ...).

Right now, there's no description in the command reference of how to invoke the help text for the LFE plugin in rebar3. Add it!

e.g.:

$ rebar3 lfe

lfe <task>:
  clean              Clean apps .ebin files
  clean-all          Execute all clean commands
  clean-build        Remove the rebar _build directory
  clean-cache        Remove the project's cache directories
  compile            Compile LFE project
  escriptize         Escriptize an LFE escript project
  ltest              Run LFE tests that have been created with the ltest project.
  release            Build a release for the LFE project
  repl               Run an LFE REPL with project apps and deps in path.
  run                Run the project's main function.
  run-escript        Run an LFE escript
  run-release        Run an LFE release
  versions           Get various versions

There is an old plugin for this, but iirc, it was quite buggy and never really worked that well. Let's revisit and re-imagine rebar3 lfe repl ...

Maybe we can just use rebar3 release to generate the release instead?

It would be nice to eval something as done with lfe -eval '...' without having to point to the appropriate lfe binary buried under ./_build.

Expected usage:

$ rebar3 lfe eval '...'

Not sure if this is necessary, since this is provided by rebar3. However, one thing I have noticed with other rebar3 plugins is that the downloaded cache for plugins is preserved and it can be tricky to ensure that the latest version is actually downloaded from a repo. Perhaps the upgrade command only cleans the cache when an actual release is identified? Dunno. This need to be examined in detail, with any missing use cases identified.

Also update the badge in the README

On this page:

• https://lfe.io/reference/lfe-rebar3/current/command-ref/projects/release.html

These steps are missing:

• cd into project dir
• generate release

... and it shouldn't be!

For projects that have been created with rebar3 new lfe_release, this command will generate all the files necessary to build and run the release.

This will basically execute the binary at _build/CURRENT-PROFILE/bin/APP-NAME and depend upon the escriptize command.

From comments in lfe-rebar3/compile#29

Originally filed here: lfe-rebar3/compile#28

• a project with an lfe include and no additional settings in rebar.confg
• a project with no include but which uses the include from a dep and has no additional settings in rebar.confg
• both of those first two options, but with {lfe_first_files, ["src/.."]}. set in the rebar.confg
• both of those first two options, but with {lfe_opts, [{i,"..."}]}. set in the rebar.confg
• both of those first two options, but with lfe_first_files and lfe_opts set in the rebar.confg

it's called [version] but should be [versions]

How to run an LFE project?

My project https://github.com/prokopiy/aira has deps:

└─ aira─0.0.0+build.12.refff15a0a (project app)
├─ csv─1 (git repo)
├─ lfe─2.0-dev (git repo)
└─ uuid─0.0.0+build.7.ref3f79d20 (git repo)

Why when i run the command "rebar3 lfe run" an error occurs ?

===> Verifying dependencies...
===> Compiling aira
Running script '/usr/bin/rebar3' with args [] ...
exception error: undefined function
in (uuid : v4)
in aira:my-fun/0 (/home/prokopiy/MEGAsync/workspace/aira/src/aira.lfe, line 10)
in lists:map/2 (lists.erl, line 1239)
in lists:map/2 (lists.erl, line 1239)
in lfe_eval:eval_call/2 (/home/prokopiy/MEGAsync/workspace/aira/_build/default/plugins/lfe/src/lfe_eval.erl, line 866)
in lfescript:eval_code/4 (/home/prokopiy/MEGAsync/workspace/aira/_build/default/plugins/lfe/src/lfescript.erl, line 187)
in lfescript:parse_check_run/3 (/home/prokopiy/MEGAsync/workspace/aira/_build/default/plugins/lfe/src/lfescript.erl, line 87)
in lfescript:run/2 (/home/prokopiy/MEGAsync/workspace/aira/_build/default/plugins/lfe/src/lfescript.erl, line 59)

The Emacs formatting has not been applied to some of the LFE; this needs to be done.

This will be the mechanism whereby LFE main scripts can be run, very much like lein run for Clojure and rebar3 clojerl run for Clojerl.

E.g.:

• use of semantic versioning
• development versions / branches
• steps for making a release
• updating the templates to support the latest release of the plugin
• what users can do to use particular versions, etc.

There are three testing frameworks that should be supported:

• Erlang's eunit
• Erlang's Common Test
• the LFE ltest framework

Tasks

• Examine each of the above and the most direct, straight-forward means of supporting them in a rebar3 plugin
• Update the ltest library to decrease the number of dependencies and use the new rebar3_lfe plugin (depends upon https://github.com/lfex/ltest/milestone/1)
• Review lfe-rebar3/test plugin and determine how much of that project's code may be reused
• Add the bare-minimum code needed to support eunit tests written in LFE via rebar3 eunit
• Add the bare-minimum code needed to support Common Tests written in LFE via rebar3 ct
• Add the bare-minimum code needed to support tests written using ltest via rebar3 lfe ltest
• Explore the possibility of adding the command rebar3 lfe test which will run all tests in a project written against all supported test frameworks

For CT support, see the following:

• https://github.com/lfe-rebar3/ct (9 yrs old, so probably old rebar)
• https://github.com/erlang/rebar3/blob/master/src/rebar_prv_common_test.erl

Explicitly state that release needs to be run before run-release

The rebar3 LFE compiler doesn't seem to be compiling the LFE app (included in the rebar3.config file to be bundled with the escript). This does not work:

$ rebar3 lfe escriptize

Whereas this does:

$ rebar3 lfe compile
$ rebar3 escriptize

Depends upon:

• #40

Once ltest support has landed ...

When starting an LFE release with rebar3 lfe run-release start sometimes it doesn't actually start (checked by running rebar3 lfe run-release ping). However, almost always after running rebar3 release again, it will start, with a subsequent ping resulting in a pong.

Things to test:

• Generate a new project with rebar3 new lfe-release
• Generate a release for the project with rebar3 release
• Run the release script manually (./_build/..../app-name start)
  • do several series of starts and stops, pinging each time
  • make sure it always comes up
• Now run the rebar3 lfe run-release start command (without rebuilding the release) to check its behaviour
• Do a fresh rebuild of the release, and check again
• Create a new Erlang/OTP release (no LFE) using rebar3 new release
  • update the project's rebar.confg file and add the LFE plugin
  • use the LFE plugin command to run through the same steps above to see if the results are all the same

Initially, use of this plugin will be tricky due to the (hopefully) rapid set of changes being made. An explicit set of steps should be given for potential users/contributors during this bleeding-edge period for:

• adding/updating entries in rebar.config
• purging the rebar3 cache
• upgrading / updating the plugin (downloading the latest)
• confirming working-state
• testing the latest functionality

This document should be linked off of the README.md file under a "developer" section ...

Tasks:

• OTP library projects lfe-lib
• OTP application projects lfe-app
• OTP releases lfe-release
• escripts lfe-escript
• LFE scripts lfe-main

From the module docs:

%%% Essentially, this boils down to creating modules with dotted-notation
%%% prefixes in their names. This can be done in the same `src` directory
%%% as regular Erlang and LFE projects, or, if a developer prefers, it can
%%% be done using subdirectories. In the latter case a faux package name will
%%% be created using a combination of sub-directory names under the `src`
%%% directory and the file name itself. To be clear, in the end what is
%%% created is simply a module name, as there is no such thing in Erlang as
%%% a package.
%%% 
%%% Some examples of how files and directories will be transformed in their
%%% final form as `.beam` files:
%%% 
%%% ./src/my.package1.lfe             -> ebin/my.package1.beam
%%% ./src/my/package2.lfe             -> ebin/my.package2.beam
%%% ./src/my/other/package.lfe        -> ebin/my.other.package.beam
%%% ./src/my/really/deep/package1.lfe -> ebin/my.really.deep.package1.beam
%%% ./src/my/really/deep.package2.lfe -> ebin/my.really.deep.package2.beam
%%% ./src/my/really.deep.package3.lfe -> ebin/my.really.deep.package3.beam
%%% ./src/my.really.deep.package4.lfe -> ebin/my.really.deep.package4.beam
%%% 
%%% So, in essence, this module is responsible for transforming a nested
%%% directory structure into a single file, as well as providing the functions
%%% necessary to perform any cleanup of intermediary, temporary files.

Originally filed here: lfe-rebar3/compile#23

rebar3 new lfe-nerves

See https://hexdocs.pm/nerves/getting-started.html

On Windows, rebar3 does not support rebar3 local install which would set up $HOME/.config/rebar3 automatically for them, for some reason. Each kind of shell one might run may have a different notion where $HOME is, making it necessary to add rebar.config with the necessary plugin additions in multiple places. In a DOS or PowerShell prompt, that location is C:\Users<username>.config\rebar3\rebar.config, and in MINGW and Cygwin, it's wherever $HOME aka ~/ is.

Alternatively, there is an environment variable one can set, REBAR_GLOBAL_CONFIG_DIR, and of course one would have to do this both via Windows' standard environment variable editor and in the ~/.bash_profile initialization script for each prompt. However, once the rebar.config file is set for each prompt, everything is peachy.

OK, one thing isn't peachy. For reasons that are being investigated, the rebar3 lfe repl task needs one extra step in order to actually render the REPL. (For this same soon-to-be grokked reasons, running the lfe script by itself crash-dumps.) In order to enjoy Lisping in a fully-functional LFE REPL, you will need to invoke lfe_shell:server(). from the Erlang Shell that appears instead of the LFE REPL when you issue the rebar3 lfe repl command. Apparently, when the initialization of the LFE REPL bombs in the context of the Erlang Shell, the Erlang Shell doesn't crash with it, and issuing lfe_shel:server(). work just fine.

One final gotcha: On the DOS prompt only, the ASCII art LFE coffee cup does not render properly. Looks great in MINGW and Cygwin, but DOS being DOS it looks more like a bowl of used ramen noodles. Users are however highly encouraged to give the new Windows Terminal application a try. It renders the LFE coffee cup beautifully whether you are firing up a standard command window or a PowerShell window. And everything works in the REPL as expected from that point on.

When compiling apps in a release, if one or more of those apps has/have include files, the compile process is err'ing out before these are getting linked inside _build; all that's present in the build lib dir is the ebin subdir (no include subdir or sym link to the include dir).

In a regular app build, one sees this in an app's build dir:

$ ls -al _build/default/lib/lfe-otp/

Permissions Size User     Date Changed Name
lrwxr-xr-x    16 oubiwann 29 Sep 12:23 priv -> ../../../../priv
lrwxr-xr-x    19 oubiwann 29 Sep 12:23 include -> ../../../../include
lrwxr-xr-x    15 oubiwann 29 Sep 12:23 src -> ../../../../src
drwxr-xr-x     - oubiwann 29 Sep 12:23 ebin

This is failing for both .hrl and .lfe include files.

May be related to:

• #17

This will have no directory structure; instead, it will just generate a single script and chmod 755 it for ready use. It will require that the user have lfe in their PATH.

This will help support back-porting and easily creating micro version tags.

Make sure that the CI/CD workflow kicks off for merges and PRs for these ...

Originally filed here: lfe-rebar3/compile#24