Add synopsis to dune rules/aliases. Show synopsis in `dune show aliases`

[maxim092001]

Desired Behavior

As a user of dune, I define a lot of different rules in my project:

• Generate OCaml types from some schema
• Run CLI tool to make network request to do some validation of my OCaml code
• Download some binary executable to run before/during build
• Run tests/executable with some pre-defined flags

Usually, I add an alias to each dune rule:

(rule
 (deps
  (glob_files schema.json))
 (alias validate_schema)
 (action
  (run
   validation_bin
   --mode
   validate
   --schema
   schema.json)))

Rules may get really complex and it is hard for me as a user to understand what kind of rules I have in project, especially when I switch projects often.

Currently, dune has support to show aliases in a top level dune file via dune show aliases. I propose to enhance this functionality.

Example

User should be able to add synopsis to a dune rule:

(rule
 (synopsis "Schema validation via validation_bin tool")
 (deps
  (glob_files schema.json))
 (alias validate_schema)
 (action
  (run
   validation_bin
   --mode
   validate
   --schema
   schema.json)))

And dune show aliases should be able to display validate_schema with synopsis in its output such as:

all
default
doc
fmt
install
validate_schema --- Schema validation via validation_bin tool

I believe synopsis for default aliases can also be added as part of this feature.

I would be happy to contribute this functionality if there is an agreement that it is useful and needed. I, though, would need some on boarding....

Thanks!

[maiste]

Thanks for opening this issue! 😄
Regarding your idea, it could be interesting to document the aliases as you suggest. However, wouldn't there be an issue if you attached multiple rules to the same alias? What would be the expected outcome with two rules attached to the same alias and the two of them are declaring a synopsis?

[maxim092001]

@maiste thanks for coming back so quickly!

In my personal experience, same alias for different dune rules is useful for runtest or other tests. I didn't see custom aliases for different rules outside of tests, so eager to learn of such use cases.

That being said, there are multiple options we can take:

• Single definition
  • Display first synopsis that was found during dune show aliases.
  • Enforce synopsis to be unique per alias. Fail build if two rules with same alias try to add synopsis
• Additive aggregation: combine synopsis for dune rules into one synopsis.
  • There won't be order guarantees I assume, so it doesn't seem very useful for user.
• Additive aggregation v2: dune show aliases has output like:

  - validate_schema:
    - dune:35:24 - Validate schema rule alias synopsis 1
    - dune:80:35 - Validate schema rule alias synopsis 2
  

  • Shows rules with different synopsis for same aliases
• Attach synopsis to alias definition
  • Currently you can define top level alias in dune file without attaching it to rule: (alias (name validate_schema))
  • We can allow synopsis for aliases only for such definitions and show only them during dune show aliases:
    • (alias (name validate_schema) (synopsis "Schema validation"))
  • It is kinda similar to CMake add_custom_target with COMMENT approach

As a user, I would prefer either "Additive aggregation v2" or "attaching synopsis to alias definition".

Let me know what you think

[maiste]

I have already seen some projects where people would use aliases to generate some binary dependencies (the best example being ocaml.org itself 👍).

My intuition would be to attach a synopsis to alias, as you suggested. It would make it clearer about the purpose of such declarations. Maybe this is something that could live inside the dune-project. I don't know what the best is.

However, I would like to have other Dune people input on this to make sure it is not heading into the wrong direction and to make sure I'm not the only one to see interest in this feature 😄

[maxim092001]

However, I would like to have other Dune people input on this to make sure it is not heading into the wrong direction and to make sure I'm not the only one to see interest in this feature 😄

@rgrinberg and @emillon you would probably have an opinion!

[rgrinberg]

Sure, I don't mind. Seems like a straightforward enhancement

[Leonidas-from-XIV]

My suggestion would be the following

(rule
 (deps
  (glob_files schema.json))
 (alias (name validate_schema) (synopsis "Validates a schema"))
 (action
  (run
   validation_bin
   --mode
   validate
   --schema
   schema.json)))

So when the synopsis is missing it would be equivalent to (alias validate_schema).

[maiste]

Thanks for feedback!

My concern with attaching it inside the rule is when you end up to use an alias at multiple places with multiple synopsis. As mentioned by @maxim092001, it can be handled:

• by raising an error if we already have the synopsis (if we go for the inside rule solution, this seems to be the best) or
• by concatenating all the synopsis or
• remember the position and display the synopsis linked with the location.

My first intuition was to put it inside the dune-project but I can't think of a good syntax to reflect this. Also, putting the information far from the alias input wouldn't be a good UX.

[emillon]

You could reuse the alias stanza to do this.

[maxim092001]

I'd like to discuss issue this during next dune-dev call on Wed 19 March if there is time!

[Leonidas-from-XIV]

I've added it to the agenda for the meeting.