build.edn

Make your Clojure library build process easy.

Note	This project is alpha version. Breaking changes may happen

Table of Contents

• Usage
  • Getting started
  • Manual usage
  • Version operation
  • Chain some functionarities
• build.edn file format
  • Available variables
  • Lint your build.edn
• Deploy repositories / credentials
• GitHub Actions
• Projects using build.edn
• License

Usage

Getting started

build.edn make you buildable your libraries only preparing build.edn file for the simple usage.

• build.edn

  • {:lib com.github.YOUR-ACCOUNT/AWESOME-LIB
     ;; You could also specify a fixed version like "0.1.2" if you want.
     :version "0.1.{{git/commit-count}}"}

• deps.edn

  • {:aliases
     {:build {:deps {com.github.liquidz/build.edn {:mvn/version "0.11.266"}}
                                                   ;; You could also specify a git tag and sha
                                                   ;; :git/tag "0.11.266" :git/sha "849302d"
              :ns-default build-edn.main}}}

• use by clojure cli

  • # Generate JAR file
    $ clojure -T:build jar
    
    # Install lib to your local maven repo
    $ clojure -T:build install
    
    # Deploy to clojars.org
    # Some kind of credentials are required
    $ clojure -T:build deploy

  • See clojure -T:build help for other functionarities.

Manual usage

build-edn.main namespace is just a wrapper for build-edn.core. So if you want to tune the build process a bit more, you can use build-edn.core name directly.

• deps.edn

  • {:aliases
     {:build {:deps {com.github.liquidz/build.edn {:mvn/version "0.11.266"}}
              :ns-default build}}}

• build.clj

  • (ns build
      (:require
       [build-edn.core :as build-edn]))
    
    (def ^:private config
      {:lib 'com.github.YOUR-ACCOUNT/AWESOME-LIB
       :version "0.1.{{git/commit-count}}"})
    
    (defn deploy
      [_]
      ;; Deploy with past name for compatibility.
      (build-edn/deploy (assoc config :lib 'AWESOME-LIB/AWESOME-LIB))
      (build-edn/deploy config))

Version operation

The following operations will update your build.edn file.

# Bump major version and update configuration file
$ clojure -T:build bump-major-version

# Bump minor version and update configuration file
$ clojure -T:build bump-minor-version

# Bump patch version and update configuration file
# But when the patch version is a variable like '{{git/commit-count}}',
# this operation will be failed.
$ clojure -T:build bump-patch-version

# Add '-SNAPSHOT' to version number and update configuration file
$ clojure -T:build add-snapshot

# Remove '-SNAPSHOT' from version number and update configuration file
$ clojure -T:build remove-snapshot

Chain some functionarities

If you’d like to use two or more functionarities at once, you can use execute.

# When you are using fixed semantic versioning
$ clojure -T:build execute :fns '[bump-patch-version deploy]'

# When you have Java source
$ clojure -T:build execute :fns '[java-compile uberjar]'

execute function will run specified functions left to right. When specified functions contain some invalid strings, execute function will fail.

build.edn file format

name	type	required?	default	description
lib	qualified-symbol?	Yes
version	string?	Yes
description	string?			You can add description tag to pom.xml.
licenses	sequential?			You can add licenses tag to pom.xml. See doc/format/licenses.adoc for more details.
source-dirs	sequential?/set? of string		Your paths in deps.edn
class-dir	string?		"target/classes"
java-paths	sequential?/set? of string			Required only for java-compile.
javac-opts	sequential? of string			Java compile options for java-compile.
jar-file	string?		"target/{{lib}}.jar"
uber-file	string?		"target/{{lib}}-standalone.jar"	Required only for uberjar.
main	symbol?			Required only for uberjar.
skip-compiling-dirs	sequential?/set? of string		#{"resouces"}	Paths to skip compiling on uberjar.
pom	map?			You can customize scm sections, etc. in pom.xml See doc/format/pom.adoc for more details.
documents	sequential?			Required only for update-documents. See doc/format/documents.adoc for more details.
deploy-repository	map?			Required only for deploy. See doc/format/deploy-repository.adoc for more details.
github-actions?	boolean?		false	See doc/github-actions.adoc for more details.

Available variables

See doc/format/variables.adoc.

Lint your build.edn

build.edn provides build-edn.core/lint and build-edn.main/lint function.

When you use :ns-default build-edn.main setting, you can lint your build.edn file with the following command.

clojure -T:build lint

Deploy repositories / credentials

See doc/deploy.adoc for more details.

GitHub Actions

If you’d like to integrate build.edn with GitHub Actions, see doc/github-actions.adoc.

Projects using build.edn

Of course, build.edn itself is using build.edn for releasing.

• liquidz/antq

• liquidz/merr

• liquidz/testdoc

• liquidz/rewrite-indented

• liquidz/dad

• sunng87/diehard

License

Copyright © 2022-2023 Masashi Iizuka

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0.

This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at https://www.gnu.org/software/classpath/license.html.