cnbbooks / lfe-rebar3-quick-start

DEPRECATED (content is now in the LFE Chinenual)

The LFE Quick Start - rebar3 Edition

This rebar3 quick start has moved. Its new location is here:

• https://cnbbooks.github.io/lfe-manual/part6/tooling/rebar3/quick-start/index.html

---

This is a version of the LFE quick start that has been re-imagined with the LFE rebar3 plugin in mind.

We cover the following:

• How to get started quickly with LFE using just rebar3 and your local installation of Erlang
• Creating a new LFE project
• Looking at LFE code in the REPL and in modules
• Provide a little insight on how this works
• Leave you with resources for jumping into LFE in more detail

lfe-rebar3-quick-start's Issues

Update typo in getting started guide - rebar2_lfe is wrong

@fnchooft reported this issue here:

• lfe/lfe#396

Original description:

https://lfe.io/reference/lfe-rebar3/current/setup/plugin.html

Maybe explicitly show the global rebar.config:

$ cat ~/.config/rebar3/rebar.config 

{plugins, [
  {rebar3_lfe,
    {git, "https://github.com/lfe-rebar3/rebar3_lfe.git", {branch, "release/0.3.x"}}
  }
]}.

errors when 'Creating a New Project' tutorial

$ rebar3 new lfe-lib my-test-lib
===> Fetching rebar3_lfe (from {git,"https://github.com/lfe-rebar3/rebar3_lfe.git",
{branch,"master"}})
===> Fetching lfe v2.0.0
===> Fetching ltest v0.13.0
===> Fetching rebar_cmd v0.2.6
===> Fetching rebar3_hex v7.0.1
===> Fetching hex_core v0.8.4
===> Fetching verl v1.1.1
===> Analyzing applications...
===> Compiling verl
===> Compiling hex_core
===> Compiling rebar3_hex
.cache/rebar3/plugins/rebar3_hex/src/rebar3_hex_organization.erl:391:5: Warning: public_key:ssh_encode/2 is deprecated and will be removed in OTP 26; use ssh_file:encode/2 instead

===> Analyzing applications...
===> Compiling rebar_cmd
===> "/home/john/.cache/rebar3/plugins/rebar_cmd/ebin/rebar_cmd.app" is missing applications entry
===> Fetching erlang_color v1.0.0
===> Analyzing applications...
===> Compiling lfe
.cache/rebar3/plugins/lfe/src/lfe_types.erl:76:21: Warning: variable 'L' is bound multiple times in this pattern. If you mean to ignore this value, use '' or a different underscore-prefixed name
.cache/rebar3/plugins/lfe/src/lfe_types.erl:76:38: Warning: variable 'L' is bound multiple times in this pattern. If you mean to ignore this value, use '' or a different underscore-prefixed name

===> Compiling ltest
===> Compiling rebar3_lfe
===> Compiling color
===> The 'name' variable is often associated with Erlang module names and/or file names. The value submitted (my-test-lib) isn't an unquoted Erlang atom. Templates generated may contain errors.
===> Writing my-test-lib/README.md
===> Writing my-test-lib/LICENSE
===> Writing my-test-lib/rebar.config
===> Writing my-test-lib/.gitignore
===> Writing my-test-lib/src/my-test-lib.lfe
===> Writing my-test-lib/src/my-test-lib.app.src
===> Writing my-test-lib/test/my-test-lib-tests.lfe

OS: linux
distro: gentoo
erlang: 24.0.2
rebar: 3.17.0

regards

john

Books without Gitbook

Gitbook has changed its services and some of our stuff no longer builds. It would be nice to use some tooling that doesn't depend upon a service going away ... and I'd love to not have to use Ruby.

Ideally, whatever solution we use going forward should satisfy these conditions:

• allow us to continue using the content we've created in markdown with no (or very few changes)
• be usable without having to install tons of dependencies on our systems (e.g., support docker usage)
• not be part of some pay-for-service that could be taken away at any point in time
• support generating and viewing books locally
  a
  One option that is used to generate the copious markdown-based books in the Rust programming language community is this one:
• https://github.com/rust-lang/mdBook

I'll see if it meets our other criteria ...a

Typo in sample code on rebar3 QuickStart

On this page: https://lfe.io/books/rebar3-quick-start/code/sample.html there's a typo in the defmodule part.

It's missing a parenthesis after (my-fun 0

(defmodule my-test-lib
(export (my-fun 0
(my-sum 2))))

If I try to compile I get an error:
src/my-test-lib.lfe:1: bad module export definition

Should be:

(defmodule my-test-lib
(export (my-fun 0)
(my-sum 2)))

Add "How to cite" at the end of each book

Template not found

When issuing the command

rebar3 new lfe-lib my-test-lib

I get

template not found.

I'm working through the "LFE Quick Start with rebar3_lfe" and am on the "Creating a New Project" page.
My OS is Ubuntu Linux 20.04 and my version of Erlang is:

