Stand-alone Erlang

Stand-alone Erlang is a minimal Erlang distribution. It features:

Download.

Installation (linux)

Here is a typescript of a session where we fetch, install and test SAE:

Fetching and installing SAE

$ wget http://www.sics.se/~joe/sae-r9b0-1.tgz
$ gunzip sae-r9b0-1.tgz
$ tar -xf sae-r9b0-1.tar
$ cd sae-r9b0-1/dist
./Install
installing executables in /home/joe/bin
installing code in /home/joe/lib/sae
patching executables
rebase: /home/joe/bin/ecc as /home/joe/lib/sae
rebase: /home/joe/bin/elink as /home/joe/lib/sae
rebase: /home/joe/bin/esh as /home/joe/lib/sae
rebase: /home/joe/bin/escript as /home/joe/lib/sae
rebase: /home/joe/bin/ear as /home/joe/lib/sae
ecc is ok
elink is ok
beam_evm is ok
Compiling and building a test program
Running the test
Running test
test worked

Test that we can find ecc and elink.

$ which ecc
/home/joe/bin/ecc
$ which elink
/home/joe/bin/elink

Make the test programs:

$ cd ../examples
$ make
ecc test_hello.erl
ecc test_url.erl
ecc test_autoload.erl
ecc test_autoload1.erl
ecc test_dets.erl
ecc test_bug.erl
ecc test_include.erl
elink test_hello.beam
elink test_url.beam 
elink test_autoload.beam
elink test_dets.beam
elink test_bug.beam 
elink test_include.beam 
./test_hello
Hello world
Args=["./test_hello"]
test_hello worked
./test_url
test_url worked
./test_include
test_include worked
./test_dets
test_dets worked
./test_autoload
Auto load test incomplete $ROOTDIR not defined
./test_bug
aaaa
test_bug worked

Test that scripting works. Note: fib1 is an interpreted script. fib2 is a compiled script.

$ cd ../dist
./factorial 20
factorial 25 = 15511210043330985984000000

$ cd ../examples
$ time ./fib1 24
fib 24 = 46368

real    0m2.603s
user    0m2.490s
sys     0m0.060s

$ time ./fib2 24
fib 24 = 46368

real    0m0.451s
user    0m0.400s
sys     0m0.020s

Very quick start

Store the following in a file called hello.erl:

-module(hello).

-export([start/1]).

start(Args) ->
    io:format("Hello world~nArgs=~p~n", [Args]),
    erlang:halt().

Compile and run as follows:

$ ecc hello.erl
$ elink hello.beam 
$ ./hello 1 2 3
Hello world
Args=["./hello","1","2","3"]

The file hello is a 2 KByte executable which can be distributed together with the original system files.

Quick start (Linux)

To compile:

> ecc *.erl

This will compile all the .erl files in the current directory producing .beam files if the compilation was successful.

To create a Unix application called myUnixProg give the command:

> elink -o myUnixProg *.beam

When the program is run in Unix with the command:

> myUnixProg Arg1 Arg2 ...

The function:

myUnixProg:start([Arg1, Arg2, ...])

Will be called. All the arguments are Erlang strings.

Making windows executables

This does not work yet

Note: Windows executables can be built in Unix or vice. versa

To create a stand-alone windows application called myWindowsProg.exe give the following command:

> elink -t windows -o myWindowsProg.exe *.beam

elink reference

> elink
elink [-shell] [-windows] [-o OUT[.exe]]
    [-s M] -m M1.beam [M2.beam M3.beam ...]

      Make an executable OUT
      Excuting OUT will load the code in M1 M2 M3
      The command >OUT[.exe] Arg1, Arg2
      Will cause M:start([Arg1, Arg2, ...]) to be evaluated
   
   > elink [-m] M1.beam M2.beam M3.beam
        implies s = M1 o=M1
   > elink -o Mi[.exe] -m M1.beam M2.beam
         Mi must be in M1 M2 ...
         implies s = Mi
   > elink -s Mj -o Mi.[exe] -m M1.beam M2.beam
       Mj must be in M1 M2 ...
   > elink -r Dir Executable
       Rehomes Executable to ERL_EARS=Dir

elink examples

> elink a1.beam a2.beam ...

Makes an executable called a1. The start function is a1:start(...)

> elink a1.beam a2.beam ...

Makes an executable called a1. The start function is a1:start(...)

> elink -o a3 a1.beam a2.beam ...

Makes an executable called a3. The start function is a3:start(...) - one of the beam files must be a3.beam

> elink -o a3 -s a4 a1.beam a2.beam ...

Makes an executable called a3. The start function is a4:start(...) - a3.beam and a4.beam must be included on the command line

> elink -shell ...

Makes an executable that runs in a shell capable of understanding line editing commands. This is useful if you want to write an interactive application that behaves like the Erlang shell.

> elink -r /home/joe/foo/bar /home/joe/bing/bongo

Changes the environment ${ERLANG_EARS} which is hidden inside the executable /home/joe/bing/bongo to /home/joe/foo/bar.

The directory /home/joe/foo/bar must contain the files erlang.ear and ErlBoot_new.img - this command is so obscure that you will probably never ever need to use it. If you got this far then no manual will help.

Erlang scripts

escript is the scripting interface to Erlang.

Here is an example of a simple Erlang script:

#!/usr/bin/env escript
-export([main/1]).

main([X]) ->
    J = list_to_integer(X),
    N = fac(J),
    io:format("factorial ~w = ~w~n",[J, N]).

fac(0) -> 1;
fac(N) ->
    N * fac(N-1).

Make the file executable and run:

> chmod u+x ./factorial
> ./factorial 123
factorial 123 = 12146304367025329675766243241881295855454217088
483382315328918161829235892362167668831156960612640202170735835
221294047782591091570411651472186029519906261646730733907419814
952960000000000000000000000000000

The script must export main/1. The directive -mode(compile) can be included to improve efficiency.

esh

esh is an interactive query shell. To start it:

> esh
Erlang (BEAM) emulator version 5.2 [source] [hipe]

Eshell V5.2  (abort with ^G)
1> 

ecc

ecc is the Erlang compiler.

> ecc *.erl

Compiles files. ecc accepts the following flags:

elink

elink is the Erlang linker.

elink [-shell] [-windows] [-o OUT[.exe]]
      [-s Mod] [-m] M1.beam ...

Arguments can be pretty much in any order.

ear

ear is a command line utility for maintaining Erlang archives.

Erlang stand-alone applications use demand-code loading or static code loading.

The demand code loader loads code from Erlang archives (.ear files) - Erlang archives are created with the ear command.

In a statically loaded application all necessary code is loaded contained in the application.

The preferred method of building an application is to use demand code loading. The base distribution includes a single archive erlang.ear which contains all the modules and include files in stdlib kernel and compiler - this is sufficient for making a large class of applications.

Building and maintaining Erlang archives is done with the program ear

Shipping several applications with your own personal library

If you have several applications you might like to proceed as follows:

Create a personal library

> ear -a joe.ear PathToCompiledModules1/*.beam
> ear -a joe.ear PathToCompiledModules2/*.beam
> ear -a joe.ear PathToCompiledModules3/*.beam

Now distribute joe.ear the installer must place this in the same directory as erlang.ear, module names in joe.ear must not collide with the names in erlang.ear