Merge branch 'master' into cli-doc

Author: puredanger

content/dev/contrib_howto.adoc

@@ -25,7 +25,7 @@ Things you should do if you are a Clojure Contrib committer:
 
 * maintain your library and respond to questions/issues that arise
 * do your work on the master branch, or (if you are working on a significant chunk you want to keep temporarily separate) on a feature-specific branch that you create yourself
-* use the Maven Release option on build.clojure.org to make releases
+* use the GitHub "Release on demand" Action to make releases
 * coordinate with other committers before making changes to their libraries
 * accept contributions from others only if they have <<contributors#,signed the CA>>
 

content/dev/contrib_libs.adoc

@@ -14,7 +14,7 @@ These libraries use the same contribution model (<<contributor_agreement#,Contri
 * Source control - Git libraries on GitHub
 * Issues - https://clojure.atlassian.net/projects/CLJ[JIRA]
 * Development model - patches in JIRA, no PRs
-* Continuous integration - https://build.clojure.org[Jenkins]
+* Continuous integration - GitHub actions in each project
 * Doc generation and hosting - https://tomfaulhaber.github.io/autodoc/[Autodoc] and GitHub https://clojure.github.io/[pages]
 * Builds - Maven with deployment to Maven Central under the groupId `org.clojure`
 

content/dev/contributors.csv

@@ -1013,7 +1013,7 @@ Alan Malloy,
 Henrish Maluleka,henroid
 Itay Maman,
 Chester Mancini,chetmancini
-Vedang Manerikar,
+Vedang Manerikar,vedang
 Max Jiayin Mao,jmao
 Matthew Maravillas,
 Tom Marble,

content/guides/dev_startup_time.adoc

@@ -24,11 +24,12 @@ The `compile` function takes a namespace symbol and compiles that namespace and
 
 Subsequently, when any of those compiled namespaces are required, the class file will be loaded, rather than the original `.clj` file. If a source file is updated (and thus newer), it will be loaded instead. Periodically, you will need to re-compile to account for new dependencies or changing code.
 
-One special case is the `user.clj` file loaded automatically by the Clojure runtime, before any other code is loaded. If you are using a `user.clj` in dev, you need to force a reload because it has already been loaded automatically:
+Note that compilation is a side effect of loading, so has no effect on already loaded namespaces. In particular, one special case is the `user.clj` file, which is loaded automatically by the Clojure runtime. If you are using a `user.clj` in dev (or need to compile namespaces that are already compiled), you can do so by forcing a reload while compiling:
 
 [source,clojure]
 ----
-(binding [*compile-files* true] (require 'user :reload-all))
+(binding [*compile-files* true] ;; compile during load
+  (require 'user :reload-all))  ;; reload this and all transitively loaded namespaces
 ----
 
 That's it! This technique can substantially reduce your startup time during development, particularly as the number of dependencies you load increases.

content/guides/faq.adoc

@@ -383,7 +383,7 @@ All Clojure vars are globally available so again there is not much in the way of
 [[clj_replace]]
 **<<faq#clj_replace,Is clj a replacement for lein and boot?>>**
 
-No. The clojure tools are focused on a) building classpaths and b) launching clojure programs. They do not (and will not) create artifacts, deploy artifacts, etc.
+No. The Clojure CLI is focused on a) building classpaths and b) launching clojure programs. It does not (and will not) create artifacts, deploy artifacts, etc, although they may facilitate these actions through tools and libraries.
 
 tools.deps aims to provide programmatic building blocks for dependency resolution and classpath construction. clj/clojure wraps these into a command-line form that can be used to run Clojure programs. You can compose these pieces to do many other things.
 
@@ -438,7 +438,7 @@ https://groups.google.com/forum/#!msg/clojure/jWMaop_eVaQ/3M4gddaXDZoJ[Link] to
 [[native]]
 **<<faq#native,Will there be a native version of Clojure in the future?>>**
 
-Frequently people ask for a "native" version of Clojure, ie one that does not rely on the JVM. ClojureScript self-hosting is one current path but probably only useful for a subset of use cases. The https://www.graalvm.org/[GraalVM] project includes standalone execution using the SubstrateVM. Native images produced with Graal start extremely fast but may have fewer opportunities to optimize performance than the full JVM.
+Frequently people ask for a "native" version of Clojure, ie one that does not rely on the JVM. ClojureScript self-hosting is one current path but probably only useful for a subset of use cases. The https://www.graalvm.org/[GraalVM] project can be used to create a standalone binary executable. Native images produced with Graal start extremely fast but may have fewer opportunities to optimize performance than the full JVM.
 
 However, neither of these is likely what people are envisioning when they ask for a "native version of Clojure", which is a version of the language that is not JVM-hosted and compiles directly to a native executable, probably via something like LLVM. Clojure leverages an enormous amount of performance, portability, and functionality from the JVM and relies heavily on things like a world-class garbage collector. Building a "Clojure native" would require a large amount of work to make a version of Clojure that was slower (probably much slower), less portable, and with significantly less functionality (as the Clojure library relies heavily on the JDK). The Clojure core team has no plans to work on this but it would be an amazing learning project for anyone and we encourage you to go for it!
 

content/guides/tools_build.adoc

@@ -57,7 +57,7 @@ The remainder of this guide demonstrates individual common use cases and how to
 
 The most common Clojure build creates a jar file containing Clojure source code. To do this with tools.build we'll use the following tasks:
 
-* `create-basis` - to create a project basis
+* `create-basis` - to create a project basis (note: this will download deps as a side effect)
 * `copy-dir` - to copy Clojure source and resources into a working dir
 * `write-pom` - to write a pom file in the working dir
 * `jar` - to jar up the working dir into a jar file
@@ -72,17 +72,19 @@ The build.clj will look like this:
 (def lib 'my/lib1)
 (def version (format "1.2.%s" (b/git-count-revs nil)))
 (def class-dir "target/classes")
-(def basis (b/create-basis {:project "deps.edn"}))
 (def jar-file (format "target/%s-%s.jar" (name lib) version))
 
+;; delay to defer side effects (artifact downloads)
+(def basis (delay (b/create-basis {:project "deps.edn"})))
+
 (defn clean [_]
   (b/delete {:path "target"}))
 
 (defn jar [_]
   (b/write-pom {:class-dir class-dir
                 :lib lib
                 :version version
-                :basis basis
+                :basis @basis
                 :src-dirs ["src"]})
   (b/copy-dir {:src-dirs ["src" "resources"]
                :target-dir class-dir})
@@ -148,23 +150,25 @@ An example build for a compiled uberjar will look like this:
 (def lib 'my/lib1)
 (def version (format "1.2.%s" (b/git-count-revs nil)))
 (def class-dir "target/classes")
-(def basis (b/create-basis {:project "deps.edn"}))
 (def uber-file (format "target/%s-%s-standalone.jar" (name lib) version))
 
+;; delay to defer side effects (artifact downloads)
+(def basis (delay (b/create-basis {:project "deps.edn"})))
+
 (defn clean [_]
   (b/delete {:path "target"}))
 
 (defn uber [_]
   (clean nil)
   (b/copy-dir {:src-dirs ["src" "resources"]
                :target-dir class-dir})
-  (b/compile-clj {:basis basis
+  (b/compile-clj {:basis @basis
                   :ns-compile '[my.lib.main]
                   :class-dir class-dir})
   (b/uber {:class-dir class-dir
            :uber-file uber-file
-           :basis basis
-           :main 'my.lib.main}))
+           :basis @basis
+           :main 'my.lib.main})))
 ----
 
 This example directs `compile-clj` to compile the main namespace (by default source will be loaded from the basis :paths). Compilation is transitive and all namespaces loaded by the compiled namespace will also be compiled. You may need to add additional namespaces if code is dynamically or optionally loaded.
@@ -199,10 +203,12 @@ For example, consider a parameterization that includes an extra set of dev resou
 (def lib 'my/lib1)
 (def version (format "1.2.%s" (b/git-count-revs nil)))
 (def class-dir "target/classes")
-(def basis (b/create-basis {:project "deps.edn"}))
 (def jar-file (format "target/%s-%s.jar" (name lib) version))
 (def copy-srcs ["src" "resources"])
 
+;; delay to defer side effects (artifact downloads)
+(def basis (delay (b/create-basis {:project "deps.edn"})))
+
 (defn clean [params]
   (b/delete {:path "target"})
   params)
@@ -212,7 +218,7 @@ For example, consider a parameterization that includes an extra set of dev resou
     (b/write-pom {:class-dir class-dir
                   :lib lib
                   :version version
-                  :basis basis
+                  :basis @basis
                   :src-dirs ["src"]})
     (b/copy-dir {:src-dirs srcs
                  :target-dir class-dir})
@@ -246,24 +252,26 @@ This build creates a jar with classes compiled from Java sources and your Clojur
 (def lib 'my/lib1)
 (def version (format "1.2.%s" (b/git-count-revs nil)))
 (def class-dir "target/classes")
-(def basis (b/create-basis {:project "deps.edn"}))
 (def jar-file (format "target/%s-%s.jar" (name lib) version))
 
+;; delay to defer side effects (artifact downloads)
+(def basis (delay (b/create-basis {:project "deps.edn"})))
+
 (defn clean [_]
   (b/delete {:path "target"}))
 
 (defn compile [_]
   (b/javac {:src-dirs ["java"]
             :class-dir class-dir
-            :basis basis
+            :basis @basis
             :javac-opts ["--release" "11"]}))
 
 (defn jar [_]
   (compile nil)
   (b/write-pom {:class-dir class-dir
                 :lib lib
                 :version version
-                :basis basis
+                :basis @basis
                 :src-dirs ["src"]})
   (b/copy-dir {:src-dirs ["src" "resources"]
                :target-dir class-dir})

content/news/2013/06/28/clojure-clore-async-channels.adoc

@@ -57,7 +57,7 @@ There are analogous operations for use on ordinary threads - http://clojure.gith
 
 === Mixing modes
 
-You can put on a channel from either flavor of `>!`/`>!!` and similarly take with either of `<!`/`<<!` in any combination, i.e. the channel is oblivious to the nature of the threads which use it.
+You can put on a channel from either flavor of `>!`/`>!!` and similarly take with either of `<!`/`<!!` in any combination, i.e. the channel is oblivious to the nature of the threads which use it.
 
 === alt
 

content/news/2023/12/15/deref.adoc

@@ -0,0 +1,46 @@
+= Clojure Deref (Dec 15, 2023)
+Alex Miller
+2023-12-15
+:jbake-type: post
+
+ifdef::env-github,env-browser[:outfilesuffix: .adoc]
+
+Welcome to the Clojure Deref! This is a weekly link/news roundup for the Clojure ecosystem (feed: https://clojure.org/feed.xml[RSS]). Thanks to Anton Fonarev for link aggregation.
+
+== Podcasts and videos
+
+* https://www.youtube.com/watch?v=skMMvxWjmNM[Cooking up a workflow for data (by Slutsky, Prately & McLean)] - London Clojurians
+* https://www.youtube.com/watch?v=xgewqM39KNo[Learning Clojure, First Steps—Printing Things] - Clojure Diary
+* https://www.youtube.com/watch?v=TjzEIHgsgEM[Learn Clojure, First Steps — Arithmetic] - Clojure Diary
+* https://www.youtube.com/watch?v=Y4J8PJuBB6U[Flutter/MX: Compute Cycle Detected?! It Happens. We fix it] - Ken Tilton
+* https://www.youtube.com/watch?v=77WFLQiroXg[Flutter/MX: Yes, Virginia, the dataflow paradigm can procedural] - Ken Tilton
+* https://www.youtube.com/watch?v=YCW-du_y4s4[Beginner's guide to clojure.test and test runners: eftest, kaocha, cognitect test runner] - Andrey Fadeev
+* https://www.youtube.com/watch?v=ME-XEC1yEjs[Improving UI :: Advent of Clojure] - Roman Liutikov
+* https://www.youtube.com/watch?v=7PiocGVzEDs[Hacking the compiler! :: Advent of Clojure] - Roman Liutikov
+* https://clojuredesign.club/episode/103-explorify/[Ep 103: Explorify!] - Functional Design in Clojure
+
+== Blogs, articles, and projects
+
+* https://fpsd.codes/blog/clojure-bites-mazeboard-3-more-async-to-fully-decouple-layers/[Clojure Bites - Mazeboard 3 - core.async to update the UI layer] - Francesco Pischedda
+* https://blog.janetacarr.com/building-a-clojure-ci-cd-pipeline/[Building a Clojure CI/CD pipeline of CERTAIN DOOM] - Janet A. Carr
+* https://tonitalksdev.com/digitalocean-app-platform-database-migrations[DigitalOcean App Platform and Database Migrations] - Toni Talks Dev
+* https://blog.nundrum.net/posts-output/2023-12-07-clojure-to-clojurescript/[From Clojure to ClojureScript] - Nundrum
+* https://yamlscript.org/posts/advent-2023/dec-15/[Naughty is Nice!] - Ingy döt Net
+
+== Libraries and Tools
+
+New releases and tools this week:
+
+* https://github.com/balloneij/familiar-codox-theme[familiar-codox-theme] 0.1.0 - A Javadoc inspired Codox theme
+* https://github.com/roman01la/cljs-react-devtools[cljs-react-devtools]  - React DevTools for ClojureScript wrappers
+* https://github.com/noahtheduke/splint[splint] https://github.com/NoahTheDuke/splint/releases/tag/v1.11[1.11] - A Clojure linter focused on style and code shape
+* https://github.com/studistcorporation/sleepydog[sleepydog] 0.1.3 - Clojure library for tracing (possibly async) applications with Datadog
+* https://github.com/damn/gdl[gdl]  - Make 2D desktop games in clojure
+* https://github.com/clyfe/clara-eav[clara-eav] https://github.com/clyfe/clara-eav/blob/master/CHANGELOG.md#019---2023-12-15[0.1.9] - EAV triplets for Clara Rules
+* https://github.com/clj-kondo/clj-kondo[clj-kondo] https://github.com/clj-kondo/clj-kondo/blob/master/CHANGELOG.md#20231215[2023.12.15] - Static analyzer and linter for Clojure code that sparks joy
+* https://github.com/BetterThanTomorrow/joyride[joyride] https://github.com/BetterThanTomorrow/joyride/blob/master/CHANGELOG.md#0041---2023-12-13[0.0.41] - Making VS Code Hackable like Emacs since 2022
+* https://github.com/behrica/add-devcontainer[add-devcontainer] https://github.com/behrica/add-devcontainer/blob/main/CHANGELOG.md#03[0.3] - Babashka script which adds a devcontainer configuration to a clojure project in current folder
+* https://github.com/clj-commons/aleph[aleph] https://github.com/clj-commons/aleph/blob/master/CHANGES.md#070-rc1[0.7.0-rc1] - Asynchronous streaming communication for Clojure - web server, web client, and raw TCP/UDP
+* https://github.com/nextjournal/clojure-mode[clojure-mode] https://github.com/nextjournal/clojure-mode/blob/main/CHANGELOG.md#031[0.3.1] - Clojure/Script mode for CodeMirror 6
+* https://github.com/juji-io/datalevin[datalevin] https://github.com/juji-io/datalevin/blob/master/CHANGELOG.md#0825-2023-12-14[0.8.25] - A simple, fast and versatile Datalog database
+* https://github.com/squint-cljs/squint[squint] https://github.com/squint-cljs/squint/blob/main/CHANGELOG.md#v0482-2-23-12-14[0.4.82] - Light-weight ClojureScript dialect

content/reference/atoms.adoc

@@ -42,3 +42,16 @@ user=> "Elapsed time: 941.445 msecs"
 
 user=> "Elapsed time: 0.044 msecs"
 ----
+
+== Related functions
+
+Create an Atom: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/atom[atom]
+
+Examine an Atom: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/deref[deref] _(see also the +@+ <<reader#,reader>> macro)_
+
+Change Atom state: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/swap![swap!] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/reset![reset!] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/swap-vals![swap-vals!] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/reset-vals![reset-vals!]
+
+Validators: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/set-validator![set-validator!] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/get-validator[get-validator]
+
+Watchers: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/add-watch[add-watch] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/remove-watch[remove-watch]
+

content/reference/deps_and_cli.adoc

@@ -472,7 +472,7 @@ The resolve-deps args should be provided as an alias in one of deps sources and
 
 == Prepare JVM environment
 
-The JVM has many options and some programs also take configuration via Java system properties. JVM options can be passed on the command line for any execution specfier by prefixing with `-J`. If multiple options are specified, each must be prefixed.
+The JVM has many options and some programs also take configuration via Java system properties. JVM options can be passed on the command line for any execution specifier by prefixing with `-J`. If multiple options are specified, each must be prefixed.
 
 Additionally, main execution can take a map with key `:jvm-opts`: