Added get-started page. #227
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,118 @@ | ||||||||
| --- | ||||||||
| title: Get Started | ||||||||
| page: get-started | ||||||||
| isGettingStarted: true | ||||||||
| --- | ||||||||
|
|
||||||||
| # Get started | ||||||||
|
|
||||||||
| Welcome, new Haskeller! Read on to quickly set up your Haskell development environment, execute your first lines of code, and get directions for further learning. | ||||||||
|
|
||||||||
| ## Content | ||||||||
| - [Set up a Haskell development environment](#set-up-a-haskell-development-environment) | ||||||||
| - [GHCup: universal installer](#ghcup-universal-installer) | ||||||||
| - [Editor](#editor) | ||||||||
| - [Running your first lines of code](#running-your-first-lines-of-code) | ||||||||
| - [Writing your first Haskell program](#writing-your-first-haskell-program) | ||||||||
| - [Participate in the community](#participate-in-the-community) | ||||||||
| - [Next steps](#next-steps) | ||||||||
|
|
||||||||
| ## Set up a Haskell development environment | ||||||||
|
|
||||||||
| A complete Haskell development environment consists of the Haskell toolchain (compiler, language server, build tool) and an editor with good Haskell support. The quickest way to get this set up is to: | ||||||||
|
|
||||||||
| 1. Use **GHCup** to install and manage the Haskell toolchain. | ||||||||
| 2. Use [**VSCode**](https://code.visualstudio.com/) as the editor, with the Haskell extension installed. | ||||||||
|
There was a problem hiding this comment. How would you feel about linking to the free VSCodium builds instead of the non-free version? There was a problem hiding this comment. I understand the motivation, but I don't think that is beneficial for the goal of reducing friction to get new people to learn Haskell. Those that care about open source will probably reach out vscodium anyway, while for those that don't, this probably isn't the best moment to introduce it -> we are already introducing Haskell which is complex enough. If this will be a stopper for merging, I can change it to VSCodium, but I think it sends the wrong message to newcomers to Haskell. |
||||||||
|
|
||||||||
| ### GHCup: universal installer | ||||||||
|
|
||||||||
| [GHCup](https://www.haskell.org/ghcup/#) is a universal installer for Haskell that will install everything you need to program in Haskell, and will help you manage those installations (update, switch versions, ...). Follow the instructions on the [GHCup webpage](https://www.haskell.org/ghcup/#) to install GHCup. Then use it to install the Haskell toolchain, which consists of: | ||||||||
|
|
||||||||
| 1. **GHC** (The Haskell compiler) We will use GHC below to run our examples, but in practice you will mostly use a tool like Cabal or Stack to build your code, instead of GHC directly. | ||||||||
| 2. **HLS** (The Haskell Language Server) You won't use HLS directly, instead your code editor will use it in the background to provide you with a great experience while editing Haskell code. | ||||||||
| 3. **Cabal** (A Haskell build tool) You will use Cabal to structure your Haskell projects, build them, run them, define dependencies, ... . | ||||||||
| 4. **Stack** (A Haskell build tool) An alternative to Cabal. | ||||||||
|
|
||||||||
|
|
||||||||
| <div class="bs-callout bs-callout-info"> | ||||||||
| <p> | ||||||||
| <h4>Cabal and Stack: which one should I install?</h4> | ||||||||
| We recommend installing both. Most Haskell projects can be built using Cabal, but some might require Stack. Installing both guarantees that you can use either, and while following a tutorial or book you can use whatever they recommend. | ||||||||
| </p> | ||||||||
| </div> | ||||||||
|
|
||||||||
| ### Editor | ||||||||
| [**Visual Studio Code**](https://code.visualstudio.com/) ([**VSCode**](https://code.visualstudio.com/)) is a popular choice with well-supported Haskell integration. Install the [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell) and you are all set. It should work out of the box and use your installation of HLS. To learn about support for other editors, check out [HLS docs for editor configuration](https://haskell-language-server.readthedocs.io/en/latest/configuration.html#configuring-your-editor). | ||||||||
|
|
||||||||
| ## Running your first lines of code | ||||||||
|
There was a problem hiding this comment. I wonder if we could bring the interactive tutorial over from the main page to here to make some of this a bit more interactive? There was a problem hiding this comment. I think that's probably worth delaying to a separate PR. There was a problem hiding this comment. That is interesting idea! I was considering a bit what to do with it, since it feels like right now we have two CTAs on landing page -> one is "Get Started" button, second is "Try it" prompt. Ideally there would be just one. But, if we would try to include it in the get-started page, I think it would side track us -> on get-started we are getting them to install tooling, and then we want them to use what they installed and try haskell through that, so when they are done with the get-started page, they have everything installed and have an idea how to use it -> they now feel ready to play with Haskell on their machine and had their first victory. So at the moment I don't have a good idea how to plug in Try It into get-started. One option might be to remove it from landing page, but that does feel a bit bad since it is so cool. So I would probably just leave it for the time being, I don't think it hurts. |
||||||||
|
|
||||||||
| We have everything set up, let's use it! The Haskell compiler, GHC, comes with an interactive interpreter called GHCi which is great for playing with Haskell and trying things out, so let's give it a spin. Run `ghci` at your command prompt, which will start a new GHCi prompt for you. Let's do a simple calculation to check Haskell's computing capabilities: | ||||||||
| ``` | ||||||||
| > 6 + 3^2 * 4 | ||||||||
| 42 | ||||||||
| ``` | ||||||||
|
|
||||||||
| 42 is a nice even number, but what about the first 10 even numbers after it? | ||||||||
| ``` | ||||||||
| > take 10 (filter even [43..]) | ||||||||
| [44,46,48,50,52,54,56,58,60,62] | ||||||||
| ``` | ||||||||
|
|
||||||||
| What is the sum of those? | ||||||||
| ``` | ||||||||
| > sum it | ||||||||
| 530 | ||||||||
| ``` | ||||||||
| **NOTE**: We used a special feature of GHCi here, which is a special `it` variable that remembers the result of the last expression. | ||||||||
|
|
||||||||
| Great, you got the first taste of Haskell! Now let's get to running a real program. | ||||||||
|
|
||||||||
| ## Writing your first Haskell program | ||||||||
|
|
||||||||
| In your editor, create a new file named `hello.hs`. Write the following in it: | ||||||||
|
There was a problem hiding this comment. Just nit-picking here, but it's unusual for There was a problem hiding this comment. @aaronallen8455 Actually, the GHC guide uses the same example: There was a problem hiding this comment. Yes, and I understand why - so that the resulting executable has the desired name. It just bothers me slightly that it diverges from the conventional naming pattern for There was a problem hiding this comment. We'd see more lowercase There was a problem hiding this comment. We can do whatever you like here, I don't mind. I think |
||||||||
| ```hs | ||||||||
| main = do | ||||||||
|
There was a problem hiding this comment.
Suggested change
Not only is it best practice to give type signatures to top level bindings, but I feel like types should make an appearance somehow, since it's such a core part of the language. There was a problem hiding this comment. That is a good point, but I don't think So I am soemwhat for showing off types, if we can do it in an easy way, but I don't think this example with IO would fall under that. |
||||||||
| putStrLn "Hello, everybody!" | ||||||||
| putStrLn ("Please look at my favorite odd numbers: " ++ show (filter odd [10..20])) | ||||||||
| ``` | ||||||||
|
|
||||||||
| You can now compile it with `ghc` to produce an executable called `hello` that we will then run: | ||||||||
| ``` | ||||||||
| > ghc hello.hs | ||||||||
| > ./hello | ||||||||
| Hello, everybody! | ||||||||
| Please look at my favorite odd numbers: [11,13,15,17,19] | ||||||||
| ``` | ||||||||
|
|
||||||||
| There you go, you just wrote a short, polite program in Haskell! | ||||||||
|
|
||||||||
| **GHCI TIP**: You can also load your file directly into `ghci`, which will enable you to play with any functions and other definitions you defined in it. So for our example, we can just load `hello.hs` with GHCi and then call the function `main` like this: | ||||||||
| ``` | ||||||||
| > ghci hello.hs | ||||||||
| GHCi, version 8.10.7: https://www.haskell.org/ghc/ :? for help | ||||||||
| [1 of 1] Compiling Main ( hello.hs, interpreted ) | ||||||||
| Ok, one module loaded. | ||||||||
| > main | ||||||||
| Hello, everybody! | ||||||||
| Please look at my favorite odd numbers: [11,13,15,17,19] | ||||||||
| ``` | ||||||||
|
|
||||||||
| ## Participate in the community | ||||||||
|
|
||||||||
| By participating in the Haskell community you be able to ask for help and learn about new developments in the Haskell ecosystem. Some of the most popular places to interact with the community are: | ||||||||
|
|
||||||||
| - [Haskell Discourse](https://discourse.haskell.org/) | ||||||||
| - [Haskell subreddit](https://www.reddit.com/r/haskell/) | ||||||||
| - [https://wiki.haskell.org/IRC_channel](https://wiki.haskell.org/IRC_channel) | ||||||||
|
|
||||||||
| We recommend joining right now, and don't be shy to ask for help! Check [https://www.haskell.org/community](https://www.haskell.org/community) for a full list of resources relating to the Haskell community. | ||||||||
|
|
||||||||
| ## Next steps | ||||||||
|
There was a problem hiding this comment. I'm not entirely sure about this particular list of resources, but I like the general idea of picking a couple of free resources as a starting point. There was a problem hiding this comment. We can discuss it, we had a bit of conversation on it here on the PR and ended up with this. I am big fan of LYAH (even though it is somewhat outdated), and also like the new book with building static blog generator, think they are very accessible and practical. I don't know much about the materials from the uni that we listed but they were on top of course list of Documentation page on haskell.org . |
||||||||
|
|
||||||||
| Popular free learning resources for beginners: | ||||||||
|
|
||||||||
| - [Introductory Haskell course of the University of Pennsylvania (CIS194)](https://www.seas.upenn.edu/~cis1940/spring13/lectures.html) (course) | ||||||||
| - [Learn You a Haskell for Great Good!](http://learnyouahaskell.com/) (book) | ||||||||
| - [Learn Haskell by building a blog generator](https://lhbg-book.link) (book) | ||||||||
|
|
||||||||
| This is just the tip of the iceberg though: check [Documentation](https://www.haskell.org/documentation/) for a bigger list of learning resources. That is it, fellow Haskeller! Enjoy learning Haskell, do (not?) be lazy and see you in the community! | ||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like the phrasing here. "Welcome, new Haskller!" is a great intro.