Configuration parameters for a session. These remain the same throughout the whole session's lifetime.

Default session configuration. Most users will probably instead want localSessionConfigFromEnv.

Use this instead of creating your own SessionConfig to be robust against extensions of SessionConfig.

defaultSessionConfig = SessionConfig {
    configDir              = "."
  , configLocalWorkingDir  = Nothing
  , configExtraPathDirs    = []
  , configInProcess        = False
  , configGenerateModInfo  = True
  , configPackageDBStack   = [GlobalPackageDB, UserPackageDB]
    -- ghc-prim, integer-gmp, etc., all have their own licenses specified
    -- in their .cabal files.
  , configLicenseExc       = ["rts"]
  , configLicenseFixed     = [
        ("bin-package-db", (Just BSD3, Nothing,           Nothing))
      , ("ghc",            (Just BSD3, Just "../LICENSE", Just "The GHC Team"))
      , ("ghc-prim",       (Just BSD3, Just "LICENSE",    Nothing))
      , ("integer-gmp",    (Just BSD3, Just "LICENSE",    Nothing))
      ]
  , configLog              = const $ return ()
  , configDeleteTempFiles  = True
  , configIdeBackendServer = (defaultProgramSearchPath,"ide-backend-server")
  , configIdeBackendExeCabal = (defaultProgramSearchPath,"ide-backend-exe-cabal")
  }

A search path to use when locating executables. This is analogous to the unix $PATH or win32 %PATH% but with the ability to use the system default method for finding executables (findExecutable which on unix is simply looking on the $PATH but on win32 is a bit more complicated).

The default to use is [ProgSearchPathDefault] but you can add extra dirs either before, after or instead of the default, e.g. here we add an extra dir to search after the usual ones.

['ProgramSearchPathDefault', 'ProgramSearchPathDir' dir]

This type is a handle to a session state. Values of this type point to the non-persistent parts of the session state in memory and to directories containing source and data file that form the persistent part of the session state. Whenever we perform updates or run queries, it's always in the context of a particular handle, representing the session we want to work within. Many sessions can be active at once, but in normal applications this shouldn't be needed.

Create a fresh session, using some initial configuration.

Throws an exception if the configuration is invalid, or if GHC_PACKAGE_PATH is set.

Like initSession, but also takes a IdeCallbacks.

Since 0.10.0

How should the session be initialized?

Client code should use defaultSessionInitParams to protect itself against future extensions of this record.

Session callbacks. Currently this just configures how logging is handled.

Default session configuration.

Use this instead of creating your own IdeCallbacks to be robust against extensions of IdeCallbacks.

> defaultIdeCallbacks = IdeCallbacks
>  { ideCallbacksLogFunc = \_ _ _ _ -> return ()
>  }

Close a session down, releasing the resources.

This operation is the only one that can be run after a shutdown was already performed. This lets the API user execute an early shutdown, e.g., before the shutdownSession placed inside bracket is triggered by a normal program control flow.

If code is still running, it will be interrupted.

Like shutdownSession, but don't be nice about it (SIGKILL)

Restart a session

This puts the session in a "dead" state; it won't _actually_ be restarted until the next call to updateSession.

Declarative description of session updates

IdeSessionUpdate forms a monoid, which is right-biased: "later" calls override "earlier" ones:

updateTargets targets1 <> updateTargets2

is equivalent to

updateTargets2

However, updates of a different nature are not necessarily executed in order; for instance,

updateDynamicOpts opts <> updateSourceFile fp bs

is equivalent to

updateSourceFile fp bs <> updateDynamicOpts opts

In both cases options are set before new source files are compiled.

File commands are updated in order, so that

updateSourceFile fp bs <> updateSourceFile fp bs'

is equivalent to

updateSourceFile fp bs'

which is consistent with "later updates override earlier ones".

Given the current IDE session state, go ahead and update the session, eventually resulting in a new session state, with fully updated computed information (typing, etc.).

The update can be a long running operation, so we support a callback which can be used to monitor progress of the operation.

A session update that changes a source file by providing some contents. This can be used to add a new module or update an existing one. The FilePath argument determines the directory and file where the module is located within the project. In case of Haskell source files, the actual internal compiler module name, such as the one given by the getLoadedModules query, comes from within module ... end. Usually the two names are equal, but they needn't be.

Like updateSourceFile except that instead of passing the source by value, it's given by reference to an existing file, which will be copied.

A session update that deletes an existing source file.

Set ghc options

This function is stateless: the set of actions options is the set provided by the last call to updateGhcOptions.

Set RTS options for the ghc session (this does not affect executables)

This will cause a session restart.

NOTE: Limiting stack size does not seem to work for ghc 7.4 (https:/github.comfpcoide-backendissues/258).

