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".

Delete all files currently managed in this session

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.

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.

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.

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.