Options.hs

-- | Options supported by the debugger
--
-- For parsing see 'Development.Debug.Options.Parser'
module Development.Debug.Options
  ( HdbOptions(..) ) where

import Colog.Core (Severity)

-- | The options `hdb` is invoked in the command line with
data HdbOptions
  -- | @server [--internal-interpreter] [--disable-ipe-backtraces] --port <port>@
  = HdbDAPServer
    { port :: Int
    , verbosity :: Severity
    , internalInterpreter :: Bool
    , disableIpeBacktraces :: Bool
    }
  -- | @cli [--internal-interpreter] [--disable-ipe-backtraces] [--entry-point=<entryPoint>] [--extra-ghc-args="<args>"] [<entryFile>] -- [<entryArgs>]@
  | HdbCLI
    { entryPoint :: String
    , entryFile :: FilePath
    , entryArgs :: [String]
    , extraGhcArgs :: [String]
    , verbosity :: Severity
    , internalInterpreter :: Bool
    , disableIpeBacktraces :: Bool
    , debuggeeStdin :: Maybe FilePath
    }

  -- | @proxy --port <port>@
  --
  -- The proxy command serves as a middle man between the user and the debugger.
  -- It is used implicitly by DAP mode when using the internal interpreter:
  -- upon initialization, the debugger server asks the DAP client to
  -- @runInTerminal@ the @hdb proxy --port ...@ command at a port determined by
  -- the debugger server.
  --
  -- The proxy mode will forward stdin to the debugger server and will be
  -- forwarded the debuggee's stdout. This essentially enables the user to
  -- observe and interact with the execution of the debugger, in a standalone
  -- terminal.
  --
  -- (When using the external interpreter, the proxy isn't necessary because
  -- the DAP server can launch directly the external interpreter attached to
  -- the user's terminal)
  --
  -- See #44 for the original ticket
  | HdbProxy
    { port :: Int
    , verbosity :: Severity
    }

  -- | Launch the custom-for-the-debugger external interpreter for running the
  -- debuggee process.
  --
  -- Using an external interpreter will guarantee the debugger and debuggee run
  -- on separate processes. This comes with many benefits:
  --  * Debugger vs debuggee threads naturally separated
  --  * Debugger vs debuggee stdin/stdout/stderr naturally separated
  --  * No *** Ignoring breakpoint when debugging the debugger against another program
  --
  --  A custom server is necessary for the custom commands (starting with GHC
  --  9.16) and because the external interpreter in GHC 9.14 is not compiled
  --  with -threaded, which is a requirement for using thread/stack cloning
  --  messages in the external process.
  --
  --  See #169
  | HdbExternalInterpreter
      { writeFd :: Int
      , readFd  :: Int
      }

  -- | Launch the custom-for-the-debugger external interpreter and connect it
  -- to the debugger through a TCP socket.
  | HdbExternalInterpreterPort
      { port :: Int
      }