Set include paths (equivalent of GHC's -i parameter). In general, this requires session restart, because GHC doesn't revise module dependencies when targets or include paths change, but only when files change.

This function is stateless: semantically, the set of currently active include paths are those set in the last call to updateRelativeIncludes. Any paths set earlier (including those from configRelativeIncludes) are wiped out and overwritten in each call to updateRelativeIncludes.

Enable or disable code generation in addition to type-checking. Required by runStmt.

A session update that changes a data file by giving a new value for the file. This can be used to add a new file or update an existing one.

Like updateDataFile except that instead of passing the file content by value, it's given by reference to an existing file (the second argument), which will be copied.

Deletes an existing data file.

Delete all files currently managed in this session

Set environment variables

Use updateEnv [(var, Nothing)] to unset var.

Note that this is intended to be stateless:

updateEnv []

will reset the environment to the server's original environment.

Set command line arguments for snippets (i.e., the expected value of getArgs)

Set buffering mode for snippets' stdout

Set buffering mode for snippets' stderr

Set compilation targets. In general, this requires session restart, because GHC doesn't revise module dependencies when targets or include paths change, but only when files change.

Build an exe from sources added previously via the ide-backend updateSourceFile* mechanism. The modules that contains the main code are indicated in second argument to buildExe. The function can be called multiple times with different arguments. Additional GHC options, applied only when building executables, are supplied in the first argument.

We assume any indicated module is already successfully processed by GHC API in a compilation mode that makes computedImports available (but no code needs to be generated). The environment (package dependencies, ghc options, preprocessor program options, etc.) for building the exe is the same as when previously compiling the code via GHC API. The module does not have to be called Main, but we assume the main function is always main (we don't check this and related conditions, but GHC does when eventually called to build the exe).

The executable files are placed in the filesystem inside the build subdirectory of getDistDir, in subdirectories corresponding to the given module names. The build directory does not overlap with any of the other used directories and with its path.

Logs from the building process are saved in files build/ide-backend-exe.stdout and build/ide-backend-exe.stderr in the getDistDir directory.

Note: currently it requires configGenerateModInfo to be set (see #86). Also, after session restart, one has to call updateSession at least once (even with empty updates list) before calling it for buildExe. This ensures the code is compiled again and the results made accessible.

Build haddock documentation from sources added previously via the ide-backend updateSourceFile* mechanism. Similarly to buildExe, it needs the project modules to be already loaded within the session and the generated docs can be found in the doc subdirectory of getDistDir.

Logs from the documentation building process are saved in files doc/ide-backend-doc.stdout and doc/ide-backend-doc.stderr in the getDistDir directory.

Note: currently it requires configGenerateModInfo to be set (see #86).

Build a file containing licenses of all used packages. Similarly to buildExe, the function needs the project modules to be already loaded within the session. The concatenated licenses can be found in file licenses.txt inside the getDistDir directory.

The function expects .cabal files of all used packages, except those mentioned in configLicenseExc, to be gathered in the directory given as the first argument (which needs to be an absolute path or a path relative to the data dir). The code then expects to find those packages installed and their license files in the usual place that Cabal puts them (or the in-place packages should be correctly embedded in the GHC tree).

We guess the installed locations of the license files on the basis of the haddock interfaces path. If the default setting does not work properly, the haddock interfaces path should be set manually. E.g., cabal configure --docdir=the_same_path --htmldir=the_same_path affects the haddock interfaces path (because it is by default based on htmldir) and is reported to work for some values of the_same_path.

Logs from the license search and catenation process are saved in files licenses.stdout and licenses.stderr in the getDistDir directory.

Note: currently configGenerateModInfo needs to be set for this function to work (see #86).

Note: if the executable uses TH and its module is named Main (and so it's not compiled as a part of a temporary library) configDynLink needs to be set. See #162.

This type represents intermediate progress information during compilation.

This type represents the status of the compilation from an IDE update.

Handles to the running code snippet, through which one can interact with the snippet.

Requirement: concurrent uses of supplyStdin should be possible, e.g., two threads that share a RunActions should be able to provide input concurrently without problems. (Currently this is ensured by supplyStdin writing to a channel.)

The outcome of running code

Buffer modes for running code

Note that NoBuffering means that something like putStrLn will do a syscall per character, and each of these characters will be read and sent back to the client. This results in a large overhead.

When using LineBuffering or BlockBuffering, runWait will not report any output from the snippet until it outputs a linebreak/fills the buffer, respectively (or does an explicit flush). However, you can specify a timeout in addition to the buffering mode; if you set this to Just n, the buffer will be flushed every n microseconds.

NOTE: This is duplicated in the IdeBackendRTS (defined in IdeSession)

Information about a triggered breakpoint

Run a given function in a given module (the name of the module is the one between module ... end, which may differ from the file name). The function resembles a query, but it's not instantaneous and the running code can be interrupted or interacted with.

runStmt will throw an exception if the code has not been compiled yet, or when the server is in a dead state (i.e., when ghc has crashed). In the latter case getSourceErrors will report the ghc exception; it is the responsibility of the client code to check for this.

Like runStmt, but runs the statement in a pseudoterminal.

Run the main function from the last compiled executable.

runExe will throw an exception if there were no executables compiled since session init, or if the last compilation was not successful (checked as in getBuildExeStatus) or if none of the executables last compiled have the supplied name or when the server is in a dead state (i.e., when ghc has crashed). In the last case getSourceErrors will report the ghc exception; it is the responsibility of the client code to check for this.

Resume a previously interrupted statement

Repeatedly call runWait until we receive a Right result, while collecting all Left results

Breakpoint

Set a breakpoint at the specified location. Returns Just the old value of the breakpoint if successful, or Nothing otherwise.

Print and/or force values during debugging

Only valid in breakpoint state.

The type of queries in a given session state.

Queries are in IO because they depend on the current state of the session but they promise not to alter the session state (at least not in any visible way; they might update caches, etc.).

The collection of source and data files submitted by the user.

GHC version

NOTE: Defined in such a way that the Ord instance makes sense.

Recover the fixed config the session was initialized with.

Obtain the source files directory for this session.

Obtain the data files directory for this session.

Obtain the directory prefix for results of Cabal invocations. Executables compiled in this session end up in a subdirectory build, haddocks in doc, concatenated licenses in file licenses, etc.

Read the current value of one of the source modules.

Read the current value of one of the data files.

Get the list of all data files currently available to the session: both the files copied via an update and files created by user code.

Is code generation currently enabled?

Get all current environment overrides

Get the RPC server used by the session.

Which GHC version is `ide-backend-server` using?

Get the collection of files submitted by the user and not deleted yet. The module names are those supplied by the user as the first arguments of the updateSourceFile and updateSourceFileFromFile calls, as opposed to the compiler internal module ... end module names. Usually the two names are equal, but they needn't be.

Get information about the last breakpoint that we hit

Returns Nothing if we are not currently stopped on a breakpoint.

Get any compilation errors or warnings in the current state of the session, meaning errors that GHC reports for the current state of all the source modules.

Note that in the initial implementation this will only return warnings from the modules that changed in the last update, the intended semantics is that morally it be a pure function of the current state of the files, and so it would return all warnings (as if you did clean and rebuild each time).

getSourceErrors does internal normalization. This simplifies the life of the client and anyway there shouldn't be that many source errors that it really makes a big difference.

Get the list of correctly compiled modules, as reported by the compiler

Get the mapping from filenames to modules (as computed by GHC)

Get exit status of the last invocation of buildExe, if any.

Get exit status of the last invocation of buildDoc, if any.

Get exit status of the last invocation of buildLicenses, if any.

Get information about an identifier at a specific location

Get information the type of a subexpressions and the subexpressions around it

Use sites

Use sites are only reported in modules that get compiled successfully.

Minimal .cabal file for the loaded modules seen as a library. The argument specifies the name of the library.

License is set to AllRightsReserved. All transitive package dependencies are included, with package versions set to the currently used versions. Only modules that get compiled successfully are included. Source directory is the currently used session source directory. Warning: all modules named Main (even in subdirectories or files with different names) are ignored so that they don't get in the way when we build an executable using the library and so that the behaviour is consistent with that of buildExe.

Get import information

This information is available even for modules with parse/type errors

Autocompletion

Use idInfoQN to translate these IdInfos into qualified names, taking into account the module imports.

(Transitive) package dependencies

These are only available for modules that got compiled successfully.

Identifiers in Haskell are drawn from a number of different name spaces

For now we represent types in pretty-printed form

Information about identifiers

Identifier info that is independent of the usage site

An error or warning in a source module.

Most errors are associated with a span of text, but some have only a location point.

Severity of an error.

A package ID in ide-backend consists of a human-readable package name and version (what Cabal calls a source ID) along with ghc's internal package key (primarily for internal use).

Returned when the IDE asks "what's at this particular location?"

Construct qualified name following Haskell's scoping rules

Show approximately a haddock link (without haddock root) for an id. This is an illustration and a test of the id info, but under ideal conditions could perhaps serve to link to documentation without going via Hoogle.

Exceptions thrown by the remote server

We typically get packages from several databases, and stack them together. This type lets us be explicit about that stacking. For example typical stacks include:

[GlobalPackageDB]
[GlobalPackageDB, UserPackageDB]
[GlobalPackageDB, SpecificPackageDB "package.conf.inplace"]

Note that the GlobalPackageDB is invariably at the bottom since it contains the rts, base and other special compiler-specific packages.

We are not restricted to using just the above combinations. In particular we can use several custom package dbs and the user package db together.

When it comes to writing, the top most (last) package is used.

Some compilers have a notion of a database of available packages. For some there is just one global db of packages, other compilers support a per-user or an arbitrary db specified at some location in the file system. This can be used to build isloated environments of packages, for example to build a collection of related packages without installing them globally.

Print the id info maps to stdout (for debugging purposes only)

Print autocompletion to stdout (for debugging purposes only)

Print file mapping to stdout (for debugging purposes only)

Crash the GHC server. For debugging only. If the specified delay is Nothing, crash immediately; otherwise, set up a thread that throws an exception to the main thread after the delay.

Extensions of all source files we keep in our source directory.

For detecting runtime version mismatch between the server and the library

We use a Unix timestamp for this so that these API versions have some semantics (http:/www.epochconverter.com, GMT).

Build the concatenation of all license files from a given list of packages. See buildLicenses.