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.
   8
   9 The ``$CABAL`` environment variable is set to the path of the ``cabal-install`` executable
  10 which invoked the subcommand.
  11
  12 It is strongly recommended that you implement your custom commands by calling the
  13 CLI via the ``$CABAL`` variable rather than linking against the ``Cabal`` library.
  14 There is no guarantee that the subcommand will link against the same version of the
  15 ``Cabal`` library as ``cabal-install`` so it would lead to unexpected results and
  16 incompatibilities.
  17
  18 ``cabal-install`` can also display the help message of the external command.
  19 When ``cabal help <cmd>`` is invoked, then ``cabal-<cmd> <cmd> --help`` will be called so
  20 your external command can display a help message.
  21
  22 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>`_.