Workspace — polylith/clj-poly 0.2.20

Workspace

The workspace directory is where all your code and most of your configuration lives.

Unless otherwise noted, our examples assume poly is installed as a stand-alone tool. Adjust your command line if you’ve installed poly differently.

See also: Bootstrapping a Workspace.

Let’s start our tutorial by creating an example workspace with a top namespace of se.example using the create workspace command. By default, this command also creates a git repository, so execute it outside any existing git repository:

poly create workspace name:example top-ns:se.example branch:main :commit

The poly tool has created an example workspace in the main branch of a new git repository and committed all files.

The se.example top namespace is just an example. Stick with this name when following this example, but choose whatever name makes sense when creating your own Polylith workspaces.

If the branch parameter is not provided, the default branch will be used. You can retrieve the default branch name using the following command:

git var GIT_DEFAULT_BRANCH

Your workspace directory structure should look like this:

example                # Workspace dir
├── .git/              # Git repository dir
├── .gitignore         # Files and dirs git should ignore
├── .vscode/
│   └── settings.json  # Configuration for Calva
├── bases/             # Dir for poly bases
├── components/        # Dir for poly components
├── deps.edn           # Config for development project
├── development/
│   └── src/           # Development project sources
├── logo.png           # Polylith logo
├── projects/          # Dir for deployable projects
├── readme.md          # Documentation
└── workspace.edn      # Workspace config file

We designed the directory structure for quick navigation and ease of use. Your service-level building blocks are easy to find and understand, which helps you to reason about your system at a higher level.

Each top-level directory contains a specific Polylith concept:

A base is a building block that exposes a public API to the outside world, e.g., external systems and users.
A component is a building block that encapsulates a specific domain or part of the system.
A project specifies a deployable artifact and what components and bases it contains.
The development project (development/ + deps.edn) supports working on all code from one place.

This structure gives a consistent shape to all Polylith projects. The familiar convention ensures that all developers, be they new or veterans, will quickly get started on Polylith systems that are new to them. We think you will fall in love with the power and simplicity the Polylith structure gives to your projects!

The bases, components, and projects directories include a .keep file. This file ensures that git tracks these otherwise empty directories. You can delete the .keep files after you add other files.

The workspace.edn file looks like:

{:top-namespace "se.example"
 :interface-ns "interface"
 :default-profile-name "default"
 :compact-views #{}
 :vcs {:name "git"
       :auto-add false}
 :tag-patterns {:stable "stable-*"
                :release "v[0-9]*"}
 :projects {"development" {:alias "dev"}}}

The deps.edn file:

{:aliases  {:dev {:extra-paths ["development/src"] (1)
                  :extra-deps {org.clojure/clojure {:mvn/version "1.11.1"}}}

            :test {:extra-paths []} (2)

            :poly {:main-opts ["-m" "polylith.clj.core.poly-cli.core"] (3)
                   :extra-deps {polyfy/clj-poly {:mvn/version "0.2.18"}}}}}

1	The `:dev` alias supports your Polylith development environment
2	The `:test` alias supports your tests
3	The `:poly` alias allows you to run `poly` as a local dependency, e.g., `clj -M:poly version`, and isn’t used by `poly` stand-alone.

Existing git Repository

You can also create a Polylith workspace inside an existing git repo. There are two ways to do this. Either you create the workspace directly at the root of the git repository (without giving a workspace name) by executing:

cd my-git-repo-dir
poly create workspace top-ns:com.mycompany

…which results in:

my-git-repo-dir
├── bases
├── components
├── deps.edn
├── development
├── projects
└── workspace.edn

…or you create the workspace in a directory under the git repository root by executing e.g.:

cd my-git-repo-dir
poly create workspace name:my-workspace top-ns:com.mycompany

…which result in:

my-git-repo-dir
└── my-workspace
    ├── bases
    ├── components
    ├── deps.edn
    ├── development
    ├── projects
    └── workspace.edn

In the above examples you’ll notice we ommitted the :commit option. It is not supported when creating a workspace in an existing git repository. You’ll have to commit your new workspace files yourself.

To execute a command, you need to be at the root of your workspace:

cd my-workspace
poly info

Bootstrapping a Workspace

If you don’t have a stand-alone version of poly installed and prefer to use poly as a dependency, you can bootstrap your workspace.

All techniques above still apply, but you will instead create a workspace like so:

clojure -Sdeps '{:deps {polylith/clj-poly {:mvn/version "RELEASE"}}}' \
        -M -m  polylith.clj.core.poly-cli.core \
        create workspace name:example top-ns:se.example :commit

And now you can use poly as a dependency:

cd example
clojure -M:poly info