Adding a getting started tutorial describing the core GHC tools #88
Conversation
|
Thanks! In case you don't know you can find a built artifact at https://github.com/haskell-infra/www.haskell.org/actions/workflows/main.yml which will show everyone what your changes look like. |
There was a problem hiding this comment.
Thanks for the PR! Having more documentation like this will be incredibly valuable.
I think there are a few opportunities for cleanup here that could make this a lot more accessible. I made some specific notes in the PR, but more broadly:
I don't see where this is linked from the rest of the site- do we want to add a link to the top-level documentation page to this so users can find it, or will we open up this later along with other articles?
I am having a hard time figuring out who the audience is for this article. Early on it addresses a reader who has seemingly never used haskell before at all, but at the end of the article it starts talking about RTS options and profiling. I don't think the same people are going to benefit from both of those things at the same time, so I think we'd be better off breaking that up.
| isDocumentation: true | ||
| --- | ||
|
|
||
| # Learn about the core tools |
There was a problem hiding this comment.
Given the audience for this article, I wonder if we wouldn't be better to actually pick an installation method and walk through it to start with (or we can have that as another article and link back to it). I know that picking a single installation method will be controversial, but it seems like this document is suffering a lot from the lack of being able to assume a specific configuration.
There was a problem hiding this comment.
Thank you for the review!
How do you feel this document is suffering from a lack of being able to assume a specific configuration? Apart from the note below ("if you installed your ...") I don't see any issues (except for one section you mentioned and I will reply there) - the document acts as if the user has ghc, runghc and ghci installed.
There was a problem hiding this comment.
The main thing is that I think the prose sometimes becomes a bit hard to follow because of the need to talk around multiple setups. Being able to say: "Type xyz into your terminal" is a powerful thing in terms of making the tutorial easy for people to follow. As a secondary issue, I think if we're aiming this at early beginners, the fact that there are many choices is going to be overwhelming to them.
There was a problem hiding this comment.
I think I could understand better if you could please mention places where you think the prose becomes a bit hard to follow and could be improved.
I don't quite understand because except for one instance (using packages) this tutorial does not talk about multiple setups. And it does not asks the users to make choices.
There was a problem hiding this comment.
@rebeccaskinner I believe installation instructions have no place here, that's what https://www.haskell.org/downloads/ is for
| with the Haskell toolchain, namely, `ghc`, `runghc` and `ghci`. | ||
| These tools can be used to compile, interpret or explore Haskell programs. | ||
|
|
||
| Note: if you installed your Haskell toolchain using the stack tool only |
There was a problem hiding this comment.
See above, while I think this note is perfectly reasonable if we're not making assumptions about how things are installed, I think it would be a much better document if we just assumed an installation method.
|
|
||
| GHC created the following files: | ||
|
|
||
| 1. `hello.hi` - Haskell interface file, we won't discuss that in this article |
There was a problem hiding this comment.
If we're not going to talk about the hi and o files, maybe we shouldn't bring them up here? Perhaps something like "When we compile the application, GHC will dutifully creating our new executable, hello (or hello.exe on windows). You may notice a couple of other files that get generated too, but we won't worry about them in this tutorial."
There was a problem hiding this comment.
I would like to hear more opinions on this, I think this is a reasonable change, but I also think that this bit of information is enough to make the user say "oh, ok." and carry on without thinking much about it, and without us brushing this information under the table.
There was a problem hiding this comment.
I'm fine with listing the aux files as it is done now. I don't see harm either way really but prefer a little precision here.
core-tools.markdown
Outdated
| GHC will produce an executable when the source file: | ||
|
|
||
| 1. Defines the binding `main` in the source file | ||
| 2. Defines the module name to be `Main` (this can be done by adding `module Main where` at the top of the file), or does not have a module declaration (which is then inferred as the module `Main`). |
There was a problem hiding this comment.
I wonder if we might not want to include the module in initial hello world example too, rather than mentioning it here for the first time.
There was a problem hiding this comment.
Same, I'm also very tempted at having the hello world program a one-liner. I will go with whatever you think is better.
There was a problem hiding this comment.
We can use :
$ ghc -e 'putStrLn "hello world!"'
hello world!for a one-liner
There was a problem hiding this comment.
I don't think one-liner is the goal though :) should we even cover -e at all? I've never used it myself. I would rather just pick whether to use a module definition or not.
|
|
||
| A more thorough introduction to GHCi can be found in the [GHC user guide](https://downloads.haskell.org/~ghc/9.0.1/docs/html/users_guide/ghci.html). | ||
|
|
||
| ### Using external packages in ghci |
There was a problem hiding this comment.
Again I wonder if we should maybe just presume one of cabal or stack and stick with it for the tutorial rather than trying to show it both ways.
There was a problem hiding this comment.
In this case I disagree for the following reasons:
- I would really prefer one unifying document that will work for both stack and cabal users so that all learning resources could just point to it
- By not picking a blessed option we are showing that both options are good
- The different between the two options is very minimal, so I think it is worth "the price"
- I don't want to pick cabal because then this tutorial is not useful for me - who use stack and suggest others to use stack
- I don't want to pick stack because cabal users should have this information easily available as well
There was a problem hiding this comment.
Agreed, this is the opportunity to unify an approach to both Cabal & Stack.
There was a problem hiding this comment.
My 5c: it is really annoying to have to jump over every other sentence in a section because it mentions "the other" tool that I don't use. Please, don't do that. I really hope that this page, if it covers both tools, does this in separate (sub)sections even if these sections are small.
There was a problem hiding this comment.
I don't think you'll experience such annoyances in this article because this happens exactly once in the article in an extremely tiny section. I'm open to seeing an alternative presentation of the information though.
There was a problem hiding this comment.
It doesn't happen exactly once unfortunately: lines 13, 231, 258 all introduce tool-related topics. After reading the whole document I don't have better suggestions though, so I'd leave it as it is probably but add the cabal-related solution to the issue raised on line 258 (see my comment there).
There was a problem hiding this comment.
Thanks for the review!
I don't see where this is linked from the rest of the site- do we want to add a link to the top-level documentation page to this so users can find it, or will we open up this later along with other articles?
I talked to @Kleidukos about this as well and I am not sure where this document should be linked, the ideas we had are from the download page, the documentation page (thought it is in a dire need of revamp), a new getting started page that could be made or even school.haskell.org. I don't know what is the right place and would like to open this for discussion.
I am having a hard time figuring out who the audience is for this article. Early on it addresses a reader who has seemingly never used haskell before at all, but at the end of the article it starts talking about RTS options and profiling. I don't think the same people are going to benefit from both of those things at the same time, so I think we'd be better off breaking that up.
The audience are indeed readers who have never used Haskell before, but I think it is a good opportunity to also cater to a larger portion of Haskell users by including a slightly more advanced (but still quite common) usage section that unfortunately (to my eyes, I may be mistaken) just isn't very well known/covered by other popular material, so I wanted to "save the trouble" of looking it up .
Basically what I wanted to say is "hey new user, when you are ready, you can find information about these very common things here". This might not be the best way to do it and I can remove this section if you think it's better.
Perhaps a simple sentence such as "The GHC manual contains more useful information on how to control the Haskell runtime and how to profile Haskell programs" would suffice.
| isDocumentation: true | ||
| --- | ||
|
|
||
| # Learn about the core tools |
There was a problem hiding this comment.
Thank you for the review!
How do you feel this document is suffering from a lack of being able to assume a specific configuration? Apart from the note below ("if you installed your ...") I don't see any issues (except for one section you mentioned and I will reply there) - the document acts as if the user has ghc, runghc and ghci installed.
| with the Haskell toolchain, namely, `ghc`, `runghc` and `ghci`. | ||
| These tools can be used to compile, interpret or explore Haskell programs. | ||
|
|
||
| Note: if you installed your Haskell toolchain using the stack tool only |
|
|
||
| GHC created the following files: | ||
|
|
||
| 1. `hello.hi` - Haskell interface file, we won't discuss that in this article |
There was a problem hiding this comment.
I would like to hear more opinions on this, I think this is a reasonable change, but I also think that this bit of information is enough to make the user say "oh, ok." and carry on without thinking much about it, and without us brushing this information under the table.
core-tools.markdown
Outdated
| GHC will produce an executable when the source file: | ||
|
|
||
| 1. Defines the binding `main` in the source file | ||
| 2. Defines the module name to be `Main` (this can be done by adding `module Main where` at the top of the file), or does not have a module declaration (which is then inferred as the module `Main`). |
There was a problem hiding this comment.
Same, I'm also very tempted at having the hello world program a one-liner. I will go with whatever you think is better.
|
|
||
| A more thorough introduction to GHCi can be found in the [GHC user guide](https://downloads.haskell.org/~ghc/9.0.1/docs/html/users_guide/ghci.html). | ||
|
|
||
| ### Using external packages in ghci |
There was a problem hiding this comment.
In this case I disagree for the following reasons:
- I would really prefer one unifying document that will work for both stack and cabal users so that all learning resources could just point to it
- By not picking a blessed option we are showing that both options are good
- The different between the two options is very minimal, so I think it is worth "the price"
- I don't want to pick cabal because then this tutorial is not useful for me - who use stack and suggest others to use stack
- I don't want to pick stack because cabal users should have this information easily available as well
|
Regarding the RTS page, maybe a one-page lesson on the Haskell School would do the job better than a one-paragraph overview? |
My main issue is discoverability of the content - this page has the opportunity to be view by most new Haskell users, so if we think this information is important in this context we should link to it from here. It could live in either Haskell School or GHC manual or a different article |
|
|
||
| GHC created the following files: | ||
|
|
||
| 1. `hello.hi` - Haskell interface file, we won't discuss that in this article |
There was a problem hiding this comment.
I'm fine with listing the aux files as it is done now. I don't see harm either way really but prefer a little precision here.
core-tools.markdown
Outdated
|
|
||
| #### Optimisations | ||
|
|
||
| Another very useful flag is `-O`. This flag asks GHC to compile the program with optimisations and code improvements at the cost of taking longer to compile. |
There was a problem hiding this comment.
Is there a convention about prefferred line width? I'd prefer to have something more consistent inside one file at least.
There was a problem hiding this comment.
I can work with whatever convention is required
|
|
||
| A more thorough introduction to GHCi can be found in the [GHC user guide](https://downloads.haskell.org/~ghc/9.0.1/docs/html/users_guide/ghci.html). | ||
|
|
||
| ### Using external packages in ghci |
There was a problem hiding this comment.
It doesn't happen exactly once unfortunately: lines 13, 231, 258 all introduce tool-related topics. After reading the whole document I don't have better suggestions though, so I'd leave it as it is probably but add the cabal-related solution to the issue raised on line 258 (see my comment there).
|
I've:
Updated tutorial render is available in the same link. |
|
Where should the link to this document go? A few ideas are:
|
|
Yes, I think this should be linked from the downloads page... however... for me it's missing a big section (which is currently not covered by the downloads page either), which is: explaining the difference of cabal and stack. And possible giving guidance as to which tool to choose. That's the main thing missing from the downloads page (and it shouldn't be there). Maybe it's out of scope of this PR, but we do need it. |
|
I think the issues we still need a resolution for in this PR are:
Is there anything I missed? |
|
Sorry I haven't been able to look at this yet. I will do so as soon as I get the opportunity. |
core-tools.markdown
Outdated
| If you'd like to learn more about them, | ||
| [the GHC manual](This article describes the most common usage of the core tools) | ||
| Contains additional information on how to use the tools, including how to control | ||
| the runtime system and how to profile Haskell programs. |
There was a problem hiding this comment.
Something funny is going on here
There was a problem hiding this comment.
More precisely, the markdown notation is inverted
There was a problem hiding this comment.
whoops. thank you - should be fixed now.
|
I think the content is looking better here with the edits. There are two major questions that are still standing out in my mind: The first is the more immediate question of who our target reader is for this. It seems to be written for a new user who is just getting started with haskell, but I'm having a hard time picturing a scenario where a user who is just getting started is going to interact with ghc this directly. I'm open to the idea that I might be wrong here, but it seems to me that most users are going to install stack or cabal and just do everything through there- and in general I'd think that's probably what we'd want to encourage for the most part. I hope this isn't taken to mean that this or similar documentation aren't needed- I think it's really good that we're starting to look at this, I just want to be very mindful of ensuring that we have a very clear set of users in mind with the docs that we write, and understand how the docs help them on their journey to learn and use haskell effectively. The second question is a bit less immediate, but I'd like to understand where we're going with this stuff in general. Is this just one additional document that we want to have to supplement the information on the downloads page, or is it part of some larger work that we need to consider? In either case I think we need to figure out how we want to link to it and where it's going to live. |
|
In my experience, a lot of new users want to just learn the language, which means interacting with ghci, and compiling simple example executables, without starting a project or introducing any external deps at all. This especially holds in many classroom settings. |
|
When I started, I spent some time just using a REPL and then started using |
|
@rebeccaskinner this is an interesting point. In my opinion for anything that has less than a few package dependencies, using For example, a learner that wants to create a guessing game can just use or similar to run their program without having to figure out anything else. In my opinion this lowers the barrier of entry. But I also understand your opinion saying that using stack/cabal is inevitable for larger programs so this article might not be useful. This is really up to you to decide whether this is the right content to have on haskell.org and whatever you decide is fine with me.
I definitely support this conversation. cc @Kleidukos |
Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
Fix external packages usage and add cabal instructions
|
I think it would be good to have a meeting between the Haskell.org committee and the documentation task force to brainstorm the best way for Haskell.org to host great documentation for Haskell! |
|
On my end, I have become a stakeholder in this effort because the first lesson of Haskell School will require the reader to have a basic understand of how to use ghci/cabal/stack for simple snippets of code (that may depend on external dependencies like containers or text). I definitely agree that a call is warranted so that we can synchronise our clocks. @tomjaguarpaw Can I let you come back to me once you know who from the h.org committee would like to participate in the call? |
|
OK, I will take care of arranging that on the Haskell.org end. |
|
ping |
| in the current directory using this command: | ||
|
|
||
| ```sh | ||
| cabal install --lib async say --package-env . |
There was a problem hiding this comment.
cabal install --lib adds stuff to the default environment, which can cause very confusing build errors later when building projects. I'd advise to not mention it at all.
Instead, use cabal repl --build-depends async.
There was a problem hiding this comment.
@hasufell that's not totally correct: the command as was written worked just fine and didn't touch the global environment. That's because of the --package-env . part. I'd vote for putting it back. But up to you guys.
There was a problem hiding this comment.
@ulysses4ever Thanks, I overlooked that.
There was a problem hiding this comment.
I see you both agree that this is actually ok, so I'll revert the change.
There was a problem hiding this comment.
I also double-checked that preceding text tries to explain what's happening in a nutshell. But maybe Julian has a point here and it would make sense to add a warning (after the command):
(Warning: the command may work without the
--package-env .part but in that case it will use the global environment instead of the local one. This is known to lead to complicated problems in some cases and discouraged.)
Of course, the warning itself may sound too confusing for a novice, as well as simply extending the text that we'd like to keep short, so I am not 100% sure.
There was a problem hiding this comment.
I'd like avoid these kind of warnings in this text. I also don't think it's relevant because the specific command we teach isn't problematic. If users want to experiment with different commands than what we show they will have to figure it out from other texts.
|
@soupi would it be possible to post a comment about why this was closed? |
After several months of no response/indication of progress, this PR doesn't feel like it's going to get merged, so I'm closing it to take it off my plate. |
|
I'm not part of the haskell.org committee, so I cannot approve. Sorry. |
|
@soupi fair enough, thank you for the answer and for your work. |
|
Well hopefully @Kleidukos can get this merged into the school of haskell work? |
|
I'd rather hear from @tomjaguarpaw since he said he would arrange it on the Haskell Committee end, before doing anything on my own without coordination from one of the stakeholders. |
|
@Kleidukos I mean, this PR was just closed in this repo because the submitter gave up on getting it merged here. So I would hope the work can be adopted elsewhere if its not going here. |
|
If @soupi allows it, I would like to petition the Haskell.org Committee to adopt this work and bring it to fruition. |
|
Sorry if you were waiting for me on this. I don't have any news but I'll bring it to the attention of the committee. |
|
After having raised this with committee, our decision is that we would love to link to the School of Haskell (including the article in this PR) or perhaps indeed host the School of Haskell under haskell.org in due course. However, this one article feels like it would be out of place on haskell.org, without putting it in the additional context of the Haskell school. Speaking personally, it seems to me that changes to haskell.org beyond the level of "minor" are slow to make for historical reasons, party to do with fear of reopening old controversies. I am optimistic that the situation will slowly improve over time. In the meantime I suggest that bold new web content start its life somewhere off haskell.org and we aim to bring it onto haskell.org once the community has had the opportunity to see its value. |
I'm confused by this. school of haskell is discontinued and is read-only. https://school.haskell.org/ points nowhere and https://github.com/haskellfoundation/HaskellSchool gives no information about where it is hosted either. If someone does host it, there seems to be an issue with discoverability. |
|
Perhaps @Kleidukos can provide an update of School of Haskell. |
|
I've used this PR and added it to the ghcup homepage, simplifying some sections and adding another section about cabal project creation: https://www.haskell.org/ghcup/steps/ |
|
Hi, indeed Haskell School isn't being hosted anywhere. |
@Kleidukos
This PR adds a tutorial describing the core GHC tools. It covers common usage of
ghc,runghcandghcias well as slightly more advanced usage, and linking to the GHC manual where appropriate.This page can be used as a first step towards a getting started guide and can be linked from the documentation or downloads pages.
Similar ideas have been previously requested here.
Rendered