tools: improve v symlink -githubci diagnostic message, when used ou…

…tside CIs or with sudo (#21340)

.github/workflows/check_symlink_works.yml

@@ -0,0 +1,88 @@
+name: V Symlink Works
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'cmd/tools/vsymlink.v'
+      - '.github/workflows/check_symlink_works.yml'
+  pull_request:
+    paths:
+      - 'cmd/tools/vsymlink.v'
+      - '.github/workflows/check_symlink_works.yml'
+
+jobs:
+  check-ubuntu-with-sudo:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout V
+        uses: actions/checkout@v4
+      - name: Build V
+        run: make && sudo ./v symlink
+      - name: Check if V is usable
+        run: |
+          pwd
+          v version
+          cd ~
+          pwd
+          v version
+          echo 'println(123)' > hi.v
+          v run hi.v
+          echo 'Using `sudo ./v symlink` :rocket: !!!' >> $GITHUB_STEP_SUMMARY
+
+  check-ubuntu:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout V
+        uses: actions/checkout@v4
+      - name: Build V
+        run: make && ./v symlink -githubci
+      - name: Check if V is usable
+        run: |
+          pwd
+          v version
+          cd ~
+          pwd
+          v version
+          echo 'println(123)' > hi.v
+          v run hi.v
+          echo "Everything was fine :rocket:" >> $GITHUB_STEP_SUMMARY
+
+  check-macos:
+    runs-on: macos-13
+    steps:
+      - name: Checkout V
+        uses: actions/checkout@v4
+      - name: Build V
+        run: make && ./v symlink -githubci
+      - name: Check if V is usable
+        run: |
+          pwd
+          v version
+          cd ~
+          pwd
+          v version
+          echo 'println(123)' > hi.v
+          v run hi.v
+          echo "Everything fine on macos too :rocket:" >> $GITHUB_STEP_SUMMARY
+
+  check-windows:
+    runs-on: windows-2019
+    steps:
+      - name: Checkout V
+        uses: actions/checkout@v4
+      - name: Build V
+        run: |
+          .\make.bat
+          .\v.exe symlink -githubci
+      - name: Check if V is usable
+        shell: bash
+        run: |
+          pwd
+          v version
+          cd ~
+          pwd
+          v version
+          echo 'println(123)' > hi.v
+          v run hi.v
+          echo "All fine on Windows as well :rocket:" >> $GITHUB_STEP_SUMMARY

cmd/tools/vsymlink.v

@@ -39,7 +39,12 @@ fn setup_symlink_github() {
 	// 1. https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#environment-files
 	// 2. https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable
 	mut content := os.read_file(os.getenv('GITHUB_PATH')) or {
-		panic('Failed to read GITHUB_PATH.')
+		eprintln('The `GITHUB_PATH` env variable is not defined.')
+		eprintln('    This command: `v symlink -githubci` is intended to be used within GithubActions .yml files.')
+		eprintln('    It also needs to be run *as is*, *** without `sudo` ***, otherwise it will not work.')
+		eprintln('    For local usage, outside CIs, on !windows, prefer `sudo ./v symlink` .')
+		eprintln('    On windows, use `.\\v.exe symlink` instead.')
+		exit(1)
 	}
 	content += '\n${os.getwd()}\n'
 	os.write_file(os.getenv('GITHUB_PATH'), content) or { panic('Failed to write to GITHUB_PATH.') }