Make crystal more beginner friendly

[faustinoaq]

After seeing this Treehouse teacher trying to experiment with crystal I thought we can improve the way we show crystal to newcomers:

• Make linking errors more clear to the user or making packages like git, openssl recommended packages on installation guide see Treehouse video at 1:16:48 See Add explanatory message to linker command output on link failure #5486
• Make shards dependencies errors clear to the user (maybe a help message saying shard install), see Treehouse video at 1:21:46 See Suggest possible solutions to failing requires #5487
• Make crystal available on Windows 😉 see: Coordinate porting to Windows #5430
• With crystal foo.cr --flag, when --flag isn't found, mention "did you mean crystal foo.cr -- --flag" see 1:37:35
• Add a simple tutorial similar to the "create a shard" tutorial for apps. Doesn't have to be too deep.
• Make the crystal package depend on git, a cc (which should depend on a ld), and some more of the libraries required for stdlib linking as recommended deps, and openssl-devel, etc as suggested deps. In addition to the linking error improvements above.

/cc @bcardiff @fridgerator

Update (2017-11-15)

• Add ideas by @RX14

Update (2018-12-06)

• Change Windows issue to Coordinate porting to Windows #5430

[RX14]

Presumably cc @kennethlove too :)

I'd add a few things to this list too:

• With crystal foo.cr --flag, when --flag isn't found, mention "did you mean crystal foo.cr -- --flag"
• Add a simple tutorial similar to the "create a shard" tutorial for apps. Doesn't have to be too deep.
• Make the crystal package depend on git, a cc (which should depend on a ld), and some more of the libraries required for stdlib linking as recommended deps, and openssl-devel, etc as suggested deps. In addition to the linking error improvements above.

[Wulfklaue]

Several items that i see in the video are:

Missing system dependencies, for instance for Debian or Ubuntu you need:

Debian 9  ( Minimum server install with only SSH ): apt-get install apt-transport-https dirmngr libssl-dev gcc zlib1g-dev git
Ubuntu: sudo apt-get install libssl-dev git

Those are missing dependencies that came up before.

• libssl-dev only comes up if you try running the Crystal HTTP ( As it needs the SSL libs )

• apt-transport-https dirmngr zlib1g-dev are all required under Debian 9+ ( Minimum server install with only SSH ) for the Crystal installer to even work. The install documentation assumes these are all installed ( as they are under Ubuntu ) but by default they are not in the net-install Debian.

In any case, several of those packages are needed just for the https://crystal-lang.org/docs/installation/on_debian_and_ubuntu.html > https://dist.crystal-lang.org/apt/setup.sh to work properly. It wrong to assume these packages are default installed.

This is also clearly something the Treehouse youtube author ran into with the compiler linker errors.

• I think gcc was also used in Debian but it has been a few weeks from when i installed so not sure anymore. I wrote down all these missing packages at that time.

• Git ... well ... Shards... No git, error like the Treehouse youtube.

So technically its best to add the dependencies to the https://dist.crystal-lang.org/apt/setup.sh script. Will save people the trouble. Same with ensuring that git is installed.

[straight-shoota]

I'd add having a good tutorial for beginners to get started (see #4462).

@faustinoaq Maybe you could add the additional ideas with checkboxes to the initial post for Github to register them as sub-tasks.

@RX14 I don't think crystal should depend on git. You can use crystal perfectly fine without git, even shards does not necessarily need it (supposed you use only other sources). But it should probably be included in the default installer/installation instructions (recommended install).

And shards should actually provide a more detailed error message (Error missing git command line tool. Please install Git first!) if it can't find a git executable. I don't know why this wasn't the case in the screencast. The installed Crystal version is 0.22.0-1 which should come with shards 0.7.1 which includes the has_git_command check. @ysbaddaden any idea? (1:28:10 in the video)

[kennethlove]

I'm not a Crystal user (or even a Ruby user) but it's awesome to see a ticket aimed at making something more beginner-friendly.

I'd be interested in helping to produce a beginner tutorial if you'd like.

[faustinoaq]

Maybe you could add the additional ideas with checkboxes to the initial post for Github to register them as sub-tasks.

@straight-shoota done! 👍

[faustinoaq]

Add a simple tutorial similar to the "create a shard" tutorial for apps. Doesn't have to be too deep.

@RX14 Maybe we can update 👉 https://crystal-lang.org/docs/guides/writing_shards.html and put it at begining of documentation.

@kennethlove BTW, we have a Crystal Tools Organization inspired by Julia Editor Organization, we're even working on a Language Server Protocol for Crystal and we also have an extension for VSCode 😉

[hanyuone]

I think a nice addition to this would be to make errors post-compilation clearer, if possible, so something like this:

Error opening file 'resources/level1.json' with mode 'r': No such file or directory (Errno)
0x1063daea0: *raise<Errno>:NoReturn at ??
0x1063eb1c4: *File::new<String, String, Int32, Nil, Nil>:File at ??
0x1063fe816: ~procProc(Nil)@src/mirrors/display/start_display.cr:18 at ??
0x1063d8ca1: __crystal_main at ??
0x1063fcda1: main at ??

could be more intuitive. It takes a while to tell what the error is at first glance, since the first line is formatted exactly the same as the other lines, and doesn't stand out.

