cabal-install: don't pass exe name to external commands

Previously the executable name of the external command was passed to external commands as the
first argument.

This behaviour was adapated from cargo which does this because of reasons that are internal
to rust that do not affect GHC Haskell, and are even orthogonal to patterns that see common use in
Haskell.

Additionally, it complicates the 'simple' case which is what we should optimize for when building
such a feature.

The previous use case (one executable that serves multiple external subcommands) is still possible
by the following means:
- using a wrapper around the executable
- using a symlink and check argv[0] in the executable

Additionally, the variable `$CABAL` that was set by `cabal-install` was renamed to `CABAL_EXTERNAL_CABAL_PATH`. This has two reasons:
1. it makes migration easier for users of the external command feature that were previously expecting the name of the executable
   to appear in `argv[1]`
2. it does not unnecessarily pollute the environment variable namespace as it turns out some other tools have been and are already
   using this name, historically

Resolves #10275

Author: MangoIV

cabal-install/src/Distribution/Client/Main.hs

@@ -372,17 +372,20 @@ mainWorker args = do
       -> [String]
       -> IO (CommandParse Action)
     delegateToExternal commands' name cmdArgs = do
+      -- we rely on cabal's implementation of findProgramOnSearchPath not following
+      -- symlinks here. If that ever happens, then the argv[0] of the called executable
+      -- will be different to the intended one and will break tools that work by reading it.
       mCommand <- findProgramOnSearchPath normal defaultProgramSearchPath ("cabal-" <> name)
       case mCommand of
-        Just (exec, _) -> return (CommandReadyToGo $ \_ -> callExternal exec name cmdArgs)
+        Just (exec, _) -> return (CommandReadyToGo $ \_ -> callExternal exec cmdArgs)
         Nothing -> defaultCommandFallback commands' name cmdArgs
 
-    callExternal :: String -> String -> [String] -> IO ()
-    callExternal exec name cmdArgs = do
+    callExternal :: String -> [String] -> IO ()
+    callExternal exec cmdArgs = do
       cur_env <- getEnvironment
       cabal_exe <- getExecutablePath
-      let new_env = ("CABAL", cabal_exe) : cur_env
-      result <- try $ createProcess ((proc exec (name : cmdArgs)){env = Just new_env})
+      let new_env = ("CABAL_EXTERNAL_CABAL_PATH", cabal_exe) : cur_env
+      result <- try $ createProcess ((proc exec cmdArgs){env = Just new_env})
       case result of
         Left ex -> printErrors ["Error executing external command: " ++ show (ex :: SomeException)]
         Right (_, _, _, ph) -> waitForProcess ph >>= exitWith

cabal-testsuite/PackageTests/ExternalCommand/cabal.test.hs

@@ -17,7 +17,6 @@ main = do
     addToPath (takeDirectory exe_path) $ do
       -- Test that the thing works at all
       res <- cabal_raw_action ["aaaa"] (\h -> () <$ Process.waitForProcess h)
-      assertOutputContains "aaaa" res
 
       -- Test that the extra arguments are passed on
       res <- cabal_raw_action ["aaaa", "--foobaz"] (\h -> () <$ Process.waitForProcess h)

cabal-testsuite/PackageTests/ExternalCommandEnv/setup-test/AAAA.hs

@@ -4,7 +4,7 @@ import System.Environment
 import System.Process
 
 main = do
-  cabal_proc <- getEnv "CABAL"
+  cabal_proc <- getEnv "CABAL_EXTERNAL_CABAL_PATH"
   other_var <- getEnv "OTHER_VAR"
   putStrLn ("OTHER_VAR is set to: " ++ other_var)
   callProcess cabal_proc ["--version"]

cabal-testsuite/PackageTests/ExternalCommandExitCode/cabal.test.hs

@@ -18,7 +18,6 @@ main = do
     addToPath (takeDirectory exe_path) $ do
       -- Test that the thing works at all
       res <- fails $ cabal_raw_action ["aaaa"] (\h -> () <$ Process.waitForProcess h)
