Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/liquidz/build.edn

Make your Clojure library build process easy.
https://github.com/liquidz/build.edn

clojure clojure-library

Last synced: 17 days ago
JSON representation

Make your Clojure library build process easy.

Awesome Lists containing this project

README 

        
= build.edn

:toc:

:toc-placement: preamble

:toclevels: 2



// Need some preamble to get TOC:

{empty}



Make your Clojure library build process easy.



NOTE: This project is alpha version. Breaking changes may happen



image:https://github.com/liquidz/build.edn/workflows/test/badge.svg["GitHub Actions for test workflow", link="https://github.com/liquidz/build.edn/actions?query=workflow%3Atest"]

image:https://github.com/liquidz/build.edn/workflows/lint/badge.svg["GitHub Actions for lint workflow", link="https://github.com/liquidz/build.edn/actions?query=workflow%3Alint"]

image:https://github.com/liquidz/build.edn/workflows/dependencies/badge.svg["GitHub Actions for dependencies workflow", link="https://github.com/liquidz/build.edn/actions?query=workflow%3Adependencies"]



image:https://img.shields.io/clojars/v/com.github.liquidz/build.edn["Clojars Project", link="https://clojars.org/com.github.liquidz/build.edn"]



== Usage



=== Getting started



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



* build.edn

** {blank}

+

[source,clojure]

----

{: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

** {blank}

+

[source,clojure]

----

{: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

** {blank}

+

[source,bash]

----

# 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

** {blank}

+

[source,clojure]

----

{:aliases

 {:build {:deps {com.github.liquidz/build.edn {:mvn/version "0.11.266"}}

          :ns-default build}}}

----

* build.clj

** {blank}

+

[source,clojure]

----

(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.



[source,bash]

----

# 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`.



[source,bash]

----

# 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



[cols="1,1,1,1,6a"]

|===

| 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 link:./doc/format/licenses.adoc[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 https://maven.apache.org/scm/maven-scm-plugin/usage.html[scm] sections, etc. in pom.xml

See link:./doc/format/pom.adoc[doc/format/pom.adoc] for more details.



| documents

| `sequential?`

|

|

| Required only for `update-documents`. +

See link:./doc/format/documents.adoc[doc/format/documents.adoc] for more details.



| deploy-repository

| `map?`

|

|

| Required only for `deploy`. +

See link:./doc/format/deploy-repository.adoc[doc/format/deploy-repository.adoc] for more details.



| github-actions?

| `boolean?`

|

| false

| See link:./doc/github-actions.adoc[doc/github-actions.adoc] for more details.



|===



=== Available variables



See link:./doc/format/variables.adoc[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.



[source,bash]

----

clojure -T:build lint

----



== Deploy repositories / credentials



See link:./doc/deploy.adoc[doc/deploy.adoc] for more details.



== GitHub Actions



If you'd like to integrate build.edn with GitHub Actions,

see link:./doc/github-actions.adoc[doc/github-actions.adoc].



== Projects using build.edn



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



* https://github.com/liquidz/antq[liquidz/antq]

* https://github.com/liquidz/merr[liquidz/merr]

* https://github.com/liquidz/testdoc[liquidz/testdoc]

* https://github.com/liquidz/rewrite-indented[liquidz/rewrite-indented]

* https://github.com/liquidz/dad[liquidz/dad]

* https://github.com/sunng87/diehard[sunng87/diehard]



== License



Copyright © 2022-2023 https://twitter.com/uochan[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.