From fa8b7bdced10bd0192beb04016914bae4005a947 Mon Sep 17 00:00:00 2001
From: Aire-One <aireone@aireone.xyz>
Date: Wed, 23 Oct 2024 20:09:48 +0200
Subject: [PATCH] initial deploy recipe

---
 Makefile                                  | 10 +++++
 README.md                                 | 52 +++++++++++++++++++++--
 awesomerc-dev-1.rockspec                  |  4 +-
 config/awesome/rc.lua                     |  9 ++++
 scripts/run.sh                            |  7 ++-
 src/awesomerc/{awesomerc.lua => init.lua} |  7 ---
 6 files changed, 77 insertions(+), 12 deletions(-)
 create mode 100644 config/awesome/rc.lua
 rename src/awesomerc/{awesomerc.lua => init.lua} (99%)

diff --git a/Makefile b/Makefile
index c5eeb11..43a9542 100644
--- a/Makefile
+++ b/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
diff --git a/README.md b/README.md
index 2770318..ce629ba 100644
--- a/README.md
+++ b/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?
diff --git a/awesomerc-dev-1.rockspec b/awesomerc-dev-1.rockspec
index e7a1af0..c1e3824 100644
--- a/awesomerc-dev-1.rockspec
+++ b/awesomerc-dev-1.rockspec
@@ -10,7 +10,9 @@ description = {
 }
 build = {
    type = "builtin",
-   modules = {},
+   modules = {
+      ["awesomerc.init"] = "src/awesomerc/init.lua",
+   },
 }
 test = {
    type = "busted",
diff --git a/config/awesome/rc.lua b/config/awesome/rc.lua
new file mode 100644
index 0000000..2d0ea0b
--- /dev/null
+++ b/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"
diff --git a/scripts/run.sh b/scripts/run.sh
index dc78b0b..44e7527 100755
--- a/scripts/run.sh
+++ b/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"
         ;;
diff --git a/src/awesomerc/awesomerc.lua b/src/awesomerc/init.lua
similarity index 99%
rename from src/awesomerc/awesomerc.lua
rename to src/awesomerc/init.lua
index 7a49e5f..831ab2e 100644
--- a/src/awesomerc/awesomerc.lua
+++ b/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 {