Workspace (Workspace v0.2.1)
View SourceA Workspace
is a collection of mix projects under the same git repo.
Workspace
provides a set of tools for working with multiple projects under
the same git repo. Using path dependencies between the projects and the
provided tools you can effectively work on massive codebases properly
split into reusable packages.
Structuring a folder as a workspace root
A workspace is a normal Mix.Project
with some tweaks:
- No actual code is expected, so
:elixirc_paths
is set to[]
- It must have a
:workspace
project option configured with a:type
set to:workspace
.
def project do
[
workspace: [
type: :workspace,
# arbitrary options can be set there
],
# rest Mix.Project settings
]
end
A generator is provided for bootstrapping a new workspace project:
$ mix workspace.new NAME
Workspace projects
A mix project is considered a workspace project if:
- it is located in a subfolder of the workspace root path
- it is not included in the ignored projects or ignored paths in the workspace config
Assuming the folder structure:
my_workspace
├── apps
│ ├── api # an API app
│ └── ui # the UI project
├── mix.exs # this is the workspace root definition
├── .workspace.exs # the workspace config
└── packages # various reusable packages under packages
├── package_a
├── package_b
└── package_c
In the above example:
- We have defined a
Workspace
undermy_workspace
folder - All mix projects under
my_workspace
are by default considered workspace packages. In the above example it will include the:api
,:ui
,:package_a
,:package_b
and:package_c
packages.
Ignoring a package or a path
Assume you want to exclude package_c
from the workspace. You
can add it to the :ignore_projects
configuration option in
.workspace.exs
:
ignore_projects: [:package_a]
If you wanted to ignore all projects under an other
folder
you could set the :ignore_paths
option:
ignore_paths: ["other"]
Notice that in the latter case the path is assumed to be relative to the workspace root.
For more details check the Workspace.Config
documentation.
Duplicate package names
Notice that duplicate package names are not allowed. If upon initialization
of a workspace two projects with the same :name
are detected then
an exception will be raised.
For example the following workspace:
my_workspace
├── apps
│ └── api
├── mix.exs
├── packages
│ ├── package_a # package_a project defined under packages
│ └── package_b
└── shared
└── package_a # redefinition of package_a
would fail to initialize since :package_a
is defined twice.
Loading a workspace
A Workspace
can be constructed by calling the new/2
function. It
will use the given path and config object in order to load and validate
all internal projects.
The workspace graph
The most important concept of the Workspace
is the projects graph. The
project graph is a directed acyclic graph where each vertex is a project
and each edge a dependency between the two projects.
The workspace graph is constructed implicitly upon workspace's creation in order to ensure that all path dependencies are valid and decorate each project with graph metadata.
Inspecting the graph
You can use the workspace.graph
command in order to see the
graph of the given workspace
. For example:
mix workspace.graph --workspace-path test/fixtures/sample_workspace
on a test fixture would produce:
package_a
├── package_b
│ └── package_g
├── package_c
│ ├── package_e
│ └── package_f
│ └── package_g
└── package_d
package_h
└── package_d
package_i
└── package_j
package_k
You can additionally plot is as mermaid graph by specifying the
--format mermaid
flag:
Workspace filtering
As your workspace grows running a CI task on all projects becomes too slow. To address this, code change analysis is supported in order to get the minimum set of projects that need to be executed.
Workspace
supports various filtering modes. Each one should be used in
context with the underlying task. For more details check filter/2
.
Global filtering options
:ignored
- ignores these specific projects:selected
- considers only these projects:only_roots
- considers only the graph roots (sources), e.g. ignores all projects that have a parent in the graph.
Code analysis related options
:modified
- returns only the modified projects, e.g. projects for which the code has changed:affected
- returns all affected projects. Affected projects are the modified ones plus the
:modified
and :affected
can be combined with the global filtering options.
Understanding when and how to filter a workspace
Workspace filtering should be actively used on big workspaces in order to improve the local build and CI times.
Some examples follow:
- If a workspace is used by multiple teams and contains multiple apps, you should select a specific top level app when building the project. This will ignore all other irrelevant apps.
- When changing a specific set of projects, you should use
:modified
for formatting the code since everything else is not affected. - Similarly for testing you should use the
:affected
filtering since a change on a project may affect all parents. - It is advised to have generic CI pipelines on master/main branches that do not apply any filtering.
Visualizing what is affected
You can use the --show-status
flag in most of workspace
commands to indicate
what is unchanged, modified or affected.
For instance if you have changed package_f
and package_d
you can visualize
the graph using workspace.graph --format mermaid --show-status
Modified projects are indicated with red colors, and affected projects are highlighted with orange color.
You could now use the proper filtering flags based on what you want to run:
# We want to build only the top level affected projects
mix workspace.run -t compile --only-roots --affected
# we want to format only the modified ones
mix workspace.run -t format --modified
# we want to test all the affected ones
mix workspace.run -t test --affected
Environment variables
The following environment variables are supported:
WORKSPACE_DEBUG
- if set then debug information will be printed.
Environment variables that are not meant to hold a value (and act basically as
flags) should be set to either 1
or true
, for example:
$ WORKSPACE_DEBUG=true mix workspace.check
Multiple workspaces under the same git repo
You can have multiple workspaces under the same git repo with the only constraint that they cannot be nested.
Nested workspaces
Notice that nested workspaces are not allowed, for example if you have the following structure:
workspace
├── .workspace.exs
├── another_workspace
│ ├── .workspace.exs
│ └── mix.exs
└── mix.exs
an error will be raised.
This may be useful if you have a monorepo with various projects that have different dependencies and/or different teams managing them with different policies.
For example, assuming a git repo under my-repo
you could create as many workspaces as
you wish:
$ cd my-repo
$ mix workspace.new common
$ mix workspace.new backend
$ mix workspace.new frontend/app_a
Isolated workspaces
Each workspace is treated in isolation, e.g. changes on workspace common
do not
affect the status of workspace backend
, even if there are path dependencies
between the two workspaces.
Running workspace commands from the root of the repo
If you wish you can install workspace
at the root, and install commands from
there, specifying the workspace path. This way you will not have to cd
into the
different workspaces, improving the developer experience.
You will need a minimal mix.exs
at the root for istalling workspace
:
defmodule Root.MixWorkspace do
use Mix.Project
def project do
[
app: :root,
version: "0.2.0",
elixir: "~> 1.15",
start_permanent: Mix.env() == :prod,
deps: deps(),
elixirc_paths: []
]
end
def application do
[
extra_applications: []
]
end
defp deps do
[
{:workspace, "~> 0.2"}
]
end
end
Now from the root you can run workspace commands on any workspace:
$ mix workspace.list --workspace-path common
$ mix workspace.status --workspace-path frontend/app_a
Summary
Functions
Creates a new Workspace
from the given workspace path
Similar to new/2
but raises in case of error.
Get the given project from the workspace.
Similar to project/2
but raises in case of error
Returns true
if the given app
is a workspace
project, false
otherwise.
Returns the workspace projects as a list.
Functions
@spec new(path :: binary(), config_or_path :: keyword() | binary()) :: {:ok, Workspace.State.t()} | {:error, binary()}
Creates a new Workspace
from the given workspace path
config_or_path
can be one of the following:
- A path relative to the workspace root path pointing to the workspace config
(
.workspace.exs
in most cases) - A keyword list with the config
The workspace is created by finding all valid mix projects under the workspace root.
Returns {:ok, workspace}
in case of success, or {:error, reason}
if something fails.
@spec new!(path :: binary(), config :: keyword() | binary()) :: Workspace.State.t()
Similar to new/2
but raises in case of error.
@spec project(workspace :: Workspace.State.t(), app :: atom()) :: {:ok, Workspace.Project.t()} | {:error, binary()}
Get the given project from the workspace.
If the project is not a workspace member, an error tuple is returned.
@spec project!(workspace :: Workspace.State.t(), app :: atom()) :: Workspace.Project.t()
Similar to project/2
but raises in case of error
@spec project?(workspace :: Workspace.State.t(), app :: atom()) :: boolean()
Returns true
if the given app
is a workspace
project, false
otherwise.
Returns the workspace projects as a list.
Options
:order
- Specifies the order in which the projects list will be returned. It can be one of the following::alphabetical
- Sorts the projects by their application names in ascending order.:postorder
- Performs a depth-first search on the project graph and returns the projects in post-order. In this order, outer leaves (projects without dependencies) are returned first, followed by their parent projects, respecting the dependency relationships between them.- If not specified, the projects will be returned in their original order without any sorting.
For example for the following workspace graph:
we would get the following:
Workspace.projects(workspace, order: :alphabetical) # [:bar, :baz, :foo, :zoo] # with :postorder set the packages are returned bottom to top respecting # dependencies, notice this is not deterministic, e.g. you could also get # [:baz, :bar, :foo, :zoo] Workspace.projects(workspace, order: :postorder) # [:baz, :foo, :bar, :zoo]