Liking cljdoc? Tell your friends :D

Project

There are two kinds of projects in Polylith: development and deployable.

The development project:

  • Where you work with the code, often from a REPL.

  • Described in ./deps.edn which:

    • Specifies all clj/cljc/cljs bricks used by the project + tools.deps project libraries.

    • Optionally defines profiles.

  • Described in ./package.json (if exists) which:

    • Specifies all cljs bricks used by the project + NPM project libraries.

  • Source code to support development (not part of any component or base) lives under the ./development directory.

A deployable project:

  • Used to build deployable artifacts, e.g., lambda functions, REST APIs, tools, etc.

  • Has its own directory under the ./projects directory (e.g., my-project), which:

    • Has a deps.edn specifying the clj/cljc/cljs bricks and tools.deps libraries used by the deployable project.

      • If the referenced bricks contain any clj/cljc tests, they are run when you execute the test command (cljs tests are not executed).

    • Can optionally have a resources directory.

    • Can optionally have a test directory for project-specific tests.

    • Doesn’t have a src directory. We discourage a src directory for deployable projects; all production code should normally only live in bricks.

The :projects key in ./workspace.edn configures project aliases and, optionally, how poly should run your tests.

Let’s continue with our tutorial. The last thing you did was create a cli base. Run the following create project command:

poly create project name:command-line dialect:clj

Your workspace should now look like this:

example
├── bases
│   └── cli
│       ├── deps.edn
│       ├── resources
│       │   └── cli
│       ├── src
│       │   └── se
│       │       └── example
│       │           └── cli
│       │               └── core.clj
│       └── test
│           └── se
│               └── example
│                   └── cli
│                       └── core_test.clj
├── components
│   └── user
│       ├── deps.edn
│       ├── resources
│       │   └── user
│       ├── src
│       │   └── se
│       │       └── example
│       │           └── user
│       │               ├── core.clj
│       │               └── interface.clj
│       └── test
│           └── se
│               └── example
│                   └── user
│                       └── interface_test.clj
├── deps.edn
├── development
│   └── src
│       └── dev
│           └── lisa.clj
├── logo.png
├── projects
│   └── command-line (1)
│       ├── deps.edn
│       └── package.json (2)
├── readme.md
└── workspace.edn
1new command-line project
2The create component command didn’t create a package.json file. If the dialect had been set to cljs, the file would have looked like this (the content can be customized in Templates):
{
  "name": "@poly/command-line",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
  },
  "devDependencies": {
    "shadow-cljs": "^3.2.0"
  }
}

The poly tool helpfully reminds us:

  It's recommended to add an alias to :projects in ./workspace.edn for the command-line project.

If you don’t follow this advice, the command-line project heading will default to ?1 when running the info command. Go ahead and add an alias in your ./workspace.edn:

  {...
   :projects {"development" {:alias "dev"}
              "command-line" {:alias "cl"}}} (1)
1Add the cl alias for the command-line project

Add the user component and the cli base to your new project by editing projects/command-line/deps.edn:

{:deps {poly/user {:local/root "../../components/user"} (1)
        poly/cli  {:local/root "../../bases/cli"} (2)

        org.clojure/clojure {:mvn/version "1.12.0"}}
1Add user component
2Add cli base

The :local/root paths begin with ../../ because the components and bases directories are two levels up relative to projects/command-line directory.

When you run the test command, poly will determine which tests should run. If you want to run tests for each deployable project outside of poly using Clojure’s tools.deps, you must specify the test paths in your ./deps.edn.

Each ./projects/**/deps.edn specifies what bricks to include via :local/root dependencies. The poly test command determines the appropriate test dependencies from each referenced brick’s deps.edn.

But Clojure’s tools.deps does not include test dependencies from :local/root dependencies. To support IDEs and other tooling, you must compensate by adding your brick tests as separate paths in your ./deps.edn, just as you did for your user component and cli base.

Where you specify dependency to bricks differs based on the project type:

  • For the development project: ./deps.edn > :aliases > :dev > :extra-deps

  • For deployable projects: ./projects/PROJECT-DIR/deps.edn > :deps

Can you improve this documentation? These fine people already did:
Joakim Tengstrand, Furkan Bayraktar, Johan Mynhardt & Sean Corfield
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
× close