From 8908f480fe131e54e3db683ee653b481c106e2c1 Mon Sep 17 00:00:00 2001
From: Yumeng Xiao <yumeng.xiao@outlook.com>
Date: Mon, 29 Jun 2026 00:55:00 -0400
Subject: [PATCH 1/5] fix(macos): spawn readFilesCommand via posix_spawnp

The POSIX path used vfork()+execlp()+exit(0) to run the generated
readsCommand script. On macOS this fails ("Failed spawning
readFilesCommand", upstream issue #2663) because the script has no
shebang and posix_spawn-style exec has no ENOEXEC->/bin/sh fallback;
calling exit() in a vfork child is also undefined behavior.

Replace with posix_spawnp invoking "<shell> <script>" explicitly, with
proper error checking. POSIX-only branch; the Windows system()-based
path is unchanged. Ported from upstream PR #2693.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 source/Parameters_openReadsFiles.cpp | 45 ++++++++++++++++++----------
 1 file changed, 29 insertions(+), 16 deletions(-)

diff --git a/source/Parameters_openReadsFiles.cpp b/source/Parameters_openReadsFiles.cpp
index f76bfe69..e63bada7 100644
--- a/source/Parameters_openReadsFiles.cpp
+++ b/source/Parameters_openReadsFiles.cpp
@@ -5,6 +5,12 @@
 
 #ifdef _WIN32
 #include "wincompat.h"
+#else
+#include <spawn.h>
+#include <unistd.h>
+// environ is declared in <unistd.h> on glibc but not on macOS; declare it
+// explicitly so posix_spawnp can pass the current environment on every platform.
+extern char **environ;
 #endif
 
 // Large read buffer for ifstream to reduce system call overhead
@@ -132,24 +138,31 @@ void Parameters::openReadsFiles()
 
             readFilesCommandPID[imate]=0;
 
+            // Run the generated readsCommand script through a shell using
+            // posix_spawnp. Invoking it explicitly as "<shell> <script>" means
+            // the script does not need a #! shebang line (none is written by
+            // default, i.e. when --sysShell is "-") and we do not rely on
+            // execvp's ENOEXEC -> /bin/sh fallback, which posix_spawn does not
+            // provide. This fixes "Failed spawning readFilesCommand" on macOS
+            // (upstream issue #2663). posix_spawnp also avoids the undefined
+            // behavior of the previous vfork()+exit(0): calling exit() in a
+            // vfork child flushes the parent's stdio buffers and runs atexit
+            // handlers in the shared address space, and reported success even
+            // when exec failed.
             ostringstream errOut;
-            pid_t PID=vfork();
-            switch (PID) {
-                case -1:
-                    errOut << "EXITING: because of fatal EXECUTION error: Failed vforking readFilesCommand\n";
-                    errOut << errno << ": " << strerror(errno) << "\n";
-                    exitWithError(errOut.str(), std::cerr, inOut->logMain, EXIT_CODE_PARAMETER, *this);
-                    break;
-
-                case 0:
-                    //this is the child
-                    execlp(readsCommandFileName.at(imate).c_str(), readsCommandFileName.at(imate).c_str(), (char*) NULL);
-                    exit(0);
-
-                default:
-                    //this is the father, record PID of the children
-                    readFilesCommandPID[imate]=PID;
+            string readsCommandShell = (sysShell!="-" ? sysShell : "/bin/sh");
+            char* spawnArgv[] = { const_cast<char*>(readsCommandShell.c_str()),
+                                  const_cast<char*>(readsCommandFileName.at(imate).c_str()),
+                                  (char*) NULL };
+            pid_t PID=0;
+            int spawnErr = posix_spawnp(&PID, readsCommandShell.c_str(), NULL, NULL, spawnArgv, environ);
+            if (spawnErr != 0) {
+                errOut << "EXITING: because of fatal EXECUTION error: Failed spawning readFilesCommand: "
+                       << readsCommandShell << " " << readsCommandFileName.at(imate) << "\n";
+                errOut << spawnErr << ": " << strerror(spawnErr) << "\n";
+                exitWithError(errOut.str(), std::cerr, inOut->logMain, EXIT_CODE_PARAMETER, *this);
             };
+            readFilesCommandPID[imate]=PID; //record PID of the child
 
             inOut->readIn[imate].open(readFilesInTmp.at(imate).c_str());
 #endif

From 9554642048659555ce350d9862267a524d832790 Mon Sep 17 00:00:00 2001
From: Yumeng Xiao <yumeng.xiao@outlook.com>
Date: Mon, 29 Jun 2026 00:55:13 -0400
Subject: [PATCH 2/5] feat: big-endian support with guarded little-endian fast
 path

STAR read the genome, suffix array and packed arrays through native
uint*/uint128* casts, assuming little-endian byte order, which caused
"next index is smaller than previous" failures on big-endian hosts
(s390x, ppc64).

Add byteOrder.h with loadUintLE/storeUintLE helpers and route the four
endian-sensitive sites (PackedArray::operator[]/writePacked,
funCompareSuffixes, funCalcSAiFromSA) through them. The helpers are
guarded by STAR_BIG_ENDIAN: little-endian builds keep the original
single-instruction native load (zero performance/behavior change), and
only known big-endian compiles take the portable byte-wise path. The
existing MSVC byte-access path in funCalcSAiFromSA is reused for BE.

The byte-wise implementation is exposed by name and unit-tested
(test_byteOrder.cpp) so the BE algorithm is validated on the LE CI
runner. Ported from the patch in upstream issue #2690.

Note: compile-validated only; CI has no big-endian runner.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 source/Genome_genomeGenerate.cpp | 21 ++++++------
 source/PackedArray.cpp           |  5 +--
 source/PackedArray.h             |  3 +-
 source/SuffixArrayFuns.cpp       |  9 ++---
 source/byteOrder.h               | 59 ++++++++++++++++++++++++++++++++
 test/CMakeLists.txt              |  1 +
 test/unit/test_byteOrder.cpp     | 54 +++++++++++++++++++++++++++++
 7 files changed, 134 insertions(+), 18 deletions(-)
 create mode 100644 source/byteOrder.h
 create mode 100644 test/unit/test_byteOrder.cpp

diff --git a/source/Genome_genomeGenerate.cpp b/source/Genome_genomeGenerate.cpp
index 86f54f82..9b92deaf 100755
--- a/source/Genome_genomeGenerate.cpp
+++ b/source/Genome_genomeGenerate.cpp
@@ -28,33 +28,32 @@ uint globalL;
 
 inline int funCompareSuffixes ( const void *a, const void *b){
 
-    uint *ga=(uint*)((globalG-7LLU)+(*((uint*)a)));
-    uint *gb=(uint*)((globalG-7LLU)+(*((uint*)b)));
+    const char *ga=(globalG-7LLU)+(*((uint*)a));
+    const char *gb=(globalG-7LLU)+(*((uint*)b));
 
     uint jj=0;
     int  ii=0;
     uint va=0,vb=0;
-    uint8 *va1, *vb1;
 
     while (jj < globalL) {
-        va=*(ga-jj);
-        vb=*(gb-jj);
+        va=loadUintLE(ga-8*jj); // little-endian 8-byte load (native on LE)
+        vb=loadUintLE(gb-8*jj);
 
         #define has5(v) ((((v)^0x0505050505050505) - 0x0101010101010101) & ~((v)^0x0505050505050505) & 0x8080808080808080)
 
         if (has5(va) && has5(vb))
         {//there is 5 in the sequence - only compare bytes before 5
-            va1=(uint8*) &va;
-            vb1=(uint8*) &vb;
             for (ii=7;ii>=0;ii--)
-            {
-                if (va1[ii]>vb1[ii])
+            {//extract byte ii via shift: portable regardless of host byte order
+                uchar va1=(uchar)((va>>(8*ii))&0xffLLU);
+                uchar vb1=(uchar)((vb>>(8*ii))&0xffLLU);
+                if (va1>vb1)
                 {
                     return 1;
-                } else if (va1[ii]<vb1[ii])
+                } else if (va1<vb1)
                 {
                     return -1;
-                } else if (va1[ii]==5)
+                } else if (va1==5)
                 {//va=vb at the end of chr
                     if ( *((uint*)a) > *((uint*)b) )
                     {//anti-stable order,since indexes are sorted in the reverse order
diff --git a/source/PackedArray.cpp b/source/PackedArray.cpp
index a31616db..99a27145 100644
--- a/source/PackedArray.cpp
+++ b/source/PackedArray.cpp
@@ -20,8 +20,9 @@ void PackedArray::writePacked( uint jj, uint x) {
    uint S=b%8LLU;
 
    x = x << S;
-   uint* a1 = (uint*) (charArray+B);
-   *a1 = ( (*a1) & ~(bitRecMask<<S) ) | x;
+   uint a1 = loadUintLE(charArray+B); // little-endian byte stream (native load on LE)
+   a1 = ( a1 & ~(bitRecMask<<S) ) | x;
+   storeUintLE(charArray+B, a1);
 };
 
 void PackedArray::pointArray(char* pointerCharIn) {
diff --git a/source/PackedArray.h b/source/PackedArray.h
index 78df9912..0f241a58 100644
--- a/source/PackedArray.h
+++ b/source/PackedArray.h
@@ -2,6 +2,7 @@
 #define PACKEDARRAY_DEF
 
 #include "IncludeDefine.h"
+#include "byteOrder.h"
 
 class PackedArray {
     private:
@@ -26,7 +27,7 @@ inline uint PackedArray::operator [] (uint ii) {
    uint B=b/8;
    uint S=b%8;
 
-   uint a1 = *((uint*) (charArray+B));
+   uint a1 = loadUintLE(charArray+B); // little-endian byte stream (native load on LE)
    a1 = (a1>>S) & bitRecMask; // bitmask instead of double-shift (upstream PR #791)
    return a1;
 };
diff --git a/source/SuffixArrayFuns.cpp b/source/SuffixArrayFuns.cpp
index 80287ec8..a5942592 100644
--- a/source/SuffixArrayFuns.cpp
+++ b/source/SuffixArrayFuns.cpp
@@ -359,8 +359,9 @@ uint funCalcSAiFromSA(char* gSeq, PackedArray& gSA, Genome &mapGen, uint iSA, in
     uint saind=0;
     if (dirG)
     {
-#ifdef STAR_UINT128_STRUCT
-        // MSVC: no native 128-bit int, use direct byte access
+#if defined(STAR_UINT128_STRUCT) || STAR_BIG_ENDIAN
+        // No native 128-bit int (MSVC) or big-endian host: read the genome byte
+        // stream directly, which is correct regardless of host byte order.
         const char *gPtr = gSeq + SAstr;
         for (int ii=0; ii<L; ii++)
         {
@@ -379,14 +380,14 @@ uint funCalcSAiFromSA(char* gSeq, PackedArray& gSA, Genome &mapGen, uint iSA, in
             };
             saind=saind<<2;
             saind+=g2;
-#ifndef STAR_UINT128_STRUCT
+#if !defined(STAR_UINT128_STRUCT) && !STAR_BIG_ENDIAN
             g1=g1>>8;
 #endif
         };
         return saind;
     } else
     {
-#ifdef STAR_UINT128_STRUCT
+#if defined(STAR_UINT128_STRUCT) || STAR_BIG_ENDIAN
         const char *gPtr = gSeq + mapGen.nGenome - SAstr - 16;
         for (int ii=0; ii<L; ii++)
         {
diff --git a/source/byteOrder.h b/source/byteOrder.h
new file mode 100644
index 00000000..f14856f5
--- /dev/null
+++ b/source/byteOrder.h
@@ -0,0 +1,59 @@
+#ifndef CODE_byteOrder
+#define CODE_byteOrder
+
+#include "IncludeDefine.h"
+
+// STAR stores the genome, suffix array and packed arrays as a little-endian byte
+// stream (the first bit lives in the least-significant bit of charArray[0]). On
+// little-endian hosts such data can be read with a single native integer load,
+// which is fast. On big-endian hosts that load would byte-swap the value, so the
+// integer has to be assembled from / scattered to the byte stream explicitly.
+//
+// Only the load/store from memory is byte-order sensitive; once the value is a
+// host integer, extracting bytes via shifts is portable. The little-endian fast
+// path is the default; only known big-endian compiles take the portable path, so
+// x86-64 and ARM64 (incl. MSVC, which never targets big-endian) are unaffected.
+
+// STAR_BIG_ENDIAN may be forced via -DSTAR_BIG_ENDIAN=1 (e.g. to exercise the
+// portable path on a little-endian build for testing); otherwise it is detected.
+#ifndef STAR_BIG_ENDIAN
+    #if defined(__BYTE_ORDER__) && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
+        #define STAR_BIG_ENDIAN 1
+    #else
+        #define STAR_BIG_ENDIAN 0
+    #endif
+#endif
+
+// Portable byte-wise implementations: interpret/produce sizeof(uint) (==8) bytes
+// in little-endian order regardless of host byte order. Exposed by name so they
+// can be unit-tested directly even on a little-endian machine.
+inline uint loadUintLE_bytewise(const char *p) {
+    uint v=0;
+    for (uint ib=0; ib<sizeof(uint); ib++)
+        v |= ((uint)(uchar)p[ib]) << (8*ib);
+    return v;
+}
+inline void storeUintLE_bytewise(char *p, uint v) {
+    for (uint ib=0; ib<sizeof(uint); ib++)
+        p[ib] = (char)((v >> (8*ib)) & 0xffLLU);
+}
+
+// Load sizeof(uint) (==8) bytes as a little-endian unsigned integer.
+inline uint loadUintLE(const char *p) {
+#if STAR_BIG_ENDIAN
+    return loadUintLE_bytewise(p);
+#else
+    return *((const uint*)p);
+#endif
+}
+
+// Store an unsigned integer as sizeof(uint) (==8) little-endian bytes.
+inline void storeUintLE(char *p, uint v) {
+#if STAR_BIG_ENDIAN
+    storeUintLE_bytewise(p, v);
+#else
+    *((uint*)p) = v;
+#endif
+}
+
+#endif
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index c98062aa..8f7b4c78 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -28,6 +28,7 @@ add_executable(star_tests
     unit/test_FastResetVector.cpp
     unit/test_binarySearch2.cpp
     unit/test_PackedArray.cpp
+    unit/test_byteOrder.cpp
     unit/test_UMIgraph.cpp
     unit/test_blocksOverlap.cpp
     unit/test_EmptyDrops.cpp
diff --git a/test/unit/test_byteOrder.cpp b/test/unit/test_byteOrder.cpp
new file mode 100644
index 00000000..790b2a02
--- /dev/null
+++ b/test/unit/test_byteOrder.cpp
@@ -0,0 +1,54 @@
+#include "doctest/doctest.h"
+#include "byteOrder.h"
+#include <cstring>
+
+// Reference little-endian interpretation, independent of host byte order.
+static uint refLoadLE(const unsigned char *p) {
+    uint v = 0;
+    for (uint i = 0; i < sizeof(uint); i++)
+        v |= ((uint)p[i]) << (8 * i);
+    return v;
+}
+
+TEST_CASE("byteOrder - loadUintLE_bytewise matches little-endian reference") {
+    // This exercises the big-endian code path's algorithm even on a
+    // little-endian CI runner: the byte-wise loader must always interpret the
+    // buffer as little-endian regardless of host byte order.
+    unsigned char buf[8] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF};
+    CHECK(loadUintLE_bytewise((const char*)buf) == refLoadLE(buf));
+    CHECK(loadUintLE_bytewise((const char*)buf) == 0xEFCDAB8967452301ULL);
+}
+
+TEST_CASE("byteOrder - storeUintLE_bytewise produces little-endian bytes") {
+    char buf[8] = {};
+    storeUintLE_bytewise(buf, 0xEFCDAB8967452301ULL);
+    unsigned char expect[8] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF};
+    CHECK(std::memcmp(buf, expect, 8) == 0);
+}
+
+TEST_CASE("byteOrder - native loadUintLE agrees with portable byte-wise path") {
+    // On little-endian hosts the native single-instruction load must give the
+    // same value as the portable byte-wise path; this is the invariant that lets
+    // the LE fast path and the BE portable path be used interchangeably.
+    const uint vals[] = {0ULL, 1ULL, 0xFFULL, 0x100ULL, 0x1FFFFFULL,
+                         12345678901234ULL, ~0ULL, 0xDEADBEEFCAFEBABEULL};
+    for (uint v : vals) {
+        char buf[8];
+        storeUintLE_bytewise(buf, v);
+        CHECK(loadUintLE((const char*)buf) == loadUintLE_bytewise((const char*)buf));
+        CHECK(loadUintLE((const char*)buf) == v);
+    }
+}
+
+TEST_CASE("byteOrder - store/load round-trip (both paths)") {
+    const uint vals[] = {0ULL, 42ULL, 0x7FFFFFFFFFFFFFFFULL, ~0ULL, 0xA5A5A5A5A5A5A5A5ULL};
+    for (uint v : vals) {
+        char nbuf[8], bbuf[8];
+        storeUintLE(nbuf, v);            // native (LE) or portable (BE), per build
+        storeUintLE_bytewise(bbuf, v);   // always portable
+        CHECK(loadUintLE((const char*)nbuf) == v);
+        CHECK(loadUintLE_bytewise((const char*)bbuf) == v);
+        // Both encoders must yield identical on-disk bytes (format stability).
+        CHECK(std::memcmp(nbuf, bbuf, 8) == 0);
+    }
+}

From 03075b6af5a8e900fed75fa0c3ad8b5bedc17776 Mon Sep 17 00:00:00 2001
From: Yumeng Xiao <yumeng.xiao@outlook.com>
Date: Mon, 29 Jun 2026 00:55:27 -0400
Subject: [PATCH 3/5] feat: referenceless CRAM output (--outSAMtype CRAM)

Add CRAM as an output container. STAR produces its BAM via the proven
output path, then transcodes it to referenceless CRAM at finalization
(cramOutput.cpp, using bundled HTSlib with CRAM_OPT_NO_REF, so no
external reference FASTA is required). On conversion failure the
original BAM is kept and the run continues.

- Parameters_runtimeSetup: accept "CRAM" as outSAMtype[0], reusing the
  BAM Unsorted/SortedByCoordinate logic; set outCRAMbool and CRAM names.
- STAR.cpp: transcode Aligned.out.bam / Aligned.sortedByCoord.out.bam
  to .cram after wiggle output, removing the intermediate BAM.
- Hot per-record output code is untouched; the transcriptome BAM stays
  BAM for RSEM/Salmon. CRAM is incompatible with --outStd.
- WebUI: CRAM options in the outSAMtype dropdown, .cram artifacts and
  MIME type.
- Registered cramOutput in CMake build.

Implemented properly rather than porting the incomplete upstream draft
PR #2670 (which wrote a NULL header and rerouted the working BAM path).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 source/CMakeLists.txt              |  1 +
 source/Parameters.h                |  2 +
 source/Parameters_runtimeSetup.cpp | 24 +++++++++---
 source/STAR.cpp                    | 18 +++++++++
 source/cramOutput.cpp              | 61 ++++++++++++++++++++++++++++++
 source/cramOutput.h                | 17 +++++++++
 source/parametersDefault           |  1 +
 source/webui/WebUI.cpp             |  1 +
 source/webui/WebUI_html.inc        |  4 +-
 source/webui/WebUI_report.cpp      |  1 +
 10 files changed, 124 insertions(+), 6 deletions(-)
 create mode 100644 source/cramOutput.cpp
 create mode 100644 source/cramOutput.h

diff --git a/source/CMakeLists.txt b/source/CMakeLists.txt
index b585b1ba..dad1b24e 100644
--- a/source/CMakeLists.txt
+++ b/source/CMakeLists.txt
@@ -383,6 +383,7 @@ set(STAR_SOURCES
     serviceFuns.cpp
     GlobalVariables.cpp
     BAMoutput.cpp
+    cramOutput.cpp
     BAMfunctions.cpp
     ReadAlign_alignBAM.cpp
     BAMbinSortByCoordinate.cpp
diff --git a/source/Parameters.h b/source/Parameters.h
index b1163394..35421bed 100755
--- a/source/Parameters.h
+++ b/source/Parameters.h
@@ -163,6 +163,7 @@ class Parameters {
 
         //SAM output
         string outBAMfileCoordName, outBAMfileUnsortedName, outQuantBAMfileName;
+        string outCRAMfileCoordName, outCRAMfileUnsortedName;//referenceless CRAM outputs (--outSAMtype CRAM)
         string samHeader, samHeaderHD, samHeaderSortedCoord, samHeaderExtra;
         string outSAMmode,  outSAMorder, outSAMprimaryFlag;
         vector<string> outSAMattributes, outSAMheaderHD, outSAMheaderPG;
@@ -184,6 +185,7 @@ class Parameters {
         int outBAMcompression;
         vector <string> outSAMtype;
         bool outBAMunsorted, outBAMcoord, outSAMbool;
+        bool outCRAMbool;//true when --outSAMtype CRAM: produce BAM then transcode to referenceless CRAM
         uint32 outBAMcoordNbins;
         uint32 outBAMsortingBinsN;//user-defined number of bins for sorting
         string outBAMsortTmpDir;
diff --git a/source/Parameters_runtimeSetup.cpp b/source/Parameters_runtimeSetup.cpp
index 5f31b683..5b07569f 100644
--- a/source/Parameters_runtimeSetup.cpp
+++ b/source/Parameters_runtimeSetup.cpp
@@ -155,12 +155,22 @@ void Parameters::inputParameters_runtimeSetup() {
     outSAMbool=false;
     outBAMunsorted=false;
     outBAMcoord=false;
+    outCRAMbool=false;
     if (runMode=="alignReads" && outSAMmode != "None") {//open SAM file and write header
-        if (outSAMtype.at(0)=="BAM") {
+        if (outSAMtype.at(0)=="BAM" || outSAMtype.at(0)=="CRAM") {
+            //CRAM reuses the proven BAM output path and is transcoded to referenceless
+            //CRAM at finalization (see bamToCramReferenceless / STAR.cpp)
+            outCRAMbool = (outSAMtype.at(0)=="CRAM");
+            if (outCRAMbool && outStd!="Log") {
+                ostringstream errOut;
+                errOut <<"EXITING because of fatal PARAMETER error: --outSAMtype CRAM is not compatible with --outStd "<<outStd<<"\n";
+                errOut <<"SOLUTION: re-run STAR with --outStd Log (the default) when using --outSAMtype CRAM\n";
+                exitWithError(errOut.str(), std::cerr, inOut->logMain, EXIT_CODE_PARAMETER, *this);
+            };
             if (outSAMtype.size()<2) {
                 ostringstream errOut;
-                errOut <<"EXITING because of fatal PARAMETER error: missing BAM option\n";
-                errOut <<"SOLUTION: re-run STAR with one of the allowed values of --outSAMtype BAM Unsorted OR SortedByCoordinate OR both\n";
+                errOut <<"EXITING because of fatal PARAMETER error: missing "<<outSAMtype.at(0)<<" option\n";
+                errOut <<"SOLUTION: re-run STAR with one of the allowed values of --outSAMtype "<<outSAMtype.at(0)<<" Unsorted OR SortedByCoordinate OR both\n";
                 exitWithError(errOut.str(), std::cerr, inOut->logMain, EXIT_CODE_PARAMETER, *this);
             };
             for (uint32 ii=1; ii<outSAMtype.size(); ii++) {
@@ -171,7 +181,7 @@ void Parameters::inputParameters_runtimeSetup() {
                 } else {
                     ostringstream errOut;
                     errOut <<"EXITING because of fatal input ERROR: unknown value for the word " <<ii+1<<" of outSAMtype: "<< outSAMtype.at(ii) <<"\n";
-                    errOut <<"SOLUTION: re-run STAR with one of the allowed values of --outSAMtype BAM Unsorted or SortedByCoordinate or both\n";
+                    errOut <<"SOLUTION: re-run STAR with one of the allowed values of --outSAMtype "<<outSAMtype.at(0)<<" Unsorted or SortedByCoordinate or both\n";
                     exitWithError(errOut.str(), std::cerr, inOut->logMain, EXIT_CODE_PARAMETER, *this);
                 };
             };
@@ -182,6 +192,8 @@ void Parameters::inputParameters_runtimeSetup() {
                 } else {
                     outBAMfileUnsortedName=outFileNamePrefix + "Aligned.out.bam";
                 };
+                if (outCRAMbool)
+                    outCRAMfileUnsortedName=outFileNamePrefix + "Aligned.out.cram";
                 inOut->outBAMfileUnsorted = bgzf_open(outBAMfileUnsortedName.c_str(),("w"+to_string((long long) outBAMcompression)).c_str());
             };
             if (outBAMcoord) {
@@ -190,6 +202,8 @@ void Parameters::inputParameters_runtimeSetup() {
                 } else {
                     outBAMfileCoordName=outFileNamePrefix + "Aligned.sortedByCoord.out.bam";
                 };
+                if (outCRAMbool)
+                    outCRAMfileCoordName=outFileNamePrefix + "Aligned.sortedByCoord.out.cram";
                 inOut->outBAMfileCoord = bgzf_open(outBAMfileCoordName.c_str(),("w"+to_string((long long) outBAMcompression)).c_str());
                 if (outBAMsortingThreadN==0) {
                     outBAMsortingThreadNactual=min(6, runThreadN);
@@ -223,7 +237,7 @@ void Parameters::inputParameters_runtimeSetup() {
         } else {
             ostringstream errOut;
             errOut <<"EXITING because of fatal input ERROR: unknown value for the first word of outSAMtype: "<< outSAMtype.at(0) <<"\n";
-            errOut <<"SOLUTION: re-run STAR with one of the allowed values of outSAMtype: BAM or SAM \n"<<flush;
+            errOut <<"SOLUTION: re-run STAR with one of the allowed values of outSAMtype: BAM, CRAM, or SAM \n"<<flush;
             exitWithError(errOut.str(), std::cerr, inOut->logMain, EXIT_CODE_PARAMETER, *this);
         };
     };
diff --git a/source/STAR.cpp b/source/STAR.cpp
index 2630d00a..650e4e26 100755
--- a/source/STAR.cpp
+++ b/source/STAR.cpp
@@ -21,6 +21,7 @@
 #include "sysRemoveDir.h"
 #include "BAMfunctions.h"
 #include "bamSortByCoordinate.h"
+#include "cramOutput.h"
 #include "Transcriptome.h"
 #include "signalFromBAM.h"
 #include "mapThreadsSpawn.h"
@@ -296,6 +297,23 @@ int main(int argInN, char *argIn[])
         signalFromBAM(P.outBAMfileCoordName, wigOutFileNamePrefix, P);
     };
 
+    // CRAM output: transcode the finished BAM output(s) to referenceless CRAM.
+    // Done after wiggle (which reads the sorted BAM) so the intermediate BAM is
+    // still present. Reuses STAR's proven BAM path; only the final container changes.
+    if (P.outCRAMbool)
+    {
+        if (P.outBAMunsorted)
+        {
+            *(P.inOut->logStdOut) << timeMonthDayTime() << " ..... started CRAM conversion (unsorted)\n" << flush;
+            bamToCramReferenceless(P.outBAMfileUnsortedName, P.outCRAMfileUnsortedName, P);
+        };
+        if (P.outBAMcoord)
+        {
+            *(P.inOut->logStdOut) << timeMonthDayTime() << " ..... started CRAM conversion (sorted)\n" << flush;
+            bamToCramReferenceless(P.outBAMfileCoordName, P.outCRAMfileCoordName, P);
+        };
+    };
+
     g_statsAll.writeLines(P.inOut->outChimJunction, P.pCh.outJunctionFormat, "#", STAR_VERSION + string("   ") + P.commandLine);
 
     g_statsAll.progressReport(P.inOut->logProgress);
diff --git a/source/cramOutput.cpp b/source/cramOutput.cpp
new file mode 100644
index 00000000..a41ed60b
--- /dev/null
+++ b/source/cramOutput.cpp
@@ -0,0 +1,61 @@
+#include "cramOutput.h"
+#include "htslib/htslib/sam.h"
+#include "ErrorWarning.h"
+#include <iostream>
+#include <cstdio>
+
+bool bamToCramReferenceless(const std::string &inBam, const std::string &outCram, Parameters &P) {
+
+    samFile *in = sam_open(inBam.c_str(), "rb");
+    if (in==NULL) {
+        warningMessage("Could not open intermediate BAM for CRAM conversion: "+inBam+" ; keeping BAM output.", std::cerr, P.inOut->logMain, P);
+        return false;
+    };
+
+    sam_hdr_t *hdr = sam_hdr_read(in);
+    if (hdr==NULL) {
+        sam_close(in);
+        warningMessage("Could not read BAM header for CRAM conversion: "+inBam+" ; keeping BAM output.", std::cerr, P.inOut->logMain, P);
+        return false;
+    };
+
+    samFile *out = sam_open(outCram.c_str(), "wc"); //"wc" = write CRAM
+    if (out==NULL) {
+        sam_hdr_destroy(hdr);
+        sam_close(in);
+        warningMessage("Could not open output CRAM file: "+outCram+" ; keeping BAM output.", std::cerr, P.inOut->logMain, P);
+        return false;
+    };
+
+    // Referenceless CRAM: encode sequences verbatim, no external reference needed.
+    hts_set_opt(out, CRAM_OPT_NO_REF, 1);
+    if (P.runThreadN>1)
+        hts_set_threads(out, P.runThreadN);
+
+    bool ok = (sam_hdr_write(out, hdr) >= 0);
+    bam1_t *b = bam_init1();
+    int r = 0;
+    while (ok && (r = sam_read1(in, hdr, b)) >= 0) {
+        if (sam_write1(out, hdr, b) < 0) {
+            ok = false;
+            break;
+        };
+    };
+    if (r < -1) //sam_read1 returns -1 at EOF, < -1 on error
+        ok = false;
+
+    bam_destroy1(b);
+    sam_hdr_destroy(hdr);
+    sam_close(in);
+    if (sam_close(out) < 0)
+        ok = false;
+
+    if (ok) {
+        remove(inBam.c_str()); //drop the intermediate BAM
+        P.inOut->logMain << "CRAM conversion: " << inBam << " -> " << outCram << " (referenceless)\n" << std::flush;
+    } else {
+        remove(outCram.c_str()); //failed conversion: drop partial CRAM, keep BAM
+        warningMessage("CRAM conversion failed for "+inBam+" ; keeping BAM output.", std::cerr, P.inOut->logMain, P);
+    };
+    return ok;
+};
diff --git a/source/cramOutput.h b/source/cramOutput.h
new file mode 100644
index 00000000..73e76109
--- /dev/null
+++ b/source/cramOutput.h
@@ -0,0 +1,17 @@
+#ifndef CODE_cramOutput
+#define CODE_cramOutput
+
+#include <string>
+#include "Parameters.h"
+
+// Transcode a finished BAM file to referenceless CRAM, then remove the input
+// BAM on success. This implements --outSAMtype CRAM by reusing STAR's proven
+// BAM output path and converting at finalization, leaving the hot per-record
+// output code untouched. Referenceless CRAM (CRAM_OPT_NO_REF) stores sequences
+// verbatim, so no external reference FASTA is required.
+//
+// Returns true on success. On any failure it removes the partial CRAM, leaves
+// the original BAM in place, and emits a warning (the run is not aborted).
+bool bamToCramReferenceless(const std::string &inBam, const std::string &outCram, Parameters &P);
+
+#endif
diff --git a/source/parametersDefault b/source/parametersDefault
index 27ff94c0..fec77896 100755
--- a/source/parametersDefault
+++ b/source/parametersDefault
@@ -305,6 +305,7 @@ outSAMtype                      SAM
     strings: type of SAM/BAM output
                                 1st word:
                                 BAM  ... output BAM without sorting
+                                CRAM ... output referenceless CRAM (BAM is produced then transcoded to CRAM; no external reference FASTA required)
                                 SAM  ... output SAM without sorting
                                 None ... no SAM/BAM output
                                 2nd, 3rd:
diff --git a/source/webui/WebUI.cpp b/source/webui/WebUI.cpp
index b6742ef7..6c68ba5f 100644
--- a/source/webui/WebUI.cpp
+++ b/source/webui/WebUI.cpp
@@ -712,6 +712,7 @@ void WebUI::run() {
 
         // Top-level known files
         for (const char* name : {"Aligned.sortedByCoord.out.bam", "Aligned.out.bam",
+                                  "Aligned.sortedByCoord.out.cram", "Aligned.out.cram",
                                   "Aligned.out.sam", "SJ.out.tab",
                                   "Log.final.out", "Log.out", "WebUI_Report.html"}) {
             addFile(name);
diff --git a/source/webui/WebUI_html.inc b/source/webui/WebUI_html.inc
index 9a4712cb..1deb1977 100644
--- a/source/webui/WebUI_html.inc
+++ b/source/webui/WebUI_html.inc
@@ -132,11 +132,13 @@ R"HTML(
         <label>Output Prefix <span style="font-weight:400;color:#aaa">(directory must exist)</span></label>
         <input id="outPrefix" type="text" placeholder="/data/output/sample_">
       </div>
-      <div class="field" style="flex:0 0 230px" data-tip="Output alignment format. BAM SortedByCoordinate: required for IGV, featureCounts, HTSeq. BAM Unsorted: faster, use with --quantMode TranscriptomeSAM for RSEM. None: skip alignment output for count-only runs.">
+      <div class="field" style="flex:0 0 230px" data-tip="Output alignment format. BAM SortedByCoordinate: required for IGV, featureCounts, HTSeq. BAM Unsorted: faster, use with --quantMode TranscriptomeSAM for RSEM. CRAM: smaller referenceless CRAM (no reference FASTA needed). None: skip alignment output for count-only runs.">
         <label>outSAMtype</label>
         <select id="samtype">
           <option value="BAM SortedByCoordinate">BAM SortedByCoordinate</option>
           <option value="BAM Unsorted">BAM Unsorted</option>
+          <option value="CRAM SortedByCoordinate">CRAM SortedByCoordinate</option>
+          <option value="CRAM Unsorted">CRAM Unsorted</option>
           <option value="SAM">SAM</option>
           <option value="None">None (count only)</option>
         </select>
diff --git a/source/webui/WebUI_report.cpp b/source/webui/WebUI_report.cpp
index 16e7932c..ab552e4d 100644
--- a/source/webui/WebUI_report.cpp
+++ b/source/webui/WebUI_report.cpp
@@ -91,6 +91,7 @@ std::string artifactType(const std::string& name) {
     if (ends(".tsv"))   return "tsv";
     if (ends(".csv"))   return "csv";
     if (ends(".bam"))   return "bam";
+    if (ends(".cram"))  return "cram";
     if (ends(".sam"))   return "sam";
     if (ends(".tab"))   return "tab";
     if (ends(".html"))  return "html";

From 6a57e0e303163de07df1445b1d141d141677c642 Mon Sep 17 00:00:00 2001
From: Yumeng Xiao <yumeng.xiao@outlook.com>
Date: Mon, 29 Jun 2026 00:55:40 -0400
Subject: [PATCH 4/5] build: Makefile ARM64/macOS/libomp parity and cramOutput

Port the platform-detection from upstream PR #2694 to the Makefile (CI
uses CMake, which already handles ARM64; this is for `make` users):
- detect UNAME_S/UNAME_M; select -mavx2 on x86_64, -march=armv8-a+simd
  on ARM64/AArch64
- macOS + Apple clang OpenMP: -Xpreprocessor -fopenmp + libomp include,
  -lomp at link; add native STARforMac target (dynamic libomp)
- portable BSD/macOS date fallback for the build timestamp
- add cramOutput.o to OBJECTS

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 source/Makefile | 59 ++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 49 insertions(+), 10 deletions(-)

diff --git a/source/Makefile b/source/Makefile
index 985bd5b3..45a0e97b 100644
--- a/source/Makefile
+++ b/source/Makefile
@@ -11,18 +11,46 @@ CXXFLAGSextra ?=
 # user may define the compiler
 CXX ?= g++
 
+# ---- Platform / architecture detection -----------------------------------
+UNAME_S := $(shell uname -s)
+UNAME_M := $(shell uname -m)
+
+# ---- OpenMP flags --------------------------------------------------------
+# GNU/Linux: -fopenmp links libgomp automatically.
+# macOS + Apple clang: needs -Xpreprocessor -fopenmp at compile time, plus an
+# explicit libomp include path and -lomp at link time (no bundled OpenMP).
+ifeq ($(UNAME_S),Darwin)
+    LIBOMP ?= $(shell brew --prefix libomp 2>/dev/null)
+    ifeq ($(LIBOMP),)
+        ifneq ($(wildcard /opt/homebrew/opt/libomp/include/omp.h),)
+            LIBOMP := /opt/homebrew/opt/libomp
+        else
+            LIBOMP := /usr/local/opt/libomp
+        endif
+    endif
+    OPENMP_CXXFLAGS := -Xpreprocessor -fopenmp -I$(LIBOMP)/include
+    OPENMP_LDFLAGS  := -L$(LIBOMP)/lib -lomp
+else
+    OPENMP_CXXFLAGS := -fopenmp
+    OPENMP_LDFLAGS  :=
+endif
+
 # pre-defined flags
 LDFLAGS_shared := -pthread -Lhtslib -Bstatic -lhts -Bdynamic -lz -lparasail
 LDFLAGS_static := -static -static-libgcc -pthread -Lhtslib -lhts -lz -lparasail
-LDFLAGS_Mac :=-pthread -lz htslib/libhts.a -lparasail
-LDFLAGS_Mac_static :=-pthread -lz -static-libgcc htslib/libhts.a -lparasail
+# macOS: Apple clang has no -static-libgcc and no fully static binary; "static"
+# here means htslib is linked as a static archive. libomp is linked via OPENMP_LDFLAGS.
+LDFLAGS_Mac :=-pthread -lz htslib/libhts.a -lparasail $(OPENMP_LDFLAGS)
+LDFLAGS_Mac_static :=-pthread -lz htslib/libhts.a -lparasail $(OPENMP_LDFLAGS)
+LDFLAGS_Mac_dynamic :=-pthread -lz htslib/libhts.a -lparasail $(OPENMP_LDFLAGS)
 LDFLAGS_gdb := $(LDFLAGS_shared)
 
 DATE_FMT = --iso-8601=seconds
 ifdef SOURCE_DATE_EPOCH
     BUILD_DATE ?= $(shell date -u -d "@$(SOURCE_DATE_EPOCH)" "$(DATE_FMT)" 2>/dev/null || date -u -r "$(SOURCE_DATE_EPOCH)" "$(DATE_FMT)" 2>/dev/null || date -u "$(DATE_FMT)")
 else
-    BUILD_DATE ?= $(shell date "$(DATE_FMT)")
+    # GNU date supports --iso-8601; BSD/macOS date does not, so fall back to a portable format.
+    BUILD_DATE ?= $(shell date "$(DATE_FMT)" 2>/dev/null || date -u "+%Y-%m-%dT%H:%M:%S%z")
 endif
 
 BUILD_PLACE ?= $(HOSTNAME):$(shell pwd)
@@ -42,10 +70,17 @@ GIT_BRANCH_COMMIT_DIFF := -D'GIT_BRANCH_COMMIT_DIFF="$(GIT_BRANCH_COMMIT_DIFF)"'
 # Defaults, can be overridden by make arguments or environment
 CXXFLAGS ?= -pipe -Wall -Wextra
 CFLAGS ?= -pipe -Wall -Wextra -O3
-CXXFLAGS_SIMD ?= -mavx2
+# SIMD flags: AVX2 on x86_64, NEON on ARM64/AArch64 (incl. Apple Silicon).
+ifeq ($(UNAME_M),x86_64)
+    CXXFLAGS_SIMD ?= -mavx2
+else ifeq ($(UNAME_M),amd64)
+    CXXFLAGS_SIMD ?= -mavx2
+else
+    CXXFLAGS_SIMD ?= -march=armv8-a+simd
+endif
 
 # Unconditionally set essential flags and optimization options
-CXXFLAGS_common := -std=c++17 -fopenmp $(COMPTIMEPLACE) $(GIT_BRANCH_COMMIT_DIFF)
+CXXFLAGS_common := -std=c++17 $(OPENMP_CXXFLAGS) $(COMPTIMEPLACE) $(GIT_BRANCH_COMMIT_DIFF)
 CXXFLAGS_main := -O3 $(CXXFLAGS_common)
 CXXFLAGS_gdb := -O0 -g3 $(CXXFLAGS_common)
 
@@ -91,7 +126,7 @@ OBJECTS = systemFunctions.o funPrimaryAlignMark.o \
 	sjdbLoadFromFiles.o sjdbLoadFromStream.o sjdbPrepare.o sjdbBuildIndex.o sjdbInsertJunctions.o mapThreadsSpawn.o \
 	Parameters_readFilesInit.o Parameters_openReadsFiles.o Parameters_closeReadsFiles.o Parameters_readSAMheader.o \
 	bam_cat.o serviceFuns.o GlobalVariables.o \
-	BAMoutput.o BAMfunctions.o ReadAlign_alignBAM.o BAMbinSortByCoordinate.o signalFromBAM.o bamRemoveDuplicates.o BAMbinSortUnmapped.o
+	BAMoutput.o cramOutput.o BAMfunctions.o ReadAlign_alignBAM.o BAMbinSortByCoordinate.o signalFromBAM.o bamRemoveDuplicates.o BAMbinSortUnmapped.o
 
 SOURCES := $(wildcard *.cpp) $(wildcard *.c)
 
@@ -125,8 +160,6 @@ ifneq ($(MAKECMDGOALS),clean)
 ifneq ($(MAKECMDGOALS),CLEAN)
 ifneq ($(MAKECMDGOALS),CLEAN)
 ifneq ($(MAKECMDGOALS),clean_solo)
-ifneq ($(MAKECMDGOALS),STARforMac)
-ifneq ($(MAKECMDGOALS),STARforMacGDB)
 Depend.list: $(SOURCES) parametersDefault.xxd htslib
 	echo $(SOURCES)
 	'rm' -f ./Depend.list
@@ -136,8 +169,6 @@ endif
 endif
 endif
 endif
-endif
-endif
 
 htslib : htslib/libhts.a
 
@@ -197,6 +228,14 @@ STARforMacStatic : LDFLAGS := $(LDFLAGSextra) $(LDFLAGS_Mac_static) $(LDFLAGS)
 STARforMacStatic : Depend.list parametersDefault.xxd $(OBJECTS)
 	$(CXX) -o STAR $(CXXFLAGS) $(OBJECTS) $(LDFLAGS)
 
+# Native macOS build (Apple clang). Links htslib statically and libomp
+# dynamically. On Apple Silicon this produces an arm64-native binary; on Intel
+# Macs an x86_64 binary. Build with:  make STARforMac CXX=clang++
+STARforMac : CXXFLAGS := $(CXXFLAGSextra) $(CXXFLAGS_main) -D'COMPILE_FOR_MAC' $(CXXFLAGS)
+STARforMac : LDFLAGS := $(LDFLAGSextra) $(LDFLAGS_Mac_dynamic) $(LDFLAGS)
+STARforMac : Depend.list parametersDefault.xxd $(OBJECTS)
+	$(CXX) -o STAR $(CXXFLAGS) $(OBJECTS) $(LDFLAGS)
+
 STARlongForMacStatic : CXXFLAGS := -D'COMPILE_FOR_LONG_READS' $(CXXFLAGSextra) $(CXXFLAGS_main) -D'COMPILE_FOR_MAC' $(CXXFLAGS)
 STARlongForMacStatic : LDFLAGS := $(LDFLAGSextra) $(LDFLAGS_Mac_static) $(LDFLAGS)
 STARlongForMacStatic : Depend.list parametersDefault.xxd $(OBJECTS)

From 89d116b16ad86e22e900cbcb74e7a924e8e9ea8b Mon Sep 17 00:00:00 2001
From: Yumeng Xiao <yumeng.xiao@outlook.com>
Date: Mon, 29 Jun 2026 00:55:40 -0400
Subject: [PATCH 5/5] docs: document CRAM output, ARM64/macOS, and big-endian
 support

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7b813270..bba93c95 100644
--- a/README.md
+++ b/README.md
@@ -24,8 +24,9 @@ https://github.com/birdingman0626/STAR/issues
 
 HARDWARE/SOFTWARE REQUIREMENTS
 ==============================
-  * x86-64 compatible processors
+  * x86-64 compatible processors, or ARM64/AArch64 (incl. Apple Silicon)
   * 64 bit Linux, Mac OS X, or Windows
+  * little-endian or big-endian hosts (big-endian, e.g. s390x/ppc64, is compile-supported but not part of CI)
 
 MANUAL
 ======
@@ -331,6 +332,11 @@ FORK CHANGES
   * Pure C++ implementation using cpp-httplib + nlohmann/json; no Node.js required
   * Child-process execution model keeps the server stable across run failures
 
+### Output Formats & Portability (new)
+  * **Referenceless CRAM output** (`--outSAMtype CRAM Unsorted|SortedByCoordinate`): STAR produces its normal BAM via the proven output path, then transcodes it to CRAM at finalization using bundled HTSlib (`source/cramOutput.cpp`). Uses `CRAM_OPT_NO_REF`, so **no external reference FASTA is required**. CRAM is typically ~10–25% smaller than BAM on full-quality data (the gain comes from CRAM's rANS/quality/read-name codecs, not reference compression). On conversion failure the original BAM is kept and the run continues. Applies to the main `Aligned.*` outputs; the transcriptome BAM (`--quantMode TranscriptomeSAM`) stays BAM for RSEM/Salmon compatibility. Selectable in the Web UI.
+  * **ARM64 / Apple Silicon**: native arm64 builds; AVX2 auto-disabled on ARM (CMake) and `-march=armv8-a+simd` selected in the Makefile. macOS native build target added: `make STARforMac CXX=clang++` (links libomp dynamically).
+  * **Big-endian support** (`source/byteOrder.h`): the genome, suffix array and packed arrays are accessed as a little-endian byte stream regardless of host byte order, fixing the "next index is smaller than previous" failure on big-endian hosts (s390x, ppc64). Guarded so little-endian builds keep the native single-instruction load (zero performance/behavior change); only known big-endian compiles take the portable byte-wise path. Ported from the patch in upstream issue #2690. *Compile-validated only — no big-endian runner in CI.*
+
 ### Performance Optimizations
   * MSVC compiler: `/O2 /Ob2 /Oi /GL` with `/LTCG` link-time optimization (Windows)
   * SRW locks replacing CRITICAL_SECTION (faster mutex, Windows)
@@ -350,6 +356,7 @@ FORK CHANGES
     - Better exon-pair selection for chimeric junctions (overlapping cross-reference exon, not just first/last)
     - Trim stitched transcripts to the junction-relevant side before rescoring
     - Fix cross-mate `roStart` computation (`a2.Lread` instead of `a1.Lread` on negative strand)
+  * macOS: spawn `readFilesCommand` via `posix_spawnp` instead of `vfork()`+`execlp()`+`exit()`, fixing "Failed spawning readFilesCommand" with gzipped input on macOS (upstream issue #2663). Avoids the undefined behavior of calling `exit()` in a `vfork` child. POSIX-only path; the Windows `system()`-based path is unchanged.
 
 ### Project Quality
   * C++17 standard (upgraded from C++11)