Dependency Management

New dependencies should not be included without community consensus first being obtained via a [DISCUSS] thread on the dev@cassandra.apache.org mailing list.

As Cassandra is an ASF project, all included libraries must follow Apache’s software license requirements.

Cassandra uses the Ant build system and Maven POMs for dependency specification. In Cassandra 5.0 the format of POMs was moved from within the build.xml file to separate POM template files that are processed by Ant. In both pre-5.0 and post-5.0 Cassandra, there are several POMs that dependencies can be included in:

  • parent-pom

    • Contains all dependencies with the respective version. All other poms will refer to the artifacts with specified versions listed here.

    • Since Cassandra 5.0, the parent-pom template is .build/parent-pom-template.xml.

  • build-deps-pom(-sources) + coverage-deps-pom

    • used by the ant build target. Listed dependencies will be resolved and copied to build/lib/{jar,sources} by executing the maven-ant-tasks-retrieve-build target. This should contain libraries that are required for build tools (grammar, docs, instrumentation), but are not shipped as part of the Cassandra distribution.

    • Since Cassandra 4.0, coverage-deps-pom has been removed and the build-deps-pom template is .build/cassandra-build-deps-template.xml.

  • all-pom

  • test-deps-pom

    • Referenced by maven-ant-tasks-retrieve-test to retrieve and save dependencies to build/test/lib. Exclusively used during JUnit test execution.

    • Since Cassandra 3.0, test-deps-pom has been removed.

The ant write-poms target produces valid POM files in the build/ directory.

Dependencies added to the lib/ directory are built into the release artifacts by the ant artifacts target (see target resolver-dist-lib). Libraries distributed this way must meet the ASF distribution policy.

Dependency management before Cassandra 5.0

To update dependencies, update the parent and child POM definitions in build.xml. The parent POM should include the dependency tag with groupId, artifactId, version, and optional scope fields. The child POM(s) should include the dependency tag with groupId and artifactId. See the Maven docs for a complete reference on how to reference dependencies across parent and child POMs.

Here is an example of a commit that changes dependency versions pre-5.0.

Dependency management in Cassandra 5.0 and later

In Cassandra 5.0 and later, dependencies are managed in Maven POM templates in .build/*-template.xml. These templates are processed into valid Maven POMs and copied to build/\*.pom by the ant write-poms task.

For new dependencies, add to parent-pom-template and cassandra-deps-template, and optionally cassandra-build-deps-template if the dependency is required for build only. See the Maven docs on how to reference dependencies in the parent POM from the child POMs.

For dependency versions that need to be available in build.xml and parent-pom-template, specify the version as a property in build.xml, add it to the ant write-poms target, then add the property to parent-pom-template with the value of the template substitution.

Here is an example of a commit that changes dependency versions since 5.0.

Troubleshooting and conflict resolution

Here are some useful commands that may help you out resolving conflicts.

  • ant realclean - gets rid of the build directory, including build artifacts.

  • mvn dependency:tree -f build/apache-cassandra-\*-SNAPSHOT.pom -Dverbose -Dincludes=org.slf4j

    • shows transitive dependency tree for artifacts, e.g. org.slf4j. In case the command above fails due to a missing parent pom file, try running ant mvn-install.

  • rm ~/.m2/repository/org/apache/cassandra/apache-cassandra/ - removes cached local Cassandra maven artifacts