Skip to content

Add documentation for depexts (#13657)#13831

Merged
Alizter merged 6 commits intoocaml:mainfrom
sabine:issue_13657
Apr 15, 2026
Merged

Add documentation for depexts (#13657)#13831
Alizter merged 6 commits intoocaml:mainfrom
sabine:issue_13657

Conversation

@sabine
Copy link
Copy Markdown
Contributor

@sabine sabine commented Mar 18, 2026

Add a new reference page documenting external system dependencies (depexts):

  • declaration in opam files,
  • lock directory format (standard and portable),
  • the dune show depexts command,
  • platform variables with environment overrides, and
  • build failure hints.

This is a first PR to lay the groundwork (reference docs) for #13657. There will be one or more followups to add the remaining new pages (tutorial, how to), and to make the addition to the existing doc.

Comment thread doc/reference/depexts.rst Outdated
Copy link
Copy Markdown
Collaborator

@Leonidas-from-XIV Leonidas-from-XIV left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for starting the documentation on depexts.

Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Copy link
Copy Markdown
Contributor Author

@sabine sabine left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @Alizter for review comments, addressing this now

Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
Comment thread doc/reference/depexts.rst Outdated
@shonfeder shonfeder requested a review from Alizter March 24, 2026 12:40
Copy link
Copy Markdown
Collaborator

@Leonidas-from-XIV Leonidas-from-XIV left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We discussed this at standup and I was asked to re-review it. So my conclusion is that to merge it still needs a bit of rework:

  1. It needs a ticket to track that there should be a way to declare depexts without having to go through .opam.template files. Projects using dune pkg don't even need to generate .opam files usually so forcing these files onto the projects because dune-project does not support depexts is really unfortunate.
  2. It is not a reference. It's an explanation or maybe a howto and thus should be moved accordingly. The reference part of this is very short or even non-existent because the feature we'd want to document (specifying the depexts of my project) doesn't exist (see my first point).
  3. @sabine, you need to sign off the commits (to pass the DCO check) and possibly rebase. I don't think the CI failures are related to the documentation but it would still be good to have this PR pass CI successfully.

@sabine sabine changed the title Add reference documentation for depexts (#13657) Add documentation for depexts (#13657) Apr 14, 2026
@sabine
Copy link
Copy Markdown
Contributor Author

sabine commented Apr 14, 2026

Ah sorry for dropping the ball on this.

  • Rudi found an open issue that matches the feature request here: dune-project stanza for opam depext #5506.
  • since the doc as such is very short, it seems like the right place to move it is after the "Building" section, before "Packaging for Dune Compatibility", so this is where it is now
  • moved the "dune doesn't install or manage system dependencies" statement earlier in the explanation
  • do we want to call out the limitation of needing opam template files when using depexts? (I put it just as a TODO comment in the doc, but we could make it a user-facing disclaimer until the feature request is completed.)
  • added a How To on how to deal with depexts

I don't see anything right now that could be done to make this clearer, so I estimate this needs a final review (especially the new How To document)? I'm waiting for CI to finish to fix any remaining errors if any.

Copy link
Copy Markdown
Collaborator

@Leonidas-from-XIV Leonidas-from-XIV left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for picking it up again. Looks good overall, I only have a few small comments to clarify.

CI looks good now, the benchmarking failure can probably be disregarded.

Comment thread doc/howto/handle-depexts.rst Outdated
Comment thread doc/howto/handle-depexts.rst Outdated
sabine and others added 6 commits April 15, 2026 12:34
Add a new standalone reference page documenting external system
dependencies (depexts): declaration in opam files, lock directory
format (standard and portable), the dune show depexts command,
platform variables with environment overrides, and build failure hints.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: sabine <6594573+sabine@users.noreply.github.com>
- Rename title to "External System Dependencies (depexts)"
- Remove warning banner and versionadded markers (docs ship in sync)
- Remove Lock Directory Format section (implementation detail)
- Remove Platform Variables section (not user-facing)
- Remove portable/standard lock directory terminology
- Clarify depexts come from opam files, link to opam manual
- Note that dependency solving can happen automatically, not just
  via dune pkg lock
- Add opam Manual link to seealso section
- Add verification comment for error message example

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: sabine <6594573+sabine@users.noreply.github.com>
The standalone reference page didn't fit because Dune doesn't have a
native depexts feature yet. Move the explanation content into the
package management explanation doc and create a how-to guide for
declaring, querying, and diagnosing depexts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: sabine <6594573+sabine@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: sabine <6594573+sabine@users.noreply.github.com>
Not relevant for the vast majority of users.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: sabine <6594573+sabine@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: sabine <6594573+sabine@users.noreply.github.com>
Copy link
Copy Markdown
Collaborator

@Leonidas-from-XIV Leonidas-from-XIV left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Undraft once you think it is ready to be merged.

@sabine sabine marked this pull request as ready for review April 15, 2026 12:57
@Alizter Alizter merged commit a548ec6 into ocaml:main Apr 15, 2026
29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants