├── README.rst ├── coding-style.rst ├── getting-started.rst ├── ghc-packages.md └── install ├── ghcup.rst ├── other.rst └── posix-via-shell.rst /README.rst: -------------------------------------------------------------------------------- 1 | Haskell Dev 2 | ----------- 3 | 4 | * `Getting Started with GHC and cabal <./getting-started.rst>`_ 5 | * `Haskell coding style <./coding-style.rst>`_ 6 | * `GHC Package Management How-to <./ghc-packages.md>`_ 7 | -------------------------------------------------------------------------------- /coding-style.rst: -------------------------------------------------------------------------------- 1 | Haskell Coding Style 2 | ==================== 3 | 4 | The goals of a coding style are as follows: 5 | 6 | * to have a uniform coding style across a project 7 | * to make the code easy to read 8 | 9 | In some cases there are reasons for choosing a particular style over 10 | the other, in other cases we just choose one particular style without 11 | any strong reasons just for the sake of uniformity. The choices 12 | could be subjective, not all may agree but we need to have one style 13 | nevertheless. As far as possible we try to keep style conventions 14 | consistent across different language constructs as well. 15 | 16 | As long as possible please try to match the style of the file or the 17 | surrounding code. Sometimes we may have copied a file from somewhere 18 | else and we do not want to change the style, so its important to adhere 19 | to the local style rather than mixing styles. 20 | 21 | .. contents:: Table of Contents 22 | :depth: 1 23 | 24 | General Guiding Principles 25 | -------------------------- 26 | 27 | Define before use 28 | ~~~~~~~~~~~~~~~~~ 29 | 30 | Define top level declarations before their first use in the file. In 31 | other words, use the `bottom up style` to organize top level declarations. 32 | 33 | There are two rationales for this rule, (1) choose an order instead of 34 | a random ordering, (2) facilitate easier type error debugging on new 35 | changes. 36 | 37 | When refactoring, e.g. changing a fundamental type, comment out all the 38 | exports and all the top level declarations in the file using a block 39 | comment. Then uncomment the first top level declaration, change it, fix 40 | the errors, then uncomment the next one, change it and fix the errors 41 | and so on, this way we can incrementally expose the declarations and fix 42 | them. This works because we have defined each declaration before its 43 | use. Reduced scope of type inferencing makes the type errors localized. 44 | 45 | If you use type signatures on all top level declarations commenting out 46 | code may not be necessary for localized inferencing. However, define 47 | before use results in a better order of type errors. 48 | 49 | Also, you can test the code in a similar incremental fashion. You can 50 | make a lower level piece of code working and tested first and then move 51 | on to the code using it by moving further down in the file. 52 | 53 | To summarize, this is useful when refactoring or changing code in bulk. 54 | 55 | List modules in dependency order 56 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 57 | 58 | Use the dependency order principle as described in the previous section 59 | for listing modules in the cabal file as well. When refactoring, start 60 | refactoring the module higher most in the list first and comment out the 61 | rest, the whole library still keeps compiling. 62 | 63 | Whitespace 64 | ~~~~~~~~~~ 65 | 66 | Do not try to reduce whitespace and make the code dense, instead make liberal 67 | use of horizontal or vertical whitespace to make the code clearer and easier to 68 | read. 69 | 70 | Indentation 71 | ~~~~~~~~~~~ 72 | 73 | Indent each level by 4 spaces. 2 spaces makes the code look cluttered, I 74 | would prefer 8 spaces but it often makes lines too long in Haskell with 75 | multiple indentation levels. As a reference, Linux kernel uses 8 spaces 76 | and it looks very neat. 77 | 78 | If expressions or lines become too long or there are too many 79 | indentation levels then it means you need to one of the following: 80 | 81 | * Use a `let` clause to name parts of your expression 82 | * Use a `where` clause to factor out some definitions 83 | * Use top level definitions 84 | 85 | Line Length 86 | ~~~~~~~~~~~ 87 | 88 | Maximum 80 columns. This is very helpful when seeing diffs side by side. 89 | 90 | Sequence of items 91 | ~~~~~~~~~~~~~~~~~ 92 | 93 | Wherever there is a sequence of items of the same kind they are either 94 | placed on the same line (when the list is short) or each of them is on 95 | its own line. This principle also helps in reducing the size of diff 96 | automatically when new items are inserted in the sequence. 97 | 98 | In the following sections, we have listed styles of different constructs 99 | for single line and multi line cases. The single line case is used when 100 | the whole construct fits into a single line and multi line when it 101 | becomes longer than 80 columns and needs to be broken into more than one 102 | line. 103 | 104 | Try to apply the same style to all the items in a sequence. For example, 105 | do not use this:: 106 | 107 | f x y 108 | | x > y = 109 | do something 110 | | x == y = do something -- should be on the next line 111 | | otherwise = 112 | do something 113 | 114 | Its preferable to not mix single line and multi-line formats, but 115 | sometimes you can, especially the first or last line could be in a 116 | single line format even if the rest are in multiline format. 117 | 118 | Do not try to align the items with each other based on some separator 119 | on each line. Aligning becomes a headache when new entries are added 120 | in the sequence, it requires changing all the lines and produces 121 | unnecessary diffs. 122 | 123 | Delineating Sections 124 | -------------------- 125 | 126 | In the file use comments as follows to delineate different logical sections, 127 | dashes are up to 79 columns:: 128 | 129 | ------------------------------------------------------------------------------- 130 | -- Type 131 | ------------------------------------------------------------------------------- 132 | 133 | Where clause 134 | ------------ 135 | 136 | ``where`` clause is used in many constructs to separate a list of 137 | definitions from the main part of the construct. For clarity, and to 138 | explicitly indicate that a list of definition follows it is preferable 139 | to use ``where`` clause on its own line with a preceding and following 140 | blank line. However, it is acceptable to end or start a line with 141 | ``where`` in some cases:: 142 | 143 | -- when there is a single line LHS in the clause 144 | module Streamly.Internal.Data.Stream (Step (..)) where 145 | 146 | ... 147 | 148 | class Functor f where 149 | ... 150 | 151 | -- when there is a single line RHS in the clause 152 | f x = 153 | ... 154 | 155 | where f1 = ... 156 | 157 | Multi line, do not indent the body of `where` clause:: 158 | 159 | f x = 160 | ... 161 | 162 | where 163 | 164 | f1 = ... 165 | 166 | f2 y = do 167 | putStrLn x 168 | ... 169 | 170 | Single line definitions within `where` may omit blank lines between them:: 171 | 172 | f x = 173 | ... 174 | 175 | where 176 | 177 | f1 = ... 178 | f2 y = ... 179 | 180 | Module level pragmas 181 | -------------------- 182 | 183 | Keep the lines sorted by the pragma name, do not align the ends of lines:: 184 | 185 | {-# LANGUAGE BangPatterns #-} 186 | {-# LANGUAGE CPP #-} 187 | {-# LANGUAGE ConstraintKinds #-} 188 | 189 | Module Declaration 190 | ------------------ 191 | 192 | Single line :: 193 | 194 | module Streamly.Internal.Data.Stream (Step (..)) 195 | 196 | where 197 | 198 | ... 199 | 200 | Multi-line :: 201 | 202 | module Streamly.Internal.Data.Stream 203 | ( 204 | -- * The stream type 205 | Step (..) 206 | 207 | -- * Construction 208 | , nil 209 | , nilM 210 | , cons 211 | ) 212 | 213 | where 214 | 215 | Exports 216 | ------- 217 | 218 | * Export symbols explicitly. Rationale: 219 | 220 | * If not explicitly exported, you may miss unused functions in the 221 | module as all functions get exported by default. For example, you defined 222 | a benchmarking function but did not add it to benchmarks list. It will 223 | never be reported as it is treated as used via implicit exports. 224 | * Compiler optimizations get impacted due to exporting because the compiler 225 | has to optimize the function and put it in the interface files. 226 | Optimizations work better and are more efficient if you explictly export. 227 | 228 | Imports 229 | ------- 230 | 231 | * When reading code we want to find out where a symbol is coming 232 | from. Import symbols explicitly by names or import the modules qualified 233 | as long as possible. 234 | 235 | * If the number of symbols imported is too long and we do not want to 236 | import qualified, then we have to import all symbols from a module 237 | implicitly. To help the reader find out where a symbol may be coming 238 | from we place all the implicit imports together as a separate group. 239 | 240 | * To add a new symbol or import to existing imports, we need to figure 241 | out where to add it, for this case sorting of imports is useful. Placing 242 | the qualified imports as a separate group may also help in this. 243 | 244 | * Having many import groups makes one think about the groups/grouping 245 | scheme every time you have to insert an import, making it difficult to 246 | maintain. 247 | 248 | Based on the above, we can have: 249 | 250 | * Explicit import group 251 | * qualified import group 252 | * implicit import group 253 | 254 | Single line:: 255 | 256 | import Control.Concurrent (killThread, myThreadId, takeMVar, threadDelay) 257 | 258 | Multi line, list style to avoid rearrangement when adding new items:: 259 | 260 | import Control.Exception 261 | ( AsyncException 262 | , Exception 263 | , SomeException 264 | , assert 265 | , fromException 266 | , mask_ 267 | ) 268 | 269 | Variable Naming 270 | --------------- 271 | 272 | * Use verbs for functions and nouns for values. 273 | * Use camelCase. 274 | * Do not capitalize all letters of an abbreviation, it may become 275 | problematic if capitals are next to each other e.g. `decodeHTTPUTF8` vs 276 | `decodeHttpUtf8`. 277 | * Use shorter variable names for shorter scopes, and longer variable names for 278 | bigger scopes. 279 | * In general, avoid using a prime on the variable names, e.g. use `step1` 280 | instead of `step'`. Numbered indexing is better because it is easier 281 | on the eyes especially when there are many of them sprinkled around 282 | and we can represent multiple generations of the variables without 283 | adding more characters e.g. we can write `step2` instead of `step''`. 284 | 285 | Top Level Declarations 286 | ---------------------- 287 | 288 | * All top level Declarations should be separated by a blank line. 289 | Multiple single line declarations may not have a blank line 290 | between them. 291 | * Pragmas must be placed before the declaration it applies to 292 | * haddock comments should come before the pragmas 293 | * There should be no blank lines between haddock comment, pragmas, and 294 | the declaration. 295 | 296 | The LHS and RHS can be combined on the same line when the whole 297 | definition fits in a single line. Otherwise, RHS should start on a 298 | separate line. Some constructs like ``do`` have an exception to this 299 | rule, in which case the keyword ``do`` could be on the same line as LHS. 300 | 301 | Example of multiple declarations separated by a blank line:: 302 | 303 | -- | An empty 'Stream'. 304 | {-# INLINE nil #-} 305 | nil :: Monad m => Stream m a 306 | nil = Stream (\_ _ -> return Stop) () 307 | 308 | -- | An empty 'Stream' with a side effect. 309 | {-# INLINE nilM #-} 310 | nilM :: Monad m => m b -> Stream m a 311 | nilM m = Stream (\_ _ -> m >> return Stop) () 312 | 313 | Single line:: 314 | 315 | nil = Stream (\_ _ -> return Stop) () 316 | 317 | Two line:: 318 | 319 | -- fit in two lines when one line is too long 320 | nil = 321 | Stream (\_ _ -> return Stop) () 322 | 323 | Multi line:: 324 | 325 | f x = 326 | case x of 327 | 1 -> ... 328 | 2 -> ... 329 | _ -> ... 330 | 331 | INLINE/SPECIALIZE pragmas are important for performance, those (and 332 | pragmas in general) are placed before the signature so that they are 333 | clearly visible (compared to placement after the function definition). 334 | 335 | Data Declarations 336 | ----------------- 337 | 338 | Separate data declarations by a blank line. 339 | 340 | Single line:: 341 | 342 | data Step s a = Yield a s | Skip s | Stop 343 | 344 | data Person = Person String String Int 345 | 346 | -- Single field records 347 | data Person = Person {firstName :: String} 348 | 349 | Two line:: 350 | 351 | data Step s a = 352 | Yield a s | Skip s | Stop 353 | 354 | Multi line:: 355 | 356 | -- | Sum types 357 | data Step s a = 358 | Yield a s -- ^ Yield 359 | | Skip s -- ^ Skip 360 | | Stop -- ^ Stop 361 | 362 | -- | Product types (prefer records when there are too many fields) 363 | data Person = Person 364 | String String Int 365 | 366 | data Person = Person 367 | String -- ^ First name 368 | String -- ^ Last name 369 | Int -- ^ Age 370 | 371 | -- | Records 372 | data Person = Person 373 | { firstName :: String -- ^ First name 374 | , lastName :: String -- ^ Last name 375 | , age :: Int -- ^ Age 376 | } deriving (Eq, Show) 377 | 378 | -- | Records, with long comments for fields 379 | data Person = Person 380 | { 381 | -- | First name 382 | firstName :: String 383 | 384 | -- | Last name 385 | , lastName :: String 386 | 387 | -- | Age 388 | , age :: Int 389 | } deriving (Eq, Show) 390 | 391 | Signatures 392 | ---------- 393 | 394 | To keep signatures consistent with function definition formatting style, 395 | we keep the `::` on the same line as the function name as we keep `=` on 396 | the same line in definitions. 397 | 398 | Single line:: 399 | 400 | f :: (Monad m, IsStream m, Num a) => a -> t m a 401 | 402 | Two line:: 403 | 404 | -- Constraint can be combined with the LHS line as long as it is not broken 405 | -- on more than one line. 406 | f :: (Monad m, IsStream m, Num a) 407 | => a -> t m a 408 | 409 | Multi line:: 410 | 411 | f :: 412 | (Monad m, IsStream m, Num a) 413 | => a -> t m a 414 | 415 | f :: 416 | (a -> b) 417 | -> t m a 418 | -> t m b 419 | 420 | f :: 421 | ( Monad m -- ^ Monad 422 | , IsStream m -- ^ Stream 423 | , Num a -- ^ Num 424 | ) 425 | => a -- ^ a 426 | -> t m a -- ^ t m a 427 | 428 | Sequence Types 429 | -------------- 430 | 431 | Single line:: 432 | 433 | list = [One, Two, Three] 434 | 435 | tuple = (One, Two, Three) 436 | 437 | Multi line:: 438 | 439 | list = 440 | [ One 441 | , Two 442 | , Three 443 | ] 444 | 445 | tuple = 446 | ( One 447 | , Two 448 | , Three 449 | ) 450 | 451 | Nested:: 452 | 453 | list = 454 | [ Group1 455 | [ One 456 | , Two 457 | , Three 458 | ] 459 | , Group2 460 | [ One 461 | , Two 462 | , Three 463 | ] 464 | ] 465 | 466 | tuple = 467 | ( 468 | ( One 469 | , Two 470 | , Three 471 | ) 472 | , 473 | ( One 474 | , Two 475 | , Three 476 | ) 477 | ) 478 | 479 | Expressions 480 | ----------- 481 | 482 | Use single whitespace to separate operators and terms. Do not use 483 | whitespace after opening and before closing parentheses. Do not use 484 | whitespace between lambda and the first argument. 485 | 486 | :: 487 | 488 | a + b -- single whitespace around operators 489 | (a + b) -- no whitespace around parenthesis 490 | [1, 2] -- no whitespace around square brackets 491 | \x -> return x -- no whitespace after "\" 492 | 493 | Avoid creating long expressions, name parts of a long expression using `let`, 494 | `where` or top level binding and use those names to make the expression 495 | shorter. 496 | 497 | `case` statements 498 | ----------------- 499 | 500 | DO NOT USE THIS :: 501 | 502 | foobar = case x of 503 | Just j -> foo 504 | Nothing -> bar 505 | 506 | Use this instead :: 507 | 508 | foobar = 509 | case x of 510 | Just y -> foo 511 | Nothing -> bar 512 | 513 | Nested/multi line case alternatives:: 514 | 515 | foobar = 516 | case x of 517 | Just y -> 518 | case y of 519 | Just z -> ... 520 | Nothing -> ... 521 | Nothing -> bar 522 | 523 | `do` block :: 524 | 525 | foobar = 526 | case x of 527 | Just y -> do 528 | case y of 529 | Just z -> ... 530 | Nothing -> ... 531 | putStrLn "hello" 532 | Nothing -> bar 533 | 534 | Do not align the arrows. 535 | 536 | Lambdas 537 | ------- 538 | 539 | Single line:: 540 | 541 | f x = g $ h $ \y -> putStrLn y 542 | 543 | Multi line:: 544 | 545 | f x = 546 | g $ h $ \y -> do 547 | putStrLn "hello " 548 | return y 549 | 550 | f x = 551 | ( g 552 | $ h 553 | $ \y -> do 554 | putStrLn "hello " 555 | return y 556 | ) 557 | 558 | `if`-`then`-`else` 559 | ------------------ 560 | 561 | Single line :: 562 | 563 | if x then y else z 564 | 565 | Multi line :: 566 | 567 | if x 568 | then y 569 | else z 570 | 571 | if x 572 | then 573 | case y of 574 | True -> ... 575 | False ... 576 | else z 577 | 578 | One way branching in a cascading conditional clause can be flattened to reduce 579 | indentation, this is just another way writing a multi-way if without using the 580 | extension:: 581 | 582 | if x 583 | then y 584 | else if z 585 | then u 586 | else v 587 | 588 | Top Level Function Definitions 589 | ------------------------------ 590 | 591 | * See the "top level declarations" section earlier for general guidelines and 592 | examples. 593 | * Each declaration must have a type signature 594 | * Do not use a blank line between multiple equations of the same function. 595 | 596 | Let Clause 597 | ---------- 598 | 599 | Single line :: 600 | 601 | let x = f x in x 602 | 603 | Multi line, align the end of `let` with end of `in`, this alignment 604 | is compatible with `do` blocks which require `in` to be nested inside 605 | `let`:: 606 | 607 | let x = f x 608 | in x 609 | 610 | Multi line with single line definitions:: 611 | 612 | let f x = x 613 | g x = x 614 | in f y + g y 615 | 616 | Multi line, indent the body within the definition, separate the 617 | multi line definitions with a blank line:: 618 | 619 | let f x y = 620 | case x of 621 | True -> x 622 | False -> y 623 | ... 624 | 625 | g x y = 626 | case x of 627 | True -> x 628 | False -> y 629 | ... 630 | in f a b || g c d 631 | 632 | `do` Blocks 633 | ----------- 634 | 635 | Usually the `do` keyword can be combined with the previous line:: 636 | 637 | parselMx' pstep initial extract (Stream step state) = do 638 | initial >>= go SPEC state [] 639 | ... 640 | 641 | if x == y 642 | then do 643 | ... 644 | ... 645 | else do 646 | ... 647 | ... 648 | 649 | let f x y = do 650 | putStrLn x 651 | putStrLn y 652 | ... 653 | in f y 654 | 655 | If not, start a `do` like this:: 656 | 657 | do 658 | putStrLn "hello" 659 | putStrLn "hello" 660 | 661 | Guards 662 | ------ 663 | 664 | Single line :: 665 | 666 | f (One x) 667 | | x < y = True 668 | | otherwise = False 669 | 670 | Multi line :: 671 | 672 | f (One x) 673 | | x < y = 674 | case x of 675 | 1 -> ... 676 | 2 -> ... 677 | _ -> ... 678 | | otherwise = False 679 | 680 | In ``case`` :: 681 | 682 | case x of 683 | One y 684 | | y < z1 -> 685 | f z1 686 | | y < z2 -> do 687 | ... 688 | ... 689 | | otherwise -> 690 | f y 691 | Two y -> 692 | ... 693 | 694 | Its preferable to not mix single line and multi-line formats, but 695 | sometimes you can (especially, the first line or the last line could be 696 | in single line format), use your judgement. 697 | 698 | Function Application & Composition 699 | ---------------------------------- 700 | 701 | Single line:: 702 | 703 | scanlM sstep (return szero) (return . sessionOutputStream) flush stream 704 | 705 | k x = f (g (h x)) 706 | k x = f $ g $ h x 707 | k x = h x & g & f 708 | k = f . g . h 709 | 710 | Two line:: 711 | 712 | scanlM 713 | sstep (return szero) (return . sessionOutputStream) flush stream 714 | 715 | scanlM sstep (return szero) (return . sessionOutputStream) flush stream 716 | arg1 arg2 ... 717 | 718 | Multi line:: 719 | 720 | scanlM 721 | sstep 722 | (return szero) 723 | (return . sessionOutputStream) 724 | flush 725 | stream 726 | 727 | lookup e m = 728 | foldrM 729 | (\(a, b) xs -> if e == a then return (Just b) else xs) 730 | (return Nothing) 731 | m 732 | 733 | func = 734 | S.drain 735 | (encodeLatin1Lax 736 | (S.concatUnfold A.read 737 | (S.concatMapWith parallel use 738 | (S.unfold TCP.acceptOnPort 8090 739 | ) 740 | ) 741 | ) 742 | ) 743 | 744 | func = 745 | S.drain 746 | $ encodeLatin1Lax 747 | $ S.concatUnfold A.read 748 | $ S.concatMapWith parallel use 749 | $ S.unfold TCP.acceptOnPort 8090 750 | 751 | func = 752 | ( S.drain 753 | $ encodeLatin1Lax 754 | $ S.concatUnfold A.read 755 | $ S.concatMapWith parallel use 756 | $ S.unfold TCP.acceptOnPort 8090 757 | ) 758 | 759 | func = 760 | ( S.drain 761 | . encodeLatin1Lax 762 | . S.concatUnfold A.read 763 | . S.concatMapWith parallel use 764 | . S.unfold TCP.acceptOnPort 765 | ) 8090 766 | 767 | -- non-aligning operators 768 | func = 769 | ( S.drain 770 | `op` encodeLatin1Lax 771 | `ope` S.concatUnfold A.read 772 | `oper` S.concatMapWith parallel use 773 | `opera` S.unfold TCP.acceptOnPort 8090 774 | ) 775 | 776 | Multi line in `do` block:: 777 | 778 | func = do 779 | putStrLn "do block" 780 | S.unfold TCP.acceptOnPort 8090 781 | & S.concatMapWith parallel use 782 | & S.concatUnfold A.read 783 | & encodeLatin1Lax 784 | & S.drain 785 | 786 | The first line can collapse multiple items in the same line and the last line 787 | could be a multi line expr:: 788 | 789 | do 790 | putStrLn "do" 791 | return $ Skip $ -- multiple `$` applications in a single line 792 | if done 793 | then (FromSVarDone sv) 794 | else (FromSVarRead sv) 795 | 796 | f x = 797 | g $ h $ \y -> do 798 | putStrLn "hello " 799 | return y 800 | 801 | -- alternatively it can be formatted like a sequence 802 | 803 | do 804 | putStrLn "do" 805 | return 806 | $ Skip 807 | $ if done 808 | then (FromSVarDone sv) 809 | else (FromSVarRead sv) 810 | 811 | f x = 812 | ( g 813 | $ h 814 | $ \y -> do 815 | putStrLn "hello " 816 | return y 817 | ) 818 | 819 | Haddock 820 | ------- 821 | 822 | * User visible (exported and not internal) declarations must have 823 | haddock documentation. 824 | * Add examples, annotations like `See also`, `Unsafe`, `Time 825 | complexity`, `Space complexity`, `since` where applicable. 826 | 827 | :: 828 | 829 | -- | Create an @Array Word8@ of the given length from a machine address 830 | -- 'Addr#'. 831 | -- 832 | -- >>> fromAddr# 5 "hello world!"# 833 | -- > [104,101,108,108,111] 834 | -- 835 | -- /See also: 'fromString#'/ 836 | -- 837 | -- /Unsafe/ 838 | -- 839 | -- /Time complexity: O(1)/ 840 | -- 841 | -- /Space complexity: O(1)/ 842 | -- 843 | -- @since 0.8.0 844 | -- 845 | {-# INLINE fromAddr# #-} 846 | fromAddr# :: Int -> Addr# -> IO (Array Word8) 847 | fromAddr# n addr# = do 848 | 849 | References 850 | ---------- 851 | 852 | * https://www.joachim-breitner.de/blog/739-Avoid_the_dilemma_of_the_trailing_comma 853 | * https://stackoverflow.com/questions/10483635/why-do-lots-of-programmers-move-commas-to-the-next-line 854 | -------------------------------------------------------------------------------- /getting-started.rst: -------------------------------------------------------------------------------- 1 | Getting Started with GHC & cabal 2 | ================================ 3 | 4 | The purpose of this guide is to document best practices for new users to 5 | get started on using the Haskell compiler ``ghc`` and Haskell build tool 6 | ``cabal``. If you follow this guide and run into a problem `please raise 7 | an issue here `_. 8 | For diagnostics, please see the FAQ_ section in the end. 9 | 10 | This guide is primarily oriented towards POSIX shell users. On 11 | Windows, ``ghc`` is installed on top of ``msys`` which provides a POSIX 12 | shell. This document, with some changes, may apply to Windows as well 13 | but it has not been tested. We assume ``cabal`` version 3.0 or higher 14 | and GHC version ``8.2.1`` or higher. 15 | 16 | .. contents:: Table of Contents 17 | :depth: 1 18 | 19 | Install ``ghc`` and ``cabal`` 20 | ----------------------------- 21 | 22 | Install the Glasgow Haskell compiler ``ghc`` and the build tool ``cabal``. 23 | 24 | * `Preferred method for Linux and Mac OSX `_ 25 | * `Shell method for Linux/Mac OSX/POSIX `_ 26 | * `Other methods `_ 27 | 28 | Verify Installation 29 | ~~~~~~~~~~~~~~~~~~~ 30 | 31 | To check that the tools are installed and available in your PATH, run:: 32 | 33 | $ ghc --version 34 | $ ghc -e 'putStrLn "hello world!"' 35 | $ cabal --version 36 | 37 | If it does not work check if the directory where the tools are installed 38 | is in your `PATH`. Make sure you have followed the installation 39 | instructions carefully, especially the part where it asks you to setup 40 | the `PATH` for you. 41 | 42 | Hello World! 43 | ------------ 44 | 45 | An executable must have a ``Main`` module consisting of a `main` 46 | function where the program execution starts:: 47 | 48 | $ cat hello.hs 49 | module Main where 50 | main :: IO () 51 | main = putStrLn "hello world" 52 | 53 | $ ghc hello.hs 54 | $ ./hello 55 | 56 | The first line is optional, any module without an explicit name is 57 | treated as a ``Main`` module by default. 58 | 59 | Haskell Packages 60 | ---------------- 61 | 62 | The canonical Haskell package repository is `Hackage 63 | `_, hosting thousands of packages consisting of 64 | libraries as well as useful executable programs. You can browse the packages 65 | and their documentation on `Hackage `_. 66 | 67 | ``cabal`` can install packages from Hackage so that they can be used by 68 | ``ghc``. To get familiar with ``cabal``'s commands and options use:: 69 | 70 | $ cabal --help 71 | 72 | Before you can install or use the packages, you need to fetch and update 73 | the list of packages from Hackage:: 74 | 75 | $ cabal update 76 | 77 | Side Note: ``cabal`` keeps its housekeeping data in ``$HOME/.cabal``. The 78 | fetched package index and packages are kept in 79 | ``$HOME/.cabal/packages/hackage.haskell.org/``. 80 | 81 | Compiling Haskell Programs 82 | -------------------------- 83 | 84 | Isolated Compilation 85 | ~~~~~~~~~~~~~~~~~~~~ 86 | 87 | We compiled the above program using ``ghc`` directly. This program 88 | has a dependency only on the ``base`` package which is shipped with ``ghc``. 89 | In general, a program may depend on several other packages and each 90 | dependency may have many versions. When you are compiling program ``A`` 91 | it may require package ``X`` version ``v1``, on the other hand when 92 | you are compiling program ``B`` it may require package ``X`` version 93 | ``v2``. If we install packages globally then we can only install/activate 94 | one version of any given package. This means we can either compile 95 | program ``A`` or program ``B`` but not both together. 96 | 97 | To avoid such issues, we recommend that you ALWAYS use a dedicated 98 | package directory to build a program, even if it is a single file 99 | program. Using a dedicated directory provides an isolated build 100 | environment (see details in the following sections). ``cabal`` would 101 | install the necessary dependency versions specific to the program and 102 | invoke ``ghc`` with those dependencies versions. This way each program 103 | gets its own build environment and they do not interfere with each 104 | other. 105 | 106 | When installing library packages globally, there are many other ghc 107 | package management related details that you may need to know to debug 108 | issues around ``ghc`` not being able to use a package or cabal not being 109 | able to install a package due to version conflicts. Therefore, we 110 | recommend that you NEVER use ``ghc`` to compile directly outside a cabal 111 | build directory. This also means that you never need to use ``cabal 112 | install`` to install library packages outside of a cabal directory. You 113 | can of course use ``cabal install`` to install executables globally e.g. 114 | ``cabal install hlint --install-dir ~/.local/bin`` would install the 115 | ``hlint`` executable in ``~/.local/bin``. 116 | 117 | Building and Running a Program 118 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 119 | 120 | Let us write the hello world example in an isolated build 121 | environment. We will create a cabal ``package`` for our program to 122 | do so. First create a directory for our ``hello-world`` package. This 123 | directory will contain an independent and isolated build environment for 124 | our package:: 125 | 126 | $ mkdir hello-world 127 | $ cd hello-world 128 | 129 | Now create a package description file (``.cabal``). This 130 | file contains important information on how to build the package, 131 | including dependencies of the package, compiler options, executables, 132 | benchmarks, test suites to build:: 133 | 134 | $ cabal init 135 | 136 | This would create a file named ``hello-world.cabal`` in the current 137 | directory. The contents of the file look like this:: 138 | 139 | name: hello-world 140 | version: 0.1.0.0 141 | 142 | executable hello-world 143 | main-is: Main.hs 144 | build-depends: base >=4.13 && <4.14 145 | 146 | It says, this directory contains a package named ``hello-world`` 147 | whose version number is ``0.1.0.0``. The package contains an 148 | executable called ``hello-world`` whose main module lives in the 149 | file ``Main.hs``. The package depends on the ``base`` package. 150 | `base `_ is a fundamental 151 | library package required by all Haskell programs. ``base`` package 152 | provides the `Prelude` module which is implicitly imported by Haskell 153 | programs. The function ``putStrLn`` in our program comes from the 154 | `Prelude `_ 155 | module. You can add more packages here separated with commas. 156 | 157 | The default package name ``hello-world`` is automatically derived by 158 | ``cabal init`` from the current directory name. You can use a different 159 | name using ``cabal init -p``. Or you can just edit the ``.cabal`` 160 | file and change the package name field, you have to remember that the 161 | ``.cabal`` file name must always be the same as the package name so if 162 | you change the package name you would have to rename it as well. You 163 | can use ``cabal init --help`` to know about more ``init`` options to use. 164 | 165 | We can now write our program in the file ``Main.hs``. In fact, ``cabal 166 | init`` itself creates one for us, we can edit it if we want:: 167 | 168 | $ cat Main.hs 169 | module Main where 170 | 171 | main :: IO () 172 | main = putStrLn "Hello, Haskell!" 173 | 174 | Note that ``Main.hs`` is not a special name, you can change it to 175 | whatever name you want as long as you use the same name in the ``main-is`` 176 | field of the ``executable`` section in the ``.cabal`` file 177 | 178 | Let us now build and run our program:: 179 | 180 | $ cabal run 181 | 182 | This command builds the executable ``hello-world`` from the module ``Main.hs`` 183 | as specified in the ``.cabal`` file, and then runs the executable. The 184 | executable and all other intermediate build artifacts are created in the 185 | ``dist-newstyle`` directory. 186 | 187 | We can clean the build artifacts using:: 188 | 189 | $ cabal clean 190 | 191 | If we want to just build the package and not run it:: 192 | 193 | $ cabal build 194 | 195 | The executable ``hello-world`` can be found inside the ``dist-newstyle`` 196 | directory. ``cabal build -v`` would print its path as well as a lot of other 197 | information including how it invokes ``ghc``:: 198 | 199 | $ cabal build -v 200 | ... 201 | Linking /Users/harendra/hello-world/dist-newstyle/build/x86_64-osx/ghc-8.8.3/hello-world-0.1.0.0/x/hello-world/build/hello-world/hello-world ... 202 | 203 | We can run that executable directly too instead of using ``cabal run``:: 204 | 205 | $ /Users/harendra/hello-world/dist-newstyle/build/x86_64-osx/ghc-8.8.3/hello-world-0.1.0.0/x/hello-world/build/hello-world/hello-world 206 | Hello, Haskell! 207 | 208 | Use ``cabal --help`` for general ``cabal`` commands and options. For 209 | more details on command line options please refer to `this section in 210 | cabal user guide `_. 211 | To know more about the fields you can use in the cabal file `please see this 212 | section `_. 213 | 214 | Note: Command line options and their behavior has changed in recent versions 215 | of ``cabal`` and the newer options (with a ``v2-`` prefix) are now used 216 | by default in cabal 3.0 or higher (i.e. ``cabal build`` is the same as 217 | ``cabal v2-build``). Please do not get confused with the older cabal 218 | command line options (with a ``v1-`` prefix) which may be mentioned in 219 | some sections of the user guide. 220 | 221 | Specifying ``ghc-options`` 222 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 223 | 224 | In the ``executable`` stanza of the cabal file we can use the ``ghc-options`` 225 | field to pass command line options to ``ghc`` when building our executable:: 226 | 227 | executable hello-world 228 | main-is: Main.hs 229 | build-depends: base >=4.13 && <4.14 230 | ghc-options: -v 231 | 232 | If you are interested in how things work internally, the ``ghc -v`` 233 | option could be especially useful to see how cabal sets up the package 234 | databases for ``ghc``, i.e. where the compiled dependencies are coming from:: 235 | 236 | Using binary package database: /Users/harendra/.ghcup/ghc/8.8.3/lib/ghc-8.8.3/package.conf.d/package.cache 237 | Using binary package database: /Users/harendra/.cabal/store/ghc-8.8.3/package.db/package.cache 238 | Using binary package database: /Users/harendra/hello-world/dist-newstyle/packagedb/ghc-8.8.3/package.cache 239 | Using binary package database: /Users/harendra/hello-world/dist-newstyle/build/x86_64-osx/ghc-8.8.3/hello-world-0.1.0.0/x/hello-world/package.conf.inplace/package.cache 240 | 241 | This could be useful if you face an issue where ``ghc`` complains that a 242 | particular package is not found. For more details about how ghc package 243 | management works see `GHC package management guide `_. 244 | 245 | Compiling with ``ghc`` directly 246 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 247 | 248 | Now that we have an isolated package build setup. We can even directly use 249 | ``ghc`` (version ``8.2.1`` or higher) to compile the files in our package 250 | instead of using ``cabal build``. 251 | 252 | For ``ghc`` to use the same package dependencies as ``cabal`` invokes 253 | it with we need to first create an ``environment`` file for ``ghc`` to 254 | use:: 255 | 256 | cabal build --write-ghc-environment-files=always 257 | 258 | This will generate an ``environment`` file at the root of the package 259 | directory:: 260 | 261 | $ ls .ghc.* 262 | .ghc.environment.x86_64-darwin-8.8.3 263 | 264 | You can put this in your ``$HOME/cabal.config`` or ``cabal.project.local`` so 265 | that you do not have to specify this on each build:: 266 | 267 | $ cat cabal.project.local 268 | write-ghc-environment-files: always 269 | 270 | Now we can use ``ghc`` directly to compile any module in this package:: 271 | 272 | $ ghc Main.hs 273 | Loaded package environment from /Users/harendra/hello-world/.ghc.environment.x86_64-darwin-8.8.3 274 | [1 of 1] Compiling Main ( Main.hs, Main.o ) 275 | Linking Main ... 276 | 277 | $ ./Main 278 | Hello, Haskell! 279 | 280 | How It works? 281 | ............. 282 | 283 | From version ``8.2.1`` onwards ``ghc`` always looks for an environment 284 | file in the current directory or in any of the parent directories 285 | and loads it if found. The environment file contains a list of package 286 | databases and packages for use by ``ghc``. 287 | 288 | ``cabal build`` sets up the environment file to use the package 289 | dependency versions that it has selected for the current package. 290 | 291 | Note: Do not forget to do a ``cabal build`` before compiling with ``ghc`` 292 | directly. 293 | 294 | Using extra dependencies 295 | ........................ 296 | 297 | If you want to use a package not specified in the ``build-depends`` 298 | section of the cabal file then you need to first install it from within 299 | the project directory and then explicitly ask ``ghc`` to use it:: 300 | 301 | $ cabal install unordered-containers 302 | $ ghc -package unordered-containers Main.hs 303 | 304 | GHC Documentation 305 | ~~~~~~~~~~~~~~~~~ 306 | 307 | It may be a good idea to go through the `ghc` help text:: 308 | 309 | $ ghc --help 310 | $ man ghc 311 | 312 | See `the GHC user guide `_ for more details. 313 | 314 | Creating Modules 315 | ~~~~~~~~~~~~~~~~ 316 | 317 | Till now, we used only one module the ``Main`` module in our program. Let us 318 | now create another module and import it in our ``Main`` module:: 319 | 320 | $ cat Hello.hs 321 | module Hello (hello) where 322 | 323 | hello :: String 324 | hello = "Hello World!" 325 | 326 | The first line defines the module ``Hello`` and exports the definition 327 | ``hello`` to be imported by other modules. Let us now use this definition in 328 | our ``Main`` module:: 329 | 330 | $ cat Main.hs 331 | module Main where 332 | 333 | import Hello (hello) 334 | 335 | main :: IO () 336 | main = putStrLn hello 337 | 338 | Now we can run it:: 339 | 340 | $ cabal run 341 | Hello World! 342 | 343 | We can see that it compiles and runs but produces the following warning:: 344 | 345 | : warning: [-Wmissing-home-modules] 346 | These modules are needed for compilation but not listed in your .cabal file's other-modules: 347 | Hello 348 | 349 | This will go away if we specify the new module in our ``executable`` 350 | stanza in the ``.cabal`` file:: 351 | 352 | executable hello-world 353 | main-is: Main.hs 354 | other-modules: Hello 355 | build-depends: base >=4.13 && <4.14 356 | 357 | We need to keep the following in mind when creating modules: 358 | 359 | * Module name (``Hello``) used in the module construct must match its file 360 | name (``Hello.hs``). 361 | * For hierarchical modules, if the module name is ``Example.Hello`` 362 | then the path of the module in the file system must be 363 | ``Example/Hello.hs`` relative to the import root. 364 | 365 | Interactive Haskell REPL (GHCi) 366 | ------------------------------- 367 | 368 | Once you have created an isolated package build environment, you can 369 | use the REPL (read-eval-print-loop) for fast evaluation of Haskell 370 | expressions or modules. 371 | 372 | For example, if you want to play with ``streamly``, type the following in your 373 | cabal package directory from the previous section:: 374 | 375 | $ cabal repl 376 | Build profile: -w ghc-8.8.3 -O1 377 | In order, the following will be built (use -v for more details): 378 | - hello-world-0.1.0.0 (exe:hello-world) (ephemeral targets) 379 | Preprocessing executable 'hello-world' for hello-world-0.1.0.0.. 380 | GHCi, version 8.8.3: https://www.haskell.org/ghc/ :? for help 381 | [1 of 1] Compiling Main ( Main.hs, interpreted ) 382 | Ok, one module loaded. 383 | *Main> 384 | 385 | It starts ``ghci``, the Haskell REPL, loading the ``Main`` module. You now 386 | have all the imports and symbols from the ``Main`` module accessible in the 387 | repl, you can evaluate those interactively:: 388 | 389 | *Main> main 390 | hello 391 | world 392 | *Main> S.drain $ S.mapM print $ S.fromList [1..3] 393 | 1 394 | 2 395 | 3 396 | 397 | We have all the dependency packages specified in ``build-depends`` 398 | available in GHCi, we can import any modules from those as we wish:: 399 | 400 | *Main> import qualified Streamly.Data.Fold as FL 401 | *Main FL> S.fold (FL.drainBy print) (S.fromList [1..3]) 402 | 1 403 | 2 404 | 3 405 | 406 | If we want any additional packages to be available in the REPL without 407 | having to specify them in the ``.cabal`` file, we can do that by using a 408 | CLI option:: 409 | 410 | $ cabal repl --build-depends streamly-bytestring 411 | 412 | Like ``ghc``, ``ghci`` also uses the ``environment`` files. Like ``ghc`` 413 | we can also use ``ghci`` directly instead of using ``cabal repl`` once 414 | the environment file is generated:: 415 | 416 | $ ghci 417 | GHCi, version 8.8.3: https://www.haskell.org/ghc/ :? for help 418 | Loaded package environment from /Users/harendra/hello-world/.ghc.environment.x86_64-darwin-8.8.3 419 | Prelude> :load Main 420 | [1 of 1] Compiling Main ( Main.hs, interpreted ) 421 | Ok, one module loaded. 422 | *Main> main 423 | hello 424 | world 425 | *Main> 426 | 427 | Type ``:?`` for help. 428 | See `the GHCi user guide `_ 429 | for comprehensive documentation. 430 | 431 | Using Dependencies 432 | ------------------ 433 | 434 | Using Packages from Hackage 435 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 436 | 437 | We can use any package from Hackage in our program by specifying it in 438 | the ``build-depends`` field (do not forget to execute ``cabal update`` 439 | at least once before this). Let's try to use the library `streamly 440 | `_ in our program. 441 | 442 | First add ``streamly`` to the dependencies:: 443 | 444 | executable hello-world 445 | main-is: Main.hs 446 | build-depends: base >=4.13 && <4.14, streamly 447 | 448 | ``import`` and use it in our ``Main`` module:: 449 | 450 | $ cat Main.hs 451 | import qualified Streamly.Prelude as S 452 | 453 | main = S.drain $ S.fromListM [putStrLn "hello", putStrLn "world"] 454 | 455 | $ cabal run 456 | 457 | See `the README for streamly on Hackage 458 | `_ for more code snippets 459 | to try out. 460 | 461 | Using Packages from github 462 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 463 | 464 | Let's say you want to play with the latest/unreleased version of `streamly from 465 | github `_. You will need a 466 | ``cabal.project`` file to do that. This file describes project level 467 | meta information, for example, all your packages (you can 468 | have multiple packages under the same directory tree, each one as a 469 | subdirectory with a ``.cabal`` file), build options for 470 | each package, where to source the package from etc.:: 471 | 472 | $ cat cabal.project 473 | packages: . 474 | source-repository-package 475 | type: git 476 | location: https://github.com/composewell/streamly 477 | tag: master 478 | 479 | ``packages: .`` means include the package in the current directory. The 480 | ``source-repository-package`` stanza specifies the ``streamly`` package's 481 | location as a github repository. We can specify any ``commit-id`` in the 482 | ``tag`` field. 483 | 484 | Now when we build this package, the ``streamly`` package used in the 485 | dependencies will be fetched from the github repository instead of Hackage. 486 | We can now use ``cabal repl`` as usual and we will be using the version of 487 | `streamly` from github:: 488 | 489 | $ cabal repl 490 | 491 | Using Non-Haskell Dependencies 492 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 493 | 494 | When a package depends on a C library we need to tell cabal where the 495 | library and its header files are:: 496 | 497 | $ cat cabal.project.local 498 | package text-icu 499 | extra-include-dirs: /opt/local/include 500 | extra-lib-dirs: /opt/local/lib 501 | 502 | NOTE: It seems this works only in cabal.project.local and not in cabal.project, 503 | see https://github.com/haskell/cabal/issues/2997 . 504 | 505 | We can also use the command line options, however, they do not apply to 506 | dependencies, they only apply to local packages:: 507 | 508 | $ cabal build --extra-include-dirs=/opt/local/include --extra-lib-dirs=/opt/local/lib 509 | 510 | GHC uses ``gcc`` or ``clang`` to compile C sources. The header file search 511 | path and library search path for ``gcc`` and ``clang`` can be specified using 512 | environment variables. This could be useful when you are not in a 513 | project context e.g. when installing a package using ``cabal install`` 514 | or if some other program is invoking cabal from inside:: 515 | 516 | $ export C_INCLUDE_PATH=/opt/local/include 517 | $ export CPLUS_INCLUDE_PATH=/opt/local/include 518 | $ export LIBRARY_PATH=/opt/local/lib:/usr/lib:/lib 519 | 520 | Customizing how dependencies are built 521 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 522 | 523 | Options passed to the build command, are ``global`` which means they 524 | apply to all your source packages, their dependencies, and dependencies 525 | of dependencies. For example:: 526 | 527 | $ cabal build --ghc-options=-Werror 528 | 529 | We can use the ``configure`` command to persistently save the settings in a 530 | ``cabal.project.local`` file:: 531 | 532 | $ cabal configure --ghc-options=-Werror 533 | $ cat cabal.project.local 534 | 535 | package * 536 | ghc-options: -Werror 537 | 538 | program-options 539 | ghc-options: -Werror 540 | 541 | If we want a setting to be applied only to a certain package or dependency:: 542 | 543 | $ cat cabal.project 544 | package streamly 545 | ghc-options: -Werror 546 | 547 | Freezing Dependency Versions 548 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 549 | 550 | ``cabal`` picks the dependency versions based on the constraints 551 | specified in the cabal file. When newer versions of dependencies become 552 | available or if the compiler version changes (which changes the ``base`` 553 | package version), cabal's dependency solver can pick a different set of 554 | dependency versions satisfying the constraints. However, if you want to 555 | freeze the versions picked by ``cabal`` you can use the ``cabal freeze`` 556 | command. It generates a ``cabal.project.freeze`` file consisting of the 557 | exact versions and build flags of the packages chosen by cabal. If that 558 | file exists ``cabal`` always picks up exactly those versions. 559 | 560 | This command can also be useful if you want to know all the dependencies of the 561 | project and their versions. 562 | 563 | Using Stackage Snapshots 564 | ~~~~~~~~~~~~~~~~~~~~~~~~ 565 | 566 | `Stackage `_ releases a consistent set 567 | of versions of Haskell packages that are known to build together, 568 | known as stackage ``lts`` Haskell snapshots. You can use the ``lts`` 569 | snapshots with cabal using the ``cabal.project.freeze`` file provided by 570 | stackage:: 571 | 572 | curl https://www.stackage.org/lts/cabal.config > cabal.project.freeze 573 | 574 | Packages Tied to GHC 575 | ~~~~~~~~~~~~~~~~~~~~ 576 | 577 | There are some packages whose versions change along with GHC versions 578 | because they depend on the GHC version. Versions of these packages (in 579 | the dependency version ranges) cannot be upgraded unless you use an 580 | appropriate version of GHC as well. These packages are also known as 581 | wired-in packages in ghc. Some important wired-in packages are: 582 | 583 | * `base `_ 584 | * `template-haskell `_ 585 | * `ghc-prim `_ 586 | 587 | `See this link for a complete list of wired-in packages 588 | `_. 589 | 590 | Cabal configuration 591 | ~~~~~~~~~~~~~~~~~~~ 592 | 593 | The behavior of ``cabal`` is determined by the following configuration, 594 | in the increasing priority order: 595 | 596 | * $HOME/.cabal/config (the user-wide global configuration) 597 | * cabal.project (the project configuration) 598 | * cabal.project.freeze (the output of cabal freeze) 599 | * cabal.project.local (the output of cabal configure) 600 | * command line flags 601 | * Environment variables 602 | 603 | `See cabal.project section in cabal user guide `_. 604 | 605 | Debugging 606 | --------- 607 | 608 | Because of strong type system, there is very little debugging required 609 | in Haskell compared to other languages. Low level debugging is seldom 610 | required. The most commonly used high level debugging technique is by 611 | printing debug messages on console using 612 | `the Debug.Trace module `_ 613 | or `putStrLn`. 614 | 615 | GHCi has a `built in debugger 616 | `_ 617 | with breakpoint and stepping support, however, this is not used much in 618 | practice. `gdb` can also be used on Haskell executables, however, this is 619 | mainly for advanced users because the low level code has little or no 620 | similarity with the high level code. 621 | 622 | Haskell (GHC) versions 623 | ---------------------- 624 | 625 | GHC is the de-facto Haskell compiler, Haskell version practically means 626 | GHC version. New versions of GHC are released quite often. Compared 627 | to other languages migrating to newer versions of GHC is pretty 628 | easy. Most packages work for many versions of GHC. However, you can 629 | expect some packages not yet building for the latest version of GHC and some 630 | not supporting versions that are too old. In many cases packages not yet 631 | supprting the newer versions can be built for newer versions by just 632 | using the ``--allow-newer`` option in ``cabal``. The recommended version 633 | range is usually the last three versions. 634 | 635 | Selecting the ``ghc`` version to use 636 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 637 | 638 | By default ``cabal`` picks up the ``ghc`` executable available in the 639 | shell ``PATH``. 640 | 641 | You can also use the cabal option to use a specific ``ghc`` version e.g. 642 | ``cabal build -w ghc-8.8``. 643 | 644 | You can also specify the ``ghc`` to be used for compilation in the 645 | ``cabal.project`` file using the ``with-compiler`` field. 646 | 647 | Selecting the ``ghc`` version with ``ghcup`` 648 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 649 | 650 | ``ghcup`` provides multiple versions of ``ghc`` and a currently 651 | activated version. ``ghcup set 8.8.3`` activates the ghc version 652 | ``8.8.3``. 653 | 654 | IMPORTANT NOTE: The activated version of ``ghc`` changes in all 655 | your shells and not just in the current shell. 656 | 657 | ``ghcup`` provides ``ghc`` and other version sensitive auxiliary 658 | ``executables like ghci``, ``haddock`` etc. in ``$HOME/.ghcup/bin``. 659 | 660 | * ``$HOME/.ghcup/bin/ghc`` => currently activated version of ghc 661 | * ``$HOME/.ghcup/bin/ghc-8.8`` => latest ghc-8.8.x 662 | * ``$HOME/.ghcup/bin/ghc-8.8.3`` => ghc-8.8.3 663 | 664 | These are symlinks to the binaries in ``$HOME/.ghcup/ghc``. You have the 665 | symlinks available in your shell ``PATH``. When you use ``ghcup set`` 666 | to activate a particular ghc version then it just modifies the ``ghc`` 667 | symlink to point to that version. 668 | 669 | Browsing Documentation: Haddock 670 | ------------------------------- 671 | 672 | HTML documentation for Haskell sources can be automatically generated using 673 | the ``haddock`` tool. To generate documentation for a package:: 674 | 675 | $ cabal haddock 676 | 677 | And then open the link displayed by this command in a browser. 678 | 679 | Searching Code: Hoogle 680 | ---------------------- 681 | 682 | Hoogle is a powerful search engine to search and browse the Haskell 683 | code base. You can search by terms, package names or even by types. We 684 | can `use it online `_ for all packages on 685 | Stackage. 686 | 687 | Using Hoogle search on a local package 688 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 689 | 690 | We can use hoogle on our package by generating a Hoogle database. 691 | Hoogle depends on the haddock documentation. When generating haddock 692 | docs, additionally generate a hoogle file as well:: 693 | 694 | $ cabal haddock --haddock-hoogle 695 | ... 696 | ~/streamly/dist-newstyle/build/x86_64-osx/ghc-8.8.3/streamly-0.7.2/doc/html/streamly/streamly.txt 697 | 698 | Then we can generate a hoogle database from this haddock directory:: 699 | 700 | $ hoogle generate --local=~/streamly/dist-newstyle/build/x86_64-osx/ghc-8.8.3/streamly-0.7.2/doc/html/streamly/ 701 | 702 | $ ls -al ~/.hoogle/*.hoo 703 | -rw-r--r-- 1 harendra staff 913433 Jun 18 21:05 /Users/harendra/.hoogle/default-haskell-5.0.17.hoo 704 | 705 | Bug alert: it appears that hoogle does not follow symbolic links in the 706 | directory path. 707 | 708 | To use the Hoogle database, run ``hoogle server --local -p 8080``. Then 709 | visit ``http://127.0.0.1:8080/`` in your browser to search using hoogle. 710 | ``--local`` is important to allow navigation of local ``file://`` URLs. 711 | 712 | We can also use the ``hoogle`` command to search directly in the database:: 713 | 714 | $ hoogle search id 715 | $ hoogle search "a -> a" 716 | $ hoogle search --info id 717 | 718 | To use hoogle in ``ghci``:: 719 | 720 | $ cat ~/.ghc/ghci.conf 721 | :def hoogle \s -> return $ ":! hoogle search \"" ++ s ++ "\"" 722 | :def doc \s -> return $ ":! hoogle search --info \"" ++ s ++ "\"" 723 | 724 | Then in ``ghci`` use can use:: 725 | 726 | :hoogle id 727 | :doc id 728 | 729 | Build times and Space Utilization 730 | --------------------------------- 731 | 732 | When we install a package or use a dependency in a program, ``cabal`` 733 | fetches the source packages from Hackage and compiles them. Haskell/GHC 734 | compilation speed is slower than imperative languages, say, C 735 | compilers. A lot of it is because of many expensive optimizations 736 | performed by GHC. In the first few package installs or builds a lot of 737 | dependencies may be fetched and built, therefore, initial builds may 738 | take some time. Please be patient. 739 | 740 | However, after the first compilation, ``cabal`` caches and reuses the 741 | previously compiled dependencies across all builds, provided that we 742 | are using the same version of GHC and default compilation options for 743 | dependencies. Whenever you change a compiler version you may see longer 744 | build times due to rebuilding the dependencies for that version. For 745 | faster build speeds avoid changing the compiler version often. 746 | 747 | ``cabal`` caches the previously built packages in ``$HOME/.cabal`` directory. 748 | The cache size may grow as more dependencies are fetched and built. Commonly 749 | 5-10 GB space allocation is reasonable for the cache. 750 | 751 | .. _FAQ: 752 | 753 | Frequently Asked Questions (FAQ) 754 | -------------------------------- 755 | 756 | Make sure that you have read and followed the guide above. 757 | 758 | When building your project 759 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 760 | 761 | Q: I am getting a ``Could not find module ...`` error:: 762 | 763 | Main.hs:3:1: error: 764 | Could not find module ‘Data.Foo’ 765 | Perhaps you meant 766 | Data.Bool (from base-4.13.0.0) 767 | Data.Fix (needs flag -package-key data-fix-0.2.1) 768 | Data.Pool (needs flag -package-key resource-pool-0.2.3.2) 769 | Use -v (or `:set -v` in ghci) to see a list of the files searched for. 770 | | 771 | 3 | import Data.Foo 772 | | ^^^^^^^^^^^^^^^ 773 | 774 | A: You have used the module ``Data.Foo`` in your program but you have not 775 | specified the package providing this module in the ``build-depends`` field of 776 | your executable or library section of your cabal file. Add it by editing the 777 | ``.cabal`` file. Assuming the module ``Data.Foo`` is in package ``foo``:: 778 | 779 | executable hello-world 780 | main-is: Main.hs 781 | build-depends: base >=4.13 && <4.14, foo 782 | 783 | If you do not know which package the module ``Data.Foo`` belongs to, you 784 | can search the module name on `hoogle `_ or use 785 | the `documentation by module on stackage 786 | `_ 787 | 788 | Q: I am getting a ``Could not resolve dependencies`` along with 789 | ``constraint from non-upgradeable package requires installed instance`` 790 | error:: 791 | 792 | Resolving dependencies... 793 | cabal: Could not resolve dependencies: 794 | [__0] trying: clock-project-0.1.0.0 (user goal) 795 | [__1] next goal: base (dependency of clock-project) 796 | [__1] rejecting: base-4.13.0.0/installed-4.13.0.0 (conflict: clock-project => 797 | base>=4.14 && <4.15) 798 | [__1] rejecting: base-4.14.0.0, base-4.13.0.0, base-4.12.0.0, base-4.11.1.0, 799 | base-4.11.0.0, base-4.10.1.0, base-4.10.0.0, base-4.9.1.0, base-4.9.0.0, 800 | base-4.8.2.0, base-4.8.1.0, base-4.8.0.0, base-4.7.0.2, base-4.7.0.1, 801 | base-4.7.0.0, base-4.6.0.1, base-4.6.0.0, base-4.5.1.0, base-4.5.0.0, 802 | base-4.4.1.0, base-4.4.0.0, base-4.3.1.0, base-4.3.0.0, base-4.2.0.2, 803 | base-4.2.0.1, base-4.2.0.0, base-4.1.0.0, base-4.0.0.0, base-3.0.3.2, 804 | base-3.0.3.1 (constraint from non-upgradeable package requires installed 805 | instance) 806 | [__1] fail (backjumping, conflict set: base, clock-project) 807 | After searching the rest of the dependency tree exhaustively, these were the 808 | goals I've had most trouble fulfilling: base, clock-project 809 | 810 | A. The key part is ``conflict: clock-project => base>=4.14 && <4.15`` 811 | and ``constraint from non-upgradeable package requires installed 812 | instance``. The ``base`` package version constraints in your cabal file are in 813 | conflict with the ``base`` version of the current compiler you are using. Each 814 | compiler version is tied to a particular ``base`` package version which cannot 815 | be upgraded. You need to either change the constraints in your cabal file to 816 | allow the ``base`` package version corresponding to the ``ghc`` version you are 817 | using or change your ``ghc`` version. 818 | 819 | You can see ``base`` versions corresponding to ``ghc`` versions `here 820 | `_ 821 | . If you are using ``ghcup``, ``ghcup list`` shows ``ghc`` and 822 | corresponding ``base`` versions. 823 | 824 | Q: I am getting a ``Could not resolve dependencies`` error but I am not using 825 | the packages mentioned in the error message in my project:: 826 | 827 | Resolving dependencies... 828 | cabal: Could not resolve dependencies: 829 | [__0] trying: slides-0.1.0.0 (user goal) 830 | [__1] trying: base-4.13.0.0/installed-4.13.0.0 (dependency of slides) 831 | ... 832 | 833 | A: You may not be using the dependency package in question but 834 | it may be a dependency of a dependency. In such case, you cannot 835 | fix the dependency version in your cabal file but you can use the 836 | ``--allow-newer`` ``cabal`` option e.g. ``cabal build --allow-newer 837 | ...``. You can also allow newer version of a specific set of packages 838 | e.g. ``cabal build --allow-newer=streamly ...``. 839 | 840 | Q: I do not see any dependency version issue in my ``.cabal`` file, but 841 | I am still getting a ``Could not resolve dependencies`` error. I am 842 | puzzled:: 843 | 844 | Resolving dependencies... 845 | cabal: Could not resolve dependencies: 846 | [__0] next goal: xls (user goal) 847 | [__0] rejecting: xls-0.1.3, xls-0.1.2, xls-0.1.1 (constraint from user target 848 | requires ==0.1.0) 849 | [__0] rejecting: xls-0.1.0 (constraint from user target requires ==0.1.3) 850 | [__0] fail (backjumping, conflict set: xls) 851 | After searching the rest of the dependency tree exhaustively, these were the 852 | goals I've had most trouble fulfilling: xls 853 | 854 | A: ``cabal`` looks for ``.cabal`` files in all the subdirectories. If 855 | the ``.cabal`` file in your current directory seems fine, look for any other 856 | ``.cabal`` files in your tree (which may be lying around by mistake) 857 | 858 | Q: Some random weird problem, unexpected behavior when building a project: 859 | 860 | A: When all else fails, try ``cabal clean`` or removing the ``dist-newstyle`` 861 | directory. 862 | 863 | Q: I am getting these strange messages:: 864 | 865 | $ cabal test 866 | cabal: Cannot test the package streamly-process-0.1.0.0 because none of the 867 | components are available to build: the test suite 'system-process-test' is not 868 | available because the solver did not find a plan that included the test 869 | suites. Force the solver to enable this for all packages by adding the line 870 | 'tests: True' to the 'cabal.project.local' file. 871 | 872 | $ cabal test system-process-test 873 | cabal: Cannot run the test suite 'system-process-test' because the solver did 874 | not find a plan that included the test suites for streamly-process-0.1.0.0. It 875 | is probably worth trying again with test suites explicitly enabled in the 876 | configuration in the cabal.project{.local} file. This will ask the solver to 877 | find a plan with the test suites available. It will either fail with an 878 | explanation or find a different plan that uses different versions of some 879 | other packages. Use the '--dry-run' flag to see package versions and check 880 | that you are happy with the choices. 881 | 882 | A: Use ``cabal test --enable-test`` and you will get a better error message. 883 | 884 | When Compiling Directly With GHC or using GHCi 885 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 886 | 887 | Q: ``cannot satisfy -package-id`` error:: 888 | 889 | $ ghc -O2 zz.hs 890 | Loaded package environment from /projects/streamly/.ghc.environment.x86_64-darwin-8.8.3 891 | : cannot satisfy -package-id fusion-plugin-0.2.1-inplace 892 | (use -v for more information) 893 | 894 | A: The package ``fusion-plugin-0.2.1`` is specified as a dependency in 895 | your cabal file. This package is listed in the ``.ghc.environment*`` 896 | file but has not been built. ``-inplace`` means it is a local package 897 | and not one downloaded from Hackage. Run ``cabal build fusion-plugin`` 898 | to make this error go away. 899 | 900 | Q: ``Could not find module`` error:: 901 | 902 | examples/WordClassifier.hs:28:1: error: 903 | Could not find module ‘Data.None’ 904 | Use -v (or `:set -v` in ghci) to see a list of the files searched for. 905 | | 906 | 28 | import Data.None 907 | | ^^^^^^^^^^^^^^^^ 908 | 909 | A: To resolve this: 910 | 911 | 1) Add the package providing module ``Data.None`` in the 912 | ``build-depends`` field in cabal file. Do not forget to do ``cabal build 913 | --write-ghc-environment-files=always`` after adding it. 914 | 915 | Alternatively, use ``cabal install `` (from within the project 916 | directory) to add the package to your ``.ghc.environment.*`` file. 917 | 918 | 2) If the package providing ``Data.None`` is already present in 919 | ``build-depends``, check if you have a ``.ghc.environment.*`` file in the 920 | project directory, if not use ``cabal build 921 | --write-ghc-environment-files=always`` to generate it. 922 | 923 | Q: ``Could not load module ... It is a member of the hidden package`` error:: 924 | 925 | examples/WordClassifier.hs:13:1: error: 926 | Could not load module ‘Data.HashMap.Strict’ 927 | It is a member of the hidden package ‘unordered-containers-0.2.10.0’. 928 | You can run ‘:set -package unordered-containers’ to expose it. 929 | (Note: this unloads all the modules in the current scope.) 930 | Use -v (or `:set -v` in ghci) to see a list of the files searched for. 931 | | 932 | 13 | import qualified Data.HashMap.Strict as Map 933 | | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 934 | 935 | A: The package providing the module ``Data.HashMap.Strict``, i.e. 936 | ``unordered-containers`` is available in ``cabal``'s package cache, 937 | but it is not mentioned as a dependency in your project. Do any of the 938 | following to resolve this: 939 | 940 | 1) Add ``unordered-containers`` in the ``build-depends`` field in cabal file. 941 | Do not forget to do ``cabal build --write-ghc-environment-files=always`` 942 | after adding it. 943 | 944 | 2) Use ``cabal install `` (from within the project directory) to add 945 | the package to your ``.ghc.environment.*`` file. 946 | 947 | 3) Use ``ghc -package unordered-containers`` to make it available to ``ghc`` 948 | anyway. 949 | 950 | Q: When running ``cabal repl`` I ran into :: 951 | 952 | $ cabal repl 953 | Resolving dependencies... 954 | TODO: add support for multiple packages in a directory 955 | CallStack (from HasCallStack): 956 | error, called at ./Distribution/Client/ProjectOrchestration.hs:548:9 in main:Distribution.Client.ProjectOrchestration 957 | 958 | Your project may have multiple packages/cabal files. Specify the package, that 959 | you want to use. For example:: 960 | 961 | $ cabal repl streamly 962 | 963 | Q: When running ``cabal repl`` I ran into :: 964 | 965 | [84 of 84] Compiling Streamly.Internal.FileSystem.Event.Darwin ( src/Streamly/Internal/FileSystem/Event/Darwin.hs, interpreted ) 966 | Error: bytecode compiler can't handle some foreign calling conventions 967 | Workaround: use -fobject-code, or compile this module to .o separately. 968 | 969 | A: As suggested in the error message, use :: 970 | 971 | $ cabal repl --ghc-options -fobject-code streamly 972 | 973 | When Installing packages 974 | ~~~~~~~~~~~~~~~~~~~~~~~~ 975 | 976 | Occasionally you may install *library* packages *within your project* 977 | scope. However, when installing *executable* packages, make sure that you are 978 | outside a project directory, otherwise the project's dependency 979 | constraints would apply to the package you are installing and the 980 | installation may fail. ``cabal install`` may fail with some of the 981 | errors described above, see the sections above for a resolution of 982 | those. 983 | 984 | Occasionally ``cabal install foo`` may fail with a compilation error due to 985 | several reasons: 986 | 987 | * In many cases, packages take time to move to newer versions of 988 | ``ghc``. Ideally, if the dependency version bounds are correctly set 989 | then the dependency resolution itself should fail with a newer compiler. 990 | However, many package authors use relaxed upper bounds on dependencies, 991 | and the build may fail with a compilation error if breaking changes 992 | arrive in a newer version. 993 | * There may be an error in specifying the version bounds. The version bounds 994 | may not have been tested. 995 | 996 | You can resolve these errors by: 997 | 998 | * Try the ``--allow-newer`` cabal option mentioned earlier. 999 | * Go to the Hackage page of the package, go to the ``Status`` section and click 1000 | on ``Hackage CI`` button, you can see the build matrix of the package. 1001 | From the matrix you can find out which compiler versions can compile 1002 | this package. You can also take a look at the ``tested-with`` field 1003 | in the cabal file of the package, to find the right compiler version 1004 | to use. Try an appropriate version of ``ghc``. 1005 | 1006 | Bugs & Quirks 1007 | ~~~~~~~~~~~~~ 1008 | 1009 | Q: ``ghc-pkg list`` does not show all the packages that cabal can use. 1010 | 1011 | A: Ideally, once we write the ``.ghc.environment`` file, ``ghc-pkg`` 1012 | should be able to list all the packages that cabal uses in a 1013 | project. However, ``ghc-pkg`` is not (yet?) aware of the environment 1014 | files and it lists only packages that are directly registered with ``ghc``. 1015 | This would be a minimal set when using latest cabal workflows, cabal does not 1016 | register packages directly with ``ghc`` it uses environment files. 1017 | 1018 | Q: ``cabal`` throws an error like this, even though I have cabal-version as the 1019 | first line:: 1020 | 1021 | Errors encountered when parsing cabal file ./xls.cabal: 1022 | 1023 | xls.cabal:1:1: error: 1024 | cabal-version should be at the beginning of the file starting with spec version 2.2. See https://github.com/haskell/cabal/issues/4899 1025 | 1026 | 1 | cabal-version: 3 1027 | | ^ 1028 | 1029 | A: This is a bug in cabal, use "3.0" instead of "3" in version. 1030 | 1031 | Q. I specified a flag using "--flag" and it is not working 1032 | 1033 | A: Spelling mistakes in flags are silently ignored. Be sure to specify the 1034 | correct flag. 1035 | 1036 | Q. Can I always specify a comment in cabal file using "--" 1037 | 1038 | A. No, only at the beginning of a line. 1039 | 1040 | Q: Can ``cabal`` report better errors? 1041 | 1042 | A: Yes. 1043 | 1044 | Quick References 1045 | ---------------- 1046 | 1047 | Installing: 1048 | 1049 | * `Haskell compiler installer (ghcup) page `_ 1050 | * `Haskell compiler (GHC) download page `_ 1051 | * `Haskel build tool (cabal) download page `_ 1052 | 1053 | Tool Guides: 1054 | 1055 | * `GHC user guide `_ 1056 | * `Haskell REPL (GHCi) user guide `_ 1057 | * `GHC package management guide `_ 1058 | * `cabal user guide `_ 1059 | * `File format and field descriptions `_ 1060 | * `Command line options `_ 1061 | * `Cabal handy reference `_ 1062 | 1063 | Package Repositories, Documentation, Search: 1064 | 1065 | * `Haskell package repository (Hackage) `_ 1066 | * `Stackage package snapshots `_ 1067 | * `Documentation by module on stackage `_ 1068 | * `Haskell Search Engine `_ 1069 | * https://hackage-search.serokell.io/ 1070 | 1071 | Packages: 1072 | 1073 | * `base: The Haskell standard library `_ 1074 | 1075 | * `Haskell Debug.Trace module `_ 1076 | * `Haskell Prelude module `_ 1077 | * `template-haskell: The Haskell macro system `_ 1078 | * `ghc-prim: Primitives provided by GHC `_ 1079 | * `GHC boot packages `_. 1080 | * `GHC version to GHC boot package version mapping `_ 1081 | 1082 | Resources: 1083 | 1084 | * `A curated list of awesome resources for the Haskell Cabal build tool. `_ 1085 | -------------------------------------------------------------------------------- /ghc-packages.md: -------------------------------------------------------------------------------- 1 | ## GHC Package Management 2 | 3 | When running `ghc` or `ghci` from command line you can only `import` 4 | Haskell packages that ghc knows about. Haskell Packages must be 5 | installed by a build tool, e.g. `cabal`, before ghc can use them. 6 | 7 | For quick resolution of any package related issues, when using `ghc` 8 | directly, you can use `ghc -v` to see how and from where GHC is loading 9 | its packages. Read the following paragraphs for a detailed explanation 10 | of package management in GHC to better understand how it works. 11 | 12 | ### Package Databases 13 | 14 | GHC can pick up packages from a `stack of package 15 | databases`. By default there are two databases known to GHC: 16 | 17 | * a `global` database at `/lib/ghc-/package.conf.d/` 18 | * a `user` database at `$HOME/.ghc/arch-os-version/package.conf.d` or on 19 | Windows at `C:\Documents And Settings\user\ghc\package.conf.d` 20 | 21 | The `GHC_PACKAGE_PATH` environment variable and several GHC command line 22 | options can be used to specify a custom stack of package databases. In 23 | addition, environment files can also be used to specify package 24 | databases. 25 | 26 | `ghc-pkg` is the utility shipped with `ghc` to create and manipulate package 27 | databases. Usually they are created by build tools. 28 | 29 | ### What's there in a package database? 30 | 31 | A package database directory e.g. 32 | `/lib/ghc-/package.conf.d/` consists of a 33 | number of `.conf` files or package description file, one for 34 | each installed package. A `.conf` file describes the package name, 35 | version etc. and where its binaries and interface files are installed. 36 | 37 | For example, 38 | `/lib/ghc-/package.conf.d/base-.conf` 39 | tells us that its static or dynamic lib binaries (`libHSbase-4.13.0.0.a`, 40 | `libHSbase-4.13.0.0-ghc8.8.2.dylib`) and interface files 41 | (`.hi`) of the modules exposed by `base` are installed in 42 | `/lib/ghc-/base-`. 43 | 44 | ### Which installed package will be used? 45 | 46 | Custom package databases can be created by build tools. Package 47 | databases can be described by package environment files or by 48 | `GHC_PACKAGE_PATH` or by GHC command line options. Note that package 49 | environment files are only available from GHC 8.2.1 onwards. 50 | 51 | GHC searches for package databases in the following order, first one is the 52 | highest preference: 53 | 54 | 1. `-package-env`, `-package-db` etc. command line options 55 | 2. `GHC_ENVIRONMENT` environment variable 56 | 3. `.ghc.environment.arch-os-version` in the current dir or in any parent dir 57 | 4. `$HOME/.ghc/arch-os-version/environments/default` 58 | 5. `GHC_PACKAGE_PATH` 59 | 6. default `user` (`$HOME/.ghc/arch-os-version/package.conf.d`) and 60 | `global` (`/lib/ghc-/package.conf.d/`) package 61 | databases 62 | 63 | `ghc -v` can tell in what order and which package databases GHC is 64 | loading and because of which configuration. If GHC is being invoked by 65 | a build tool like `cabal` then you may want to use the tool's verbosity 66 | option to see what command line options are being passed to GHC. You can 67 | also pass `-v` as an additional GHC option via the build tool to see 68 | what `ghc` is doing. 69 | 70 | Note that `ghc-pkg` does not use the environments files therefore the 71 | list of packages reported by `ghc-pkg list` may not contain the packages 72 | used by GHC. 73 | 74 | ### Where is my package installed? 75 | 76 | When you use `cabal update; cabal install streamly --lib` what happens? `cabal 77 | update` downloads the latest index of packages from `hackage`, the index can be 78 | found at `~/.cabal/packages/hackage.haskell.org/01-index.tar.gz`. 79 | 80 | `cabal install streamly --lib` downloads the source tarball of latest or 81 | requested version of `streamly` from hackage and places it in, say, 82 | `~/.cabal/packages/hackage.haskell.org/streamly/0.7.1/`. It then untars 83 | the source, builds it and installs the resulting binaries and interface 84 | files in, say, `~/.cabal/store/ghc-8.8.2/strmly-0.7.1-2409d7f6`. 85 | It then registers the package in its package database 86 | at `~/.cabal/store/ghc-8.8.2/package.db`, creating a 87 | `~/.cabal/store/ghc-8.8.2/package.db/strmly-0.7.1-2409d7f6.conf` file: 88 | 89 | ``` 90 | name: streamly 91 | version: 0.7.1 92 | visibility: public 93 | id: strmly-0.7.1-2409d7f6 94 | key: strmly-0.7.1-2409d7f6 95 | ... 96 | ``` 97 | 98 | We now have a package with a unique `package-id` `strmly-0.7.1-2409d7f6` in 99 | cabal's package db. cabal's package db is registered in GHC's default 100 | environment file found at `~/.ghc/x86_64-darwin-8.8.2/environments/default`: 101 | 102 | ``` 103 | clear-package-db 104 | global-package-db 105 | package-db /Users/harendra/.cabal/store/ghc-8.8.2/package.db 106 | ... 107 | package-id strmly-0.7.1-2409d7f6 108 | ``` 109 | 110 | `cabal install` also adds `package-id strmly-0.7.1-2409d7f6` in this 111 | file so that the package becomes available to GHC by default. Note that 112 | all the packages in cabal's package db are available to GHC but only 113 | those which are listed with a `package-id` entry are visible to it by 114 | default others remain hidden. Hidden packages can also be used by using 115 | an explicit `-package` flag on ghc command line. 116 | 117 | ### What all packages are available to me? 118 | 119 | You can list the packages in global and user package dbs using `ghc-pkg list`. 120 | However, there may be more custom package dbs being used via an environment 121 | file, e.g. in the previous section we saw the cabal package-db 122 | `/Users/harendra/.cabal/store/ghc-8.8.2/package.db` being used in the 123 | default environment file. We can list the packages available from this package 124 | db by using `ghc-pkg list --package-db 125 | /Users/harendra/.cabal/store/ghc-8.8.2/package.db`: 126 | 127 | ``` 128 | ... 129 | streamly-0.7.0 130 | streamly-0.7.1 131 | streamly-0.7.1 132 | ... 133 | ``` 134 | 135 | We see that there are multiple packages with the same name and version 136 | available. We can use `ghc-pkg list -v` to find out the package-ids: 137 | 138 | ``` 139 | ... 140 | streamly-0.7.0 (strmly-0.7.0-2235c7de) 141 | streamly-0.7.1 (strmly-0.7.1-2409d7f6) 142 | streamly-0.7.1 (strmly-0.7.1-56b85fb3) 143 | ... 144 | ``` 145 | 146 | ### Multiple instances of a package 147 | 148 | We can have multiple packages with the same name and even same version 149 | in the same package db but having different package-ids. 150 | 151 | We saw earlier that cabal created a package-id `strmly-0.7.1-2409d7f6` 152 | for streamly. The last part in that name is a hash to make the 153 | package-id unique. For example, we can have another instance of 154 | streamly-0.7.1 installed as package-id `strmly-0.7.1-56b85fb3`. 155 | 156 | Since only package-id has to be unique you may have multiple packages with the 157 | same name and even same version visible to ghc at the same time. Also, you may 158 | a module of the same name exposed by multiple different packages. In such cases 159 | when you import a module ghc cannot determine where to import it from. For 160 | example if you have the following entries in the environment file: 161 | 162 | ``` 163 | ... 164 | package-id strmly-0.7.0-2235c7de 165 | package-id strmly-0.7.1-56b85fb3 166 | ... 167 | ``` 168 | 169 | ``` 170 | $ ghci 171 | GHCi, version 8.8.2: https://www.haskell.org/ghc/ :? for help 172 | Loaded package environment from /Users/harendra/.ghc/x86_64-darwin-8.8.2/environments/default 173 | Prelude> import Streamly 174 | 175 | : error: 176 | Ambiguous module name ‘Streamly’: 177 | it was found in multiple packages: streamly-0.7.0 streamly-0.7.1 178 | Prelude> 179 | ``` 180 | 181 | ### Using packages by package-id 182 | 183 | Existence of multiple packages with the same name and version is not an 184 | issue, we can tell ghc which package-id to use, e.g.: 185 | 186 | ``` 187 | $ ghci -package-id strmly-0.7.1-56b85fb3 188 | GHCi, version 8.8.2: https://www.haskell.org/ghc/ :? for help 189 | Loaded package environment from /Users/harendra/.ghc/x86_64-darwin-8.8.2/environments/default 190 | Prelude> import Streamly 191 | Prelude Streamly> 192 | ``` 193 | 194 | ### Uninstalling a package 195 | 196 | We can remove the package with package-id `strmly-0.7.1-2409d7f6` from the 197 | previous example using: 198 | 199 | ``` 200 | $ ghc-pkg unregister strmly-0.7.1-2409d7f6 --ipid --package-db /Users/harendra/.cabal/store/ghc-8.8.2/package.db 201 | ``` 202 | 203 | We can see that `strmly-0.7.1-2409d7f6.conf` goes away after this command. But 204 | the installed package artifacts still remain in 205 | `~/.cabal/store/ghc-8.8.2/strmly-0.7.1-2409d7f6/`. We can remove it manually 206 | otherwise cabal will get confused when we try to install the package again. 207 | 208 | ### Renaming modules 209 | 210 | If module names exported by different packages conflict we can rename modules 211 | e.g. 212 | 213 | ``` 214 | $ cat rename.hs 215 | import qualified Streamly.Data.Fold as FL 216 | import qualified Streamly.Data.Stream as S 217 | 218 | main = do 219 | x <- S.fold FL.sum $ S.fromList [1..10] 220 | print x 221 | 222 | $ ghc -package "streamly (Streamly.Prelude as Streamly.Data.Stream)" rename.hs 223 | ``` 224 | 225 | ### Packages in Cabal Projects 226 | 227 | When building a project, build tools like `cabal` may install packages 228 | in a private `package database` and pass specific options to GHC to tell 229 | it where the packages are located. So the packages that are visible 230 | inside a project may not necessarily be available to `ghc` when invoked 231 | from command line outside the project and vice-versa. The details may 232 | depend on the specific build tool. 233 | 234 | Use `cabal build --write-ghc-environment-files=always` to write a 235 | `.ghc.environment.x86_64-darwin-8.8.2` file when cabal builds the 236 | project. If we use `always` this options needs to be used only once, cabal then 237 | remembers it in its global configuration and will always generate the 238 | environment file on each build. 239 | 240 | The environment file allows `ghc` to be be able to use all the 241 | package dependencies of the project when invoked from any directory 242 | within the project. This allows compilation of any .hs file within the 243 | project using `ghc` directly. 244 | 245 | If we look at the environment file we will see: 246 | 247 | ``` 248 | clear-package-db 249 | global-package-db 250 | package-db /Users/harendra/.cabal/store/ghc-8.8.2/package.db 251 | package-db dist-newstyle/packagedb/ghc-8.8.2 252 | ... 253 | package-id fusion-plugin-0.2.0-inplace 254 | package-id streamly-0.7.1-inplace 255 | ... 256 | ``` 257 | 258 | It contains cabal's global package-db 259 | `/Users/harendra/.cabal/store/ghc-8.8.2/package.db` and a project 260 | local package-db `dist-newstyle/packagedb/ghc-8.8.2`. It also lists 261 | package-ids of all the dependencies of the project. We can use 262 | `ghc-pkg list` to see the packages in these dbs. The local package-db 263 | contains all the source packages that are either defined within the 264 | project or specified in the cabal.project file under `packages` or 265 | `source-repository-package` stanzas. 266 | 267 | For more details on cabal projects see [cabal user 268 | guide](https://www.haskell.org/cabal/users-guide/) . 269 | 270 | ### Boot Packages 271 | 272 | GHC compiler code itself depends on a number of packages called `boot 273 | packages`. Some of these packages are automatically installed when you 274 | install `ghc`. `wired-in` packages are a subset of boot packages whose 275 | version is strictly determined by the ghc version e.g. `ghc-prim`, 276 | `base` and `template-haskell`. If you are using the GHC API i.e. the 277 | `ghc` package then it automatically constrains that the versions of 278 | boot packages used by the user package are the same as used by that GHC 279 | version. 280 | 281 | ### References 282 | 283 | See [GHC package database](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/packages.html) for more details on how GHC handles packages. 284 | -------------------------------------------------------------------------------- /install/ghcup.rst: -------------------------------------------------------------------------------- 1 | ghcup 2 | ----- 3 | 4 | ``ghcup`` installs the Glasgow Haskell Compiler from the official 5 | release channels, enabling you to easily switch between different 6 | versions. It maintains a self-contained ``~/.ghcup`` directory. 7 | 8 | Install 9 | ------- 10 | 11 | * Follow instructions at https://www.haskell.org/ghcup/ 12 | 13 | Help 14 | ---- 15 | 16 | :: 17 | 18 | $ ghcup --help 19 | 20 | Where is my stuff? 21 | ------------------ 22 | 23 | ``$HOME/.ghcup/bin`` contains: 24 | 25 | * ``ghcup`` to set current ghc version in `PATH`, to install/remove ghc versions 26 | * ``ghc`` to compile Haskell programs 27 | * ``cabal`` to install Haskell packages and build Haskell projects 28 | 29 | Your shell ``PATH`` is automatically setup by the installation script to 30 | find these, you can also use ``source $HOME/.ghcup/env`` to set it up 31 | any time. 32 | -------------------------------------------------------------------------------- /install/other.rst: -------------------------------------------------------------------------------- 1 | Basic install 2 | ------------- 3 | 4 | * Download ``ghc`` from https://www.haskell.org/ghc/download.html 5 | * Download ``cabal`` from https://www.haskell.org/cabal/download.html 6 | -------------------------------------------------------------------------------- /install/posix-via-shell.rst: -------------------------------------------------------------------------------- 1 | Install `ghc` and `cabal` on POSIX using Shell 2 | ============================================== 3 | 4 | The following example is for Debian 10, for other 5 | distributions replace the tar file (``.tar.xz``) URL below 6 | with an appropriate ``ghc`` tar image URL `from this page 7 | `_. 8 | 9 | Install ``ghc`` 10 | --------------- 11 | 12 | Install ``ghc`` version ``8.10.1`` under ``$HOME/.local/ghc/``:: 13 | 14 | $ mkdir -p $HOME/.local/ghc/installer 15 | $ cd $HOME/.local/ghc/installer 16 | $ wget https://downloads.haskell.org/~ghc/8.10.1/ghc-8.10.1-x86_64-deb10-linux.tar.xz | tar -Jxf 17 | $ cd ghc-8.10.1 18 | $ ./configure --prefix=$HOME/.local/ghc/8.10.1 19 | $ make install 20 | $ cd 21 | $ rm -rf $HOME/.local/ghc/installer 22 | 23 | Setup your shell to find the newly installed ``ghc``. For example, if 24 | you are using ``bash`` shell:: 25 | 26 | $ echo 'export PATH=$HOME/.local/ghc/8.10.1/bin' >> $HOME/.bash_profile 27 | $ source $HOME/.bash_profile 28 | 29 | Install ``cabal`` 30 | ----------------- 31 | 32 | Install ``cabal`` version 3.2 under ``$HOME/.local/bin/``:: 33 | 34 | $ mkdir -p $HOME/.local/bin 35 | $ wget -O - https://downloads.haskell.org/~cabal/cabal-install-3.2.0.0/cabal-install-3.2.0.0-x86_64-unknown-linux.tar.xz | tar -JOfx > $HOME/.local/bin 36 | 37 | Setup your shell to include ``$HOME/.local/bin/`` in your `PATH`. For example, 38 | if you are using ``bash``:: 39 | 40 | $ echo 'export PATH=$HOME/.local/bin' >> $HOME/.bash_profile 41 | $ source $HOME/.bash_profile 42 | --------------------------------------------------------------------------------