Improving the installation instructions

[ivanperez-keera]

The current installation instructions use the following way to check that Copilot is installed correctly:

To test that Copilot is available, execute the following:

$ ghci <<< 'import Language.Copilot'

It should end with a line like the following and not print any error messages:

ghci> ghci> Leaving GHCi.

I think that way of checking things is a bit ugly. Users unfamiliar with Haskell don't know what's happening.

I'm thinking that maybe we should change it to:

$ runhaskell <<< 'import Language.Copilot; main = putStrLn "Success"'

but I'm open to other ideas that are compatible with the current setup (no additional tools, no wrapper scripts).

[fdedden]

I agree, just printing a simple 'Success' is a lot more clear. It does not solve the problem of users having to run a somewhat random looking piece of code though. A solution could be to bundle a check-copilot (or similar) script, but that clutters the users environment with something they will only run once.

The solution aside, one problem I have is that using <<< over echo '..' | runhaskell is a so-called bashism, and not very portable. I strongly advise we rewrite it.

[kaBeech]

For the problem of users having to run a somewhat random looking piece of code, what if the code is explained in the documentation where it appears? Something like:

To test that Copilot is available, execute the following:

$ echo 'import Language.Copilot; main = putStrLn "Success"' | runhaskell

This defines and runs a simple program that imports Copilot and prints a success message. It should print a line like the following and not print any error messages:

Success

[kaBeech]

Two more thoughts:

DRY

Since the install steps are different depending on OS but the testing steps are the same for all, would it be helpful to DRY up the README by moving the testing steps out of the Installation section and into their own section?

Scripting

I hear the goal of not cluttering the users' environment with something they will only run once. I also hear the goal of making onboarding to Copilot as easy as possible for new users.

How would you feel about something like a create-copilot-app script that would ask the user for the name of their program (e.g. "MyApp"), create MyApp.hs (which includes something like import Language.Copilot; main = putStrLn "Success"), and run it once to produce the success message?

This could also provide an opportunity to educate users on the basics of starting out with Copilot through comments in the created file (MyApp.hs) or through a welcome message (like this one I provide to assist users of my documentation software).

If desired, create-copilot-app could, before asking for the name of the program, ask if the user wants to create a new program or an example program. If the latter is chosen, it instead creates one of the programs from the examples/ directory.

Perhaps this violates the "no additional tools, no wrapper scripts" requirement, but since a check-copilot script is being discussed I figure I'll offer this idea as well.

[Rezenders]

Hi,

As a new copilot and Haskell user, I had difficulties in running the Heater example in the README as described in issue #444.

I would suggest replacing:

runhaskell Heater.hs

With:

Start ghci:

$ ghci

Then withing ghci run the following command: (Maybe an explanation of what this command does would be also useful)

:set -package copilot-c99

and

:set -package copilot-language

The output should be similar to:

$ ghci
GHCi, version 8.8.4: https://www.haskell.org/ghc/  :? for help
Loaded package environment from /home/gus/.ghc/x86_64-linux-8.8.4/environments/default
Prelude> :set -package copilot-c99
package flags have changed, resetting and loading new packages...
Prelude> :set -package copilot-language
package flags have changed, resetting and loading new packages...

Then, to load a Haskell monitor specification file (I'm not sure this is the best name for this file), e.g., the Heater.hs example, run the following command in ghci:

:l Heater.hs 

Then, to generate the files heater.c, heater.h and heater_types.h, containing, respectively, the implementation of the monitors, the interface, and a declaration of any types declared in the specification (empty in this case), run in ghci:

:main

PS: The Haskell file should be in the same directory in which you started ghci, or you need to specify the full path to the file.

Alternatively, you could fix/propose how to fix the issue of running the original command directly:

runhaskell Heater.hs

[Rezenders]

Also, add in the section other-linux-distributions before cabal v2-install --lib copilot:

cabal v2-update