Liking cljdoc? Tell your friends :D

polylith.clj.core.api.interface

If we want to build tooling around Polylith or e.g. use poly functionality in our build.clj file, then we can use the clj-poly library and get access to some of the functionality that is included in the poly command line tool.

The difference between the clj-poly library and the poly tool is that the latter is AOT compiled into Java bytecode, while the library is just a normal Clojure library (source code that is zipped into a jar file). This is good, because now we can expect the same behaviour from both.

We can use the poly tool as a library by including the clj-poly library as a dependency to a project's deps.edn file, e.g.:

:aliases {:dostuff {...
                    :extra-deps {...
                                 polylith/clj-poly {:mvn/version "0.2.19"}}

...or by selecting a sha from the polylith GitHub repo, e.g.:

...
polylith/clj-poly {:git/url   "https://github.com/polyfy/polylith.git"
                   :sha       "3b3e4ceac31d27f9a87862286f1ba01a3e4705ef"
                   :deps/root "projects/poly"}

As an example, the clj-poly library is first specified in the build alias in polylith's build.clj and then used in build.clj.

If you need more access than is exposed by the API at the moment, just reach out to the Polylith team in Slack and we will try to help out.

All other code that is not part of the public API, is used at your own risk, and may change in a breaking way between clj-poly versions.

If we want to build tooling around Polylith or e.g. use `poly` functionality in our
`build.clj` file, then we can use the [clj-poly](https://clojars.org/polylith/clj-poly) library
and get access to some of the functionality that is included in the `poly` command line tool.

The difference between the `clj-poly` library and the `poly` tool is that the latter is AOT compiled
into Java bytecode, while the library is just a normal Clojure library (source code that is zipped
into a jar file). This is good, because now we can expect the same behaviour from both.

We can use the `poly` tool as a library by including the `clj-poly` library
as a dependency to a project's `deps.edn` file, e.g.:
```clojure
:aliases {:dostuff {...
                    :extra-deps {...
                                 polylith/clj-poly {:mvn/version "0.2.19"}}
```

...or by selecting a [sha](https://github.com/polyfy/polylith/commits/master) from
the polylith GitHub repo, e.g.:
```clojure
...
polylith/clj-poly {:git/url   "https://github.com/polyfy/polylith.git"
                   :sha       "3b3e4ceac31d27f9a87862286f1ba01a3e4705ef"
                   :deps/root "projects/poly"}
```

As an example, the `clj-poly` library is first specified in the
[build](https://github.com/polyfy/polylith/blob/5ff79341e7dc3fc6a486584c6c2f2f46cb577d6e/deps.edn#L120)
alias in polylith's `build.clj` and then used in
[build.clj](https://github.com/polyfy/polylith/blob/9e79264981b0c5be6e6cb70c93a540a82c489510/build.clj#L83).

If you need more access than is exposed by the API at the moment, just reach out to the
Polylith team in [Slack](https://clojurians.slack.com/messages/C013B7MQHJQ)
and we will try to help out.

All other code that is not part of the public API, is used at your own risk,
and may change in a breaking way between `clj-poly` versions.
raw docstring

api-versionclj

The version of the different types of APIs, stored in a hash map with these keys:

 :api           The version of this API.
 :test-runner   The version of the test runner.
 :ws            The version of the workspace structure.

Each key stores a map with two keys:

 :breaking       Increased by one if a breaking change + :non-breaking is set to zero.
 :non-breaking   Increased by one if a non-breaking change.

When a new version of the clj-poly library is released to Clojars, any of the three APIs may change version, but the ambition is to never break :api and :test-runner.

With :ws it's different, and we know that the workspace structure will change over time, so pay extra attention every time you bump clj-poly and have a look at the versions page, which lists all the changes for different versions.

Examples of a breaking change of the workspace structure:

- If an attribute changes name.
- If an attribute is deleted.
- If an attribute starts to store its data in a breaking way.

Any changes that only add functionality/attributes, will increase the :non-breaking number by one.

If you use a SNAPSHOT version, then you can check next-release.adoc to get a summary of all the changes that have been made since the last stable/final release.

The version of the different types of APIs, stored in a hash map with these keys:
```clojure
 :api           The version of this API.
 :test-runner   The version of the test runner.
 :ws            The version of the workspace structure.
```

Each key stores a map with two keys:
```clojure
 :breaking       Increased by one if a breaking change + :non-breaking is set to zero.
 :non-breaking   Increased by one if a non-breaking change.
```

When a new version of the [clj-poly](https://clojars.org/polylith/clj-poly) library is released to Clojars,
any of the three APIs may change version, but the ambition is to never break `:api` and `:test-runner`.

With `:ws` it's different, and we know that the workspace structure will change over time, so pay extra
attention every time you bump `clj-poly` and have a look at the [versions](https://cljdoc.org/d/polylith/clj-poly/CURRENT/doc/versions) page,
which lists all the changes for different versions.

Examples of a breaking change of the workspace structure:
```
- If an attribute changes name.
- If an attribute is deleted.
- If an attribute starts to store its data in a breaking way.
```
Any changes that only add functionality/attributes, will increase the `:non-breaking` number by one.

If you use a SNAPSHOT version, then you can check [next-release.adoc](https://github.com/polyfy/polylith/blob/master/next-release.adoc)
to get a summary of all the changes that have been made since the last stable/final release.
sourceraw docstring

checkclj

(check)

The value of ok? is set to true if no error messages, e.g.:

{:ok? true
 :error-messages []}
The value of ok? is set to true if no error messages, e.g.:
```clojure
{:ok? true
 :error-messages []}
```
sourceraw docstring

projects-to-deployclj

(projects-to-deploy since)

Returns the projects that have changed (directly or indirectly) since the last stable point in time, and is primarily used to know which projects to build and deploy.

If called with:

(projects-to-deploy "release")

...it will execute the equivalent to this under the hood:

poly ws get:changes:changed-or-affected-projects since:release skip:development

...which returns all changed or affected projects, except development, since the last release. If since is passed in as nil then stable will be used.

Returns the projects that have changed (directly or indirectly) since the _last stable point in time_,
 and is primarily used to know which projects to build and deploy.

If called with:
```clojure
(projects-to-deploy "release")
```

...it will execute the equivalent to this under the hood:

```
poly ws get:changes:changed-or-affected-projects since:release skip:development
```

...which returns all changed or affected projects, except `development`, since the last release.
If `since` is passed in as `nil` then `stable` will be used.
sourceraw docstring

testclj

(test & args)

Runs tests. If since is not given, then "stable" will be used.

How to also include project tests since latest release (run tests incrementally).

(test :project "since:release")

How to run all tests since previous release for the 'myproject' project.

(test :all "since:previous-release" "project:myproject")

The arguments can come in any order.

Runs tests. If since is not given, then "stable" will be used.

How to also include project tests since latest release (run tests incrementally).
```clojure
(test :project "since:release")
```

How to run all tests since previous release for the 'myproject' project.
```clojure
(test :all "since:previous-release" "project:myproject")
```

The arguments can come in any order.
sourceraw docstring

workspaceclj

(workspace since & keys)

Returns the workspace or part of the workspace by passing in either a key that can be found in the :tag-patterns keys in workspace.edn optionally prefixed with previous-, or a git SHA, as the first argument, and a list of keywords, strings, or numbers as the second argument. :keys and :count are also valid keys to pass in.

Examples:

;; Returns the whole workspace structure, equivalent to: poly ws since:stable
(workspace nil)

;; Returns the whole workspace structure, equivalent to: poly ws since:release
(workspace "release")

;; Returns the interface namespace name, equivalent to: poly ws get:settings:interface-ns
(workspace nil "settings" "interface-ns")

Passing in since is only needed if we access things under the :changes top key or :bricks-to-test and :projects-to-test under :projects.

Avoid using things under :configs, if they can be found in e.g. :settings, :components, :bases, :projects, or elsewhere.

Note that since version 0.2.18 we only publish clj-poly to Clojars and not the old clj-api.

Returns the workspace or part of the workspace by passing in either
a key that can be found in the `:tag-patterns` keys in `workspace.edn`
optionally prefixed with `previous-`, or a git SHA, as the first argument,
and a list of keywords, strings, or numbers as the second argument.
`:keys` and `:count` are also valid keys to pass in.

Examples:
```clojure
;; Returns the whole workspace structure, equivalent to: poly ws since:stable
(workspace nil)

;; Returns the whole workspace structure, equivalent to: poly ws since:release
(workspace "release")

;; Returns the interface namespace name, equivalent to: poly ws get:settings:interface-ns
(workspace nil "settings" "interface-ns")
```

Passing in `since` is only needed if we access things under the `:changes` top key
or `:bricks-to-test` and `:projects-to-test` under `:projects`.

Avoid using things under `:configs`, if they can be found in e.g. `:settings`,
`:components`, `:bases`, `:projects`, or elsewhere.

Note that since version `0.2.18` we only publish `clj-poly` to Clojars and not the old `clj-api`.
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close