Clojurians Log v2

@dustingetz, FYI

Hi @ghopper! For the articles to show, the hyperfiddle/electric jar's pom, like you guessed, would need to point back to the hyperfiddle github repo. This can point back to a git sha or git tag, but should reflect the revision of the git repo at the time of jar creation. I see in the current https://repo.clojars.org/com/hyperfiddle/electric/v2-alpha-349-ge9996713/electric-v2-alpha-349-ge9996713.pom, that there is an <scm> entry:

<scm>
  <tag>vv2-alpha-349-ge9996713</tag>
</scm>

The API docs are generated by analyzing sources in the jar. I could look deeper but maybe I should understand more about hyperfiddle first. Cljdoc currently describes APIs by platform (currently clj vs cljs). Does hyperfiddle, by its nature, blur the line here? Could the cljdoc analyzer glean hyperfiddle's public API by loading and analyzing its sources?

I'd originally sent something here, as I was confused by the errors in https://cljdoc.org/builds/70788 (https://app.circleci.com/pipelines/github/cljdoc/builder/44560/workflows/349bb17d-7a79-4c6f-987a-91a91b0d1c55/jobs/60935). It seems like it might be more than just missing <scm> props. Will look into fixing the <tag> and adding the other missing props. The public API I would expect cljdoc to analyze are all .cljc files. I'm not sure what you mean exactly by cljdoc being dependent on platform. I imagine it would generate two separate docs (for clj and cljs) that are roughly the same? @dustingetz may be able to answer better (if willing 🙂)

Yeah I don't know much about hyperfiddle yet. I thought it might be doing something magical-ish with regards to platforms. Maybe not!

I wouldn't imagine it would be anything special from the perspective of cljdoc. 🙂

Beats me!

The CircleCI failures are related to loading sources to discover the public API. For this particular failure, we see analysis failing with: Could not locate clojure/core/async__init.class, clojure/core/async.clj or clojure/core/async.cljc on classpath I'd have to dig into hyperfiddle to try to understand why this would be happening.

Happy to try and help, would you like me to take a peek?

If you're willing, that'd be great, though if you'd rather wait until the <scm> props are fixed to see if that fixes anything, I'd understand as well. 🙂 I didn't dig too deeply to realize the error was actually when loading the JAR for analysis and not some unrelated error, so that's helpful to know. 🤔

API will still fail even after <scm> fix. But <scm> fix is still interesting to get articles loading.

To control how articles are displayed (ordering hierarchy), you would want to explore https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#article-config.

So for the API failure, I see that an attempt to load clojure.core.async is being made https://github.com/hyperfiddle/electric/blob/47b4f3d6a311f42c89a94dc72213c0dca4c5d10b/src/contrib/missionary_core_async.cljc#L5... but I don't see this https://github.com/clojure/core.async as dependency in the https://repo.clojars.org/com/hyperfiddle/electric/v2-alpha-349-ge9996713/electric-v2-alpha-349-ge9996713.pom hence the failure. Sometimes libs have optional dependencies and instruct their users to bring them in if they want to use certain features. We typically handle this for cljdoc via specifying provided deps in the pom.

One thing that I feel is very important is to define the public API, for cljdoc this means marking internal nses (or vars in nses) with :no-doc metadata. I see some :no-doc in hyperfiddle, but don't know how religiously it has been applied. Cljdoc will not attempt analyze nses marked with :no-doc.

Anyhoo, if you have questions or want a hand, I check in here often.

Thank you so much, this is all very helpful. 🙂

Found where the extra v prefix is coming from: https://github.com/seancorfield/build-clj/blob/main/src/org/corfield/build.clj#L152C29-L152C36

Aha. It assumes the passed in version does not have a v. Thing to note, Sean has deprecated https://github.com/seancorfield/build-clj/blob/main/README.md: > Caution: this wrapper has outgrown its original goal (of being a simple wrapper to eliminate boilerplate) and has far more knobs and dials than I intended, so I am deprecating it -- you should learn to use raw tools.build instead!

Yeah, I may see if @dustingetz is willing to drop it. 🙂

@ghopper I'd be happy to help wean the Electric folks off my archived library 🙂

@seancorfield, I think I've just about got it, though I'd appreciate having you look over the final diff to make sure I didn't miss anything! 🙂

Sure thing. I (re-)joined the #hyperfiddle in case any other Qs come up about build-clj. I tried to find all the projects out there using it and create issues saying "Oi! Switch to tools.build!" but I somehow missed the Hyperfiddle stuff...

@ghopper Here's a commit where I switched next.jdbc from bb/jar to plain b/jar -- adding the jar-opts function really helps: https://github.com/seancorfield/next-jdbc/commit/482b26ade7b9f5ec4b73b7da67e04fffac23e6e1

(I've done this for HoneySQL and, more recently, for Polylith, as well as all the templates in clj-new so there are quite a few repos to sanity check changes against)

Yeah, I started with just copying over jar-opts. I may go back to it if you or Dustin think this was too heavy handed with relying on hard-coded top-level vars I copied over all the functions and iteratively removed parts that were unused, eventually inlining most everything that I could. https://github.com/hyperfiddle/electric/pull/48

@dustingetz, FYI ☝️ (Main reason was to fix the extra v prefix in the <scm> element of pom.xml)

You'll need to add deps-deploy as a dependency in the :build alias.

And you might as well :require it directly and use that instead of the dynamic require in build-clj -- the only reason it does that is because of the "slim" version that omits the deps-deploy dep since it's "heavy" so you can avoid it for uberjars (which don't get deployed).

Excellent, glad you're here to point these things out. 🙂 Added the dep; moving the require now 👀

I think cljdoc might still fail since the :scm info is minimal. There's no pom.xml in the Electric repo so there's no template to use for write-pom -- unless I missed it?

You're correct, I was just fixing the scm version at the moment; will look into the other missing attributes later 🙂

My repos have a template/pom.xml file that contains the static information that doesn't change, including the rest of the <scm> data: https://github.com/seancorfield/next-jdbc/blob/develop/template/pom.xml#L18-L22

These get automatically merged by tools.build?

Yes, via the :src-pom option.

Gotcha 👌

(except in Electric, there's no pom.xml file to work from I think?)

Yeah, there's not. Will look at your template and add one

Also, :src+dirs is not needed in your jar opts...

(that's a build-clj-ism that was never really a good idea 🙂 )

hi, i am headed to bed in about 1 minute will review tomorrow

Thanks, Dustin 🙂 No rush

Good catch on :src+dirs, thanks

thank you all for your help appreciate the assist