mirror of
https://github.com/ethauvin/bld.git
synced 2025-04-25 00:07:12 -07:00
157 lines
6.6 KiB
Markdown
157 lines
6.6 KiB
Markdown
[](https://opensource.org/licenses/Apache-2.0)
|
|
[](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
|
|
[](https://rife2.com/bld)
|
|
[](https://github.com/rife2/bld/releases/latest)
|
|
[](https://maven-badges.herokuapp.com/maven-central/com.uwyn.rife2/bld)
|
|
[](https://s01.oss.sonatype.org/content/repositories/snapshots/com/uwyn/rife2/bld/)
|
|
[](https://github.com/rife2/bld/actions/workflows/bld.yml)
|
|
[](https://github.com/rife2/rife2/actions/workflows/bld.yml)
|
|
|
|
<br>
|
|
|
|
<p align="center"><img src="https://github.com/rife2/bld/raw/main/images/bld_logo.png" width="120"></p>
|
|
|
|
# What is bld?
|
|
|
|
`bld` is a new build system that allows you to write your build logic in pure
|
|
Java.
|
|
|
|
`bld` was created because we're not really interested in build tools. We use
|
|
them because we have to, but we'd rather just get on with coding the real stuff.
|
|
|
|
`bld` is designed with the following principles in mind:
|
|
|
|
* tasks don't happen without you telling them to happen
|
|
* no auto-magical behavior, task behavior is explicit and API-defined
|
|
* managing libs yourself is fine, having that automated also, or mix and match
|
|
* build logic is written in Java, with all the advantages of Java
|
|
* standard collection of Java-centric tasks for common operations
|
|
* bld is distributed in a single jar, if you have the jar, you have the build system
|
|
|
|
# Designed for modern Java
|
|
|
|
bld relies on Java 17 and leverages many of the features that this version of
|
|
Java provides. Thanks to the modern language constructs, your Java build logic
|
|
ends up looking very concise, is easily readable and understood by any IDE.
|
|
You automatically get support for auto-completion and javadoc documentation,
|
|
and you can split your build logic into multiple files and classes when you
|
|
outgrow a single file.
|
|
|
|
Here is a complete bld file for a Java application using JUnit 5 for its tests.
|
|
Nothing else is needed to be able to run it, test it and distribute it:
|
|
|
|
```java
|
|
package com.example;
|
|
|
|
import rife.bld.Project;
|
|
import java.util.List;
|
|
import static rife.bld.dependencies.Repository.*;
|
|
import static rife.bld.dependencies.Scope.*;
|
|
|
|
public class MyappBuild extends Project {
|
|
public MyappBuild() {
|
|
pkg = "com.example";
|
|
name = "Myapp";
|
|
mainClass = "com.example.MyappMain";
|
|
version = version(0,1,0);
|
|
|
|
downloadSources = true;
|
|
repositories = List.of(MAVEN_CENTRAL, RIFE2_RELEASES);
|
|
scope(test)
|
|
.include(dependency("org.junit.jupiter",
|
|
"junit-jupiter",
|
|
version(5,11,0)))
|
|
.include(dependency("org.junit.platform",
|
|
"junit-platform-console-standalone",
|
|
version(1,11,0)));
|
|
}
|
|
|
|
public static void main(String[] args) {
|
|
new MyappBuild().start(args);
|
|
}
|
|
}
|
|
```
|
|
|
|
> **NOTE:** `bld` supports different ways to describe dependencies,
|
|
> `dependency("org.junit.jupiter", "junit-jupiter", version(5,11,0))` can for instance also
|
|
> be written as `dependency("org.junit.jupiter:junit-jupiter:5.11.0")`. Which format you use,
|
|
> is a matter of personal taste.
|
|
|
|
# Where does `bld` fit?
|
|
|
|
From a very high level, build tools can be organized in a matrix:
|
|
* either your tool is declarative or in code
|
|
* either your tool first describes a plan or immediately executes a plan
|
|
|
|
|
|
| | Declarative | Code | Describes | Immediate |
|
|
|--------|-------------|------|-----------|-----------|
|
|
| Maven | X | | X | |
|
|
| Gradle | | X | X | |
|
|
| `bld` | | X | | X |
|
|
|
|
Writing your build logic in the same language as your application (Java),
|
|
significantly reduces the cognitive load, and taking actions immediately
|
|
without having to mentally construct a described plan, makes it easier to
|
|
reason about your build.
|
|
|
|
# IDE support
|
|
|
|
<img src="https://rife2.com/images/bld-idea.png" style="width: 100%">
|
|
|
|
Since version 2.0, bld comes with its own [IntelliJ IDEA plugin](https://github.com/rife2/bld-idea):
|
|
|
|
* detect `bld` projects and find their main Java class
|
|
* quick access to open and edit the main Java class and wrapper properties of `bld` projects
|
|
* list all the commands in `bld` projects in a side panel
|
|
* execute one or multiple commands in the order they were selected
|
|
* reload the commands in the `bld` project
|
|
* terminate currently running `bld` commands
|
|
* `bld` console panel for command output with source code hyperlinking
|
|
* display the `bld` dependency tree
|
|
* toggle to run `bld` in offline or online mode
|
|
* auto-save all open files before executing a `bld` command
|
|
* convenient `bld` one-click cache invalidation
|
|
* set `bld` commands to run before or after IDEA compilation
|
|
* create custom `bld` command run configuration with options, JVM arguments, and before launch tasks
|
|
* assign keyboard shortcuts to `bld` commands
|
|
|
|
# Find out more
|
|
|
|
`bld` lets your build logic get out of the way so that you can focus on writing
|
|
applications.
|
|
|
|
Get started immediately by [installing](https://github.com/rife2/bld/wiki/Installation) `bld`
|
|
through Homebrew, SDKMAN!, JBang, zip archive, or run it directly from its jar file.
|
|
|
|
If you merely want to create a new project, `bld` can also be used by executing this one-liner:
|
|
|
|
```console
|
|
bash -c "$(curl -fsSL https://rife2.com/bld/create.sh)"
|
|
```
|
|
|
|
If you have any questions, suggestions, ideas or just want to chat, feel free
|
|
to post on the [forums](https://forum.uwyn.com) or to join us on [Discord](https://discord.gg/zDG6anEXQX).
|
|
|
|
Read more in the [full documentation](https://github.com/rife2/bld/wiki) and [bld Javadocs](https://rife2.github.io/bld/).
|
|
|
|
# Building `bld`
|
|
|
|
If you want to contribute to `bld` or customize it, all you have to do is clone the GitHub
|
|
repository and update the [RIFE2/core](https://github.com/rife2/rife2-core) submodule:
|
|
|
|
```console
|
|
git clone git@github.com:rife2/bld.git
|
|
cd bld
|
|
git submodule init
|
|
git submodule update
|
|
```
|
|
|
|
Then use `bld` to build itself:
|
|
|
|
```console
|
|
./bld compile
|
|
```
|
|
|
|
The project has an IntelliJ IDEA project structure. You can just open it after all
|
|
the dependencies were downloaded and peruse the code.
|