New user experience is... not ideal

[1player]

I decided I wanted to spend a few hours learning Janet. My main goal is to play with the raylib bindings and compile it to executable. Here's my experience.

1. On the main page the list of features says it's possible to compile to native binary. Great! I write a simple hello world script, and I'm trying to compile. I run janet -h and there is nothing about compilation, apart from the -k flag which does seemingly nothing.
2. Browse the docs mindlessly until I come across the jpm section and mentions of building. I am impatient, I just want to compile a script, not the whole project, especially since jpm -h has a quickbin option to "Create an executable from a janet script with a main function.". Exactly what I need, but I have no idea which two arguments it requires from me. Alright then, I will create a project.
3. There is jpm new-project but no mention of it in the official docs. Still, it creates a basic project structure that prints "Hello!". Nice!
4. Try jpm build but nothing happens, not sure why.
5. Towards the end of the jpm docs there is an incantation to create an executable. Why is this missing from the generated template? No idea.
6. Perhaps it defaults to generating a library. No problem, maybe I can get a repl into the project then! No mention on how to do that in the jpm docs.
7. Check jpm -h again and see there's a jpm repl command. Fire it up, evaluate (hello) which has been defined in the project template, fails with "unknown symbol hello".
8. Add (declare-executable :name "play" :entry "src/init.janet") to my project.janet file, run jpm build, and get error: expected integer key in range [0, 5), got nil. No idea what's going on here, time to throw the towel.

I feel Janet could use with a better onboarding experience, with a simple tutorial that creates a project, runs it in a REPL, and compiles it to binary. Also the jpm docs, the main entrypoint and way of interacting with janet, are pretty sparse and don't even mention how to create a project or run the generated hello template.

Please take this as constructive input, I do not wish to criticise the free time of others, I just this write-up makes it easier to identify what are the pain points for newbies to the project like me.

[sogaiu]

@1player

Just touching on some specifics here. Perhaps other folks may have other comments.

I didn't know about the new-project subcommand either :)

I went looking through the jpm help output and I see:

    new-project name
        Create a new Janet project in a directory `name`.

Is that where you learned about it?

Incidentally, some lines above that, I see:

    quickbin entry executable
        Create an executable from a janet script with a main function.

I tried both of those subcommands in succession, but it wasn't sufficient.

$ jpm new-project sample
author? 
description? 
creating project directory for sample
$ cd sample/
$ jpm quickbin sample/init.janet executable
generating executable c source executable.c from sample/init.janet...
error: expected integer key in range [0, 5), got nil
error: build fail
  in pdag [/home/user/.local/lib/janet/jpm/dagbuild.janet] (tailcall) on line 79, column 23
  in run-main [boot.janet] on line 3783, column 16
  in cli-main [boot.janet] on line 3928, column 17

Looks like the following modification to sample/init.janet to additionally contain an appropriate main function might help:

(defn main
  [&args]
  (print (hello)))

Then:

$ jpm quickbin sample/init.janet executable
generating executable c source executable.c from sample/init.janet...
compiling executable.c to build/executable.o...
linking executable...
$ ./executable 
Hello!

May be it would make sense for jpm's new-project subcommand to come with a default main function.

I've filed an issue at jpm's repository. May be I'll do a PR for it... Ok, here is a PR for it.

Update: Looks like it was merged.

[sogaiu]

I've started a repository with some content to provide one example demoing some of what's listed at the Features section of the main page.

Very much a work-in-progress, though there is a section on:

Export your projects to standalone executables with a companion build tool, jpm

Feedback welcome.

[1player]

Wow thanks, that repo should definitely be linked to on the Janet website. It is a very informal introduction but goes in more depth than what I could find on the official docs. Learning from example, in my opinion, tends to be more fun than trial and error while looking at the language reference.

[MarcusE1W]

Today I tried to set up a new project with jpm as described above and wanted to create the executable with jpm build instead of using quickbuild.
It took a bit of playing around but in the end it worked.

After the creation of a new project with jpm new-project example add these lines at the end of the newly created project.janet file in the example folder.

(declare-executable
 :name "example"
 :entry "example/init.janet"
)

Note: In the project.janet file in declare-executable you have to refer to the init.janet file with the folder name example/init.janet, whereas in declare-source you need to refer to src/init.janet. No idea why.

After this change jpm build finally actually builds something.
The executable can then be started with ./build/example
There is also a bin folder in the project folder, not sure what that is used for.

In my view to create an executable should be the standard template for new-project

[sogaiu]

Note: In the project.janet file in declare-executable you have to refer to the init.janet file with the folder name example/init.janet, whereas in declare-source you need to refer to src/init.janet. No idea why.

This seems like a bug. I think the path should be example/init.janet for declare-source as well unless init.janet is created in a directory named src (which it does not appear to be currently).

I made a PR at the jpm repository.

Update: the PR has been merged.

[sogaiu]

In my view to create an executable should be the standard template for new-project

Some convenient way to create a new project that is already set up to create an executable does seem like a good idea to me.

It's not obvious to me whether that would be better in new-project or a separately named thing.

I made an issue for this. Perhaps an appropriate solution can be arrived at (possibly even the original suggestion).

Update: a PR was made and got merged.

[sogaiu]

There is also a bin folder in the project folder, not sure what that is used for.

I didn't figure that out either (^^;

FWIW, I believe that is a result of this line.

[sogaiu]

It appears the declare-source path issue has been addressed and there is a new subcommand named new-exe-project which should make it easy to create a project that builds an executable.

Thanks @bakpakin!