Liking cljdoc? Tell your friends :D

Install

There are two ways to install the poly tool:

1. Stand-alone2. Clojure CLI dep

Example usage:

poly help

clojure -M:poly help

Installed via:

Homebrew on macOS, otherwise via Nix or a manual download

Adding a :poly alias in ./deps.edn

Can be invoked from:

Any directory

A Polylith workspace directory

Switch poly version via:

@<version> if using HomeBrew

Updating dependency for :poly alias in ./deps.edn

Pre-compiled for faster startup? 1

Yes

No

Table Notes:

  1. If you follow our recommendation of using the poly shell, startup time is not much of a concern.

Install as Stand-alone on macOS

First, ensure that you have Clojure CLI and git installed. If you are installing git for the first time, don’t forget to configure your git user.name and user.email.

To install the poly tool on macOS, run:

brew install polyfy/polylith/poly

The poly script is now installed and added to the system path. The script uses Java to launch the poly tool.

If you get an error such as "openjdk-13.0.2.jdk could not be opened…​", try:

  • Open MacOS System Preferences > Security & Privacy > General.

  • Click Allow at the bottom for openjdk-13.0.2.jdk.

  • Run brew install polyfy/polylith/poly again.

Verify the installation by running poly help.

You will soon create your first workspace - for now, only version, help, doc, and create workspace commands will work.

Install as Stand-alone on Linux

First, ensure that you have Clojure CLI and git installed. If you are installing git for the first time, don’t forget to configure your git user.name and user.email.

To install the poly tool on Linux:

  • Download the latest release of the poly jar, e.g.: poly-0.2.22.jar.

  • Create a directory, e.g., /usr/local/polylith, and copy the jar file to that directory.

  • Create a file poly under e.g., /usr/local/bin containing:

    #!/bin/sh

ARGS=""
while [ "$1" != "" ] ; do
 ARGS="$ARGS $1"
 shift
done

exec "/usr/bin/java" $JVM_OPTS "-jar" "/usr/local/polylith/poly-0.2.22.jar" $ARGS

  • Make sure that:

    • You are referencing the correct jar file.

    • The path to java is correct (verify with which java).

  • If you chose /usr/local/bin, it is probably already on your system path. Otherwise, adjust your system path as necessary.

  • Make poly executable via chmod +x /usr/local/bin/poly (adjust path as necessary).

Verify the installation by running poly help.

You will soon create your first workspace - for now, only version, help, doc, and create workspace commands will work.

Install Stand-alone on Windows

First, ensure that you have Clojure CLI and git installed. If you are installing git for the first time, don’t forget to configure your git user.name and user.email.

Troubleshooting Clojure CLI Install on Windows

If you are running on Windows, you might prefer to use the more user-friendly clj-msi.
Windows users should also consider using WSL and then follow instructions under Install as Stand-alone on Linux.

If you have installed Clojure’s Powershell module and see an error like:

clj : The 'clj' command was found in the module 'ClojureTools', but the module could not be loaded.
For more information, run 'Import-Module ClojureTools'.

…​and if you followed the instruction and executed this:

Import-Module ClojureTools

…​and got this error:

Import-Module : File C:\Users\Admin\Documents\WindowsPowerShell\Modules\ClojureTools\ClojureTools.psm1
cannot be loaded because running scripts is disabled on this system. For more information,
see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.

…​then try this:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Install the poly tool

  • Download the latest release of the poly jar, e.g., poly-0.2.22.jar.

  • Create a Polylith directory, e.g., C:\Program Files\Polylith, and copy the poly jar file to that directory.

  • In the same directory, create file poly.bat containing:

    @echo off
start /wait /b java %JAVA_OPTS% -jar "C:\Program Files\Polylith\poly-poly-0.2.22.jar" %*

    Double-check that it references the correct poly jar.

  • Add C:\Program Files\Polylith to the Windows Path environment variable.

Test the installation by typing poly help from the command line.

You will soon create your first workspace - for now, only version, help, doc, and create workspace commands will work.

The coloring of text is not supported on Windows.

Install as Stand-alone via Nix

First, ensure that you have Clojure CLI and git installed. If you are installing git for the first time, don’t forget to configure your git user.name and user.email.

The poly tool is installable from nixpkgs:

nix-shell -p polylith
# or
nix-env -iA 'nixos.polylith'

Test the installation by typing poly help from the command line.

You will soon create your first workspace - for now, only version, help, doc, and create workspace commands will work.

Use as Dependency

An alternative way to run the poly tool is as a dependency from the :poly alias in your ./deps.edn file.

First, ensure that you have Clojure CLI and git installed. If you are installing git for the first time, don’t forget to configure your git user.name and user.email.

After you have created a Polylith workspace, you’ll notice a ./deps.edn file was automatically generated. It includes a :poly alias. It will look something like:

 :aliases {:poly {:extra-deps {polylith/clj-poly {:mvn/version "0.2.22"}}
                  :main-opts  ["-m" "polylith.clj.core.poly-cli.core"]}}

Feel free to adjust the :mvn/version to suit your needs. For example, you might want to try out the latest SNAPSHOT version.

Docs for SNAPSHOT releases are also available on cljdoc.

Navigate to your newly created workspace directory and verify via clojure -M:poly help.

If you have no interest in using any stand-alone variant of poly and want to use poly only as a dependency, see Bootstrapping a Workspace.

For more details on how poly is released, see docs on releases.

Using a Git Dependency

If you wish, you can specify a git dep revision from the GitHub Polylith project. To do so, you’d adjust your ./deps.edn :poly alias to something like:

 :aliases {:poly {:extra-deps {polylith/clj-poly
                               {:git/url   "https://github.com/polyfy/polylith.git"
                                :sha       "INSERT-SHA-HERE"
                                :deps/root "projects/poly"}}
                  :main-opts  ["-m" "polylith.clj.core.poly-cli.core"]}}

Replace INSERT-SHA-HERE with a commit SHA from the Polylith repository, for example:

  1. From the latest commit from the master branch. (Alternatively, you can specify the latest SNAPSHOT release as a maven dependency)

  2. Or some commit SHA from a work-in-progress branch you want to try

Specifying Logging Libraries

You can add in the logging libraries you’d like to use with poly by adjusting your :poly alias in your ./deps.edn like so:

 :aliases {:poly {:extra-deps {polylith/clj-poly {:mvn/version "{poly-version}"}
                               ;; your logging libraries here:
                               org.apache.logging.log4j/log4j-api {:mvn/version "2.20.0"}
                               org.apache.logging.log4j/log4j-slf4j-impl {:mvn/version "2.20.0"}}
                  :main-opts  ["-m" "polylith.clj.core.poly-cli.core"]}}

Use as a library

The poly functionality can also be accessed as a library. The API is documented here.

JVM options

You might want to specify more RAM to the poly tool and/or where the configuration file for logging is located. These can be conveyed via the JVM_OPTS environment variable which poly will passes along to the Java runtime at launch of poly stand-alone.

❮IntroductionUpgrade❯

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
Raise an issueBrowse cljdoc sourceChat on Slack
× close