GHC.Utils.TmpFs

ghc-lib-parser-9.14.1.20251220: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Utils.TmpFs

Description

Temporary file-system management

Synopsis

- data TmpFs
- initTmpFs :: IO TmpFs
- forkTmpFsFrom :: TmpFs -> IO TmpFs
- mergeTmpFsInto :: TmpFs -> TmpFs -> IO ()
- data PathsToClean = PathsToClean {
  - ptcGhcSession :: !(Set FilePath)
  - ptcCurrentModule :: !(Set FilePath)
  }
- emptyPathsToClean :: PathsToClean
- data TempFileLifetime
  - = TFL_CurrentModule
  - | TFL_GhcSession
- newtype TempDir = TempDir FilePath
- cleanTempDirs :: Logger -> TmpFs -> IO ()
- cleanTempFiles :: Logger -> TmpFs -> IO ()
- cleanCurrentModuleTempFiles :: Logger -> TmpFs -> IO ()
- keepCurrentModuleTempFiles :: HasCallStack => Logger -> TmpFs -> IO ()
- addFilesToClean :: TmpFs -> TempFileLifetime -> [FilePath] -> IO ()
- changeTempFilesLifetime :: TmpFs -> TempFileLifetime -> [FilePath] -> IO ()
- newTempName :: Logger -> TmpFs -> TempDir -> TempFileLifetime -> Suffix -> IO FilePath
- newTempLibName :: Logger -> TmpFs -> TempDir -> TempFileLifetime -> Suffix -> IO (FilePath, FilePath, String)
- newTempSubDir :: Logger -> TmpFs -> TempDir -> IO FilePath
- withSystemTempDirectory :: String -> (FilePath -> IO a) -> IO a
- withTempDirectory :: FilePath -> String -> (FilePath -> IO a) -> IO a

# Documentation

data TmpFs #

Temporary file-system

initTmpFs :: IO TmpFs #

Initialise an empty TmpFs

forkTmpFsFrom :: TmpFs -> IO TmpFs #

Initialise an empty TmpFs sharing unique numbers and per-process temporary directories with the given TmpFs

It's not safe to use the subdirs created by the original TmpFs with the forked one. Use `newTempSubDir` to create new subdirs instead.

mergeTmpFsInto :: TmpFs -> TmpFs -> IO () #

Merge the first TmpFs into the second.

The first TmpFs is returned emptied.

data PathsToClean #

A collection of paths that must be deleted before ghc exits.

Constructors

PathsToClean |
Fields ptcGhcSession :: !(Set FilePath) Paths that will be deleted at the end of runGhc(T) ptcCurrentModule :: !(Set FilePath) Paths that will be deleted the next time `cleanCurrentModuleTempFiles` is called, or otherwise at the end of the session.

emptyPathsToClean :: PathsToClean #

An empty PathsToClean

data TempFileLifetime #

Used when a temp file is created. This determines which component Set of PathsToClean will get the temp file

Constructors

TFL_CurrentModule | A file with lifetime TFL_CurrentModule will be cleaned up at the end of upweep_mod
TFL_GhcSession | A file with lifetime TFL_GhcSession will be cleaned up at the end of runGhc(T)

#### Instances

Instances details

Show TempFileLifetime # |
Instance details Defined in GHC.Utils.TmpFs Methods showsPrec :: Int -> TempFileLifetime -> ShowS # show :: TempFileLifetime -> String # showList :: [TempFileLifetime] -> ShowS #

newtype TempDir #

Constructors

TempDir FilePath |

cleanTempDirs :: Logger -> TmpFs -> IO () #

cleanTempFiles :: Logger -> TmpFs -> IO () #

Delete all paths in `tmp_files_to_clean` and `tmp_subdirs_to_clean`.

cleanCurrentModuleTempFiles :: Logger -> TmpFs -> IO () #

Delete all paths in `tmp_files_to_clean` and `tmp_subdirs_to_clean` That have lifetime TFL_CurrentModule. If a file must be cleaned eventually, but must survive a cleanCurrentModuleTempFiles, ensure it has lifetime TFL_GhcSession.

keepCurrentModuleTempFiles :: HasCallStack => Logger -> TmpFs -> IO () #

Keep all the paths in `tmp_files_to_clean` and `tmp_subdirs_to_clean` that have lifetime TFL_CurrentModule. This function is used when `-keep-tmp-files` is used in an OPTIONS_GHC pragma. This function removes the temporary file from the TmpFs so we no longer remove it at the env when cleanTempFiles is called.

addFilesToClean :: TmpFs -> TempFileLifetime -> [FilePath] -> IO () #

Ensure that new_files are cleaned on the next call of `cleanTempFiles` or `cleanCurrentModuleTempFiles`, depending on lifetime. If any of new_files are already tracked, they will have their lifetime updated.

changeTempFilesLifetime :: TmpFs -> TempFileLifetime -> [FilePath] -> IO () #

Update the lifetime of files already being tracked. If any files are not being tracked they will be discarded.

newTempName :: Logger -> TmpFs -> TempDir -> TempFileLifetime -> Suffix -> IO FilePath #

newTempLibName :: Logger -> TmpFs -> TempDir -> TempFileLifetime -> Suffix -> IO (FilePath, FilePath, String) #

newTempSubDir :: Logger -> TmpFs -> TempDir -> IO FilePath #

Create a new temporary subdirectory that doesn't already exist The temporary subdirectory is automatically removed at the end of the GHC session, but its contents aren't. Make sure to leave the directory empty before the end of the session, either by removing content directly or by using `addFilesToClean`.

If the created subdirectory is not empty, it will not be removed (along with its parent temporary directory) and a warning message will be printed at verbosity 2 and higher.

withSystemTempDirectory #

Arguments

:: String | Directory name template. See `openTempFile`.
-> (FilePath -> IO a) | Callback that can use the directory
-> IO a |

Create and use a temporary directory in the system standard temporary directory.

Behaves exactly the same as `withTempDirectory`, except that the parent temporary directory will be that returned by `getTemporaryDirectory`.

withTempDirectory #

Arguments

:: FilePath | Temp directory to create the directory in
-> String | Directory name template. See `openTempFile`.
-> (FilePath -> IO a) | Callback that can use the directory
-> IO a |

Create and use a temporary directory.

Creates a new temporary directory inside the given directory, making use of the template. The temp directory is deleted after use. For example:

    withTempDirectory "src" "sdist." $ \tmpDir -> do ...

The `tmpDir` will be a new subdirectory of the given directory, e.g. `src/sdist.342`.