Add Crystal.main

[asterite]

Fixes #4793
Closes #4793

Please read the doc comments in the commit.

As an example, to implement what is needed in #4793 one can now write:

@[Link("allegro")]
lib LibAllegro
  fun al_run_main(argc : LibC::Int, argv : LibC::Char**, user_main : (LibC::Int, LibC::Char** -> LibC::Int)) : LibC::Int
end

# Redefine main function
fun main(argc : Int32, argv : UInt8**) : Int32
  # Pass Crystal's main function as a callback
  LibAllegro.al_run_main(argc, argv, ->Crystal.main)
end

This is a breaking change because the macro redefine_main is removed.

One more thing: I expose main to Crystal as __crystal_c_main. This makes it possible to have a user-defined method named main, so kinda fixes what's described in #4761. Next, the compiler should disallow funs and methods with the same names, but I'll send that in a separate PR.

^ I decided it's better for now to expose it as main, because otherwise to redefine it one would need to use the same cryptic name. I'll later change the compiler to never expose fun main to Crystal code because it never needs to be invoked.

There's one TODO there that is fixed by the first commit in this PR. We can get rid of it after releasing the next version.

I also removed the single usage of redefine_main, which maybe was needed before, but removing it I got the SDL samples to work (they didn't work anymore).

[Sija]

Please, enclose STDOUT and STDERR in backticks `` to link 'em to docs.

[Sija]

[...] and before executing at_exit handlers.

?

[Sija]

Shouldn't be here main_user_code(argc, argv) instead?

[ysbaddaden]

Looks great!

One minor thing: sometimes we don't want a main, for example Android applications are shared objects, loaded from Java (JNI).

[asterite]

@ysbaddaden Was that possible before this PR?

[RX14]

Would it be possible to raise early if this is executed twice? Seems like a bit of an edge case but might be worth protecting. This could be another PR though.

[Sija]

Shouldn't ->Crystal.main be ->Crystal.main(Int32, UInt8**)?

[asterite]

If it's a lib call the compiler figures out the argument types.

[Sija]

Didn't know that, cushtie!

[ysbaddaden]

@asterite no, it wasn't possible, but since it's touching main declarations, it could have been an opportunity to allow to skip generating a default main function. Anyway, no big deal.

[david50407]

Can we also provide Crystal.main(argc : Int32, argv : UInt8**, envp : UInt8**) in this change?
envp is used in many C programs, maybe we can allow this argument and skip it first.

MSDN page for envp: https://msdn.microsoft.com/en-us/library/k104fy6h.aspx

[Sija]

@david50407 envp parameter is widely accepted, yet not standardised, see discussion on SO. btw, wouldn't it be redundant with access to ENV?

[Fryguy]

@asterite This is awesome, and is exactly what I was trying to accomplish myself, but couldn't figure out. This is really nice!