Add shell chapter and tests

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().`.

plugins/shell.mk

@@ -1,11 +1,13 @@
 # Copyright (c) 2014, M Robert Martin <rob@version2beta.com>
+# Copyright (c) 2015, Loïc Hoguin <essen@ninenines.eu>
 # This file is contributed to erlang.mk and subject to the terms of the ISC License.
 
 .PHONY: shell
 
 # Configuration.
 
-SHELL_PATH ?= -pa $(CURDIR)/ebin $(DEPS_DIR)/*/ebin
+SHELL_ERL ?= erl
+SHELL_PATHS ?= $(CURDIR)/ebin $(APPS_DIR)/*/ebin $(DEPS_DIR)/*/ebin
 SHELL_OPTS ?=
 
 ALL_SHELL_DEPS_DIRS = $(addprefix $(DEPS_DIR)/,$(SHELL_DEPS))
@@ -25,4 +27,4 @@ build-shell-deps: $(ALL_SHELL_DEPS_DIRS)
 	$(verbose) for dep in $(ALL_SHELL_DEPS_DIRS) ; do $(MAKE) -C $$dep ; done
 
 shell: build-shell-deps
-	$(gen_verbose) erl $(SHELL_PATH) $(SHELL_OPTS)
+	$(gen_verbose) $(SHELL_ERL) -pa $(SHELL_PATHS) $(SHELL_OPTS)

test/plugin_shell.mk

@@ -0,0 +1,37 @@
+# Shell plugin.
+
+SHELL_CASES = default kjell
+SHELL_TARGETS = $(addprefix shell-,$(SHELL_CASES))
+SHELL_CLEAN_TARGETS = $(addprefix clean-,$(SHELL_TARGETS))
+
+.PHONY: shell $(C_SRC_TARGETS) clean-shell $(SHELL_CLEAN_TARGETS)
+
+clean-shell: $(SHELL_CLEAN_TARGETS)
+
+$(SHELL_CLEAN_TARGETS):
+	$t rm -rf $(APP_TO_CLEAN)/
+
+shell: $(SHELL_TARGETS)
+
+shell-default: build clean-shell-default
+
+	$i "Bootstrap a new OTP library named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap-lib $v
+
+	$i "Run the shell"
+	$t $(MAKE) -C $(APP) shell SHELL_OPTS="-eval 'halt()'" $v
+
+shell-kjell: build clean-shell-kjell
+
+	$i "Bootstrap a new OTP library named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap-lib $v
+
+	$i "Add Kjell to the list of shell dependencies and set as default shell"
+	$t perl -ni.bak -e 'print;if ($$.==1) {print "SHELL_DEPS = kjell\nSHELL_ERL = \$$(DEPS_DIR)/kjell/bin/kjell\n"}' $(APP)/Makefile
+
+	$i "Run the shell"
+	$t $(MAKE) -C $(APP) shell SHELL_OPTS="-eval 'halt()'" $v