Workspace
Let’s start by creating the
example
workspace with the top namespace se.example
by using the create workspace command (create w
works as well as create workspace
). Make sure you execute the command outside a git repository:poly create workspace name:example top-ns:se.example :commit
This will create a workspace in the
main
branch. By giving branch:BRANCH-NAME
the workspace can be created in a different branch, e.g.:poly create workspace name:example top-ns:se.example branch:master :commit
Note: In version0.2.13-alpha
and earlier, the workspace was automatically initiated as a git repository when we created a workspace, but from0.2.14-alpha
and later, we have to pass in:commit
to get the same behaviour. We will talk more about this in theGit
section.
The workspace directory structure will end up like this:
example # workspace dir
├── .git # git repository dir
├── bases # bases dir
├── components # components dir
├── deps.edn # development config file
├── development
│ └── src # development specific code
├── logo.png # polylith logo
├── projects # projects dir
├── readme.md # documentation
└── workspace.edn # workspace config file
The directory structure is designed for quick navigation and ease of use. It helps us to understand and find all our service-level building blocks, which lets us reason about the system at a higher level.
Each top-level directory contains a specific type of Polylith concept. A
base
is a building block that exposes a public API to external systems. A component
is a building block for encapsulating a specific domain or part of the system. A project
specifies our deployable artifacts and what components, bases, and libraries they contain. Finally, we have the development
project (development
+ deps.edn
) that we use to work with the code in one place.This structure gives a consistent shape to all Polylith projects and ensures that both new developers and veterans can quickly understand and start working with systems that are new to them. We think you will soon be addicted to the power and simplicity the Polylith structure gives to your projects!
The
bases
, components
and projects
directories also contain a .keep
file, which is added to prevent git from deleting these directories, and can be removed as soon as we add something to them.The
workspace.edn
file looks like this:{: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"}}}
...and
deps.edn
like this:{:aliases {:dev {:extra-paths ["development/src"]
:extra-deps {org.clojure/clojure {:mvn/version "1.11.1"}}}
:test {:extra-paths []}
:poly {:main-opts ["-m" "polylith.clj.core.poly-cli.core"]
:extra-deps {polyfy/polylith
{:git/url "https://github.com/polyfy/polylith"
:sha "a1581ccc87009127f2151579b826258dd57e3077"
:deps/root "projects/poly"}}}}}
Note: Version0.2.14-alpha
contains a bug which adds a space in"1.10.1"
that you need to remove manually!
If all went well, the
poly
tool managed to set the latest sha for the :poly
alias by taking it from the master
branch in this repository. We can instruct it to go and get it by passing in :latest-sha
:cd example
poly ws get:settings:vcs:polylith :latest-sha
The output will look something like this:
{:branch "master",
:latest-sha "887e4237cec8f42eaa15be3501f134732602bb41",
:repo "https://github.com/polyfy/polylith.git"}
The
:latest-sha
argument will tell the tool to go out and find the latest SHA from the Polylith repo and populate the :latest-sha
attribute, which would otherwise not be set.If you wonder how the
ws
command works or what all the settings are for, be patient, everything will soon be covered in detail.A polylith workspace can also be created inside an existing git repo. When we do that, we have two alternatives. Either we create the workspace directly at the root of the git repository by executing e.g.:
cd my-git-repo-dir
poly create workspace top-ns:com.mycompany
my-git-repo-dir
├── bases
├── components
├── deps.edn
├── development
├── projects
└── workspace.edn
...or we put the workspace in a directory under the git repository by executing e.g.:
cd my-git-repo-dir
poly create workspace name:my-workspace top-ns:com.mycompany
my-git-repo-dir
└── my-workspace
├── bases
├── components
├── deps.edn
├── development
├── projects
└── workspace.edn
To execute a command, we need to be at the root of the workspace, e.g.:
cd my-workspace
poly info
Last modified 5mo ago