Quick Start

1 Going Plaid

This guide will give you what you need in order to jump into LFE at ludicrous speed.

For a more gradual introduction (with a bit more Erlang) and for something that's going to give you time to see the stars, checkout the User Guide.

1.1 lfetool

For a quick introduction to LFE, lfetool has everything you need. The Quick Start guide will use it almost exclusively -- all in the interst of sending you a week and a half into the future.

Where appropriate, we will point you to other resources that provide more details.

Let's get started: install lfetool!

$ curl -o ./lfetool https://raw.github.com/lfe/lfetool/master/lfetool
$ bash lfetool install /usr/local/bin

Note that this does require the most recent release of Erlang right now (r16). (We are working towards full support for r15 and will update this Quick Start when that has landed.)

If you need sudo to put the script there, be sure to set the ownership:

$ chown $USER /usr/local/bin/lfetool

That way you'll be able to use the update command to get the latest version of lfetool in the future.

1.2 Other Dependencies

First and foremost, you will need Erlang installed. On Mac OS X, this is as easy as executing brew install erlang or on Ubuntu apt-get install erlang. You can also install Erlang from the various pre-built packages provided on the official Erlang download page or from the Erlang Solutions page (supports many more package types).

Personally, we prefer to manage our Erlang builds and installations with kerl. This allows for multiple versions of Erlang to be installed on your system simultaneously. For more information about using kerl in LFE projects, be sure to visit the "kerl" section of the User Guide.

You will be using rebar to build LFE under the covers as well as managing dependencies for your projects, so go ahead and get that set up: get rebar.

You will also need to download git or install it using your favorite package manager.

Next Stop

Ready for some LFE? Next you'll learn how to create a new LFE project with just one command ...

2 Your First LFE Project

A project? Already?! It sounds daunting, but it's just one command :-)

Head over to your favorite workspace in an open terminal and do this:

$ lfetool new library my-test-lib

As you watch the output crank away, read on to find out what it's doing:

2.1 Tests First!

First things first: let's get that failing unit test passing.

Here's the output we saw:

**error:{assertEqual_failed,[{module,'my-test-lib_tests'},
                     {line,11},
                     {expression,"(: my-test-lib my-adder 2 2)"},
                     {expected,4},
                     {value,5}]}

We can see that our test expected 4 but it got 5.

Before we go further, be sure you are in your project directory:

$ cd my-test-lib

Let's look at the test by opening up test/my-test-lib_tests.lfe.

Well, things there look good -- we should get 4 when 2 and 2 are added.

Let's take a look at the source module: src/my-test-lib.lfe. Ah-ha! a bug :-) There's an extra operation that's being done which we don't want.

To fix it, change this line:

  (+ x (+ y 1)))

to this:

  (+ x y))

Now re-run the unit tests:

$ make check-no-deps

And you should get a passing test:

==> my-test-lib (eunit)
======================== EUnit ========================
my-test-lib_tests: my-adder_test (module 'my-test-lib_tests')...[0.031 s] ok
=======================================================
  Test passed.

We'll talk about the make targets in a bit, but our target above run the unit tests without recompiling all the deps; just our project files and our unit tests.

2.2 Project Inventory

Okay, we've got our tests passing and our project looks healthy. But what does it have in it?

There are some other things there (e.g., the deps directory created by rebar and the ebin directory that's created when everything is compiled).

2.3 Repo Ready to Go

lfetool also did one more thing for you: inited the project in git and added all the files:

$ git status
<a name="on_branch_master"></a>
# On branch master
<a name=""></a>
#
<a name="initial_commit"></a>
# Initial commit
<a name="changes_to_be_committed:"></a>
# Changes to be committed:
<a name="(use_"git_rm_--cached_<file>"_to_unstage)"></a>
#   (use "git rm --cached <file>..." to unstage)
<a name="new_file:___gitignore"></a>
#   new file:   .gitignore
<a name="new_file:___makefile"></a>
#   new file:   Makefile
<a name="new_file:___readmerst"></a>
#   new file:   README.rst
<a name="new_file:___packageexs"></a>
#   new file:   package.exs
<a name="new_file:___rebarconfig"></a>
#   new file:   rebar.config
<a name="new_file:___src/my-test-libappsrc"></a>
#   new file:   src/my-test-lib.app.src
<a name="new_file:___src/my-test-liblfe"></a>
#   new file:   src/my-test-lib.lfe
<a name="new_file:___test/my-test-lib_testslfe"></a>
#   new file:   test/my-test-lib_tests.lfe

All you need to do it git commit -a && git push --all to wherever you want to put your project :-)

