main | ||
dev |
tools-pom
A Clojure tools.build task library related to the generation of comprehensive pom.xml
files (beyond the limited set of POM elements tools.build/tools.deps generates).
Tasks
pom
- generate a comprehensivepom.xml
file from EDN (which can come from anywhere - stored in yourbuild.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.
Important note: it is strongly recommended that you do not use this task library in conjunction with build-clj (e.g. for JAR file construction), since:
- build-clj silently overwrites various elements inside whatever "template"
pom.xml
is provided to it - some of the values for those overwritten elements assume you label your tags in source control a specific way, which will break downstream tooling that depends on those values being correct
The alternative is to use vanilla tools.build tasks for all build operations that involve pom.xml
files (notably JAR file construction), since they doesn't suffer from the same issue.
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 "LATEST_CLOJARS_VERSION"}}
:ns-default your.build.ns}
Require the namespace
(ns your.build.ns
(:require [tools-pom.tasks :as pom]))
pom
information and a pom
build task to your build
Add comprehensive (def lib 'com.github.yourusername/yourproject)
(def version (format "1.0.%s" (b/git-count-revs nil)))
(defn- set-opts
[opts]
(assoc opts
:lib lib
:version version
: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 "youremail@emailservice.com"}] ; And here
:scm {:url "https://github.com/yourusername/yourproject"
:connection "scm:git:git://github.com/yourusername/yourproject.git"
:developer-connection "scm:git:ssh://git@github.com/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
Developer Workflow
This project uses the git-flow branching strategy, with the caveat that the permanent branches are called main
and dev
, and any changes to the main
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 main
branch is only updated from dev
via PRs created by the core development team. All other changes submitted to main
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 testsclojure -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 Apache License, Version 2.0.
SPDX-License-Identifier: Apache-2.0