Comment by eduction | Hacker News Reader

Comment by eduction | Hacker News Reader

Parent Full thread

I think your pattern is right except for "its weird and undocumented" - I have found the maintainers are superb at docs -

e.g. deps.edn -

there is a "Guide" https://clojure.org/guides/deps_and_cli

there is a "Getting Started" https://clojure.org/guides/getting_started (it's branded as an overall Clojure getting started but the core of deps is just the clj/clojure command line tool you would use to install clojure)

there is a deep "Reference" with a "Rationale" https://clojure.org/reference/deps_and_cli

spec

Spec Guide - https://clojure.org/guides/spec

Spec Rationale https://clojure.org/about/spec

Spec API reference https://clojure.github.io/spec.alpha/

Spec resources (brief) https://clojure.org/community/resources#spec

(Rich Hickey also gave a couple of spec talks that are on YouTube)

Also, for my money, deps.edn is way more composable than lein, does not feel weird to me at all. Ditto for spec vs prismatic schema which preceded it. I think the latter case is one where people were more miffed that the official solution displaced a community beloved tool, but to me it genuinely seems really well thought through. There are some flaws discussed in the Rich Hickey talk "Maybe Not" which led to an experimental (still beta) spec2 but spec1 I still find miles ahead of what's available for the languages I've worked with.

"Superb" is not the word for deps.edn documentation. It is certainly documented but the gap between most Clojure documentation and the deps.edn documentation page is big. I suspect Rich wrote most of it but left the deps.edn page to someone else.The deps pages have a knack for includng pages of waffle that doesn't help to solve the current problem.

If a newbie is trying to debug

    {:deps
     {ring/ring-devel {:mvn/version "1.9.6"}}
     {ring/ring-core {:mvn/version "1.9.6"}}}

=> Error building classpath. Error reading edn. Map literal must contain an even number of forms

They have to notice that while they got 80% of their maps right, the file itself if a map with 3 forms. This is compounded by the fact that there are no examples of a multi-dependency project in the getting started page! If you know Clojure, this is an easy puzzle. For rookies, they didn't use (map) so the error message will probably trick some percent of them.

I don't think the deps documentation has been validated to provide what people actually want to know. Technically it is probably thorough, but "Superb" is a high bar it does not reach.

Probably the proper approach is learning deps by copying other people. Trying to learn it from the docs didn't work for me (it did for the rest of Clojure, so that was an unpleasant change).

Out of curiosity - what is the correct form in this case?

Ed: I'm guessing a key => list of deps, maybe?

I think you might be asking for a type :)

Not really. This is a syntactic error, not a type error.

To expand, this is the equivalent of something like {"a": 1, "b":}. The type checker in something like Typescript wouldn't ever come into play, because it's not legal syntax to begin with.

The parent was asking for the correct form, the syntax of EDN is necessary but not sufficient to specify this. A type (or a schema) is needed. Even if documented manually ad-hoc, that is better than nothing and would stop people needed to search the internet for examples.

It should be:

    {:deps
     {ring/ring-devel {:mvn/version "1.9.6"}
      ring/ring-core {:mvn/version "1.9.6"}}}

There was one too many map.

These are useful comments and issues are welcome at https://github.com/clojure/clojure-site/issues

smoothly changes gears ... although of course there can be no question that the deps documentation is managed by a man of patience, talent and extreme skill to whom we are all thankful.

Sorry, I had a bad time learning deps and the frustration still haunts me.

> a multi-dependency project in the getting started page

That's because they basically don't support monorepo multi-module projects. It's incredibly tedious and makes me long for something like Maven or Gradle (tools that otherwise are often too complicated).

How do you mean? You can specify local (fs) dependencies fine, which is presumably what you want in that scenario?

(I regularly contribute to a monorepo like this, though admittedly the top-level components are relatively disjoint.)

I mean, you can hack something together with local dependencies, yes, but there's no out of the box way to build and test everything together, or to do things like pin dependency versions across projects, have projects inherit shared configuration, etc. We end up creating a bunch of pseudo-projects that contain things like single dependencies, but this blurs the line between build time concerns and actual source code. As with everything in clojure, you can write it all yourself using something like tools.build, but it's not convenient and clearly not a first class use case.

I wonder if Polylith would be up your alley?

https://polylith.gitbook.io/polylith/

Excellent doc references, and FWIW I share your perspective on the tools.

Reply on news.ycombinator.com