The "main site" is very high level. The poly tool documentation is much more detailed and I think it answers those sorts of questions...?

https://polylith.gitbook.io/poly/ is the new GitBook version of the tool's documentation.

(that's for the shell branch of the tool -- I think the README in the tool's repo is hard to read/navigate as one giant long document so I think the GitBook version is a big improvement)

Thanks! I’m reading there now. Let’s see if it gets clearer.

And feel free to ask any Qs that the docs don't seem to answer -- we can always help improving the docs 🙂

Now read a bit, quite sequentially. It’s is much more hands-on, as you said. I still have no clue about these two things: 1. Where do I put a dependency that my component needs? (in my current case I want to use Instaparse) 2. Where do I start my REPL so that it has access to all components and all other things? Context: I have created a hello world thing with a cli command. It is the wordiest and most complex hello world I have ever written. Which I sort of expected, you don’t need Polylith for hello world. Now I want to start building the system and am eager to get the kicks from having a sound foundation.

Components each have deps.edn and external dependencies go in there (just not dependencies on other components).

Start the REPL in the workspace root, using -A:dev (or -A:dev:test more likely since you'll want to run tests in the REPL).

I thought both of those were in the docs but I guess not...?

https://polylith.gitbook.io/poly/workflow/testing for the REPL

https://polylith.gitbook.io/poly/architecture/development also has a whole bunch about starting a REPL via an IDE...?

https://polylith.gitbook.io/poly/workflow/libraries is all about external dependencies.

It's definitely one of those things where you need to read "the whole book" before you can use it -- but there's no step-by-step tutorial showing how to build, say, a web app from scratch with Polylith...

I’m pretty sure the info is in there somewhere, but I can’t find it. Which is why I think I would need some more step by step guide.

Super grateful for the reading tips here!

If it's any consolation, I read that entire thing several times before it made sense to me...

...and as we've been doing the migration at work, I've asked a lot of questions that aren't clear from the docs.

To me it looks like I have done things right, but I clearly must have missed something, because it doesn’t work. 😃

poly libs shows me this. And I start my repl at the root of the repo. But trying to evaluate the component interface file where I rquire instaparse I get

Could not locate instaparse/core__init.class, instaparse/core.clj or instaparse/core.cljc on classpath.

Now tested to start the repl from the development directory. Then it works… I can probably find the error now by comparing…

Sounds like you didn't add the component as a :local/root dependency under :dev in the workspace deps.edn file?

You should never need to start a REPL anywhere but the root of the workspace.

Each component should be listed in the :dev alias as :extra-deps with :local/root "components/<name>" and the tests listed under :test alias as :extra-paths ["components/<name>/test" ...]

Yeah, so my root deps.edn only has extra-paths, nit extra-deps. It was a while since I set this project up, I don’t remember why it looks like it does. In development deps.edn I have deps.

If you need to work with Cursive, you can use :extra-paths in :dev but that's a workaround. And then you need to add all the components' library deps into :dev as well which is a mess.

I certainly don’t need to work with Cursive 😃

I’m working on migrating the GitBook documentation right now, and I accidentally pushed some changes to it yesterday so that the example unfortunately will not work 100% (it’s about switching to tool.build). I will try to find time today to finish it and also soon release all the new stuff. In the meantime, you can use the https://github.com/polyfy/polylith documentation. I also appreciate your feedback @U0ETXRFEW. The idea has been to explain the big picture in the high-level doc and to have an example that covers all the functionality in the tool doc. I’m sure the documentation can be improved, but I also think you need to use it for a while to really understand what Polylith is about! 🙂 Good luck with that and keep on asking questions.

I think I miss an option in the Where to begin? section of the home page: https://polylith.gitbook.io/polylith/#where-to-begin

Those four options are all great. A fifth that is something like If you would like to first see and follow along how a small Polylith application is built from the ground up, read this guide, and see these videos. Please keep this guide open and use it as reference when you wonder about some concept.

I might write a guide like this some day. I will start taking notes as I open up this box of wonders.

That’s a good idea, that you make notes about things that is missing or hard to understand! I’m looking forward to the guide @U0ETXRFEW! 🙂

That's an unreleased version -- so you can't... yet.

I have :poly as an alias in my deps.edn file as a git dep, pointing at the shell branch SHA.

This is the wrong SHA, but this is what we have at work:

:poly {; for our development/logging operations:
         :jvm-opts ["-Dclojure.core.async.go-checking=true"
                    "-Dclojure.spec.check-asserts=true"
                    "-Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory"
                    "-Dlogged-future=synchronous"
                    "-XX:-OmitStackTraceInFastThrow"]
         :extra-paths ["development/src"]
         :extra-deps {io.github.polyfy/polylith
                      {#_#_#_#_:git/tag   "v0.2.12-alpha" :git/sha "4b08954"
                       ;; this SHA is post alpha12
                       :git/sha   "a3278519d9b5221142e6c2afac5da5b79381b2c2"
                       :deps/root "projects/poly"
                       #_#_:local/root "/Developer/workspace/polylith/projects/poly"}
                      ;; force latest t.d.a:
                      org.clojure/tools.deps.alpha {:mvn/version "0.12.1048"}}
         :main-opts ["-m" "polylith.clj.core.poly-cli.core"]}

(spot the development hand-holding stuff with #_#_ 🙂 )

The SHA you want is probably 768642a5e6e93eb16c4f50859248f8e204d5dfbc

Then clojure -M:poly will give you the nice shell with auto-completion etc.

Awesome. Interestingly it required that I have :extra-paths in my deps.edn

Error in ./deps.edn: {:aliases {:dev {:extra-paths ["missing required key"]}}}

Ah, it's typical to have :extra-paths ["development/src"] for your own dev-specific code (we have "development/resources" at work so we can use our own specific log4j2 properties files).

I'm a little surprised that poly requires :extra-paths in :dev -- that seems legacy. I'll create an issue.

https://github.com/polyfy/polylith/issues/144