Update README and add Vagrant devenv tasks. #9

vilfa · Oct 3, 2022 · cfa1008 · cfa1008
1 parent 2382f01
commit cfa1008
Show file tree

Hide file tree

Showing 2 changed files with 129 additions and 5 deletions.
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -2,24 +2,86 @@
     "version": "2.0.0",
     "tasks": [
         {
-            "label": "Remote: Setup",
+            "label": "Devenv: Connect to Display",
             "type": "shell",
-            "command": "${workspaceFolder}/remote/setup.sh",
+            "command": "virt-viewer -ac qemu:///system --uuid 60fa5b18-e4d6-47a4-af7a-023d3d34bfaa",
+            "group": "none",
+            "presentation": {
+                "reveal": "never",
+                "panel": "shared"
+            },
+            "isBackground": true,
+            "problemMatcher": []
+        },
+        {
+            "label": "Devenv: Prepare Project (Git)",
+            "type": "shell",
+            "command": "vagrant provision --provision-with prepare_git",
+            "group": "build",
+            "presentation": {
+                "reveal": "always",
+                "panel": "shared"
+            }
+        },
+        {
+            "label": "Devenv: Prepare Project (Local)",
+            "type": "shell",
+            "command": "vagrant provision --provision-with prepare_local",
+            "group": "build",
+            "presentation": {
+                "reveal": "always",
+                "panel": "shared"
+            }
+        },
+        {
+            "label": "Devenv: Build Project",
+            "type": "shell",
+            "command": "vagrant provision --provision-with build",
+            "group": "build",
+            "presentation": {
+                "reveal": "always",
+                "panel": "shared"
+            }
+        },
+        {
+            "label": "Devenv: Update Project",
+            "type": "shell",
+            "command": "vagrant provision --provision-with update",
+            "group": "build",
+            "presentation": {
+                "reveal": "always",
+                "panel": "shared"
+            }
+        },
+        {
+            "label": "Devenv: Run Bonsai",
+            "type": "shell",
+            "command": "vagrant provision --provision-with run",
             "group": "build",
             "presentation": {
                 "reveal": "always",
                 "panel": "shared"
             }
         },
         {
-            "label": "Remote: Build all machines",
+            "label": "Devenv: Kill Bonsai",
             "type": "shell",
-            "command": "${workspaceFolder}/remote/build.sh",
+            "command": "vagrant provision --provision-with kill",
             "group": "build",
             "presentation": {
                 "reveal": "always",
                 "panel": "shared"
             }
         },
+        {
+            "label": "Devenv: Clean Project",
+            "type": "shell",
+            "command": "vagrant provision --provision-with clean",
+            "group": "build",
+            "presentation": {
+                "reveal": "always",
+                "panel": "shared"
+            }
+        }
     ]
 }
diff --git a/README.md b/README.md
@@ -46,7 +46,69 @@ library, meaning a rock-solid foundation to build on.
 * `brightnessctl` (brightness control via waybar)
 
 ### Using the Vagrant development environment
-TODO: Finish this section
+For the optimal developer experience, it is recommended you use the provided 
+Vagrant development environment. Currently this environment is only configured 
+with the `libvirt` provider, however, multiple Vagrant providers could quite easily
+be added in the future.
+
+To use this environment, make sure, you have the latest versions of the following
+packages:
+* `vagrant` (manages virtual machines)
+* `vagrant-libvirt` (the `libvirt` plugin for Vagrant)
+* `libvirt` + `qemu` (should be installed automatically with `vagrant`)
+* `virt-manager` (graphical frontend to `libvirt`)
+* `virt-viewer` (connect to virtual machine display)
+
+After installing the necessary dependencies (a restart may be required), move to
+the project root and simply run
+```bash
+vagrant up
+```
+
+This should automatically create a new virtual machine that is set up with all
+necessary compile- and run-time dependencies. As far as using this setup goes,
+there are several commands/provisioners that are available to you, to make working
+with the development virtual machine easier. These should be run in the project 
+root, in the following form
+```bash
+vagrant provision --provision-with <command/provisioner>
+```
+
+The available commands/provisioners are
+* `connect` -> connect to the dev env display using `virt-manager`
+* `prepare_git` -> clone the git upstream & prepare meson build env
+* `prepare_local` -> copy local sources from your project root & prepare meson build env
+* `build` -> build the project in the build env
+* `update` -> update build env with sources from your project root
+* `run` -> run bonsai in the graphical session on the dev env (currently not working)
+* `kill` -> kill the bonsai process on the dev env
+* `clean` -> clean the meson build artefacts from the project folder on the dev env
+
+Thus, the steps for the first build could be
+```bash
+git clone https://github.com/vilfa/bonsai.git && cd bonsai
+vagrant up
+vagrant provision --provision-with prepare_local
+vagrant provision --provision-with build
+```
+
+Then, in the dev env graphical session, login as vagrant:vagrant, and run the built
+project with
+```bash
+cd home/vagrant/bonsai && ./builddir/bonsai/bonsai
+```
+
+Then, when you make some changes, you might want to update your source on the dev env
+and rerun the compositor. That could also be done by running
+```bash
+vagrant provision --provision-with kill
+vagrant provision --provision-with update
+vagrant provision --provision-with build
+```
+
+...and repeating the above step for running.
+
+To make this even easier, VS Code tasks are also provided. Search for 'devenv'.
 
 ### Building and installing