summaryrefslogtreecommitdiff
path: root/docs/users_guide
Commit message (Collapse)AuthorAgeFilesLines
* Rewrite CallerCC parser using ReadPMatthew Pickering2022-02-031-2/+2
| | | | | | | | | | This allows us to remove the dependency on parsec and hence transitively on text. Also added some simple unit tests for the parser and fixed two small issues in the documentation. Fixes #21033
* Improve migration strategy for the XDG compliance change to the GHC applicationZubin Duggal2022-01-311-0/+19
| | | | | | | | | | | directory. We want to always use the old path (~/.ghc/..) if it exists. But we never want to create the old path. This ensures that the migration can eventually be completed once older GHC versions are no longer in circulation. Fixes #20684, #20669, #20660
* rel-notes: Note dropping of SPARC supportBen Gamari2022-01-291-0/+2
|
* CmmToAsm: Drop ncgExpandTopBen Gamari2022-01-291-6/+0
| | | | This was only needed for SPARC's synthetic instructions.
* users-guide: Document GHC_CHARENC environment variableBen Gamari2022-01-271-4/+10
| | | | | | | As noted in #20963, this was introduced in 1b56c40578374a15b4a2593895710c68b0e2a717 but was no documentation was added at that point. Closes #20963.
* Re #18087 user's guide: add a note that -Wxxx used to be -fwarn-xxxAndreas Abel2022-01-271-0/+7
| | | | | | | | | The warning option syntax -W was introduced in GHC 8. The note should clarify what e.g. "since 7.6" means in connection with "-Wxxx": That "-fwarn-xxx" was introduced in 7.6.1. [ci skip]
* Ctd. #18087: complete :since: info for all warnings in users guideAndreas Abel2022-01-272-0/+36
| | | | | | | | Some warnings have been there "forever" and I could not trace back the exact genesis, so I wrote "since at least 5.04". The flag `helpful-errors` could have been added in 7.2 already. I wrote 7.4 since I have no 7.2 available and it is not recognized by 7.0.
* Levity-polymorphic arrays and mutable variablessheaf2022-01-261-8/+119
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This patch makes the following types levity-polymorphic in their last argument: - Array# a, SmallArray# a, Weak# b, StablePtr# a, StableName# a - MutableArray# s a, SmallMutableArray# s a, MutVar# s a, TVar# s a, MVar# s a, IOPort# s a The corresponding primops are also made levity-polymorphic, e.g. `newArray#`, `readArray#`, `writeMutVar#`, `writeIOPort#`, etc. Additionally, exception handling functions such as `catch#`, `raise#`, `maskAsyncExceptions#`,... are made levity/representation-polymorphic. Now that Array# and MutableArray# also work with unlifted types, we can simply re-define ArrayArray# and MutableArrayArray# in terms of them. This means that ArrayArray# and MutableArrayArray# are no longer primitive types, but simply unlifted newtypes around Array# and MutableArrayArray#. This completes the implementation of the Pointer Rep proposal https://github.com/ghc-proposals/ghc-proposals/pull/203 Fixes #20911 ------------------------- Metric Increase: T12545 ------------------------- ------------------------- Metric Decrease: T12545 -------------------------
* linksEric Lindblad2022-01-241-2/+2
|
* Add -fcompact-unwindRobert Hensing2022-01-241-0/+14
| | | | | | | | | | | | | | | | | | | | | | | | This gives users the choice to enable __compact_unwind sections when linking. These were previously hardcoded to be removed. This can be used to solved the problem "C++ does not catch exceptions when used with Haskell-main and linked by ghc", https://gitlab.haskell.org/ghc/ghc/-/issues/11829 It does not change the default behavior, because I can not estimate the impact this would have. When Apple first introduced the compact unwind ABI, a number of open source projects have taken the easy route of disabling it, avoiding errors or even just warnings shortly after its introduction. Since then, about a decade has passed, so it seems quite possible that Apple itself, and presumably many programs with it, have successfully switched to the new format, to the point where the old __eh_frame section support is in disrepair. Perhaps we should get along with the program, but for now we can test the waters with this flag, and use it to fix packages that need it.
* Note that ImpredicativeTypes doesn’t allow polymorphic instancesAnselm Schüler2022-01-191-0/+9
| | | | See #20939
* ms and gh linksEric Lindblad2022-01-181-2/+2
|
* ms linkEric Lindblad2022-01-171-1/+1
|
* wikipedia linkEric Lindblad2022-01-151-1/+1
|
* reinsert targetEric Lindblad2022-01-141-0/+1
|
* update URLsEric Lindblad2022-01-141-16/+16
|
* release notes: Changes to Demand analysisSebastian Graf2022-01-131-0/+11
|
* release notes: Changes to CPR analysisSebastian Graf2022-01-132-3/+69
|
* docs: MonadComprehension desugar using Alternative rather than MonadPlusMatthew Pickering2022-01-111-2/+2
| | | | Fixes #20928
* TcPlugins: `newWanted` uses the provided `CtLoc`sheaf2022-01-111-0/+8
| | | | | | | | | | | | | | | | | | The `GHC.Tc.Plugin.newWanted` function takes a `CtLoc` as an argument, but it used to discard the location information, keeping only the `CtOrigin`. It would then retrieve the source location from the `TcM` environment using `getCtLocM`. This patch changes this so that `GHC.Tc.Plugin.newWanted` passes on the full `CtLoc`. This means that authors of type-checking plugins no longer need to manually set the `CtLoc` environment in the `TcM` monad if they want to create a new Wanted constraint with the given `CtLoc` (in particular, for setting the `SrcSpan` of an emitted constraint). This makes the `newWanted` function consistent with `newGiven`, which always used the full `CtLoc` instead of using the environment. Fixes #20895
* Fix parsing & printing of unboxed sumssheaf2022-01-112-0/+28
| | | | | | | | | | | | | | | | | The pretty-printing of partially applied unboxed sums was incorrect, as we incorrectly dropped the first half of the arguments, even for a partial application such as (# | #) @IntRep @DoubleRep Int# which lead to the nonsensical (# DoubleRep | Int# #). This patch also allows users to write unboxed sum type constructors such as (# | #) :: TYPE r1 -> TYPE r2 -> TYPE (SumRep '[r1,r2]). Fixes #20858 and #20859.
* User's guide: newtype decls can use GADTSyntaxsheaf2022-01-023-4/+32
| | | | | | | | | | The user's guide failed to explicitly mention that GADTSyntax can be used to declare newtypes, so we add an example and a couple of explanations. Also explains that `-XGADTs` generalises `-XExistentialQuantification`. Fixes #20848 and #20865.
* Multiple Home UnitsMatthew Pickering2021-12-281-0/+125
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Multiple home units allows you to load different packages which may depend on each other into one GHC session. This will allow both GHCi and HLS to support multi component projects more naturally. Public Interface ~~~~~~~~~~~~~~~~ In order to specify multiple units, the -unit @⟨filename⟩ flag is given multiple times with a response file containing the arguments for each unit. The response file contains a newline separated list of arguments. ``` ghc -unit @unitLibCore -unit @unitLib ``` where the `unitLibCore` response file contains the normal arguments that cabal would pass to `--make` mode. ``` -this-unit-id lib-core-0.1.0.0 -i -isrc LibCore.Utils LibCore.Types ``` The response file for lib, can specify a dependency on lib-core, so then modules in lib can use modules from lib-core. ``` -this-unit-id lib-0.1.0.0 -package-id lib-core-0.1.0.0 -i -isrc Lib.Parse Lib.Render ``` Then when the compiler starts in --make mode it will compile both units lib and lib-core. There is also very basic support for multiple home units in GHCi, at the moment you can start a GHCi session with multiple units but only the :reload is supported. Most commands in GHCi assume a single home unit, and so it is additional work to work out how to modify the interface to support multiple loaded home units. Options used when working with Multiple Home Units There are a few extra flags which have been introduced specifically for working with multiple home units. The flags allow a home unit to pretend it’s more like an installed package, for example, specifying the package name, module visibility and reexported modules. -working-dir ⟨dir⟩ It is common to assume that a package is compiled in the directory where its cabal file resides. Thus, all paths used in the compiler are assumed to be relative to this directory. When there are multiple home units the compiler is often not operating in the standard directory and instead where the cabal.project file is located. In this case the -working-dir option can be passed which specifies the path from the current directory to the directory the unit assumes to be it’s root, normally the directory which contains the cabal file. When the flag is passed, any relative paths used by the compiler are offset by the working directory. Notably this includes -i and -I⟨dir⟩ flags. -this-package-name ⟨name⟩ This flag papers over the awkward interaction of the PackageImports and multiple home units. When using PackageImports you can specify the name of the package in an import to disambiguate between modules which appear in multiple packages with the same name. This flag allows a home unit to be given a package name so that you can also disambiguate between multiple home units which provide modules with the same name. -hidden-module ⟨module name⟩ This flag can be supplied multiple times in order to specify which modules in a home unit should not be visible outside of the unit it belongs to. The main use of this flag is to be able to recreate the difference between an exposed and hidden module for installed packages. -reexported-module ⟨module name⟩ This flag can be supplied multiple times in order to specify which modules are not defined in a unit but should be reexported. The effect is that other units will see this module as if it was defined in this unit. The use of this flag is to be able to replicate the reexported modules feature of packages with multiple home units. Offsetting Paths in Template Haskell splices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When using Template Haskell to embed files into your program, traditionally the paths have been interpreted relative to the directory where the .cabal file resides. This causes problems for multiple home units as we are compiling many different libraries at once which have .cabal files in different directories. For this purpose we have introduced a way to query the value of the -working-dir flag to the Template Haskell API. By using this function we can implement a makeRelativeToProject function which offsets a path which is relative to the original project root by the value of -working-dir. ``` import Language.Haskell.TH.Syntax ( makeRelativeToProject ) foo = $(makeRelativeToProject "./relative/path" >>= embedFile) ``` > If you write a relative path in a Template Haskell splice you should use the makeRelativeToProject function so that your library works correctly with multiple home units. A similar function already exists in the file-embed library. The function in template-haskell implements this function in a more robust manner by honouring the -working-dir flag rather than searching the file system. Closure Property for Home Units ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For tools or libraries using the API there is one very important closure property which must be adhered to: > Any dependency which is not a home unit must not (transitively) depend on a home unit. For example, if you have three packages p, q and r, then if p depends on q which depends on r then it is illegal to load both p and r as home units but not q, because q is a dependency of the home unit p which depends on another home unit r. If you are using GHC by the command line then this property is checked, but if you are using the API then you need to check this property yourself. If you get it wrong you will probably get some very confusing errors about overlapping instances. Limitations of Multiple Home Units ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are a few limitations of the initial implementation which will be smoothed out on user demand. * Package thinning/renaming syntax is not supported * More complicated reexports/renaming are not yet supported. * It’s more common to run into existing linker bugs when loading a large number of packages in a session (for example #20674, #20689) * Backpack is not yet supported when using multiple home units. * Dependency chasing can be quite slow with a large number of modules and packages. * Loading wired-in packages as home units is currently not supported (this only really affects GHC developers attempting to load template-haskell). * Barely any normal GHCi features are supported, it would be good to support enough for ghcid to work correctly. Despite these limitations, the implementation works already for nearly all packages. It has been testing on large dependency closures, including the whole of head.hackage which is a total of 4784 modules from 452 packages. Internal Changes ~~~~~~~~~~~~~~~~ * The biggest change is that the HomePackageTable is replaced with the HomeUnitGraph. The HomeUnitGraph is a map from UnitId to HomeUnitEnv, which contains information specific to each home unit. * The HomeUnitEnv contains: - A unit state, each home unit can have different package db flags - A set of dynflags, each home unit can have different flags - A HomePackageTable * LinkNode: A new node type is added to the ModuleGraph, this is used to place the linking step into the build plan so linking can proceed in parralel with other packages being built. * New invariant: Dependencies of a ModuleGraphNode can be completely determined by looking at the value of the node. In order to achieve this, downsweep now performs a more complete job of downsweeping and then the dependenices are recorded forever in the node rather than being computed again from the ModSummary. * Some transitive module calculations are rewritten to use the ModuleGraph which is more efficient. * There is always an active home unit, which simplifies modifying a lot of the existing API code which is unit agnostic (for example, in the driver). The road may be bumpy for a little while after this change but the basics are well-tested. One small metric increase, which we accept and also submodule update to haddock which removes ExtendedModSummary. Closes #10827 ------------------------- Metric Increase: MultiLayerModules ------------------------- Co-authored-by: Fendor <power.walross@gmail.com>
* Fix typosKrzysztof Gogolewski2021-12-256-6/+6
|
* Introduce -dlint flagBen Gamari2021-12-211-0/+12
| | | | | | As suggested in #20601, this is a short-hand for enabling the usual GHC-internal sanity checks one typically leans on when debugging runtime crashes.
* Rename -fcatch-bottoms to -fcatch-nonexhaustive-casesBen Gamari2021-12-211-1/+1
| | | | As noted in #20601, the previous name was rather misleading.
* codeGen: Introduce flag to bounds-check array accessesBen Gamari2021-12-211-0/+12
| | | | | | | Here we introduce code generator support for instrument array primops with bounds checking, enabled with the `-fcheck-prim-bounds` flag. Introduced to debug #20769.
* Plugin load order should follow the commandline order (fixes #17884)Andrei Barbu2021-12-151-3/+5
| | | | | | | In the past the order was reversed because flags are consed onto a list. No particular behavior was documented. We now reverse the flags and document the behavior.
* ghc-bin: Add --merge-objs modeBen Gamari2021-12-142-0/+23
| | | | | | | | | | This adds a new mode, `--merge-objs`, which can be used to produce merged GHCi library objects. As future work we will rip out the object-merging logic in Hadrian and Cabal and instead use this mode. Closes #20712.
* users-guide: Fix documentation for -shared flagBen Gamari2021-12-141-3/+4
| | | | | | This flag was previously called `--mk-dll`. It was renamed to `-shared` in b562cbe381d54e08dcafa11339e9a82e781ad557 but the documentation wasn't updated to match.
* Ghci environment: Do not remove shadowed idsJoachim Breitner2021-12-141-0/+40
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Names defined earier but shadowed need to be kept around, e.g. for type signatures: ``` ghci> data T = T ghci> let t = T ghci> data T = T ghci> :t t t :: Ghci1.T ``` and indeed they can be used: ``` ghci> let t2 = Ghci1.T :: Ghci1.T ghci> :t t2 t2 :: Ghci1.T ``` However, previously this did not happen for ids (non-types), although they are still around under the qualified name internally: ``` ghci> let t = "other t" ghci> t' <interactive>:8:1: error: • Variable not in scope: t' • Perhaps you meant one of these: ‘Ghci2.t’ (imported from Ghci2), ‘t’ (line 7), ‘t2’ (line 5) ghci> Ghci2.t <interactive>:9:1: error: • GHC internal error: ‘Ghci2.t’ is not in scope during type checking, but it passed the renamer tcl_env of environment: [] • In the expression: Ghci2.t In an equation for ‘it’: it = Ghci2.t ``` This fixes the problem by simply removing the code that tries to remove shadowed ids from the environment. Now you can refer to shadowed ids using `Ghci2.t`, just like you can do for data and type constructors. This simplifies the code, makes terms and types more similar, and also fixes #20455. Now all names ever defined in GHCi are in `ic_tythings`, which is printed by `:show bindings`. But for that commands, it seems to be more ergonomic to only list those bindings that are not shadowed. Or, even if it is not more ergonomic, it’s the current behavour. So let's restore that by filtering in `icInScopeTTs`. Of course a single `TyThing` can be associated with many names. We keep it it in the bindings if _any_ of its names are still visible unqualifiedly. It's a judgement call. This commit also turns a rather old comment into a test files. The comment is is rather stale and things are better explained elsewhere. Fixes #925. Two test cases are regressing: T14052(ghci) ghc/alloc 2749444288.0 12192109912.0 +343.4% BAD T14052Type(ghci) ghc/alloc 7365784616.0 10767078344.0 +46.2% BAD This is not unexpected; the `ic_tythings list grows` a lot more if we don’t remove shadowed Ids. I tried to alleviate it a bit with earlier MRs, but couldn’t make up for it completely. Metric Increase: T14052 T14052Type
* docs: Drop old release notesBen Gamari2021-12-103-929/+0
| | | | Closes #20786
* Add `Opt_CoreConstantFolding` to turn on constant folding (#20500)Gergo ERDI2021-12-091-0/+11
| | | | | Previously, `-O1` and `-O2`, by way of their effect on the compilation pipeline, they implicitly turned on constant folding
* More permissive parsing of higher-rank type IPssheaf2021-12-071-0/+8
| | | | | | | | | | | | | | | | | The parser now accepts implicit parameters with higher-rank types, such as `foo :: (?ip :: forall a. a -> a) => ...` Before this patch, we instead insisted on parentheses like so: `foo :: (?ip :: (forall a. a -> a)) => ...` The rest of the logic surrounding implicit parameters is unchanged; in particular, even with ImpredicativeTypes, this idiom is not likely to be very useful. Fixes #20654
* rts: +RTS -DL should imply +RTS -DlBen Gamari2021-12-071-0/+1
| | | | | Otherwise the user may be surprised by the missing context provided by the latter.
* Fix user-guide typoViktor Dukhovni2021-12-071-1/+1
|
* Add section to the user guide about OS memory usageMatthew Pickering2021-12-063-2/+110
|
* Revert "Data.List specialization to []"Matthew Pickering2021-12-031-2/+7
| | | | | | | | | | This reverts commit bddecda1a4c96da21e3f5211743ce5e4c78793a2. This implements the first step in the plan formulated in #20025 to improve the communication and migration strategy for the proposed changes to Data.List. Requires changing the haddock submodule to update the test output.
* users-guide: Describe requirements of DWARF unwindingBen Gamari2021-12-011-0/+10
| | | | As requested in #20702
* user-guide: Fix :since: of -XCApiFFIBen Gamari2021-12-011-1/+1
| | | | Closes #20504.
* Dump non-module specific info to file #20316Carrie Xu2021-12-011-4/+8
| | | | | | | | | - Change the dumpPrefix to FilePath, and default to non-module - Add dot to seperate dump-file-prefix and suffix - Modify user guide to introduce how dump files are named - This commit does not affect Ghci dump file naming. See also #17500
* docs/users_guide/bugs.rst: RewordingAnton-Latukha2021-11-291-3/+3
| | | | | | | | It is either "slightly" || "significantly". If it is "bogus" - then no quotes around "optimization" & overall using word "bogus" or use quotes in that way in documentation is... Instead, something like "hack" or "heuristic" can be used there.
* Allow boring class declarations in hs-boot filessheaf2021-11-251-3/+25
| | | | | | | | | | | | | | | | | | | | | | | There are two different ways of declaring a class in an hs-boot file: - a full declaration, where everything is written as it is in the .hs file, - an abstract declaration, where class methods and superclasses are left out. However, a declaration with no methods and a trivial superclass, such as: class () => C a was erroneously considered to be an abstract declaration, because the superclass is trivial. This is remedied by a one line fix in GHC.Tc.TyCl.tcClassDecl1. This patch also further clarifies the documentation around class declarations in hs-boot files. Fixes #20661, #20588.
* Add specific optimization flag for Cmm control flow analysis (#20500)Gergo ERDI2021-11-251-1/+11
|
* Add specific optimization flag for fast PAP calls (#6084, #20500)Gergo ERDI2021-11-251-0/+1
|
* Misc cleanupKrzysztof Gogolewski2021-11-254-36/+12
| | | | | | | | | | | | | | | | | | | | | * Remove `getTag_RDR` (unused), `tidyKind` and `tidyOpenKind` (already available as `tidyType` and `tidyOpenType`) * Remove Note [Explicit Case Statement for Specificity]. Since 0a709dd9876e40 we require GHC 8.10 for bootstrapping. * Change the warning to `cmpAltCon` to a panic. This shouldn't happen. If it ever does, the code was wrong anyway: it shouldn't always return `LT`, but rather `LT` in one case and `GT` in the other case. * Rename `verifyLinearConstructors` to `verifyLinearFields` * Fix `Note [Local record selectors]` which was not referenced * Remove vestiges of `type +v` * Minor fixes to StaticPointers documentation, part of #15603
* Add a warning for GADT match + NoMonoLocalBinds (#20485)Krzysztof Gogolewski2021-11-231-1/+27
| | | | | | | | | Previously, it was an error to pattern match on a GADT without GADTs or TypeFamilies. This is now allowed. Instead, we check the flag MonoLocalBinds; if it is not enabled, we issue a warning, controlled by -Wgadt-mono-local-binds. Also fixes #20485: pattern synonyms are now checked too.
* Implement -Wforall-identifier (#20609)Vladislav Zavialov2021-11-121-0/+28
| | | | | | | | | | In accordance with GHC Proposal #281 "Visible forall in types of terms": For three releases before this change takes place, include a new warning -Wforall-identifier in -Wdefault. This warning will be triggered at definition sites (but not use sites) of forall as an identifier. Updates the haddock submodule.
* Only pass -pie, -no-pie when linkingMatthew Bauer2021-11-111-4/+14
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Previously, these flags were passed when both compiling and linking code. However, `-pie` and `-no-pie` are link-time-only options. Usually, this does not cause issues, but when using Clang with `-Werror` set results in errors: clang: error: argument unused during compilation: '-nopie' [-Werror,-Wunused-command-line-argument] This is unused by Clang because this flag has no effect at compile time (it’s called `-nopie` internally by Clang but called `-no-pie` in GHC for compatibility with GCC). Just passing these flags at linking time resolves this. Additionally, update #15319 hack to look for `-pgml` instead. Because of the main change, the value of `-pgmc` does not matter when checking for the workaround of #15319. However, `-pgml` *does* still matter as not all `-pgml` values support `-no-pie`. To cover all potential values, we assume that no custom `-pgml` values support `-no-pie`. This means that we run the risk of not using `-no-pie` when it is otherwise necessary for in auto-hardened toolchains! This could be a problem at some point, but this workaround was already introduced in 8d008b71 and we might as well continue supporting it. Likewise, mark `-pgmc-supports-no-pie` as deprecated and create a new `-pgml-supports-no-pie`.
* Clarify hs-boot file default method restrictionssheaf2021-11-101-4/+6
| | | | | | | | | | | | | The user guide wrongly stated that default methods should not be included in hs-boot files. In fact, if the class is not left abstract (no methods, no superclass constraints, ...) then the defaults must be provided and match with those given in the .hs file. We add some tests for this, as there were no tests in the testsuite that gave rise to the "missing default methods" error. Fixes #20588
View Lorry Controller Status