From 804c8b3439b9afc60ad4451b0e7c8c304fdb51d6 Mon Sep 17 00:00:00 2001
From: Michael Tautschnig <tautschn@amazon.com>
Date: Sat, 29 Nov 2025 10:35:04 +0100
Subject: [PATCH] Update COMPILING.md with .tar.gz build instructions

Add documentation for building from .tar.gz releases:
- Instructions to manually clone java-models-library
- Clear distinction between git vs .tar.gz builds

Fixes: #7724
---
 COMPILING.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 64 insertions(+), 1 deletion(-)

diff --git a/COMPILING.md b/COMPILING.md
index 7418cbbe1b2..ad8730f4c15 100644
--- a/COMPILING.md
+++ b/COMPILING.md
@@ -67,6 +67,22 @@ files.
    ```
    git submodule update --init
    ```
+   **Note for .tar.gz source releases**: If you downloaded CBMC as a `.tar.gz`
+   archive from GitHub releases (rather than cloning the git repository), the
+   git submodules will not be included. This primarily affects JBMC compilation,
+   which requires the `java-models-library` submodule. You have two options:
+
+   - **Option 1: Manually clone java-models-library** (required for JBMC):
+     ```
+     git clone https://github.com/diffblue/java-models-library.git jbmc/lib/java-models-library
+     ```
+     This will place the java-models-library in the correct location for JBMC
+     compilation.
+
+   - **Option 2: Disable JBMC compilation** (see step 4 below):
+     If you don't need JBMC, you can skip the submodule setup and disable JBMC
+     by passing `-DWITH_JBMC=OFF` to CMake in step 4.
+
 4. Generate build files with CMake:
    ```
    cmake -S . -Bbuild
@@ -173,6 +189,9 @@ We assume that you have a Debian/Ubuntu or Red Hat-like distribution.
    git clone https://github.com/diffblue/cbmc cbmc-git
    cd cbmc-git
    ```
+   **Note for .tar.gz source releases**: If you downloaded CBMC as a `.tar.gz`
+   archive from GitHub releases, extract it and `cd` into the extracted
+   directory instead of using the `git clone` command above.
 
 3. To compile, do
    ```
@@ -187,6 +206,14 @@ We assume that you have a Debian/Ubuntu or Red Hat-like distribution.
    make -C jbmc/src setup-submodules
    make -C jbmc/src
    ```
+   **Note for .tar.gz source releases**: The `setup-submodules` target uses
+   `git submodule update --init`, which only works when building from a git
+   repository clone. If you downloaded a `.tar.gz` release, you must manually
+   clone the java-models-library before compiling JBMC:
+   ```
+   git clone https://github.com/diffblue/java-models-library.git jbmc/lib/java-models-library
+   make -C jbmc/src
+   ```
 
 ## Compiling with Make on MacOS
 
@@ -203,6 +230,10 @@ Follow these instructions:
    git clone https://github.com/diffblue/cbmc cbmc-git
    cd cbmc-git
    ```
+   **Note for .tar.gz source releases**: If you downloaded CBMC as a `.tar.gz`
+   archive from GitHub releases, extract it and `cd` into the extracted
+   directory instead of using the `git clone` command above.
+
 3. To compile CBMC, do
    ```
    make -C src minisat2-download
@@ -214,6 +245,14 @@ Follow these instructions:
    make -C jbmc/src setup-submodules
    make -C jbmc/src
    ```
+   **Note for .tar.gz source releases**: The `setup-submodules` target uses
+   `git submodule update --init`, which only works when building from a git
+   repository clone. If you downloaded a `.tar.gz` release, you must manually
+   clone the java-models-library before compiling JBMC:
+   ```
+   git clone https://github.com/diffblue/java-models-library.git jbmc/lib/java-models-library
+   make -C jbmc/src
+   ```
 
 ## Compiling with Make on Solaris
 
@@ -229,6 +268,10 @@ Maven 3 manually.
    git clone https://github.com/diffblue/cbmc cbmc-git
    cd cbmc-git
    ```
+   **Note for .tar.gz source releases**: If you downloaded CBMC as a `.tar.gz`
+   archive from GitHub releases, extract it and `cd` into the extracted
+   directory instead of using the `git clone` command above.
+
 3. To compile CBMC, type
    ```
    gmake -C src minisat2-download DOWNLOADER=wget TAR=gtar
@@ -239,6 +282,14 @@ Maven 3 manually.
    gmake -C jbmc/src setup-submodules
    gmake -C jbmc/src
    ```
+   **Note for .tar.gz source releases**: The `setup-submodules` target uses
+   `git submodule update --init`, which only works when building from a git
+   repository clone. If you downloaded a `.tar.gz` release, you must manually
+   clone the java-models-library before compiling JBMC:
+   ```
+   git clone https://github.com/diffblue/java-models-library.git jbmc/lib/java-models-library
+   gmake -C jbmc/src
+   ```
 
 ## Compiling with Make on FreeBSD
 
@@ -255,6 +306,10 @@ Maven 3 manually.
    git clone https://github.com/diffblue/cbmc cbmc-git
    cd cbmc-git
    ```
+   **Note for .tar.gz source releases**: If you downloaded CBMC as a `.tar.gz`
+   archive from GitHub releases, extract it and `cd` into the extracted
+   directory instead of using the `git clone` command above.
+
 3. To compile CBMC, do
    ```
    gmake -C src minisat2-download
@@ -265,8 +320,16 @@ Maven 3 manually.
    gmake -C jbmc/src setup-submodules
    gmake -C jbmc/src
    ```
+   **Note for .tar.gz source releases**: The `setup-submodules` target uses
+   `git submodule update --init`, which only works when building from a git
+   repository clone. If you downloaded a `.tar.gz` release, you must manually
+   clone the java-models-library before compiling JBMC:
+   ```
+   git clone https://github.com/diffblue/java-models-library.git jbmc/lib/java-models-library
+   gmake -C jbmc/src
+   ```
 
-#Working with IDEs and Docker
+# Working with IDEs and Docker
 
 ## Working with Visual Studio on Windows