Skip to content

Commit f577d94

Browse files
dmillerdmiller
committed
Extensive edit on the README
1 parent 93b1f66 commit f577d94

File tree

1 file changed

+154
-0
lines changed

1 file changed

+154
-0
lines changed

‎README.md

+154
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,161 @@
22

33
An implementation of the Clojure CLI tool and deps.edn tooling for ClojureCLR.
44

5+
For ClojureCLR on .NET 6 and later.
56

67
## Releases
78

89
The current release is 0.0.1-alpha1.
10+
11+
12+
## Installation
13+
14+
`cljr` is installed as a `dotnet tool`.
15+
16+
17+
## An introduction to deps.edna and the CLI
18+
19+
You can start by reading these references:
20+
21+
- [Clojure CLI Reference](https://clojure.org/reference/clojure_cli)
22+
- Ignore the nstallation and usage sections; we'll cover this below.
23+
- [deps.edn Reference](https://clojure.org/reference/deps_edn)
24+
25+
26+
## Intallation
27+
28+
`cljr` is installed as a `dotnet tool`:
29+
30+
```
31+
dotnet tool install asdfasdfasdfasdfasdf
32+
```
33+
34+
35+
You should see output similar to this:
36+
37+
38+
39+
You can now invoke `cljr` from the command line.
40+
41+
## Functionality
42+
43+
A significant portion of the functionality of the JVM version is available.
44+
Some parts await development. Some likly will never be implemented.
45+
46+
There are two ways to invoke the JVM tool: as 'clj' and as 'clojure'.
47+
As the docs state: "In general, you can treat these interchangeably but `clj` includes `rlwrap` for extended keyboard editing, particularly useful with the REPL.
48+
This reference uses `clj` for REPL examples and `clojure` for non-REPL examples."
49+
50+
`cljr` does not have this distinction (for now). There is just `cljr`.
51+
52+
The status of the primary commands and the command line options is detailed below.
53+
In general terms, tools and deps prep are not supported yet. Anything related to Maven or JVM is not supported.
54+
Most other things are ready for testing.
55+
56+
57+
| Command | Invocation | Implemented? |
58+
|:------------|:-----------|:-------------|
59+
| Start a repl (default) | `cljr [clj-opts] [-Aaliases]` | Yes |
60+
| Execute a function (-X) | `cljr [clj-opts] -Xaliases my/fn? [kpath v ... ] kv-map? `| Yes |
61+
| Run a tool (-T) | `cljr [clj-opts] -T[name|aliases] my/fn [kpath v ...] kv-map?` | Not yet |
62+
| Run a main namespace or script (-M) | `cljr [clj-opts] -M[aliases] [init-opts] [main-opts] [args]` | Yes |
63+
64+
The status of the options:
65+
66+
| Option | Description | Status |
67+
|:-------|:------------|:-------|
68+
|exec-opts:|
69+
| -Aaliases | Apply aliases | Supported |
70+
| -X[aliases] | Invoke function, using aliases | Supported |
71+
| -Ttoolname | Invoke tool by local name | Supported |
72+
| -T[aliases] | Invoke tool using aliases | Supported |
73+
| -M[aliases] | Invoke clojure.main, using aliases | Supported |
74+
| -P | Prepare deps but don't exec | Not yet |
75+
||
76+
|clj-opts: |
77+
| -Jopt | Pass JVM option | Irrelevant |
78+
| -Sdeps EDN | Extra deps.edn data | Supported |
79+
| -Srepro | Ignore user deps.edn file | Supported |
80+
| -Spath | Compute and echo classpath | Supported |
81+
| -Stree | Print dependency tree | Supported |
82+
| -Scp CP | Use this classpath, ignore deps.edn | Supported |
83+
| -Sforce | Force classpath computation | Supported |
84+
| -Sverbose | Print path info | Supported |
85+
| -Sdescribe | Print env and command parsing info | Supported |
86+
| -Sthreads | Set specific number of download threads | Not supported |
87+
| -Strace | Write dep expansion trace.edn | Supported |
88+
| --version | Print version to stdout and exit | Supported |
89+
| -version | Print version to stderr and exit | Supported |
90+
| --help -h -? | Print this help message | Supported |
91+
||
92+
|Programs provided by :deps alias:
93+
| -X:deps list | Print deps list+licenses | Supported |
94+
| -X:deps tree | Print deps tree | Supported |
95+
| -X:deps find-versions | Find available lib versions | Supported |
96+
| -X:deps prep | Prepare all unprepped libs in deps | Not supported (yet) |
97+
| -X:deps mvn-pom | Generate pom.xml for deps.edn | Not supported |
98+
| -X:deps mvn-install | Install maven jar to local repo | Not supported |
99+
100+
## deps.edn features
101+
102+
Most of the features of `deps.edn` files are supported.
103+
104+
-- We support git lib and local directory dependencies only. We do not support maven dependencie or local jars. (Though we should have a discussion about the latter.)
105+
-- We are still thinking about how nuget might come into play. It's complicated.
106+
-- We do not yet have support for tool publishing and preparation steps. See below.
107+
108+
Generally, one puts a `deps.edn` file in the root directory of your code. However, for projects that support multiple Clojure ports (JVM, CLR, Clojurescript), this will not always work.
109+
For example, the JVM version may want to use Maven repos for dependencies, which the CLR version does not support.
110+
111+
However, we cannot just read-conditionalization the `deps.edn` file because read-conditionalization is not supported in EDN files.
112+
The workaround is that `cljr` will look for a file named `deps-clr.edn` first, then look for `deps.edn`. This provides an override that `cljr` can see and the JVM tools will ignore.
113+
114+
115+
## Running tests
116+
117+
If you would like to run tests of your project from the command line, you can take advantage of a port of [cognitect-labs/test-runner](https://github.com/cognitect-labs/test-runner) available at [dmiller/test-runner](https://github.com/dmiller/test-runner).
118+
(If you want to look at the code, look in branch `clr-port`.)
119+
120+
Here is a sample `deps.edn` file set up to use this port of `test-runner`:
121+
122+
```Clojure
123+
{:paths ["src/main/clojure"]
124+
:deps
125+
{io.github.clojure/clr.data.generators {:git/tag "v1.1.0" :git/sha "d25d292"}}
126+
127+
:aliases
128+
{:test
129+
{:extra-paths ["src/test/clojure"]
130+
:extra-deps {io.github.dmiller/test-runner {:git/tag "v0.5.1clr" :git/sha "814e06f"}}
131+
;; :main-opts ["-m" "cognitect.test-runner" "-d" "src/test/clojure"]
132+
:exec-fn cognitect.test-runner.api/test
133+
:exec-args {:dirs ["src/test/clojure"]}}}}
134+
```
135+
136+
You would invoke test running via
137+
138+
```
139+
cljr -X:test
140+
```
141+
142+
## Notes
143+
144+
This is an alpha release. Have at it.
145+
146+
We need some design thinking around tools and prepping. Most of the library support on the JVM side are very specific to the JVM world: Maven, jars, Java-ish things.
147+
What is needed to support robust program development and installation in the CLR world. Please weigh in.
148+
149+
150+
# Copyright and License
151+
152+
Copyright © Rich Hickey and contributors
153+
154+
All rights reserved. The use and
155+
distribution terms for this software are covered by the
156+
[Eclipse Public License 1.0] which can be found in the file
157+
epl-v10.html at the root of this distribution. By using this software
158+
in any fashion, you are agreeing to be bound by the terms of this
159+
license. You must not remove this notice, or any other, from this
160+
software.
161+
162+
[Eclipse Public License 1.0]: https://opensource.org/license/epl-1-0

0 commit comments

Comments
 (0)