Deps is a simple tool for managing dependencies in Clojure projects. It's designed by the Clojure core team to facilitate two main things - managing dependencies and creating a classpath. It deliberately takes a different approach to Leiningen which is a batteries-included do-everything tool, but Deps has seen a lot of uptake because for the projects it works for it works very well, and it's considerably simpler than Leiningen and other alternatives. Let's see how to use Deps with Cursive.
Deps does require us to set a few things up before we get started. Deps is integrated with the relatively new Clojure command line tooling, but at the time of writing the command line tools are still not available on Windows. So the install instructions will depend on your OS. You can also perform this configuration when creating or importing your first Deps project, as shown below.
Install the command line tools according to the instructions. Then, go to Settings→Build, Execution, Deployment→Build Tools→Clojure Deps in the tree on the left.
In this panel, select "Use CLI tools", and enter the path to the
clojure command if required. Cursive will try to
find it in various standard locations, but if your package manager installs it in a non-standard location enter the
path here. When the path is correct, Cursive should display the CLI version and config dir location as shown here. If
that's showing, then you should be good to go!
If you're running Windows, then select the "Use tools.deps directly" option. This means that Cursive will download
tools.deps.alpha and use it as a library rather than calling out to the command line. Press Refresh, and Cursive
will download the list of available versions - generally the most recent is the one you want. Once you have the version
you want selected in the dropdown, press Download and Cursive will download that version to use.
If you're in an environment where you don't have outbound access to the internet and you're using an internal Maven repo to fetch your deps, you can use the "Use private repo" option and specify the ID and the URL of your internal repo. Cursive will also respect the IntelliJ HTTP proxy configuration when fetching Deps.
Finally, there's one limitation of this approach. Currently the system
deps.edn file is bundled with the command line
tools, so this option will cause a version of that file bundled with Cursive to be used. You can also specify the path
to the user
deps.edn file you'd like Cursive to use, this can be useful when sharing config with WSL.
To create a new project in IntelliJ, if you're at the welcome screen, click the "Create New Project" link, or if you already have a project open in IntelliJ you can use . In the following dialog, choose "Clojure" from the list of project types on the left-hand side. You'll then have a list of Clojure project types to choose from on the right. Here you can choose "Deps".
On the next screen, choose whether to use auto-import or not. This means that your project will be automatically
refreshed after you modify the
deps.edn file, and is generally a good idea.
On the next screen, give your project a name and decide where to put it:
Then, when you click "Finish" you'll have a new project to work with!
If you already have an existing project you'd like to start with, let's see how to do that.
From the welcome screen, click the "Import Project" link, or if you already have a project
open in IntelliJ you can use . Here,
you can select either the
deps.edn file or the directory containing it.
If required, select "Import project from external model" and select Deps.
In the next panel, the root directory of your project will be filled in for you. You can also choose to use auto-import
(which means that your project will be automatically refreshed after you modify the
deps.edn file) and to automatically
create content roots (i.e.
test directories) if they don't exist.
You can expand out the Global Clojure Deps settings section to configure Deps in a similar manner to the preferences pane earlier.
Finally, press 'Finish' to actually import the project.
Your project will then be opened and is ready to use.
For simple projects you don't need to explicitly import them. Just use , select either
deps.edn file or the containing directory, and your project will be automatically imported.
Often Deps projects will use aliases for different situations. Since aliases will often add source roots and dependencies that you'll need when working with your source code, you can let Cursive know which ones it should use when synchronising your project.
To do that, open the Deps toolwindow, then expand out the Aliases tree. Select the aliases you'd like to use when synchronising, then refresh your project using the icon.
One thing that is very useful when working with Deps is being able to see a tree of the dependencies of your project.
On the command line you would use
clojure -Stree to show this, but Cursive will show you this within the IDE too,
also in the Deps toolwindow. The dependencies are nested in a tree structure so you can see how each dependency
was pulled into your project:
When you have updated your
deps.edn file, you can press the icon to
re-read the project file and refresh the project dependencies. This will be performed automatically after a short delay
if you selected the auto-import option when setting up your project.
If you have a more complex project with multiple modules, Cursive will generally detect it automatically and set everything up. However because of a limitation of the IntelliJ framework which the Cursive Deps support uses, only one project at a time can be imported. This can be problematic because often the root directory of your main project isn't exactly where that one project is located. Here's how to work around this:
We'll start by creating an empty project. If you're at the welcome screen, click the "Create New Project" link, or if you already have a project open in IntelliJ you can use . In the following dialog, choose "Empty Project" from the list of project types on the left-hand side.
In the next pane, give your project a name and enter the location of the root of your main project:
When you click Finish, a new empty project will be set up and the Project Structure view will be opened so you can add some modules to it. Select Modules in the list on the left hand side, then click the icon to import a module to the project:
As before, we can adjust some settings of the new module, then press OK.
As you can see here, Cursive has actually imported various modules, not just one. This is because it transitively
follows the local dependencies between projects (using
:local/root in the
deps.edn files) and imports all those too.
You can either continue to import more modules if required, or just press OK if you're done.
And your new project is now set up and ready to use. You can then add new modules to the project using either the button in the Deps tool window, or using the context menu in the project tool window. You can remove Deps modules from the project and optionally remove the corresponding IntelliJ module using the in the Deps tool window.