Forem: Jerome Angibaud

JeKa: Run Java Sources as Fast as Native

Jerome Angibaud — Mon, 06 Jan 2025 11:30:08 +0000

JeKa — A Simple Modern Java Build Tool

JeKa is a modern Java build tool focused on simplicity.

When starting with Java, developers usually just write some code, compile it, and run it. However, this is not enough to create useful Java applications or libraries that others can reuse. To build something practical in Java, we need to:

Use third-party libraries (e.g., Guava, Gson, Commons CLI, etc.)
Package and deploy the application/library so others can use it.

This is often done with traditional build tools like Maven or Gradle. These tools require significant learning and can involve tedious configuration.
A simpler alternative is JBang, which lets you write almost single-file Java apps and easily share them.

On the other hand, Jeka offers simple dependency management and deployment ala JBang while allowing you to build standard multi-class applications or libraries with proper tests included.

🏗️ Scaffold a New Code Base

JeKa can operate in both base and project modes. The base mode uses a simpler structure, where the entire codebase resides in a single folder and dependencies are declared directly within Java classes using annotations.

Tip: To list base available options, execute: jeka base: --doc.

To create a base structure, ready for starting coding right away, execute:

jeka base: scaffold scaffold.kind=APP

You’ll get the following codebase layout:

. 
├── jeka-src             <- Source root directory
│   ├── _dev             <- Optional package containing all non-prod (build and test)
│   │   ├── test
│   │   └── Custom.java  
│   └── app              <- Suggested base package for production code/resources
│       └── App.java     
├── jeka-output          <- Generated dir where artefacts as jars, classes, reports or doc are generated
├── jeka.properties      <- Build configuration  (Java and jeka version, kbean configurations, ...)
└── README.md            <- Describes available build commands

All your Java code should be located in the jeka-src folder.

The _dev package is a special directory for source code and dependencies used exclusively for development purposes (e.g., tests, builds). If you're new to Java, you can ignore or delete it.

The scaffolded example includes an App class within the app package. You are free to add or modify classes in any package as you see fit.

🔄 Sync with IntelliJ

To synchronize with IntelliJ, execute:

jeka intellij: sync --force

📦 Add Dependencies

The App.java class uses the @JkDep annotation to reference a library. You can add as many libraries as needed. It’s a good practice to declare all dependencies in the same base class.

@JkDep("com.github.lalyos:jfiglet:0.0.9")
@JkDep("com.fasterxml.jackson:jackson-bom:2.18.2@pom")
@JkDep("com.fasterxml.jackson.core:jackson-core")
@JkDep("com.fasterxml.jackson.core:jackson-annotations")
public class App {

    public static void main(String[] args) {
        ...
    }
}

See details on dependency notations.

Additionally, you can simply copy and paste JAR files into the following directory, and they will automatically be included as dependencies:

├── jeka-boot      <- Jars included in the production classpath.

Declare non-prod dependencies

If you declare the @JkDev annotation within the _dev package, any dependencies it references will be excluded from the final production build.

package _dev;

@JkDep("org.junit:junit-bom:5.12.2@pom")
@JkDep("org.junit.platform:junit-platform-launcher")
@JkDep("org.junit.jupiter:junit-jupiter")
@JkDep("org.mockito:mockito-junit-jupiter:5.15.2")
class Custom extends KBean {
    ...
}

🏃‍♂️ Run your Application

The application can be run using:

jeka --program arg0 args1 ... # or `jeka -p` for short

To clean the compilation before starting, use the --clean or -c option. -p stands for --program shorthand.

jeka -c -p arg0 args1 ... # or `jeka -p` for short

📚 Create a Library

If you want to write a library, instead of an application, you need to declare both moduleId and versioning in order to publish it on a Maven repository:

@base.moduleId=org.example:my-lib
@base.version=1.0.0-SNAPSHOT

Now, you can publish your library by executing:

jeka maven: publish

🧪 Test your Code

The scaffolded code already contains a _dev.test.MyTest test class, ready to run.

. 
├── jeka-src           
│   ├── _dev             
│   │   └── test
│   │       └── MyTest.java

