tools.build guide should explain how -T :paths works

[Alex Miller]

The guide assumes you're putting the build.clj in the project root (which is included by -T), but it's not obvious why or how this works.

[Sean Corfield]

A recent thread in #tools-build on Slack highlighted that there's a lack of context/introduction for https://clojure.org/guides/tools_build

• It doesn't clearly state that build.clj typically goes in the project root
• It doesn't clearly state that deps.edn should have a :build alias with :deps and :ns-default
• It doesn't clearly state that the intended usage is clojure -T:build <task> and that <task> should be a function of one argument, accepting a hash map of command-line arguments, similar to -X and :exec-fn

(I'm adding this comment to summarize what they specifically tripped over trying to add a build script to their project)

[Alex Miller]

I will update this to improve it, but I don't actually agree that there is a "typical" location for build.clj or alias name. Part of the whole design of this is that those questions are up to you (I've got projects that do a variety of things). But the semantics of the build and paths and deps should be much clearer for sure.

[Alex Miller]

updated entry text at https://clojure.org/guides/tools_build to cover some of this.

[Sean Corfield]

That's excellent! Thank you @puredanger !