From d7b4e589f1716e2de5087a491ea1701d294dccbc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 22 Oct 2015 23:23:18 +0200
Subject: Add shell chapter and tests

---
 doc/src/guide/shell.asciidoc | 44 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)

(limited to 'doc/src/guide/shell.asciidoc')

diff --git a/doc/src/guide/shell.asciidoc b/doc/src/guide/shell.asciidoc
index a5643c2..083c160 100644
--- a/doc/src/guide/shell.asciidoc
+++ b/doc/src/guide/shell.asciidoc
@@ -1,5 +1,45 @@
 == Erlang shell
 
-// @todo Write it.
+Erlang.mk provides a convenient target for starting a shell
+with all the paths set properly to experiment with your code.
 
-Placeholder chapter.
+=== Configuration
+
+The `SHELL_DEPS` variable can be used to define dependencies
+that are only to be used when the `make shell` command is called.
+For example, if you want to use _kjell_ as your shell:
+
+[source,make]
+SHELL_DEPS = kjell
+
+Dependencies are downloaded and compiled the first time you
+run the `make shell` command.
+
+You can customize the executable used to start the Erlang shell.
+To continue with our example, if you want to use _kjell_ as your
+shell, you also need to change `SHELL_ERL` and point it to the
+`kjell` executable:
+
+[source,make]
+SHELL_ERL = $(DEPS_DIR)/kjell/bin/kjell
+
+You can specify additional options to be used when starting the
+shell using the `SHELL_OPTS` variable:
+
+[source,make]
+SHELL_OPTS = -setcookie chocolate
+
+Any of the usual `erl` options can be used, including `-eval`:
+
+[source,make]
+SHELL_OPTS = -eval 'my_app:run()'
+
+=== Usage
+
+To start the shell, all you need is the following command:
+
+[source,bash]
+$ make shell
+
+The shell can be stopped as usual with a double Ctrl+C or the
+command `q().`.
-- 
cgit v1.2.3

