Some feedback on teaching with jbuilder as a build tool

[grayswandyr]

Hi,

I’ve been TA-ing a course on functional programming in OCaml at ENSEEIHT, Toulouse, since September and it’s just over now. Students, 4th year students after the “baccalauréat” (how do you call them? graduates? postgraduates?), had to follow several lectures as well as roughly 10 seminars and 10 lab sessions. The whole course was completely revamped this year, so we also decided to use Jbuilder (not Dune, as we had to set up an infrastructure long before Dune 1.0) for our lab sessions.

Overall, the experience has been very nice, so kudos to Dune developers!

However, we also had a few issues that I would like to report for the record (Cc: @diml @rgrinberg ), and perhaps to foster a few evolutions of Dune (or to be shown how to solve them easily : we may have missed some information in the documentation).

1. jbuilder runtest sometimes just hangs while running, I’ll try to devise an MWE later but I’m still reporting this in case this is already a known issue.

2. Sometimes we wanted to have a program open a file whose path would be relative to the source code itself and harcoded in the ML file. For instance, the OCaml file contained something like open_in "./foo". Unfortunately, it seems Jbuilder doesn’t run runtest and utop from the same working directory, hence depending on the path written in the ML file, one of these commands failed. Is there an easy way to solve this? (We know we could use an absolute path to some location, but we have dozens of PCs running on a university network, so the configuration is not as flexible as one could expect. We’d also like to avoid passing the path on the commandline.)

3. I already spoke about this in another post ( [Dune] Link against cmo / cmi without source? ) but I’m writing this here too: we sometimes like to provide students with a .cmi/.cmo file pair but no source code. AFAIK there’s no simple, straightforward way to do this with Dune alone…

Well that’s about it. We met a couple of other problems but they could be solved in a reasonably easy way. The only trouble now is that, sometimes, students would like to create their own jbuild file or update one we have provided, and it’s a bit hard for them to know how to proceed (and the Dune documentation is good but perhaps more aimed at regular developers than students). I expect future versions of Dune or some Dune plugins, or even other tools, to ease setting up basic projects without writing the dune file yourself (e.g. something like dune new-lib mylib or dune add-dep mylib core_kernel).

[Chris00]

like open_in "./foo" . Unfortunately, it seems Jbuilder doesn’t run runtest and utop from the same working directory,

Did you mention foo as a dependency in the jbuild file? If not, the file will not be copied to _build because jbuilder does not know it is required.

[mars0i]

The only trouble now is that, sometimes, students would like to create their own jbuild file or update one we have provided, and it’s a bit hard for them to know how to proceed (and the Dune documentation is good but perhaps more aimed at regular developers than students). I expect future versions of Dune or some Dune plugins, or even other tools, to ease setting up basic projects without writing the dune file yourself (e.g. something like dune new-lib mylib or dune add-dep mylib core_kernel).

I agree that the Dune docs by themselves are not the best starting point. Maybe some of the links here would be helpful:

Quickstart OCaml

[grayswandyr]

I must confess I don’t see how to do this in this case (I only know how to achieve this with user-defined actions). An example jbuild file is the following, how would you ensure that calling runtest or utop depends on a file “foo” to be in the same working directory?

(jbuild_version 1)

(ocamllex (lexer))

(menhir
 ((modules (parser))))

(library
 ((name tp2) 
  (inline_tests)
  (preprocess (pps (ppx_inline_test)))))

[grayswandyr]

Thanks, I didn’t know this one, it’s indeed probably easier to grasp for students.

[diml]

For inline tests dependencies, you can add a deps field to the inline_tests field: https://dune.readthedocs.io/en/latest/tests.html#specifying-inline-test-dependencies. The test section of the manual is more recent and should be easier to read than older sections. We made an effort to make new sections be more than just a listing of available features.

I also did an introduction video for jbuilder. It is a bit outdated now, though if you are still using jbuilder it should be a good starting point.

[grayswandyr]

Thanks, this solves this problem. I was searching in the https://dune.readthedocs.io/en/latest/dune-files.html section…

[avsm]

1. I already spoke about this in another post ( [Dune] Link against cmo / cmi without source? ) but I’m writing this here too: we sometimes like to provide students with a .cmi/.cmo file pair but no source code. AFAIK there’s no simple, straightforward way to do this with Dune alone…

I’ve created an issue to track this on the Dune github: https://github.com/ocaml/dune/issues/1665

Please do feel free to submit quickstart guides directly to the Dune docs as well. They are a bit developer focussed at the moment, but there’s no reason why a quickstart guide can’t be added to the beginning

[rgrinberg]

• Sometimes we wanted to have a program open a file whose path would be relative to the source code itself and harcoded in the ML file. For instance, the OCaml file contained something like open_in "./foo" . Unfortunately, it seems Jbuilder doesn’t run runtest and utop from the same working directory, hence depending on the path written in the ML file, one of these commands failed. Is there an easy way to solve this? (We know we could use an absolute path to some location, but we have dozens of PCs running on a university network, so the configuration is not as flexible as one could expect. We’d also like to avoid passing the path on the commandline.)

I think this is the expected behavior. When you run tests (or any other rule) you execute the binaries from the directory where the rule is defined. When you run $ dune utop . your cwd is maintained. So you could cd into w/e directory you want and then run $ dune utop . to give you the expected behavior.

[grayswandyr]

Mmmh I’m not sure to follow you. All our files (ML and opened files) are in the same directory provided to students. And they just run jbuilder runtest or utop from this very directory. There’s no other directory to cd in. So depending on the concrete path written in an ML file, either runtest or utop will fail; unless I use @diml’s solution above for runtest.

[grayswandyr]

As a matter of fact, the https://ocamlverse.github.io/content/quickstart_ocaml_project_dune.html page cited above seems like a good start.

[mars0i]

As a matter of fact, the https://ocamlverse.github.io/content/quickstart_ocaml_project_dune.html page cited above seems like a good start.

That’s mainly by @bobbypriambodo. Maybe he would be interested in submitting a version to the Dune docs, per @avsm’s suggestion.