-      assertOutputContains "aaaa" res
       -- Check the exit code is the one returned by subcommand
       unless (resultExitCode res == ExitFailure 99) (assertFailure $ "Incorrect exit code: " ++ show (resultExitCode res))
 

cabal-testsuite/PackageTests/ExternalCommandHelp/setup-test/AAAA.hs

@@ -5,5 +5,5 @@ import System.Environment
 main = do
   args <- getArgs
   case args of
-    ["aaaa" , "--help"] -> putStrLn "I am helping with the aaaa command"
+    ["--help"] -> putStrLn "I am helping with the aaaa command"
     _ -> putStrLn "aaaa"

changelog.d/pr-11232.md

@@ -0,0 +1,24 @@
+---
+synopsis: don't pass exe name to external commands
+packages: [cabal-install]
+prs: 11232
+issues: [10275]
+significance: significant
+---
+
+Previously the executable name of the external command was passed to external commands as the first argument.
+
+This behaviour was adapted from cargo which does this because of reasons that are internal to rust that do not affect GHC Haskell, and are even orthogonal to patterns that see common use in Haskell.
+
+Additionally, it complicates the 'simple' case which is what we should optimize for when building such a feature - with this change, for any executable `cabal-foo` in your search-path, `cabal foo` will be a valid invocation of that command.
+
+The previous use case (one executable that serves multiple external subcommands) is still possible by the following means:
+
+- using a wrapper around the executable
+- using a symlink and check argv\[0\] in the executable
+
+Additionally, the variable `$CABAL` that was set by `cabal-install` was renamed to `CABAL_EXTERNAL_CABAL_PATH`. This has two reasons:
+1. it makes migration easier for users of the external command feature that were previously expecting the name of the executable
+   to appear in `argv[1]`
+2. it does not unnecessarily pollute the environment variable namespace as it turns out some other tools have been and are already
+   using this name, historically

doc/external-commands.rst

@@ -3,19 +3,27 @@ External Commands
 
 ``cabal-install`` provides a system for external commands, akin to the ones used by tools like ``git`` or ``cargo``.
 
-If you execute ``cabal <cmd>``, ``cabal-install`` will search the path for an executable named ``cabal-<cmd>`` and execute it. The name of the command is passed as the first argument and
-the remaining arguments are passed afterwards. An error will be thrown in case the custom command is not found. The exit code of cabal when calling an external command is the same as the exit code
+If you execute ``cabal <cmd>``, ``cabal-install`` will search the path for an executable named ``cabal-<cmd>`` and execute it. An error will be thrown in case the custom command is not found. The exit code of cabal when calling an external command is the same as the exit code
 of the command.
 
-The ``$CABAL`` environment variable is set to the path of the ``cabal-install`` executable
+The name of the command is *not* passed as the first argument as it is done in cargo, instead you will have to figure out the name via `argv[0]` as
+is the case in e.g. `git`.
+
+The ``$CABAL_EXTERNAL_CABAL_PATH`` environment variable is set to the path of the ``cabal-install`` executable
 which invoked the subcommand.
 
 It is strongly recommended that you implement your custom commands by calling the
-CLI via the ``$CABAL`` variable rather than linking against the ``Cabal`` library.
+CLI via the ``$CABAL_EXTERNAL_CABAL_PATH`` variable rather than linking against the ``Cabal`` library.
 There is no guarantee that the subcommand will link against the same version of the
 ``Cabal`` library as ``cabal-install`` so it would lead to unexpected results and
 incompatibilities.
 
+Historically, the `cabal-install` binary would pass the name of the executable which it is trying to invoke via the external command feature as
+the first argument to the executable itself. The main difference was that ``$CABAL_EXTERNAL_CABAL_PATH`` was called ``$CABAL``, which means that
+you can stay compatible with both versions, depending on which variable is set.
+
+Mind that if you were implementing external commands previously, you will not need to skip the first argument (the executable name) anymore.
+
 ``cabal-install`` can also display the help message of the external command.
 When ``cabal help <cmd>`` is invoked, then ``cabal-<cmd> <cmd> --help`` will be called so
 your external command can display a help message.