https://github.com/pmonks/tools-pom
A Clojure tools.build task library related to the generation of comprehensive pom.xml files.
https://github.com/pmonks/tools-pom
clojure pom-xml tools-build
Last synced: 4 months ago
JSON representation
A Clojure tools.build task library related to the generation of comprehensive pom.xml files.
- Host: GitHub
- URL: https://github.com/pmonks/tools-pom
- Owner: pmonks
- License: mpl-2.0
- Created: 2021-10-25T17:49:24.000Z (over 3 years ago)
- Default Branch: dev
- Last Pushed: 2024-11-12T03:13:27.000Z (8 months ago)
- Last Synced: 2025-02-28T01:37:06.153Z (4 months ago)
- Topics: clojure, pom-xml, tools-build
- Language: Clojure
- Homepage:
- Size: 146 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
| | | |
|---:|:---:|:---:|
| [**release**](https://github.com/pmonks/tools-pom/tree/release) | [](https://github.com/pmonks/tools-pom/actions?query=workflow%3ACI+branch%3Arelease) | [](https://github.com/pmonks/tools-pom/actions?query=workflow%3Adependencies+branch%3Arelease) |
| [**dev**](https://github.com/pmonks/tools-pom/tree/dev) | [](https://github.com/pmonks/tools-pom/actions?query=workflow%3ACI+branch%3Adev) | [](https://github.com/pmonks/tools-pom/actions?query=workflow%3Adependencies+branch%3Adev) |
[](https://clojars.org/com.github.pmonks/tools-pom/) [](https://github.com/pmonks/tools-pom/blob/release/LICENSE) [](https://github.com/pmonks/tools-pom/issues)
# tools-pom
A Clojure [tools.build](https://github.com/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](https://clojure-doc.org/articles/cookbooks/cli_build_projects/#the-generated-pomxml-file). 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](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html), 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:
```edn
:aliases
:build
{:deps {com.github.pmonks/tools-pom {:mvn/version "RELEASE"}}
:ns-default your.build.ns}
```
### Require the namespace
```clojure
(ns your.build.ns
(:require [tools-pom.tasks :as pom]))
```
### Add comprehensive `pom` information and a `pom` build task to your build
```clojure
(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](https://pmonks.github.io/tools-pom/).
## Contributor Information
[Contributing Guidelines](https://github.com/pmonks/tools-pom/blob/release/.github/CONTRIBUTING.md)
[Bug Tracker](https://github.com/pmonks/tools-pom/issues)
[Code of Conduct](https://github.com/pmonks/tools-pom/blob/release/.github/CODE_OF_CONDUCT.md)
### Developer Workflow
This project uses the [git-flow branching strategy](https://nvie.com/posts/a-successful-git-branching-model/), 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`](https://clojure.org/guides/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](https://www.mozilla.org/en-US/MPL/2.0/).
SPDX-License-Identifier: [`MPL-2.0`](https://spdx.org/licenses/MPL-2.0)