Erlang/OTP 22 [erts-10.7.2.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [hipe]

Thank you.

Change book license to CC

License:

• Summary: http://creativecommons.org/licenses/by-sa/4.0/
• Full: https://creativecommons.org/licenses/by-sa/4.0/legalcode
• Plain text: https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt

HTML:

<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">
  <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" />
</a>
<br />This work is licensed under a 
<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.

In action:

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Markdown:

[cc-license]: http://creativecommons.org/licenses/by-sa/4.0/
[cc-image]: https://i.creativecommons.org/l/by-sa/4.0/88x31.png
[![Creative Commons License][cc-image]][cc-license]
This work is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License][cc-license]

In action:

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

Generate a DOI for each release

See https://about.zenodo.org/

Add publisher info to copyright page

Mention how to run tests in the Tutorial

The tutorial at lfetool-quick-start/2.md fails to mention how to run unit tests - just shows the output.

Update book cover and style for LFE 2.0

Update all links in all LFE pages to no longer point to lfetool Quick Start ...

But to point here instead:

• http://lfe.io/rebar3-quick-start

Tutorial Example Fails

I tried to run the example from page 2.md of the tutorial after installing lfetool as described on the latest macOS. I had the problem of rebar being rebar3 nowadays. I symlinked rebar to rebar3 to get the installation to finish.

I suspect, the error below is a followup-error from above workaround: lutil does not seem to build with rebar3.

Should I use the seemingly deprecated rebar(2) or is there a better fix?

 > lfetool new library lfe-test-lib   
Setting up starter library project lfe-test-lib ...
Leeres Git-Repository in /Users/theisen/Projects/Work/lfe-test-lib/.git/ initialisiert
Removing EUnit test files ...
rm: ./.eunit/*.beam: No such file or directory
make: [clean-eunit] Error 1 (ignored)
Getting dependencies ...
===> Verifying dependencies...
===> Fetching lfe (from {git,"git://github.com/rvirding/lfe.git",{tag,"v0.9.0"}})
===> Fetching ltest (from {git,"git://github.com/lfex/ltest.git",{tag,"0.4.1"}})
===> Fetching lutil (from {git,"https://github.com/lfex/lutil.git",{tag,"0.5.1"}})
===> Dependency failure: source for lutil does not contain a recognizable project and can not be built

Add book links

Links:

• LFE documentation
• Github repo for book
• Open a ticket for the book's content
• Built with mdbook

Move this content into LFE Manual

See cnbbooks/lfe-manual#33

Then:

• Add a deprecation notice to this repo
• Link to the appropriate section in the LFE book
• Archive this repo

Redo this Quick-Start for rebar3_lfe

Once the rebar3 LFE plugin has shipped v0.3.0 (which will include testing support; see https://github.com/lfe-rebar3/rebar3_lfe/milestone/3) it will be ready for general usage. This project should be updated to reference that instead of the ancient lfetool ...

Tasks:

• Rename project to rebar3-quick-start
• Update all the content and sections that reference lfetool, converting those to use rebar3_lfe instead
• Publish new book to http://lfe.io/rebar3-quick-start/ (depends upon #6)
• Add a link to the rebar3_lfe docs pointing to the published book for this repo
• Find all the places where the old lfetool-quick-start doc is referenced and point it to the new location (moved to #9)

Core Dump testing example lib

On the unmodified example lib, following the quick start tutorial 2.md, I do

> make check-unit

Removing EUnit test files ...
removed ./.eunit/*.beam
Cleaning ebin dir ...
Compiling only project code ...
===> Verifying dependencies...
Removing old tests ...
rm -rf ./.eunit
mkdir: created directory ./.eunit
Compiling tests ...
Successfully compiled test modules.


------------------
Running unit tests ...
------------------

init terminating in do_boot ({undef,[{ltest,get-unit-beams,[],[]},{erl_eval,do_apply,6,[{_},{_}]},{erl_eval,expr,5,[{_},{_}]},{erl_eval,expr_list,6,[{_},{_}]},{erl_eval,expr,5,[{_},{_}]},{init,start_i

Crash dump is being written to: erl_crash.dump...done
init terminating in do_boot ({{badmatch,{error,{1,erl_parse,[_]}}},[{init,start_it,1,[]},{init,start_em,1,[]},{init,do_boot,3,[]}]})

Crash dump is being written to: erl_crash.dump...done
{"init terminating in do-boot",{{badmatch,{error,{1,erl-parse,["syntax error before: ","','"]}}},[{init,start-it,1,[]},{init,start-em,1,[]},{init,do-boot,3,[]}]}}

The core file starts with...

=erl_crash_dump:0.5
Thu Jul 18 08:57:09 2019
Slogan: init terminating in do_boot ({{badmatch,{error,{1,erl_parse,[_]}}},[{init,start_it,1,[]},{init,start_em,1,[]},{init,do_boot,3,[]}]})
System version: Erlang/OTP 22 [erts-10.4.4] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:1] [hipe] [dtrace]
Compiled: Thu Jul 11 12:57:25 2019
Taints: 
Atoms: 7502
Calling Thread: scheduler:3

Broken link on msgs page

src/code/msgs.md

On the bottom of this page there is a link "this tutorial" and it's broken.

Update Intro to Quick Start with required knowledge

Per this issue:

• lfe/docs#41

we need to add a note of explanation regarding what should be known before tackling LFE and where one can go to obtain this knowledge.