You can taste it, can't you? That LFE flavor coming your way? Yup, you're right. You're going to be looking at LFE code next ...

3 Hitting the Code

It may not seem like it, but we're off to a pretty fast start. If you had to do everything we've done, manually, you'd have given up by now. Seriously.

Time to put the brakes on, though, 'cause you're gonna want to see this next part in slow motion.

3.1 REPL Me Up!

Sure thing :-) Just do this from your new LFE project directory:

make shell-no-deps

(There's that -no-deps thing again... don't worry, we're going to tell you about it.)

This should give you something that looks like the following:

Erlang R16B (erts-5.10.1) [source] [smp:8:8] [async-threads:10] [hipe] ...

LFE Shell V5.10.1 (abort with ^G)
>

We're not going to spend a lot of time in the REPL right now, but feel free to take it for a spin :-)

> (+ 1 2 3 4 5 6)
21
> (* 2 (+ 1 2 3 4 5 6))
42
> (: lists foldl (lambda (n acc) (+ n acc)) 0 (: lists seq 1 6))
21

Enough fancy stuff! What about code? What does a project look like?

3.2 Sample Code

Well, you've already seen one! Let's print it here for your viewing pleasure, though. Here's the starter project you have, with just the one module:

(defmodule my-test-lib
  (export all))

(defun my-adder (x y)
  (+ x y))

It has a corresponding test module:

(defmodule my-test-lib_tests
  (export all)
  (import
    (from lfeunit-util
      (check-failed-assert 2)
      (check-wrong-assert-exception 2))))

(include-lib "deps/lfeunit/include/lfeunit-macros.lfe")

(deftest my-adder
  (is-equal 4 (: my-test-lib my-adder 2 2)))

Almost couldn't be simpler.

Here's something a little more involved you may enjoy, from the examples in the LFE source code:

(defmodule messenger-back
 (export (print-result 0) (send-message 2)))

(defun print-result ()
  (receive
    ((tuple pid msg)
      (: io format '"Received message: '~s'~n" (list msg))
      (: io format '"Sending message to process ~p ...~n" (list pid))
      (! pid (tuple msg))
      (print-result))))

(defun send-message (calling-pid msg)
  (let ((spawned-pid (spawn 'messenger-back 'print-result ())))
    (! spawned-pid (tuple calling-pid msg))))

That bit of code demonstrates one of Erlang's core features in lovely Lisp syntax :-) (For those that don't read Erlang yet, when loaded into the REPL, that example shows some bidirectional message passing between the LFE shell and a spawned process.)

If you'd like to learn more about using the LFE REPL, be sure to read the REPL Section of the User Guide.

If you want to step through a tutorial on Erlang's light-weight threds (per the example code above), you'll want to read this tutorial.

We did promise a bit more information, so we're going to do that next and then wrap up the quick start and point you in the direction of your next LFE adventure ...

4 Behind the Scenes

4.1 Using make

We promised to come back to make, so here we are.

Eventually, the Makefile will be replaced with a combination of rebar scripts and updates to lfetool, but for now it's what we've got.

There are some convenient targets available for you in the Makefile:

If you do not need to recompile dependencies (and most of the time, you don't), you can skip the deps with the following targets:

There are other interesting make targets tucked in the Makefile, and you can learn more about how to manage LFE projects by checking them out.

One thing to keep in mind for future reference: if you add new deps to your rebar.confg file, you'll need to update the ERL_LIBS in your Makefile to include them.

Read more about setting up a development environment here.

4.2 Next Steps

This has been a quick overview of what LFE has to offer, so you might enjoy reading the User Guide next. You can see all our docs at a glance by visiting the Docs page.

There is a tutorial on light-weight Erlang processes in LFE that you may be intersted in.

If you want to develop RESTful services in LFE, you should take a look at the REST on YAWS with LFE starter project.

The LFE organization on Gitub has a large collection of LFE projects that may be of interest to you.

You should also take some time reading the examples provided in the LFE source code; studying examples is the quickest way to make progress.

If at any time you would like to provide feedback about the documentation on this site, feel free to create an issue. Be sure to give a full description so that we can best help you!