You can add more tests in any package you like. However, keep in mind that test classes not located in the _dev package (or its sub-packages) will be included in the production JAR as dead code.

☕ Change Java Version

Nowadays, Java evolves rapidly, with new releases every six months. JeKa provides a very convenient way to switch between Java versions. Simply specify the desired version in the jeka.properties file:

jeka.java.version=24

This will automatically install JDK 24 during the next application compile or run.

🌍 Distribute Worldwide — No Packaging Needed

With JeKa, you don’t need to package your project into binaries or upload it to a hosting service. Just push your code to GitHub (or any Git repository), and it’s instantly runnable by anyone, anywhere.

How it works:

Push your project to GitHub or any accessible Git repository.
Anyone can run it with a single command:

jeka -r https://github.com/jeka-dev/demo-cowsay

You can also run a specific version and pass arguments to the application:

jeka -r https://github.com/jeka-dev/demo-cowsay#0.0.2 -p "Hello JeKa"

#0.0.2 refers to the Git tag 0.0.2
"Hello JeKa" is passed as an argument to the application

✅ With JeKa, your Java project becomes globally accessible—no build artifacts, no deployment steps, no hassle.

🧱 Move to Project Mode

As the codebase is growing, you'll might find more confortable in using a full project structure.

.
├── src                  
│   ├── main             <- Java code and reources
│   │   ├── java
│   │   └── resources    
│   └── test             <- Java code and reources for tests
│       ├── java
│       └── resources 
├── jeka-src             <- Optional Java (or Kotlin) code for building the project
│   └── Custom.java      
├── jeka-output          <- Generated dir where artifacts as jars, classes, reports or doc are generated
├── dependencies.txt     <- Dependency lists for compile, runtime and testing
├── jeka.properties      <- Build configuration  (Java and jeka version, kben configurations, ...)
├── jeka.ps              <- Optional Powershell script to boot Jeka on Windows
├── jeka                 <- Optional bash script to boot Jeka on Linuw/MacOS
└── README.md            <- Describes available build commands for building the project

Moving to project is easy, to figure out how to do, visit the Build Projects Tutorial.

🔷 Code with Kotlin

You can also write Kotlin code in your codebase. Just specify the Kotlin version you want to use in the jeka.properties file:

jeka.kotlin.version=2.1.0

Now, you can edit Kotlin code as shown below, seamlessly integrate it with the existing Java code in your codebase, or even create a 100% Kotlin application:

class Greeting {

    fun sayHello() : String{
        return "hello"
    }
}

🛠️ Pre-defined Build Commands

Among others, Jeka provides the following commands:

jeka base: test       # Runs tests
jeka base: pack       # Runs tests + creates jars
jeka base: runJar     # Runs the jar generated by the above command
jeka base: info       # Displays project configuration info
jeka base: depTree    # Displays dependency trees

Other commands:

jeka native: compile     # Compiles to native executable

jeka docker: build       # Builds a Docker image for the project
jeka docker: info        # Displays info about generated image.
jeka docker: buildNative # Builds a Docker image containing the native executable
jeka docker: infoNative  # Displays info about generated native image 

jeka maven: publishLocal # Publish artifacts in the local repository
jeka maven: publish      # Publish in the defined Maven repository

🏁 Conclusion

Jeka offers a practical mode to start writing real-life Java application without the burden of traditional build tools.

Its polymorphic structure allows handling increasing complexity and size gradually, without sacrificing simplicity.

Resources:

JeKa: The Simplest Way to Create Uber and Shade Jars

Jerome Angibaud — Thu, 02 Jan 2025 14:14:40 +0000

Edited 2025-10-15: Fix the Maven pom.xml sample.

JeKa is a modern Java build tool focused on simplicity.

This post is part of the "Jeka: the simplest way to..." series and shows how to create a fat jar (shaded or not) effortlessly.

For Applications : Simple Fat Jar

A common way to package Java applications is by creating FAT jars. A fat jar bundles all classes from the dependencies, so you only need the jar (along with the Java Runtime) to run the application.

Your application may need dependencies, which you can list in the dependencies.txt file as shown in the example below:

