Clojurians Log v2
cljdoc
Hi all. I have removed a dependency from deps.edn for one of my libraries as it is optional. It would therefore be :scope provided using older tooling... (although I never used lein myself). However, this now means clojars can't build documentation, as one of my namespaces requires that third-party dependency. I've read https://github.com/cljdoc/cljdoc/blob/master/doc/fixing-builds.md but I'm unsure how to fix. Is there a way of providing an alias, or set of aliases to use in the cljdoc build? I don't think deps.edn supports listing optional dependencies except through aliases. I'd be grateful for for any pointers. Thank you!
I tried using a source pom.xml with the required dependency explicitly listed as 'provided', but it appears the whole <dependencies> section is overwritten by tools.build so don't think that will work.
Lines 7-38 are my solution here…
That looks clever. Thank you! It feels as if the standard tools.build write-pom could support adding in other deps or merging any deps from a source template POM with those from deps.edn.
That would be better for sure
Hmm... yes this flow is a tad awkward. I really should get around to finishing up implementing static API analysis for cljdoc.
For libs that don't dynamically generate their API at load time (potemkin import-vars type stuff), static analysis would do the trick without any need for specifying any provided deps.
Thanks @lee - although my reflections on this are that to play nicely with the Java ecosystem my pom.xml should include optional dependencies with scope 'provided'. So, I have asked a question on http://ask.clojure.org. https://ask.clojure.org/index.php/12817/tools-support-providing-additional-dependencies-provided
I stumbled across this problem just now, with my rephrase library, and noticed that write-pom in tools.build supports :optional true in a dependency (in deps.edn) and adds <optional>true</optional> to the pom.xml file.
This seems similar to <scope>provided</scope> -- and deps.edn-based projects seem to correctly ignore such transitive deps when depending on Maven/Clojars artifacts with optional deps (good).
So I wondered whether cljdoc would be happy with an optional dep, rather than a provided-scope dep?
(I'm currently using a build.clj hack to modify the generated pom.xml to replace <optional>true</optional> with <scope>provided</scope> for now, even tho' Maven says they have different semantics, but haven't tested cljdoc with an optional dep)
If this works, it would seem to be a supported way to handle this problem for cljdoc going forward (use an alias in deps.edn to add the necessary deps with :optional true in their coords, create a basis with :aliases for use in write-pom).
Seems like a good idea to me, @seancorfield
If it works for cljdoc. I haven't tested it.
Ya, I can take a peek sometime soon
Confirmed that :optional true works with http://cljdoc.org!
Thank you @seancorfield, I'll update the cljdoc docs and cljdoc-analyzer tests.
Anybody using :optional true? I could reference your lib as an example from docs... and add it to the cljdoc-analyzer real-world lib tests.
I use it in rephrase -- https://github.com/seancorfield/rephrase/blob/main/deps.edn#L4-L6
I write the POM and build the JAR with the :optional alias, so it ends up in pom.xml which satisfies http://cljdoc.org but projects that depend on it (on http://clojars.org) don't bring nrepl/nrepl in as a transitive dependency.