chore(lang-rust): updated docs & LLDB extension

Signed-off-by: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com>

Author: georglauterbach

src/lang-rust/NOTES.md

@@ -0,0 +1,42 @@
+## Notes
+
+### Extensions
+
+| Areas                 | Extension |
+| :-------------------- | :-------- |
+| Rust Language Server  | [`rust-lang.rust-analyzer`](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) |
+| TOML Language Support | [`tamasfe.even-better-toml`](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) |
+| Debugger              | [`vadimcn.vscode-lldb`](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) |
+
+### Debugger
+
+`rust-analyzer` is configured to use `vadimcn.vscode-lldb` as its debugger.
+
+#### Pretty Printing
+
+To enable pretty printing in the debugger, add the setting
+
+```jsonc
+"lldb.launch.preRunCommands": [
+  "command script import ${containerEnv:DEV_CONTAINER_FEATURE_GHCR_IO_GEORGLAUTERBACH_LANG_RUST_LLDB_PRETTIFIER}"
+]
+```
+
+to the `devcontainer.json`'s IDE-specific settings (example shown is for VS Code). The symbol definitions are copied from [`cmrschwarz/rust-prettifier-for-lldb`](https://github.com/cmrschwarz/rust-prettifier-for-lldb).
+
+### Using a Subdirectory for Your Rust Code
+
+If your code lives in a separate directory that is not the repository root, set
+
+```jsonc
+"lldb.launch.cwd": "${containerWorkspaceFolder}/<SUBDIRECTORY OF YOUR CODE>",
+"lldb.launch.relativePathBase": "${containerWorkspaceFolder}/<SUBDIRECTORY OF YOUR CODE>"
+```
+
+You should also create a symbolic link for a potential `rust-toolchain.toml` file via
+
+```bash
+ln -s "<SUBDIRECTORY OF YOUR CODE>/rust-toolchain.toml" 'rust-toolchain.toml'
+```
+
+This is currently required for the [`rust-lang.rust-analyzer`](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) extension to work properly.

src/lang-rust/data/on_create_command.sh

@@ -5,6 +5,7 @@ set -e -u
 FEATURE_SHARE_DIR=/usr/local/share/dev_containers/features/ghcr_io/georglauterbach/lang_rust
 readonly FEATURE_SHARE_DIR
 
+# update directory permissions
 update_directory() {
   ENV_NAME=${1:?"(bug) environment variable name required"}
   ENV_VALUE=$(eval "echo \"\$${ENV_NAME}\"")
@@ -21,12 +22,13 @@ update_directory() {
   else
     printf "  -> creating directory: "
 
-    if mkdir --parents "${ENV_VALUE}" 2>/dev/null \
-    || sudo mkdir --parents "${ENV_VALUE}"; then
+    if mkdir --parents "${ENV_VALUE}"                   2>/dev/null \
+    || sudo mkdir --parents "${ENV_VALUE}"              2>/dev/null \
+    || su - root sh -c "mkdir --parents '${ENV_VALUE}'" 2>/dev/null
+    then
       echo 'done'
     else
-      echo 'failed'
-      return 1
+      echo "FAILED ('sudo' missing or 'su' with 'root' failed)"
     fi
   fi
 
@@ -39,12 +41,13 @@ update_directory() {
   }; then
     printf "  -> updating permissions: "
 
-    if chown --recursive "$(id -u):$(id -g)" "${ENV_VALUE}" 2>/dev/null \
-    || sudo chown --recursive "$(id -u):$(id -g)" "${ENV_VALUE}"; then
+    if chown --recursive "$(id -u):$(id -g)" "${ENV_VALUE}"                   2>/dev/null \
+    || sudo chown --recursive "$(id -u):$(id -g)" "${ENV_VALUE}"              2>/dev/null \
+    || su - root sh -c "chown --recursive '$(id -u):$(id -g)' '${ENV_VALUE}'" 2>/dev/null
+    then
       echo 'done'
     else
-      echo 'failed'
-      return 1
+      echo "FAILED ('sudo' missing or 'su' with 'root' failed)"
     fi
   else
     echo "  -> directory already has proper permissions"

src/lang-rust/devcontainer-feature.json

@@ -1,7 +1,7 @@
 // ref: https://github.com/devcontainers/spec/blob/main/schemas/devContainerFeature.schema.json
 {
   "id": "lang-rust",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "name": "Programming Language | Rust",
   "documentationURL": "https://github.com/georglauterbach/dev-container-features/tree/main/src/rust",
   "description": "Work efficiently and effortlessly with Rust",
@@ -42,25 +42,23 @@
         // TOML language support
         "tamasfe.even-better-toml",
         // LLVM-based debugger (LLDB)
-        "vadimcn.vscode-lldb@1.11.7"
+        "vadimcn.vscode-lldb@1.11.8"
       ],
       "settings": {
-        // TODO
+        // Mark the directory for build-artifacts as read-only
+        // and apply the same in the subdirectory `code/`
         "files.readonlyInclude": {
           "target": true,
           "code/target": true
         },
-        // TODO
+        // Exclude the directory for build-artifacts from the
+        // VS explorer watcher and apply the same in the
+        // subdirectory `code/`
         "files.watcherExclude": {
           "target": true,
           "code/target": true
         },
-        // TODO
-        "files.exclude": {
-          "target": true,
-          "code/target": true
-        },
-        // TODO
+        // Tell LLDB that we debug Rust
         "lldb.launch.sourceLanguages": [
           "rust"
         ]