release
dev

tools-pom

A Clojure tools.build task library related to the generation of comprehensive pom.xml files.

Important

tools.build v0.9.6 (October 2023) added comprehensive pom.xml file generation support via the :pom-data option to the write-pom fn. That enhancement has made this library significantly less useful, and it's recommended that you use that functionality instead of what's here.

Tasks

1. pom - generate a comprehensive pom.xml file from EDN (which can come from anywhere - stored in your build.clj, deps.edn or a separate file, or synthesised on the fly in your build tool script).

Note that the pom task is entirely data-driven, so if your input data includes elements that are not valid in a Maven POM, the resulting file will be invalid. You can check your input data by enabling the :validate-pom flag in the options that get passed to the task - this validates the resulting pom.xml file against the Maven POM schema, reporting any errors.

Using the library

Dependency

Express a maven dependency in your deps.edn, for a build tool alias:

  :aliases
    :build
      {:deps       {com.github.pmonks/tools-pom {:mvn/version "RELEASE"}}
       :ns-default your.build.ns}

Require the namespace

(ns your.build.ns
  (:require [tools-pom.tasks :as pom]))

Add comprehensive pom information and a pom build task to your build

(defn- set-opts
  [opts]
  (assoc opts
         :lib          'com.github.yourusername/yourproject
         :version      (format "1.0.%s" (b/git-count-revs nil))
         :write-pom    true
         :validate-pom true
         ; Note: this EDN can come from anywhere - you could externalise it into a separate edn file (e.g. pom.edn), synthesise it from information elsewhere in your project, or whatever other scheme you like
         :pom          {:description      "Description of your project e.g. your project's GitHub \"short description\"."
                        :url              "https://github.com/yourusername/yourproject"
                        :licenses         [:license   {:name "Apache License 2.0" :url "http://www.apache.org/licenses/LICENSE-2.0.html"}] ; Note first element is a tag
                        :developers       [:developer {:id "yourusername" :name "yourname" :email "[email protected]"}]           ; And here
                        :scm              {:url                  "https://github.com/yourusername/yourproject"
                                           :connection           "scm:git:git://github.com/yourusername/yourproject.git"
                                           :developer-connection "scm:git:ssh://[email protected]/yourusername/yourproject.git"}
                        :issue-management {:system "github" :url "https://github.com/yourusername/yourproject/issues"}}))

(defn pom
  "Construct a comprehensive pom.xml file for this project"
  [opts]
  (-> opts
      (set-opts)
      (pom/pom)))

API Documentation

API documentation is available here.

Contributor Information

Contributing Guidelines

Bug Tracker

Code of Conduct

Developer Workflow

This project uses the git-flow branching strategy, and the permanent branches are called release and dev. Any changes to the release branch are considered a release and auto-deployed (JARs to Clojars, API docs to GitHub Pages, etc.).

For this reason, all development must occur either in branch dev, or (preferably) in temporary branches off of dev. All PRs from forked repos must also be submitted against dev; the release branch is only updated from dev via PRs created by the core development team. All other changes submitted to release will be rejected.

Build Tasks

tools-pom uses tools.build. You can get a list of available tasks by running:

clojure -A:deps -T:build help/doc

Of particular interest are:

• clojure -T:build test - run the unit tests
• clojure -T:build lint - run the linters (clj-kondo and eastwood)
• clojure -T:build ci - run the full CI suite (check for outdated dependencies, run the unit tests, run the linters)
• clojure -T:build install - build the JAR and install it locally (e.g. so you can test it with downstream code)

Please note that the deploy task is restricted to the core development team (and will not function if you run it yourself).

License

Copyright © 2021 Peter Monks

Distributed under the Mozilla Public License, version 2.0.

SPDX-License-Identifier: MPL-2.0