Include instructions on how to build clojurescript itself. especially how you build it for release I thought it would be a simple as lein uberjar but I’m not sure
It’s not appropriate for the Quick Start but we have those instructions on website now, see https://clojurescript.org/community/building
I just started going through this today and noticed a few things that I believe might add friction for early and beginner ClojureScript developers
1. Comment on where to run
We show a new user the expected file structure. It could be helpful for us to tell them to
cd hello-world and run in the root of that directory.
2. Comment on
src dir in the
Hello, ClojureScript Section
There are a few implicit details that might be odd for newcomers. For example, if you do not put your
hello_world/core.cljs into the
src directory, running
clj --main cljs.main --compile hello-world.core --repl from within the
hello-world dir is not going to run successfully and will give you an
Exception in thread "main" java.lang.IllegalArgumentException: Namespace test does not exist error message.
My rationale for the above is that there are some unique qualities that developers from other languages, think Python, or JS, would find odd in CLJ/S:
- namespaces v file paths
hello-world.core where as in other languages compiling a file in the terminal would just write something like
node src/hello-world/core.js and more interestingly (which you did note, so that is awesome) the kebab case further throws people off the trail. Especially if not from a Java world.
So because the quickstart kind of skips over them, could be odd. I agree that we should not spend time talking about them here, just a comment re-enforcing that they are important.
Hope this helps!
Might be worth adding that this needs clojure 1.9 to work. 1.8 is the most recent version on macports. I know the install recommends using brew, but some of us still prefer to use port and may get bitten by this.
This is covered in the very first part of the Quick Start and we state that it’s important. Do you have something more direct that you would like to see?
It’s a Quick Start and we’re making very deliberate choices about what environments we cover. Other popular tools make similar narrowing decision in their documentation, it just makes for better reading and a better experience for more users.
I believe this is the part you were referring to?
First set up a project folder for our Hello World program. Here’s a list of the files and folders you’ll need. Note that the underscores in the names are important.
My suggestion would be to add something to the end of it like
Further, your hello_world/core.cljs must be inside of the `src` directory for the CLI tool to find your code."
The very first thing we say is that you must establish a specific directory structure with a diagram which shows exactly where to put everything. Are you skipping this part?
I don’t think I am. I see that it says
First set up a project folder for our Hello World program. and then the comment of here are the exact files and folders you will need. but I still think it is worth adding something to the effect of what I mentioned.
Unless I am indeed missing something? I am referencing this version of the quick start https://github.com/clojure/clojurescript-site/blob/quick-start-1.10/content/guides/quick-start.adoc
I hear you. I didn’t mean support another environment, just suggesting a change of “an installation of clojure” to “an installation of clojure 1.9+”. Makes it slightly more idiot proof…
For me, a major road-block in any Getting Started guide is being asked to manually set up the directory/file structure for the project, or cloning a random github project.
I haven’t used
clj at all, but isn’t there something like
clj new <template> <project>?
Out of scope for what we plan to do. But thanks for the feedback.
Hmm. If you don’t mind me asking: Why? It looks like the guide covers some ‘clj’ stuff already.