explain .itarget/.otarget more

[agarwal]

There is just one sentence explaining these targets, and it only says what .itarget is for, not .otarget.

Confusingly, these extensions are used in the example explaining dynamic dependencies. So one gets the impression that these are not supported by any builtin rules. At the least that example should end by saying "by the way this rule is already provided, we're just showing how you could implement it yourself". But that doesn't seem right either. The example specifically builds symlinks, which isn't what the builtin rule is supposed to do. So it's confusing; the example shouldn't reuse extensions that builtin rules do something different with.

Finally, is there builtin support for this extension or am I using it wrong?

$ cat a.ml 
let () = Printf.printf "hello\n"

$ cat foo.itarget 
a.byte

$ ocamlbuild foo.itarget 
Finished, 0 targets (0 cached) in 00:00:00.

$ tree .
.
├── _build
│   ├── _digests
│   ├── _log
│   └── foo.itarget
├── a.ml
└── foo.itarget

1 directory, 5 files

I was expecting a.byte to get built.

[gasche]

I think the ocamlbuild -documentation output answers your question. It says:

rule "target files"
  ~deps:[ %.itarget ]
  ~prods:[ %.otarget ]
  ~doc:"If foo.itarget contains a list of ocamlbuild targets, asking
        ocamlbuild to produce foo.otarget will build each of those targets in
        turn."
  <fun>

(This description is in the conditional style that @bobot says we should replace by a more direct style: "Building foo.otarget will built the list of targets listed in foo.itarget, one per line".)

Any pull request to improve the manual wording on this target would be, of course, warmly welcome.

[gasche]

Your point on the symlinks thing is well-taken. I'll have to maybe pick another example, or conveniently silence that part of the build rule (it's ok to simplify).

At the time I wrote those examples, I thought it was a good idea to take actual working code from the ocaml_specific.ml implementation. That would be a way to show the users, in a sense, that there is nothing hidden/magic and they have considerable flexibility at hand, similar to what the builtin rules use. Since then I have had recurring feedback that the way this is currently done in the manual is confusing (because the naming environment is not exactly the same, etc.), so I think I may have to revert this decision.

If someone has advice for other kind of rules to use as examples, I'm all ears.

[agarwal]

the ocamlbuild -documentation output answers your question

Yes it does. Thanks. I didn't get in the habit yet of checking this.

[agarwal]

If someone has advice for other kind of rules to use as examples, I'm all ears.

To be clear, I think the example is fine. It's just the choice of the deps and stamp suffixes, which conflict with builtin support for those suffixes. A better choice could be .links and stamp.links, respectively.