1 # GitHub Actions Workflow Generator 2 3 This directory contains `gen_gh_actions.py`, a script to generate GitHub Actions CI workflows from the same configuration logic used for Travis CI. 4 5 ## Usage 6 7 The script can generate workflows for different platforms: 8 9 ```bash 10 # Generate Linux CI workflow (default) 11 ./scripts/gen_gh_actions.py linux > .github/workflows/linux-ci.yml 12 13 # Generate macOS CI workflow 14 ./scripts/gen_gh_actions.py macos > .github/workflows/macos-ci.yml 15 16 # Generate Windows CI workflow 17 ./scripts/gen_gh_actions.py windows > .github/workflows/windows-ci.yml 18 19 # Generate FreeBSD CI workflow 20 ./scripts/gen_gh_actions.py freebsd > .github/workflows/freebsd-ci.yml 21 22 # Generate combined workflow with all platforms 23 ./scripts/gen_gh_actions.py all > .github/workflows/ci-all.yml 24 ``` 25 26 ## Generated Workflows 27 28 ### Linux CI (`linux-ci.yml`) 29 - **test-linux** (AMD64): `ubuntu-latest` (x86_64) 30 - ~96 configurations covering GCC, Clang, various flags 31 - **test-linux-arm64** (ARM64): `ubuntu-24.04-arm` (aarch64) 32 - ~14 configurations including large hugepage tests 33 - **Note:** Free ARM64 runners (Public Preview) - may have longer queue times during peak hours 34 35 **Total:** 110 configurations 36 37 ### macOS CI (`macos-ci.yml`) 38 - **test-macos** (Intel): `macos-15-intel` (x86_64) 39 - ~10 configurations with GCC compiler 40 - **test-macos-arm64** (Apple Silicon): `macos-latest` (arm64) 41 - ~11 configurations including large hugepage tests 42 43 **Total:** 21 configurations 44 45 ### Windows CI (`windows-ci.yml`) 46 - **test-windows** (AMD64): `windows-latest` (x86_64) 47 - 10 configurations covering MinGW-GCC and MSVC compilers 48 - 32-bit and 64-bit builds 49 - Uses MSYS2 for build environment 50 51 **Total:** 10 configurations 52 53 ### FreeBSD CI (`freebsd-ci.yml`) 54 - **test-freebsd** (AMD64): Runs in FreeBSD VM on `ubuntu-latest` 55 - Matrix testing: debug (on/off), prof (on/off), arch (32/64-bit), uncommon configs 56 - 16 total configuration combinations 57 - Uses FreeBSD 15.0 via `vmactions/freebsd-vm@v1` 58 - Uses `gmake` (GNU Make) instead of BSD make 59 60 **Total:** 16 configurations 61 62 ## Architecture Verification 63 64 Each workflow includes a "Show OS version" step that prints: 65 66 **Linux:** 67 ```bash 68 === System Information === 69 uname -a # Kernel and architecture 70 === Architecture === 71 uname -m # x86_64, aarch64, etc. 72 arch # Architecture type 73 === CPU Info === 74 lscpu # Detailed CPU information 75 ``` 76 77 **macOS:** 78 ```bash 79 === macOS Version === 80 sw_vers # macOS version and build 81 === Architecture === 82 uname -m # x86_64 or arm64 83 arch # i386 or arm64 84 === CPU Info === 85 sysctl machdep.cpu.brand_string # CPU model 86 ``` 87 88 **Windows:** 89 ```cmd 90 === Windows Version === 91 systeminfo # OS name and version 92 ver # Windows version 93 === Architecture === 94 PROCESSOR_ARCHITECTURE # AMD64, x86, ARM64 95 ``` 96 97 ## GitHub Runner Images 98 99 | Platform | Runner Label | Architecture | OS Version | Strategy | 100 |----------|--------------|--------------|------------|----------| 101 | Linux AMD64 | ubuntu-latest | x86_64 | Ubuntu 22.04+ | Auto-update | 102 | Linux ARM64 | ubuntu-24.04-arm | aarch64 | Ubuntu 24.04 | Free (Public Preview) | 103 | macOS Intel | macos-15-intel | x86_64 | macOS 15 Sequoia | Pinned | 104 | macOS Apple Silicon | macos-15 | arm64 | macOS 15 Sequoia | Pinned | 105 | Windows | windows-latest | x86_64 | Windows Server 2022+ | Auto-update | 106 | FreeBSD | ubuntu-latest (VM) | x86_64 | FreeBSD 15.0 in VM | VM-based | 107 108 ### Runner Strategy Explained 109 110 We use a **hybrid approach** to balance stability and maintenance: 111 112 **Auto-update runners (`-latest`):** 113 - **Linux AMD64**: `ubuntu-latest` - Very stable, rarely breaks, auto-updates to newest Ubuntu LTS 114 - **Windows**: `windows-latest` - Backward compatible, auto-updates to newest Windows Server 115 116 **Pinned runners (specific versions):** 117 - **Linux ARM64**: `ubuntu-24.04-arm` - **Free for public repos** (Public Preview, may have queue delays) 118 - **macOS Intel**: `macos-15-intel` - Last Intel macOS runner (EOL **August 2027**) 119 - **macOS Apple Silicon**: `macos-15` - Pin for control over macOS upgrades 120 121 **Why this approach?** 122 - Reduces maintenance (auto-update where safe) 123 - Prevents surprise breakages (pin where needed) 124 - Balances stability and staying current 125 - Uses free ARM64 runners for public repositories 126 127 ### ARM64 Queue Times 128 129 **If you experience long waits for ARM64 jobs:** 130 131 The `ubuntu-24.04-arm` runner is **free for public repositories** but is in **Public Preview**. GitHub warns: *"you may experience longer queue times during peak usage hours"*. 132 133 To reduce wait times we should upgrade to Team/Enterprise plan - then we could use `ubuntu-24.04-arm64` for faster, paid runners 134 135 ### Important Deprecation Timeline 136 137 | Date | Event | Action Required | 138 |------|-------|------------------| 139 | **August 2027** | macOS Intel runners removed | Must drop Intel macOS testing or use self-hosted | 140 | **TBD** | ARM64 runners leave Public Preview | May see improved queue times | 141 142 **Note:** `macos-15-intel` is the **last Intel-based macOS runner** from GitHub Actions. After August 2027, only Apple Silicon runners will be available. 143 144 ## Platform-Specific Details 145 146 ### Windows Build Process 147 The Windows workflow uses: 148 1. **MSYS2** setup via `msys2/setup-msys2@v2` action 149 2. **MinGW-GCC**: Standard autotools build process in MSYS2 shell 150 3. **MSVC (cl.exe)**: Requires `ilammy/msvc-dev-cmd@v1` for environment setup 151 - Uses `MSYS2_PATH_TYPE: inherit` to inherit Windows PATH 152 - Exports `AR=lib.exe`, `NM=dumpbin.exe`, `RANLIB=:` 153 4. **mingw32-make**: Used instead of `make` (standard in MSYS2) 154 155 ### macOS Build Process 156 - Uses Homebrew to install `autoconf` 157 - Tests on both Intel (x86_64) and Apple Silicon (ARM64) 158 - Standard autotools build process 159 - Excludes certain malloc configurations not supported on macOS 160 161 ### Linux Build Process 162 - Ubuntu Latest for AMD64, Ubuntu 24.04 for ARM64 163 - Installs 32-bit cross-compilation dependencies when needed 164 - Most comprehensive test matrix (110 configurations) 165 166 ## Relationship to Travis CI 167 168 This script mirrors the logic from `gen_travis.py` but generates GitHub Actions workflows instead of `.travis.yml`. The test matrices are designed to provide equivalent coverage to the Travis CI configuration. 169 170 ## Regenerating Workflows 171 172 To regenerate all workflows after modifying `gen_gh_actions.py`: 173 174 ```bash 175 ./scripts/gen_gh_actions.py linux > .github/workflows/linux-ci.yml 176 ./scripts/gen_gh_actions.py macos > .github/workflows/macos-ci.yml 177 ./scripts/gen_gh_actions.py windows > .github/workflows/windows-ci.yml 178 ``` 179 180 **Note**: The generated files should not be edited by hand. All changes should be made to `gen_gh_actions.py` and then regenerated. 181 182
Indexes created Sun Sep 20 00:26:38 UTC 2026