doc/external-commands.rst

   1 External Commands
   2 =================
   3
   4 ``cabal-install`` provides a system for external commands, akin to the ones used by tools like ``git`` or ``cargo``.
   5
   6 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
   7 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
   8 of the command.
   9
  10 The ``$CABAL`` environment variable is set to the path of the ``cabal-install`` executable
  11 which invoked the subcommand.
  12
  13 It is strongly recommended that you implement your custom commands by calling the
  14 CLI via the ``$CABAL`` variable rather than linking against the ``Cabal`` library.
  15 There is no guarantee that the subcommand will link against the same version of the
  16 ``Cabal`` library as ``cabal-install`` so it would lead to unexpected results and
  17 incompatibilities.
  18
  19 ``cabal-install`` can also display the help message of the external command.
  20 When ``cabal help <cmd>`` is invoked, then ``cabal-<cmd> <cmd> --help`` will be called so
  21 your external command can display a help message.
  22
  23 For ideas or existing external commands, visit `this Discourse thread <https://discourse.haskell.org/t/an-external-command-system-for-cabal-what-would-you-do-with-it/7114>`_.