Add warnings about exec usage. (#23820)

Related to https://github.com/nim-lang/Nim/issues/23819 and also found
in discord
https://discord.com/channels/371759389889003530/371759389889003532/1260845467147829372
Since nothing can be done, besides deprecating the function, a warning
is a better option.

---------

Co-authored-by: Juan Carlos <juancarlospaco@gmail.com>

1 files changed, 9 insertions, 2 deletions

diff --git a/lib/system/nimscript.nim b/lib/system/nimscript.nim
index bdf6145a1..40df3c7eb 100644
--- a/lib/system/nimscript.nim
+++ b/lib/system/nimscript.nim
@@ -253,7 +253,8 @@ proc cpDir*(`from`, to: string) {.raises: [OSError].} =
 proc exec*(command: string) {.
   raises: [OSError], tags: [ExecIOEffect, WriteIOEffect].} =
   ## Executes an external process. If the external process terminates with
-  ## a non-zero exit code, an OSError exception is raised.
+  ## a non-zero exit code, an OSError exception is raised. The command is
+  ## executed relative to the current source path.
   ##
   ## **Note:** If you need a version of `exec` that returns the exit code
   ## and text output of the command, you can use `system.gorgeEx
@@ -267,11 +268,17 @@ proc exec*(command: string, input: string, cache = "") {.
   raises: [OSError], tags: [ExecIOEffect, WriteIOEffect].} =
   ## Executes an external process. If the external process terminates with
   ## a non-zero exit code, an OSError exception is raised.
+  ##
+  ## .. warning:: This version of `exec` is executed relative to the nimscript
+  ## module path, which affects how the command resolves relative paths. Thus
+  ## it is generally better to use `gorgeEx` directly when you need more
+  ## control over the execution environment or when working with commands
+  ## that deal with relative paths.
   log "exec: " & command:
     let (output, exitCode) = gorgeEx(command, input, cache)
+    echo output
     if exitCode != 0:
       raise newException(OSError, "FAILED: " & command)
-    echo output
 
 proc selfExec*(command: string) {.
   raises: [OSError], tags: [ExecIOEffect, WriteIOEffect].} =