Maybe we could format these lines using ANSI escape codes for Unix systems, and get rid of the memory signatures at the front, as well as the at ?? at the back (since it's the same for every line of the error), and don't really give much information. Maybe we can provide a simplified UI for normal compilation, with fancy formatting and all, and we can provide an optional flag for people who want to see error logs such as this?

[bew]

@Qwerp-Derp you might want to look at #4968

[RX14]

In an ideal world crystal and shards would be seperate packages, and shards would have a recommended dep of git (which means it will install git unless you use --no-install-recommends for apt).

[jeff-hykin]

I'm still learning the codebase, but I'd be happy to try to manually make errors more readable/user friendly.

Just an idea (feel free to tell me why this won't work), when errors are thrown, could they include a URL to a web page dedicated to that error? The link could be to GitHub, Stack Overflow, or (preferably) a custom site. This would essentially crowd source: what causes the error, what the error actually means, and how to potentially fix it, instead of just asking Crystal codebase devs to spend their time writing better error messages.

I know the first thing I do with cant-fix-myself confusing errors is copy paste search. Often after hours of digging through poorly worded forums and Q&A sites, I end up either making a work around or reverting back to Python or JavaScript to do whatever it is I'm trying to do. Since Crystal (and most languages) don't have a Python-or-JavaScript-sized Q&A base, it would be nice to have an official place where either A. There is already an answer or B. It's clear there is no answer yet. Users probably wouldn't re-ask as many questions, answers could be found consistently and quickly (instead of using intuition and hours of Google searches), and (based on the number of visits/clicks) Crystal codebase devs could really track what the most confusing errors were.

I'm not saying build a whole custom Stack Overflow site, it could literally just be a public Slack community. Just so long as it's an official place linked to specific errors, and made obvious to new Crystal users.

[refi64]

I mean, IMO Crystal's errors are pretty good for a compiled language, though I get what you're saying...

I want to say Google Groups could work, but the UI is ugly as hell, and the mobile site is an abomination. IIRC you can't link to specific messages with Slack, so that's out of the question...

Maybe a separate GitHub repo could work? e.g. crystal-lang/help. It would have easy permalinking, and we get an already built nice UI and such.

[hanyuone]

@jeff-hykin @kirbyfan64 Why not a GitBook? I think we can create a separate GitBook from Crystal's default one and dedicate it to various errors.

[RX14]

Why not the same gitbook even? Also, i'm not sure how we would manage the error linking on the compiler side.

[bcardiff]

I definitely like the ideas listed in the top of this issue.

On a pragmatic side, I would prefer if the crystal apt package ensures that the top used libraries are there. And leave another smaller package for other setups.

Regarding the errors offered by a compiler, I would prefer an approach that works offline. The challenge is to guess the intention of the user in order to offer a suggestion. I like how elm has a repo where all the compiler errors are triggered in examples and were discussed / improved in a case by case basis.

Improving some error messages could mean adding knowledge to the compiler of not referenced part of the standard library or gems. This is a slippery slope.

Ref: compiler errors for humans

[RX14]

@bcardiff I made the debian packages produced by my "new" omnibus depend on openssl etc.

[jeff-hykin]

@RX14
I think the GitBook would work well.

In terms of linking, if you mean linking as in C++ style preprocessor-compiler-linker I won't be be able to give much insight. But linking URLs to exceptions, whenever an exception is displayed (not caught) the handler could check the GitBook or a locally cached index of the GitBook to see if an entry exists for that exception. If a an entry exist, show the link/URL for it. If there isn't an entry, then generate an entry/URL (or whatever behavior is preferred).

This type of behavior would be really flexible for new tools/exceptions.

Obviously the generic exceptions (think C's seg fault) are not going to be super useful, but they'd definitely be better than nothing for new users.

[jeff-hykin]

@bcardiff
Do you think a locally cached version of the GitBook would work for offline use?

I agree with you the elm examples are great.

I'm not sure exactly what you mean about the slippery slope though.

[bcardiff]

@jeff-hykin I don't think a cached version of an online resource would work. I would prefer noting more complicated than showing a plain text description 👴 . I enjoy to be able to program 100% offline. It also a guarantee that older versions of the compiler can be used without keeping external infrastructure.

For the slippery slope I mean some like:

1. User mention in the code HTTP::Server.new(8080) but forgets the require.
2. Someone suggest that if HTTP::Server is not found, to be more friendlier the compiler suggest as error message to include require "http/server".

For this the compiler knows about something that is not in the prelude, but at least today inside the stdlib. But then, if the constant DB is not found, should the compiler know that can be probably fixed by including crystal-db? Should the limit be shards in this organization?

[paulcsmith]

I think linking to an external resource might be helpful, but it should be for "more info" or something. Preferably most cases should be handled in plain text so the user doesn't even need to leave the terminal.

I think there are cases where that would be hard to do though. For example, instance vars and checking types. I think that is very hard to explain, so it might make sense to have a short message in the terminal, but a link to gitbook or somewhere else that explains things a bit more.

I have a few ideas for better errors, including what they should look like. I don't know if I have the skills to implement it myself, but if it would be helpful I can open an issue with the ideas and some screenshots of what I think errors could look like

[jeff-hykin]

I agree @paulcsmith. That's how I originally intended it, a plaintext error (like normal) that also includes a URL, but I probably didn't do a great job of making that clear. I definitely wouldn't want errors auto-opening a web browser or trying to auto displaying web-data into the terminal. The auto generation of URLs would just be when the user tried to follow the "more info" link, but there wasn't actually GitBook entry for the error.

@bcardiff This will probably clear up the offline stuff we were talking about.

[RX14]

I've implemented 1 and 2 in #5486 and #5487.

[beta-ziliani]

Most of the stuff is covered already, we're only missing git as dependency in the packages.