[compile]
com.github.lalyos:jfiglet:0.0.9
com.google.guava:guava:33.4.0-jre
com.fasterxml.jackson.core:jackson-core:2.18.2

[test]
org.junit.jupiter:junit-jupiter:5.8.1

To configure the fat jar generation, edit the jeka.properties file:

jeka.version=0.11.37
jeka.java.version=17

@project.pack.detectMainClass=true
@project.pack.jarType=FAT

The @project.pack.jarType property specifies the type of JAR to generate. It can be REGULAR, FAT, or SHADE.

The @project.pack.detectMainClass=true setting instructs Jeka to detect the main class to include in the manifest file.

To generate the jar, run the following command:

jeka project: pack

The FAT jar will be created in the jeka-output directory. To run it, just execute: java -jar [jar-name].jar.

For Libraries : Shade Fat jar

For libraries, an established practice consists in keeping a regular Jar and providing a Fat Jar as an additional option.

In some situation, such as a version clash, dependency classes should be relocated to a specific package to avoid classpath conflicts for the consumers. We call a shade jar, a fat jar where the dependencies classes have been re-located in a specific package.

To create such a jar, configure JeKa as follows:

jeka.version=0.11.37
jeka.java.version=17

@project.moduleId=org.examples:my-lib
@project.version=1.0.0-SNAPSHOT
@project.pack.shadeJarClassifier=all

@maven.publication.extraArtifacts=all

Now, invoking jeka prpject: pack will also create a org.examples.my-lib-all.jar file.
By opening this jar file, we can see that all dependency classes has been automatically relocated.

.
├── org                  
│   └── example             
│       └── mylib           <- Base package for my-lib classes
│           ├── MyLyb.class   
│           └── _shaded     <- Base package for dependency classes
│               ├── com.google...
│               ├── com.fasterxml.jackson...
│               └── com.github.lalyos.jfiglat...
└── META-INF             
    └── MANIFEST.MF

Additionally, adding @maven.publication.extraArtifacts=all to jeka.properties, includes the shaded JAR in the Maven publication generated by the jeka maven: publish command.

Maven Comparison

