Skip to content

How to Use CompoundVM

Jump to bottom
Jonathan Lu edited this page Nov 3, 2025 · 4 revisions

How to Use CompoundVM

CompoundVM is an optimized JDK (Java Development Kit) developed by ByteDance for enhanced compatibility and performance. This guide provides instructions on how to install, configure, and run Java applications using CompoundVM.

Table of Contents

Installation

Prerequisites

  • Supported OS: Linux (x64 and aarch64)
  • Sufficient permissions to install software

Option 1: Use Bundled JDK 8 with JVM 17

Extract the archive and set up JAVA_HOME:

tar -xzvf CompoundVM_8.0.2_linux_x64.tar.gz
export JAVA_HOME=$(pwd)/CompoundVM_8.0.2_linux_x64
export PATH=$JAVA_HOME/bin:$PATH

Option 2: Patch Your Existing JDK 8

Extract the patch into your JDK 8 directory:

tar xzf CompoundVM_8.0.2_jvm_patch_linux_x64.tar.gz -C /path/to/jdk8

Option 3: Build from Source

Recommended GCC version: 8.x, 9.x.

  1. Clone the repository: 
    git clone https://github.com/bytedance/CompoundVM.git
cd CompoundVM
  2. Build CompoundVM: 
    make -f cvm.mk cvm8
    For more build options, run: 
    make -f cvm.mk help
  3. After installation, verify with: 
    output/CompoundVM_8.1.0_linux_x64//bin/java -version
output/CompoundVM_8.1.0_linux_x64//bin/java -server17 -version
    You should see output indicating JVM 17 is enabled on JDK 8.

Quick Start

CompoundVM supports two modes of operation:

1. Standard Mode (JDK8 Compatible)

Behaves identically to standard JDK8.
Example usage:

java -version
java -jar yourapp.jar

2. High Performance Mode (JDK8 + JVM17)

To enable the high-performance mode powered by JVM 17, add -server17 as the very first option in your command.
Example usage:

java -server17 -version
java -server17 -jar yourapp.jar

The -server17 option must come before all other options.

Modes of Use

  • Standard Mode:
    No special options required. Fully compatible with JDK8 applications.

  • High Performance Mode:
    Add -server17 as the first argument to enable JVM 17 features and optimizations on top of JDK8.

Configuration

CompoundVM supports standard JVM options as well as additional performance features.

  • JVM Options Example (Standard Mode): 
    java -Xmx2G -Xms512M -XX:+UseG1GC MyApp
  • JVM Options Example (High Performance Mode): 
    java -server17 -Xmx2G -Xms512M -XX:+UseG1GC MyApp

Refer to the Configuration Guide for more options.

Running Java Applications

CompoundVM is designed to be compatible with most Java applications. Use it as a drop-in replacement for your current JDK.

  • Run a JAR file (Standard Mode):

    java -jar yourapp.jar

  • Run a JAR file (High Performance Mode):

    java -server17 -jar yourapp.jar

  • Run a class file:

    java com.example.Main

    Or in high performance mode:

    java -server17 com.example.Main

Advanced Usage

  • Build Tools Integration:
    Set JAVA_HOME in Maven, Gradle, or other tools to the CompoundVM directory.

  • Native Libraries:
    CompoundVM can load native libraries written in C, C++, and Assembly.

  • Implicitly activate JVM17+JDK8 by default:
    Set environment variable JAVA_OPTIONS=-server17.

Troubleshooting

  • If java -version does not show CompoundVM, check that JAVA_HOME and PATH are set correctly.
  • For runtime errors, review the Issues page.

FAQ

Q: Is CompoundVM compatible with standard Java applications?
A: Yes, CompoundVM aims for high compatibility with the official JDK.

Q: How do I update CompoundVM?
A: Download the latest release and repeat the installation steps.

Q: How do I enable high performance mode?
A: Add -server17 as the first option in your java command.

Support

Scan QR code to join the WeChat discussion group:
qr

Clone this wiki locally