    {-# LANGUAGE ScopedTypeVariables #-}

    {-
    -----------------------------------------------------------------------------
    --
    -- (c) The University of Glasgow 2001-2003
    --
    -- Access to system tools: gcc, cp, rm etc
    --
    -----------------------------------------------------------------------------
    -}

    module GHC.SysTools (
            -- * Initialisation
            initSysTools,

            -- * Interface to system tools
            module GHC.SysTools.Tasks,

            -- * Fast file copy
            copyFile,
            copyHandle,
            copyWithHeader,

            -- * General utilities
            Option(..),
            expandTopDir,
     ) where

    import GHC.Prelude

    import GHC.Utils.Panic
    import GHC.Driver.Session

    import GHC.SysTools.Tasks
    import GHC.SysTools.BaseDir
    import GHC.Settings.IO

    import Control.Monad.Trans.Except (runExceptT)
    import System.IO
    import Foreign.Marshal.Alloc (allocaBytes)
    import System.Directory (copyFile)

    {-
    Note [How GHC finds toolchain utilities]
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    GHC.SysTools.initSysProgs figures out exactly where all the auxiliary programs
    are, and initialises mutable variables to make it easy to call them.
    To do this, it makes use of definitions in Config.hs, which is a Haskell
    file containing variables whose value is figured out by the build system.

    Config.hs contains two sorts of things

      cGCC,         The *names* of the programs
      cCPP            e.g.  cGCC = gcc
      cUNLIT                cCPP = gcc -E
      etc           They do *not* include paths

      cUNLIT_DIR   The *path* to the directory containing unlit, split etc
      cSPLIT_DIR   *relative* to the root of the build tree,
                       for use when running *in-place* in a build tree (only)

    ---------------------------------------------
    NOTES for an ALTERNATIVE scheme (i.e *not* what is currently implemented):

    Another hair-brained scheme for simplifying the current tool location
    nightmare in GHC: Simon originally suggested using another
    configuration file along the lines of GCC's specs file - which is fine
    except that it means adding code to read yet another configuration
    file.  What I didn't notice is that the current package.conf is
    general enough to do this:

    Package
        {name = "tools",    import_dirs = [],  source_dirs = [],
         library_dirs = [], hs_libraries = [], extra_libraries = [],
         include_dirs = [], c_includes = [],   package_deps = [],
         extra_ghc_opts = ["-pgmc/usr/bin/gcc","-pgml${topdir}/bin/unlit", ... etc.],
         extra_cc_opts = [], extra_ld_opts = []}

    Which would have the advantage that we get to collect together in one
    place the path-specific package stuff with the path-specific tool
    stuff.
                    End of NOTES
    ---------------------------------------------

    ************************************************************************
    *                                                                      *
    \subsection{Initialisation}
    *                                                                      *
    ************************************************************************
    -}

    initSysTools :: String          -- TopDir path
                 -> IO Settings     -- Set all the mutable variables above, holding
                                    --      (a) the system programs
                                    --      (b) the package-config file
                                    --      (c) the GHC usage message
    initSysTools :: String -> IO Settings
    initSysTools String
    top_dir = do
      res <- ExceptT SettingsError IO Settings
    -> IO (Either SettingsError Settings)
    forall e (m :: * -> *) a. ExceptT e m a -> m (Either e a)
    runExceptT (ExceptT SettingsError IO Settings
     -> IO (Either SettingsError Settings))
    -> ExceptT SettingsError IO Settings
    -> IO (Either SettingsError Settings)
    forall a b. (a -> b) -> a -> b
    $ String -> ExceptT SettingsError IO Settings
    forall (m :: * -> *).
    MonadIO m =>
    String -> ExceptT SettingsError m Settings
    initSettings String
    top_dir
      case res of
        Right Settings
    a -> Settings -> IO Settings
    forall a. a -> IO a
    forall (f :: * -> *) a. Applicative f => a -> f a
    pure Settings
    a
        Left (SettingsError_MissingData String
    msg) -> String -> IO Settings
    forall a. HasCallStack => String -> a
    pgmError String
    msg
        Left (SettingsError_BadData String
    msg) -> String -> IO Settings
    forall a. HasCallStack => String -> a
    pgmError String
    msg

    {- Note [Windows stack allocations]
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    See: #8870 (and #8834 for related info) and #12186

    On Windows, occasionally we need to grow the stack. In order to do
    this, we would normally just bump the stack pointer - but there's a
    catch on Windows.

    If the stack pointer is bumped by more than a single page, then the
    pages between the initial pointer and the resulting location must be
    properly committed by the Windows virtual memory subsystem. This is
    only needed in the event we bump by more than one page (i.e 4097 bytes
    or more).

    Windows compilers solve this by emitting a call to a special function
    called _chkstk, which does this committing of the pages for you.

    The reason this was causing a segfault was because due to the fact the
    new code generator tends to generate larger functions, we needed more
    stack space in GHC itself. In the x86 codegen, we needed approximately
    ~12kb of stack space in one go, which caused the process to segfault,
    as the intervening pages were not committed.

    GCC can emit such a check for us automatically but only when the flag
    -fstack-check is used.

    See https://gcc.gnu.org/onlinedocs/gnat_ugn/Stack-Overflow-Checking.html
    for more information.

    -}

    -- | Copy remaining bytes from the first Handle to the second one
    copyHandle :: Handle -> Handle -> IO ()
    copyHandle :: Handle -> Handle -> IO ()
    copyHandle Handle
    hin Handle
    hout = do
      let buf_size :: Int
    buf_size = Int
    8192
      Int -> (Ptr Any -> IO ()) -> IO ()
    forall a b. Int -> (Ptr a -> IO b) -> IO b
    allocaBytes Int
    buf_size ((Ptr Any -> IO ()) -> IO ()) -> (Ptr Any -> IO ()) -> IO ()
    forall a b. (a -> b) -> a -> b
    $ \Ptr Any
    ptr -> do
        let go :: IO ()
    go = do
              c <- Handle -> Ptr Any -> Int -> IO Int
    forall a. Handle -> Ptr a -> Int -> IO Int
    hGetBuf Handle
    hin Ptr Any
    ptr Int
    buf_size
              hPutBuf hout ptr c
              if c == 0 then return () else go
        IO ()
    go

    -- | Copy file after printing the given header
    copyWithHeader :: String -> FilePath -> FilePath -> IO ()
    copyWithHeader :: String -> String -> String -> IO ()
    copyWithHeader String
    header String
    from String
    to =
      String -> IOMode -> (Handle -> IO ()) -> IO ()
    forall r. String -> IOMode -> (Handle -> IO r) -> IO r
    withBinaryFile String
    to IOMode
    WriteMode ((Handle -> IO ()) -> IO ()) -> (Handle -> IO ()) -> IO ()
    forall a b. (a -> b) -> a -> b
    $ \Handle
    hout -> do
        -- write the header string in UTF-8.  The header is something like
        --   {-# LINE "foo.hs" #-}
        -- and we want to make sure a Unicode filename isn't mangled.
        Handle -> TextEncoding -> IO ()
    hSetEncoding Handle
    hout TextEncoding
    utf8
        Handle -> String -> IO ()
    hPutStr Handle
    hout String
    header
        String -> IOMode -> (Handle -> IO ()) -> IO ()
    forall r. String -> IOMode -> (Handle -> IO r) -> IO r
    withBinaryFile String
    from IOMode
    ReadMode ((Handle -> IO ()) -> IO ()) -> (Handle -> IO ()) -> IO ()
    forall a b. (a -> b) -> a -> b
    $ \Handle
    hin ->
          Handle -> Handle -> IO ()
    copyHandle Handle
    hin Handle
    hout