As demonstrated below, Maven requires significantly more typing to achieve a similar goal.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>org.examples</groupId>
   <artifactId>my-lib</artifactId>
   <version>0.1.0-SNAPSHOT</version>
   <dependencies>
      <dependency>
         <groupId>com.github.lalyos</groupId>
         <artifactId>jfiglet</artifactId>
         <version>0.0.9</version>
      </dependency>
      <dependency>
         <groupId>com.google.guava</groupId>
         <artifactId>guava</artifactId>
         <version>33.2.1-jre</version>
      </dependency>
      <dependency>
         <groupId>com.fasterxml.jackson.core</groupId>
         <artifactId>jackson-core</artifactId>
         <version>2.17.2</version>
      </dependency>
   </dependencies>
   <build>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.6.0</version>
            <configuration>
               <minimizeJar>true</minimizeJar>
               <artifactSet>
                  <includes>
                     <include>com.google.guava:guava</include>
                     <include>com.github.lalyos:jfiglet</include>
                     <include>com.fasterxml.jackson.core:jackson-core</include>
                  </includes>
               </artifactSet>
               <relocations>
                  <relocation>
                     <pattern>com.google.common</pattern>
                     <shadedPattern>org.elasticsearch.common</shadedPattern>
                  </relocation>
                  <relocation>
                     <pattern>com.fasterxml.jackson</pattern>
                     <shadedPattern>org.elasticsearch.common.jackson</shadedPattern>
                  </relocation>
               </relocations>
               <filters>
                  <filter>
                     <artifact>*:*</artifact>
                     <excludes>
                        <exclude>META-INF/license/**</exclude>
                        <exclude>META-INF/*</exclude>
                        <exclude>META-INF/maven/**</exclude>
                        <exclude>LICENSE</exclude>
                        <exclude>NOTICE</exclude>
                        <exclude>/*.txt</exclude>
                        <exclude>build.properties</exclude>
                     </excludes>
                  </filter>
               </filters>
            </configuration>
         </plugin>
      </plugins>
   </build>
</project>

Conclusion

Jeka makes building Java projects significantly easier, with minimal configuration compared to Maven or Gradle.

Explore more examples to discover how Jeka can adapt to your project’s needs!

JeKa: The Simplest Way to Publish on Maven Central

Jerome Angibaud — Mon, 30 Dec 2024 10:48:43 +0000

Update: This article now reference the new way for publishing, via Central Portal

JeKa is a modern Java build tool focused on simplicity.
This post demonstrates how to publish to Maven Central with minimal configuration.

Prerequisite: You need a Central Portal Accountto publish on Maven Central.

Configure and Run

With JeKa, you can fully configure the build by editing the jeka.properties file as follows:

jeka.version=0.11.37
jeka.java.version=17

jeka.classpath=dev.jeka:centralprotal-plugin

@project.moduleId=com.github.djeang:vincer-dom
@project.gitVersioning.enable=true

# Metadata required by Maven Central for publishing
@maven.pub.metadata.projectName=Vincer-Dom
@maven.pub.metadata.projectDescription=Modern Dom manipulation library for Java
@maven.pub.metadata.projectUrl=https://github.com/djeang/vincer-dom
@maven.pub.metadata.projectScmUrl=https://github.com/djeang/vincer-dom.git
@maven.pub.metadata.licenses=Apache License V2.0:https://www.apache.org/licenses/LICENSE-2.0.html
@maven.publication.metadata.developers=djeang:djeangdev@yahoo.fr

Note that dependencies are listed in a dedicated dependencies.txt file to maintain clear separation of concerns.

[version]
org.junit:junit-bom:5.12.2@pom

[compile]

[test]
org.junit.platform:junit-platform-launcher
org.junit.jupiter:junit-jupiter
org.jdom:jdom2:2.0.6.1

To publish to Maven Central, execute:

jeka project: pack centralportal: publish

See a concrete example here.

GitHub action

The following Github Action workflow builds the project and publish to Maven Central:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - run: git fetch --prune --unshallow --tags
    - name: Build and publish
      env:
        JEKA_CENTRAL_PORTAL_USERNAME: ${{ secrets.CENTRAL_PORTAL_USERNAME }}
        JEKA_CENTRAL_PORTAL_PASSWORD: ${{ secrets.CENTRAL_PORTAL_PASSWORD }}
        JEKA_CENTRAL_PORTAL_SIGN_KEY: ${{ secrets.GPG_SECRET_KEY}}
        JEKA_CENTRAL_PORTAL_SIGN_KEY_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
      run: "./jeka build centralportal: publish"

Thanks to its powerful wrapper, Jeka will install specified JDK and Jeka version by itself.

Explanations

Now that you know how to do it, let's explain how it works.

Jeka and Java Versioning

For better portability and reproducibility, we can declare both the Jeka and Java versions required for building. Both versions will be automatically downloaded if not already present on the host machine.

Specify Module ID and Versioning

The published moduleId is specified using the @project.moduleId property.

The version can be explicitly specified using the @project.version property. Note that properties can be set in the jeka.properties file or passed as a command-line argument: -D@project.version=1.0.1.

Instead, we choose to rely on Git to infer the version using: @project.gitVersioning.enable=true. If there is no tag on the current commit, the version will be set to [branch]-SNAPSHOT; otherwise, it will be the tag-name.

Provide secrets

To publish on Maven Central, we need to signs artefact files with the appropriate GPG key mentioned in Central Portal.

We also need to specify credentials at publication time.

For those, Jeka expects these values to be found in the followinng environment variables:

JEKA_CENTRAL_PORTAL_USERNAME: OSSRH account username
JEKA_CENTRAL_PORTAL_PASSWORD: OSSRH account password
JEKA_CENTRAL_PORTAL_SIGN_KEY: Armored GPG secret key as a string
JEKA_CENTRAL_PORTAL_SIGN_KEY_PASSPHRASE: The passphrase protecting the secret key

The content of JEKA_CENTRAL_PORTAL_SIGN_KEY can be obtained by executing: gpg --export-secret-key --armor MY-KEY.

Provide Publication Metadata

The mandatory metadata are set using @maven.pub.metadata.xxx properties.

Note that the @maven.pub.metadata.licenses property expects a format like: [license1 name]:[license1 url],[license2 name]:[license2 url],...

Automate Release Publication

By default, the published artefacts are automatically published to Maven Central. If you want to just validate your publication an publish to Maven Central manually (from Central Portal UI), you need to specify this configuration:

@centralportal.automatic=false

Execute Build

To publish, simply execute: jeka project: pack centralportal: publish.

This will:

Create the JAR to publish (project: pack).
Create source and Javadoc JARs.
Generate the published POM file.
Compute all checksums.
Sign all published files.
Push everything to the Central Portal.

To see what will be published, execute: jeka maven: info.

Find more details here.

Comparison with Maven

The following is the Maven POM configuration equivalent for deploying a project to Maven Central:


<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <developers>
        <developer>
            <name>djeang</name>
            <email>djeangdev@yahoo.fr</email>
        </developer>
    </developers>

    <name>Vincer-DOM</name>
    <description>Modern Dom manipulation library for Java.</description>
    <url>https://github.com/djeang/vincer-dom</url>

    <groupId>com.github.djeang</groupId>
    <artifactId>vincer-dom</artifactId>
    <version>0.1.0-SNAPSHOT</version>

    <licenses>
        <license>
            <name>MIT License</name>
            <url>http://www.opensource.org/licenses/mit-license.php</url>
        </license>
    </licenses>

    <properties>
        <java.version>17</java.version>
        <maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
    </properties>

    <scm>
        <connection>scm:git:git://github.com/djeang/vincer-dom.git</connection>
        <developerConnection>scm:git:https://github.com/djeang/vincer-dom.git</developerConnection>
        <url>https://github.com/djeang/vincer-domr</url>
    </scm>

    <distributionManagement>
        <snapshotRepository>
            <id>ossrh</id>
            <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
        </snapshotRepository>
        <repository>
            <id>ossrh</id>
            <url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
        </repository>
    </distributionManagement>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.junit</groupId>
                <artifactId>junit-bom</artifactId>
                <version>5.9.1</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <version>org.junit.jupiter</version>
            <artifactId>junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <version>org.junit.platform</version>
            <artifactId>junit-platform-launcher</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
             <version>org.jdom</version>
             <artifactId>jdom2</artifactId>
            <version>2.0.6.1</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>${maven-compiler-plugin.version}</version>
                    <configuration>
                        <source>${java.version}</source>
                        <target>${java.version}</target>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-source-plugin</artifactId>
                    <version>2.2.1</version>
                    <executions>
                        <execution>
                            <id>attach-sources</id>
                            <goals>
                                <goal>jar-no-fork</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>2.9.1</version>
                    <executions>
                        <execution>
                            <id>attach-javadocs</id>
                            <goals>
                                <goal>jar</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-gpg-plugin</artifactId>
                    <version>1.5</version>
                    <executions>
                        <execution>
                          <id>sign-artifacts</id>
                          <phase>verify</phase>
                          <goals>
                              <goal>sign</goal>
                          </goals>
                        </execution>
                    </executions>
                </plugin>
                <plugin>
                    <groupId>org.sonatype.central</groupId>
                    <artifactId>central-publishing-maven-plugin</artifactId>
                    <version>0.4.0</version>
                    <extensions>true</extensions>
                    <configuration>
                         <publishingServerId>central</publishingServerId>
                        <tokenAuth>true</tokenAuth>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>me.ccampo</groupId>
                <artifactId>git-version-maven-plugin</artifactId>
                <version>0.1.0</version> 
                <extensions>true</extensions>
                <configuration>
                    <strategy hint="git"/>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Conclusion

Jeka provides a simpler, yet powerful way to build Java software and publish artifacts to Maven Central or other repositories, with much less configuration and effort than traditional tools.

Visit the website, videos, and examples to get an idea of everything Jeka can do better.

Disclaimer: I am the author of Jeka.