Meaning of "@install" in "jbuilder build @install"?

To build my project, I run jbuilder build @install, because I saw this somewhere, and it works.

What does @install mean, though?

(As far as I know, I’m not installing anything anywhere, except under _build/default off the project root.)

I think they are target aliases: https://jbuilder.readthedocs.io/en/latest/usage.html#aliases

Thanks @orbifx. That’s helpful. It clarifies the meaning of @ as indicating an alias. There is a further question about the meaning of the @install alias.

A search on “install” in the docs led me to this page which, near the bottom, says that an alias is “a build target that doesn’t produce any file” (OK, I get that; you can have the same thing in a Makefile), and that @install is the alias “that depends on everything that should be installed”. Now I need to figure out the meaning of “should be installed”. Or to put it in a more straightforward way, I need to understand what determines that this or that file is considered the kind of thing that should be installed. I haven’t done anything I’d call installing, so far, but jbuilder build @install is doing what I want. What rule is making it do that?

(I submitted an issue suggesting that the jbuilder docs contain more examples. The @install` documentation illsutrates a pattern that I remarked on there: I think that at present the jbuilder docs are good for people who already have a moderately thorough understanding of juilder, or for someone who is willing to thoroughly study most of the documentation. I think the docs can be difficult for someone learning jbuilder because in some cases understanding one definition or rule requires understanding some distant part of the docs, which in turn can require understanding another part, and so on. At a certain point it becomes difficult to figure out whether the answer to your question exists in the docs. It probably does, but figuring out the answer can be difficult.

jbuilder is still a great tool. I think it’s important to first produce documentation that’s precise, because that guides testing, maintenance, and improvements, and still helps experienced users, and the jbuilder documentation is good in this way. Eventually I hope that there are more examples, or a thorough tutorial, or lots of blog posts, etc. Given that jbuilder is becoming a central build tool for OCaml, that sort of thing could be valuable.)

3 Likes

Descending into search results that didn’t initially seem relevant to what I was trying to understand, I found information on this page that seems relevant, but that I don’t understand yet. It has something to do with the *.install files that get created in the project root. Maybe I need to understand opam better first. (Should I have to understand opam to understand using jbuilder without opam?)

Maybe the new edition of RWO will provide a thorough intro to jbuilder and its use with opam? (Added RWO and opam tags.)

It’s good that you have created an issue for missing examples. Developers sometimes struggle to assume an accurate perspective of a newcomer for writing good examples and documentation. It happens.

In the meantime you can try understanding what you are seeking experimentally. I think most people try one or two reasonable theories and make some assertions, which gets them going.

The @install target probably makes all library and executable rules and installs the generated files in their respective locations.

To clarify, jbuilder build @install will build all the necessary targets and will create a [project].install file (assuming you have a [project].opam file), but won’t actually install anything anywhere.

After running jbuilder build @install, you can run jbuilder install to actually copy the files to their correct locations (e.g., ~/.opam/[version]/bin/[executable name]).

Thanks very much @orbifx, @bcc32. That’s what I wanted to know.