initial deploy recipe

Makefile

@@ -3,3 +3,13 @@ dev:
 
 test:
 	luarocks test
+
+# Install the rock in the local tree (aka user home directory)
+deploy:
+	luarocks --local build
+	# Run at your own risk:
+	# mkdir -p ~/.config/awesome
+	# cp -r config/awesome ~/.config/awesome
+
+try-current:
+	scripts/run.sh try-current

README.md

@@ -1,20 +1,66 @@
 # awesomerc.lua boilerplate
 
-Boilerplate to help getting started with Awesome. This repository contains the default `awesomerc.lua` file with pre-configured tools.
+Boilerplate to help getting started with Awesome. This repository contains the
+default `awesomerc.lua` file with pre-configured tools.
 
 ## Features
 
 - Luacheck: Statically check the Lua code
 - Stylua: Lua code formatter
 - cSpell: Fix typo in code
-- Live run with Xephyr and restart on change with Luamon (run `make dev` command)
+- Live run with Xephyr and restart on change with Luamon (run `make dev`
+  command)
 - VSCode settings and recommended extensions
 - VSCode debugger with local-lua-debugger-vscode
 - Busted: Unit test Lua
 
+## How to use
+
+### Dev mode
+
+Run in live development with the command
+
+```sh
+make dev
+```
+
+Edit the config and get live update in the Xephyr window!
+
+The Awesome WM entrypoint is the `config/awesome/rc.lua` file. This is what
+Awesome uses as the configuration file. The role of this file is to initialize
+the environment (load luarocks, start the debugger when required, ...). The
+actual user configuration should go to the `src/awesomerc` directory. Every
+files from the sources should be mapped by the `awesomerc-dev-1.rockspec`'s
+`build.modules` table. It is required to package the configuration as a rock.
+
+### Debug with VSCode
+
+Terminate the dev mode. Then run the `Debug with Xephyr` debug profile from
+VSCode.
+
+### Deploy
+
+When ready, deploy the config to your home directory with the command
+
+```sh
+make deploy
+```
+
+The deploy recipe builds the rock and install it locally with `luarocks --local
+build`. It have to effect to pushes the rock to the `~/.luarocks` directory. For
+now, it have no effect to the current Awesome configuration. To complete the
+configuration installation, `cp config/awesome ~/.config/awesome` must be run
+manually.
+
+The `make try-current` recipe can be optionally used to start Awesome in Xephyr
+with the actual user installed configuration.
+
+Restart Awesome, now enjoy your new config!
+
 ## TODOs
 
-- Install the config to ~/.config/awesome
+- Install the config to ~/.config/awesome -> Partially done, we build a rock,
+  but don't write to the user dotfiles
 - Pipeline (GitHub Actions?)
 - Automated integration tests (with Xephyr/headless?)
 - Migrate to Teal?

awesomerc-dev-1.rockspec

@@ -10,7 +10,9 @@ description = {
 }
 build = {
    type = "builtin",
-   modules = {},
+   modules = {
+      ["awesomerc.init"] = "src/awesomerc/init.lua",
+   },
 }
 test = {
    type = "busted",

config/awesome/rc.lua

@@ -0,0 +1,9 @@
+-- awesome_mode: api-level=4:screen=on
+
+if os.getenv "LOCAL_LUA_DEBUGGER_VSCODE" == "1" then
+   require("lldebugger").start()
+end
+
+require "luarocks.loader"
+
+require "awesomerc"

scripts/run.sh

@@ -5,7 +5,7 @@ awesome=/usr/bin/awesome
 
 # TODO: configurable
 confdir=./src/awesomerc
-rcfile=$confdir/awesomerc.lua
+rcfile=./config/awesome/rc.lua
 screen=1600x900
 
 display=:1.0
@@ -34,6 +34,11 @@ case $1 in
         sleep 1 # wait for Xephyr to be ready
         runAwesome
         ;;
+    try-current)
+        startXephyr
+        sleep 1 # wait for Xephyr to be ready
+        DISPLAY=$display $awesome
+        ;;
     *)
         echo "Need command"
         ;;

src/awesomerc/init.lua

@@ -1,9 +1,3 @@
--- awesome_mode: api-level=4:screen=on
-
-if os.getenv "LOCAL_LUA_DEBUGGER_VSCODE" == "1" then
-   require("lldebugger").start()
-end
-
 local awful = require "awful"
 local beautiful = require "beautiful"
 local gears = require "gears"
@@ -14,7 +8,6 @@ local ruled = require "ruled"
 local wibox = require "wibox"
 require "awful.autofocus"
 require "awful.hotkeys_popup.keys"
-require "luarocks.loader"
 
 naughty.connect_signal("request::display_error", function(message, startup)
    naughty.notification {