Build Jdk13 Docker
Developmentbuild-jdk13-dockerBuild Jdk13 Docker is an Agent Skill for development published in the bcgit/bc-java repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Build and test the legacy jdk1.3 (build1-3) distribution on a modern host by running the genuine Sun JDK 1.3.1 inside an i386 / glibc-2.3.6 Docker container. Use this whenever the user wants to run "build1-3" / the "jdk1.3" or "Java 1.3" build, get a bcprov-jdk13 jar, reproduce a genuine-1.3 compile failure, or when a genuine JDK 1.3.1 won't start on the host ("can't find libjava.so", missing libstdc++-libc6.1-1.so.2, or a green-threads Classic VM segfault). Captures the container recipe, why glibc < 2.4 is mandatory, the uname/libstdc++/threads traps, and that the jdk1.3 source overlays have rotted (the real source floor is Java 1.4).
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/bcgit/bc-java/blob/HEAD/.claude/skills/build-jdk13-docker/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/build-jdk13-docker, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Building and testing the jdk1.3 (build1-3) distribution in Docker
The jdk1.3 distribution is driven by sh build1-3 → ant/jdk13.xml → ant/bc+-build.xml,
compiling with the real Sun JDK 1.3.1 at /opt/jdk1.3.1 and running tests on the same JRE.
Like build1-4 it is a genuine-1.3 compile floor (post-1.3 APIs fail at compile time), but it
adds two things the jdk1.4 build does not: it builds its own clean-room JCE first (from
jce/src/, so no jar signing is needed — unlike jdk1.4/jdk15to18), and its preprocessor
rewrites the Java-1.4 cert-path API (java.security.cert.CertStore/CertPath/PKIX*/…Selector) to
BC's org.bouncycastle.jce.cert.* backport, plus LinkedHashSet→HashSet.
The blocker this skill solves: a 2001-era 32-bit Sun JDK 1.3.1 cannot run on a modern Linux host. The fix is to run it in a period-appropriate i386 container.
Quick start
.claude/skills/build-jdk13-docker/build-jdk13.sh provider # build the provider -> bcprov-jdk13 jar
.claude/skills/build-jdk13-docker/build-jdk13.sh test # full build + tests
.claude/skills/build-jdk13-docker/build-jdk13.sh shell # interactive 1.3 container (fast iteration)
.claude/skills/build-jdk13-docker/build-jdk13.sh # full build (no arg)
First run builds a tiny image (bc-jdk13:etch). i386 executes natively on an x86-64 kernel — no
qemu. Everything (JDK, ant, aux jars, the repo) is bind-mounted from the host; only a uname
shim is baked into the image. A full provider round is ~10 min (the <replaceregexp> preprocess
over ~6,800 files dominates, then the nojit Classic VM compiles).
Why a genuine JDK 1.3.1 won't run on the host — and why etch
/opt/jdk1.3.1 (→ /opt/installs/jdk1.3.1_20) is a 32-bit x86 Sun JDK. On Ubuntu 24.04:
unamewall (cosmetic). Its launch wrapper (bin/.java_wrapper) predates x86-64: it readsuname -m, getsx86_64(the container shares the host's amd64 kernel), can't map that to its i386 lib dir, and dies with "can't find libjava.so." Fixed by the image'suname -m→i686shim (apt is dead on EOL etch, so there is nolinux32).- VM wall (fatal on the host). After that:
- the default
-client/HotSpot VM uses native threads whose launcher binary links the extinctlibstdc++-libc6.1-1.so.2(gone from modern distros; and 1.3 native threads on NPTL is broken anyway); - the
-classicVM uses green threads and needs no libstdc++ — but it segfaults on glibc ≥ 2.4. Cause: glibc 2.4 addedPTR_MANGLEpointer mangling; Sun's green threads hand-rolljmp_bufcontext switches, solongjmpdemangles a raw poked-in PC and jumps to garbage (catchsegvshowsEIP == fault address, empty backtrace).
- the default
So the container base must be i386 with glibc < 2.4. debian/eol:etch (Debian 4.0, glibc
2.3.6) works; debian/eol:sarge (2.3.2) also works; anything ≥ 2.4 (jessie 2.19, …) segfaults.
Green threads are user-space, so the shared modern host kernel is not a problem.
The recipe therefore forces the Classic VM / green threads via a custom jvm.cfg (-classic
first = default VM → wrapper selects green threads → no libstdc++), sidestepping both VM problems.
Recipe internals (in this skill dir)
Dockerfile—FROM debian/eol:etch; the only customization is theuname -m→i686shim.jvm.cfg— reorders-classicto the top so every forkedjava/javacdefaults to the green-threads Classic VM. Mounted over/opt/jdk1.3.1/jre/lib/jvm.cfg(works because that file already exists in the ro JDK mount).build-jdk13.sh— bind-mounts the JDK at/opt/jdk1.3.1(matchingbuild1-3's hardcodedJDKPATH), ant/opt/apache-ant-1.6.5,/opt/javamail-1.3.1,/opt/jaf-1.0.2, and the repo at/work; exports theJAVA_MAIL_HOME/JAVA_ACTIVATION_HOMEthatbuild1-3uses but forgets to set; runs as your uid so build artifacts aren't root-owned.
Two non-obvious mount facts:
- ORO for
<replaceregexp>. JDK 1.3 has nojava.util.regex, so ant's regexp preprocessing needs a Jakarta ORO impl (/opt/ant/libships only theant-apache-oroadapter). The script locates anoro-2.0.x.jar(default~/.m2/.../oro/2.0.8) and injects it withANT_ARGS="-lib /opt/extralib". It is not dropped into/opt/ant/libbecause docker cannot create a new mountpoint file inside the read-only/opt/antmount (that fails with "read-only file system"). --platform linux/386sets the userland arch but not the syscall personality, souname -mstill returnsx86_64— hence the imageunameshim rather than relying onlinux32.
The jdk1.3 overlays have rotted — the real source floor is Java 1.4
build1-3 provider does not currently produce a jar out of the box: the current src/main/java
uses Java 1.4 APIs that the jdk1.3 tree never caught up with. Known breakages (fixed where
noted; expect more to surface as each layer clears):
Throwable.initCause(Java 1.4, absent in 1.3). Everything routes throughorg.bouncycastle.util.Exceptionsandorg.bouncycastle.jcajce.provider.util.SecurityExceptions, whose base classes chain viainitCause. Handled with jdk1.3 overlays that construct message-only (1.3 has nogetCause, so no caller can observe a dropped cause) — keep the message text verbatim (test contract) and the factory signatures in lockstep with base. DirectinitCause/getCauseusers outside those two factories need per-file overlays too (grep them:grep -rl '\.initCause(\|\.getCause(' core/src/main/java prov/src/main/java).@Deprecatedsurvived preprocessing (illegal character: \64=@, then cascading<identifier> expected). Root cause: the sharedant/build.regexp${regexp}strips@Override/@SuppressWarnings/@FunctionalInterfacebut not@Deprecated;jdk14.xmlhas a dedicated@Deprecatedpass andjdk13.xmlwas missing it. Fixed by mirroring that pass intoant/jdk13.xml. (If a new annotation type appears, add a pass the same way.)
The Java-1.4-vs-1.3 delta is narrow in reachable code (initCause/getCause a handful of files,
plus a few java.net.URI/java.nio.* users, most of which already have overlays). There are no
assert statements or java.util.regex uses in reachable main code. So the effort is overlay-sync,
not a rewrite. Follow the overlay discipline in docs/claude/build-jdk14.md (prefer deleting an
overlay when base is 1.3-clean after preprocessing; NOTE-comment every overlay that must exist;
keep core/src/main/jdk1.3/.../util/Properties.java mirroring base constants).
Iterating fast
The <replaceregexp> preprocess is the ~7-min bottleneck, and the staging tree is never cleaned
by the build (stale sources keep compiling), so after changing overlays/excludes:
rm -rf build # on the host; build/ is gitignored
.claude/skills/build-jdk13-docker/build-jdk13.sh provider
For tighter loops use shell: it drops you into the 1.3 container with everything mounted, so you
can run sh build1-3 provider (or ant -f ant/jdk13.xml build-provider) directly and re-run after
editing overlays in /work, without paying container startup each time. Errors go to the console;
failed test suites write per-suite XML under build/artifacts/jdk1.3/reports/xml/.
Verify overlay fixes against the real build — the preprocessor plus 1.3 javac is the only authority,
never eyeball. Related: docs/claude/build-jdk14.md, the build-jdk15to18 skill, and CLAUDE.md's
"Main source stays Java 4 compatible" note (the maintained floor is 1.4; 1.3 is stricter still).