KB-208 – Core Development Lifecycle¶

Knowledge Base ID: KB-208
Category: ADempiere Core Development
Status: Approved
Version: 1.0
Last Updated: 2026-06-26
Applies To: BlackERP / ADempiere 3.9.4

Purpose¶

This document defines the official development lifecycle for modifications to the ADempiere Core used by BlackERP.

It documents the complete workflow from source code modification through compilation, deployment, rollback, troubleshooting and production validation.

This document supersedes any previous practice consisting of copying Adempiere.jar directly into Tomcat.

Scope¶

Applies to modifications inside:

source/base
source/client
source/extend

Examples:

Accounting Engine
Document Posting
Model Validators
Business Logic
Core Processes

Source Tree¶

source/

base/
client/
extend/
install/
packages/
tools/
utils_dev/

Development Workflow¶

Modify Java Source
        │
        ▼
Compile base
        │
        ▼
Compile client
        │
        ▼
Generate Adempiere.jar
(clientDistribute)
        │
        ▼
Sign Runtime Libraries
(setupALib)
        │
        ▼
Backup Production
        │
        ▼
Deploy
        │
        ▼
Restart Services
        │
        ▼
Smoke Test
        │
        ▼
Functional Validation

Compilation¶

Compile Base¶

cd /opt/adempiere/source/base

. ../utils_dev/myDevEnv.sh

$JAVA_HOME/bin/java \
-Dant.home="." \
$ANT_PROPERTIES \
org.apache.tools.ant.Main compile

Expected result:

BUILD SUCCESSFUL

Generate Client Runtime¶

cd /opt/adempiere/source/client

. ../utils_dev/myDevEnv.sh

$JAVA_HOME/bin/java \
-Dant.home="." \
$ANT_PROPERTIES \
org.apache.tools.ant.Main clientDistribute

Generated artifact:

source/lib/Adempiere.jar

Important:

This JAR is NOT production-ready.

It does NOT contain the runtime packaging and digital signature required by the production environment.

Runtime Packaging¶

Production JARs must always be generated using:

setupALib

Executed from:

source/install/build/Adempiere

This process:

Creates packages.jar
Merges runtime libraries
Preserves package metadata
Signs Adempiere.jar
Creates AdempiereOriginal.jar

Why setupALib is Required¶

Using only clientDistribute removes runtime package information.

Observed symptoms include:

ClassNotFoundException
Missing ModelValidators
Missing Fixed Asset classes
Missing Manufacturing classes

Deployment Procedure¶

Stop ADempiere service.
Backup current runtime JARs.
Copy signed Adempiere.jar.
Clear:

tomcat/work
tomcat/temp

Restart service.
Verify:

curl http://127.0.0.1:8080/webui/

Review:

catalina.out

Smoke Test Checklist¶

Verify:

Login
Open Windows
Complete Documents
Accounting Posting
Payment
Allocation
Invoice Posting
No ClassNotFoundException

Rollback Strategy¶

Never overwrite production without:

Adempiere.jar backup

SHA256 checksum

Deployment timestamp

Rollback consists of restoring the previous runtime JAR and restarting Tomcat.

Lessons Learned¶

During the MX VAT Cash Basis implementation the following was discovered:

clientDistribute generates a valid compilation artifact.
It is not sufficient for production deployment.
Production runtime requires setupALib.
Replacing Tomcat runtime JARs directly may remove packaged runtime components and trigger ClassNotFoundException.
The correct deployment pipeline preserves runtime packaging and digital signatures.

References¶

KB-104 – Deployment Procedure

KB-206 – Build and Compilation

KB-207 – Core Java Build and Signed Deployment