Files
ANSCORE/docs/PLAN_Linux_Licensing_Port.md
T
2026-05-23 17:29:57 +10:00

33 KiB
Raw Blame History

PLAN — Port ANSCORE Licensing Core to Linux (x86_64 + Jetson aarch64)

Status: Draft, awaiting product-side decisions before execution Target platforms: Ubuntu 22.04 x86_64, JetPack 6.x (Ubuntu 22.04 aarch64) Components in scope: core/anslicensing, core/ANSLicensingSystem, core/ANSLibsLoader Estimated effort: ~6–7 focused weeks for one engineer Risk: Medium (HWID compatibility with license server is the dominant risk) Owner: Tuan Nghia Nguyen Branch to create: linux-licensing-port


Decisions already made (do not re-litigate)

  1. Three components are in scope, in this order: ANSLibsLoader (easiest), anslicensing (medium), ANSLicensingSystem (hardest). Engine modules (ANSODEngine, ANSCV, etc.) are NOT part of this plan — they come after licensing is up.
  2. No LabVIEW support on Linux. The _LV exports and LabVIEWHeader/extcode.h includes are stripped from the Linux build via #ifdef _WIN32. The C++ and C-string (_CS) entry points become the only Linux surface.
  3. lfreist/hwinfo stays. It is already vendored at C:/ANSLibs/ANS-HWiNFO/ and is cross-platform (verified — its platform.h defines HWINFO_UNIX on Linux). All 8 hwinfo:: call sites in ANSLicense.cpp are portable as-is. No replacement library needed.
  4. HWID gains real signals on Linux. Today hwid.cpp Linux branches stub the SMBIOS UUID slot with "4294967296" and leave GetHDDPropertyList empty (2-point HWID strength vs Windows 4-point). We will fill those slots using hwinfo::MainBoard::serialNumber() and hwinfo::RAM::serialNumber() for parity.
  5. rand.cpp Linux path is replaced with getrandom(2). The current srand(time(NULL)) + rand() path is cryptographically broken and a security-correctness issue, not just a portability one.
  6. DetectClockManipulation on Linux ships as a best-effort stub. Reading journalctl history is expensive and not always available (containers, no systemd). It will log a warning and return false. Acceptable anti-tamper degradation; flagged for follow-up.
  7. MediaClient and other non-licensing Windows surface stays Windows-only. This plan does not touch them.
  8. HWiNFO is NOT the commercial HWiNFO64. It's the open-source MIT-licensed lfreist/hwinfo C++ library. No commercial license concern.

Pre-work already completed (discovery, not code)

  • ✅ Confirmed core/anslicensing/ already has Linux scaffolding: CMakeLists.txt branches on WIN32 and links curl ssl crypto; precomp.h has POSIX shims; download.cpp has a complete libcurl path; hwid.cpp has Linux CPU-ID and MAC code.
  • ✅ Inventoried Windows API surface in ANSLicensingSystem/ANSLicense.cpp (4,021 LOC):
    • Only 2 #ifdef _WIN32 blocks — the file assumes Windows top-to-bottom
    • 8 × hwinfo:: calls — portable as-is
    • 12 × PDH counter sites — need /proc rewrite (Phase 3.3)
    • 7 × DXGI sites — need NVML/libdrm rewrite (Phase 3.4)
    • 1 × WMI MSAcpi_ThermalZoneTemperature query — Linux /sys/class/thermal/ (Phase 3.2)
    • 1 × WinHTTP block — replace with libcurl already in anslicensing/download.cpp (Phase 3.5)
    • 1 × DnsQuery_A — replace with getaddrinfo (Phase 3.6)
    • Misc: GlobalMemoryStatusEx, GetProcessMemoryInfo, GetSystemDirectoryW + GetDiskFreeSpaceExW, GetCurrentProcessId (Phase 3.7)
  • ✅ Confirmed lfreist/hwinfo cross-platform support via its platform.h and the header set at C:/ANSLibs/ANS-HWiNFO/include/hwinfo/.

Open product decisions (BLOCK Phase 0)

These must be resolved with the licensing-backend team before any code is written. They determine the shape of Phase 1.

Decision 1 — HWID format compatibility with the license server

The license server validates a HWID hash that's currently produced from Windows WMI data (Win32_ComputerSystemProduct.UUID, Win32_NetworkAdapter.MACAddress, Win32_PhysicalMedia.SerialNumber, Win32_Processor.ProcessorId). On Linux we will produce hashes from different data sources (SMBIOS via /sys/class/dmi/id/, NIC MACs via getifaddrs, RAM serial via DMI, CPU ID via __get_cpuid). The hash format (the bit-packed 125-bit BitStream3 in hwid.cpp) stays identical, but the values being hashed differ. Three options:

  • A. Unified HWID, same algorithm: server treats Windows and Linux licenses identically; admin has to physically activate each device once and the hash is opaque. Simplest. Recommended.
  • B. Separate Linux license pool: server tracks platform field; Linux activations come from a dedicated key range. More work backend-side.
  • C. Backward-compat dance: keep some Windows-specific fields empty on Linux (status quo) — license matching weakens. Reject.

Owner to confirm with backend team before Phase 0.

Decision 2 — HWiNFO MainBoard::serialNumber() availability on Jetson

lfreist/hwinfo reads /sys/class/dmi/id/board_serial on Linux. On Jetson this file may not exist — ARM SBCs use device-tree, not DMI. We need to:

  • Test on a real Jetson Orin/AGX board early.
  • Define fallback signal: /proc/device-tree/serial-number (Jetson exposes this) or eMMC CID (/sys/block/mmcblk*/device/cid).

Owner needs a Jetson devkit available before Phase 1.

Decision 3 — Boost dependencies on Jetson

ANSLicensingSystem currently links libboost_log-vc143-mt-x64-1_82.lib and uses boost::property_tree::ptree and boost::date_time. Ubuntu 22.04 ships Boost 1.74 by default (libboost-all-dev). Choices:

  • A. Use system Boost on Linux (1.74). Accept minor API differences; pin via find_package(Boost 1.74 REQUIRED).
  • B. Vendor Boost 1.82. Painful build but exact parity.
  • C. Drop Boost.PropertyTree on Linux and use nlohmann/json (already a project dep via ANSLIBS_DIR/nlohmann). Smaller dep surface but a code change in ANSLicense.cpp JSON output paths.

Recommendation: A. Defer until Phase 0.5 spike confirms it builds.


Quick Start for a new session

If you're a fresh Claude session and the user has asked you to execute this plan:

  1. Read this entire document end-to-end before editing anything. The per-file checklist in Appendix A is the source of truth for what changes.
  2. Confirm prerequisites are in place:
    ls "C:/ANSLibs/ANS-HWiNFO/include/hwinfo/platform.h"   # cross-platform lib present
    git status                                              # clean working tree
    git branch --show-current                               # should be linux-licensing-port
    
  3. Verify the three product decisions above are resolved. Ask the user to paste the answers if they're not in this doc. Do NOT start Phase 1 without Decision 1 (HWID format) answered.
  4. Ask the user which phase to start with. Default to Phase 0.1.
  5. Use TaskCreate to track progress through the phases — the seven-phase structure (0 through 4 plus per-3.x sub-phases) is the natural top-level task list.
  6. Work in small commits. One file, one logical change, verify build on Windows AND Linux before the next change. The Windows build must stay green at every step.
  7. Never modify a *_LV function signature. Even on Linux where we don't compile it, the source still exists on the Windows-shared file. Touch only what's gated by #ifdef _WIN32.

How to invoke this plan

The user can paste any of these to start:

"Read docs/PLAN_Linux_Licensing_Port.md and walk me through Phase 0."

"Continue the Linux licensing port. Read docs/PLAN_Linux_Licensing_Port.md and ask what's done."

"Execute Phase 1.1 from docs/PLAN_Linux_Licensing_Port.md."

Context the new session might need that isn't in this plan

  • Build system on Linux: CMake 3.28+, Ninja, GCC 11+ on Ubuntu 22.04. Cross-compile to Jetson via JetPack 6.x SDK Manager + sysroot.
  • CUDA on Linux: CUDA 12.x, cuDNN, TensorRT 10.x from apt or NVIDIA's repo.
  • Licensing server endpoint: ask the user for the staging URL — it is NOT in source control.
  • Test hardware: x86 Ubuntu box AND a Jetson Orin Nano/AGX devkit are both required. Do not declare Phase 1 done from x86 testing alone.

1. Background

ANSCORE targets Linux (Jetson + industrial x86) per the product roadmap. The Flutter mobile app will be replaced by a Qt QML UI talking to ANSCORE over gRPC + RTSP. Licensing is the blocking dependency: no module can be loaded without ANSLicensingSystem validating the license, so it must come first.

The three components are layered:

┌──────────────────────────────┐
│ Module DLLs (ANSCV, ANSOD,…) │  ← consumers, NOT part of this plan
├──────────────────────────────┤
│ ANSLicensingSystem (façade)  │  ← Phase 3 (4–5 weeks)
├──────────────────────────────┤
│ anslicensing (SDK)           │  ← Phase 1 (2–3 weeks)
│ ANSLibsLoader (dynload)      │  ← Phase 2 (1 week)
└──────────────────────────────┘

ANSLicensingSystem depends on anslicensing; ANSLibsLoader is independent of both but consumed by ANSCV later. Phase ordering keeps the build green at every step.

2. Goals

  • All three components build on Ubuntu 22.04 x86_64 and JetPack 6.x aarch64.
  • libANSLicensingSystem.so exports the same C++ symbols and C ABI as the Windows DLL (less LabVIEW exports).
  • Linux HWID is a 4-signal hash, equivalent strength to Windows.
  • License validation works against the existing license server.
  • All Windows behavior preserved unchanged. Zero behavioral regressions on Windows builds.
  • rand.cpp on Linux uses getrandom(2) instead of insecure rand().

3. Non-goals

  • LabVIEW support on Linux.
  • macOS port (separate effort).
  • DetectClockManipulation feature parity on Linux (acceptable degradation, logged).
  • Re-architecting the licensing protocol (wire compat preserved).
  • Engine modules (ANSODEngine, ANSCV, etc.) — separate plans.
  • Build infra changes (Conan/vcpkg adoption, etc.).

4. Phases

Phase 0 — Windows-side prep (1 week, zero behavioral change)

Done on Windows. No Linux changes yet. Each step must keep the Windows build green and tests passing.

  • 0.1 Add ANSCORE_API visibility macro to all three components' public headers:
    #if defined(_WIN32)
      #if defined(ANSCORE_EXPORTS)
        #define ANSCORE_API __declspec(dllexport)
      #else
        #define ANSCORE_API __declspec(dllimport)
      #endif
    #elif defined(__GNUC__)
      #define ANSCORE_API __attribute__((visibility("default")))
    #else
      #define ANSCORE_API
    #endif
    
    Replace __declspec(dllexport) / __declspec(dllimport) site-by-site. Test on Windows that the resulting DLL exports the same symbol set (dumpbin /exports).
  • 0.2 Split LabVIEW exports out of ANSLicense.h into a new ANSLicense_LV.h that includes the LabVIEW header and declares only the _LV functions. Update Windows-side ANSLicense.cpp to include ANSLicense_LV.h. Result: ANSLicense.h has zero LabVIEW types, so Linux consumers don't drag in extcode.h.
  • 0.3 Strip <windows.h>, <winhttp.h>, etc. from public headers (ANSLIB.h:6 #include <windows.h> line is the worst offender). Use forward declarations or guard with #ifdef _WIN32 where needed in implementation files only.
  • 0.4 Vendor lfreist/hwinfo as a git submodule at 3rdparty/hwinfo (or confirm C:/ANSLibs/ANS-HWiNFO/ is the canonical copy and update CMake to point at it consistently). Add a top-level CMake option ANSCORE_USE_VENDORED_HWINFO that defaults to ON.
  • 0.5 Stand up an Ubuntu 22.04 build environment (CI runner or local VM). Install: build-essential cmake ninja-build libboost-all-dev libcurl4-openssl-dev libssl-dev libzip-dev zlib1g-dev libnvidia-ml-dev libdrm-dev libsensors4-dev. Verify CUDA 12.x + TensorRT 10.x are reachable. Smoke test: cmake -B build && ninja -C build core/anslicensing should currently fail — but it should fail with predictable errors (missing hwinfo Linux build, etc.), not config errors.

Acceptance for Phase 0:

  • Windows build green, all existing tests pass.
  • dumpbin /exports ANSLicensingSystem.dll symbol set is byte-identical to baseline.
  • ANSLicense.h does not include LabVIEWHeader/extcode.h.
  • Ubuntu environment is reproducible.
  • Decision 1, 2, 3 above are answered in writing.

Phase 1 — Port core/anslicensing (2–3 weeks)

This is the lowest-level SDK. Already 80% portable.

  • 1.1 Strengthen Linux HWID in hwid.cpp:
    • Replace the propList.push_back("4294967296") stub at line 254 with hwinfo::MainBoard board; propList.push_back(board.serialNumber());. Falls back to /proc/device-tree/serial-number on aarch64 if board_serial is missing.
    • Implement GetHDDPropertyList on Linux at line 142: enumerate block devices via /sys/block/*/device/wwid or /sys/block/*/device/serial. Filter to non-removable (skip /sys/block/*/removable == 1).
    • Add the same source to the MatchCurrentHardwareId Linux branches (lines 416, 538).
    • Cross-test: HWID produced on Ubuntu must validate on the same machine across reboots.
  • 1.2 Replace rand.cpp Linux RNG with getrandom(2):
    #include <sys/random.h>
    // ::srand(time(NULL));  ← DELETE
    // rnd = ::rand();        ← DELETE
    ssize_t n = getrandom(&rnd, sizeof(rnd), 0);
    if (n != sizeof(rnd)) {
        // fallback: open /dev/urandom directly
    }
    
    Keep random::random() constructor cheap (no kernel call); make random::rand() the syscall site. Document the change in a header comment.
  • 1.3 DetectClockManipulation Linux stub in helper.cpp — return false with ANS_DBG("ClockTamper", "skipped on Linux — no-op fallback"). Document as a known degradation.
  • 1.4 Wire CMake on Linux. The CMakeLists already has the Linux branch; verify:
    • find_package(CURL REQUIRED) resolves
    • target_link_libraries(... curl ssl crypto) links cleanly
    • Add find_package(hwinfo REQUIRED) or use the submodule
  • 1.5 Round-trip test: a small test binary that calls HardwareId::GetCurrentHardwareId(), persists the string, then calls HardwareId::MatchCurrentHardwareId(saved) and asserts true. Run on Ubuntu x86 AND a Jetson devkit.

Acceptance for Phase 1:

  • libanslicensing.so builds on Ubuntu 22.04 x86_64 and Jetson aarch64.
  • Round-trip HWID test passes on both targets across at least 3 reboots.
  • strings libanslicensing.so | grep -c '4294967296' returns 0.
  • Static analysis (cppcheck or clang-tidy) shows no new warnings on Linux build.

Phase 2 — Port core/ANSLibsLoader (1 week)

Mechanical port from LoadLibrary/GetProcAddress to dlopen/dlsym. Independent of Phase 1 and Phase 3 — can be done in parallel.

  • 2.1 Port DynLibUtils.cpp core helpers:
    #ifdef _WIN32
      HMODULE LoadLib(const char* p)            { return LoadLibraryA(p); }
      void*   GetSym(HMODULE h, const char* s)  { return GetProcAddress(h, s); }
      void    UnloadLib(HMODULE h)              { FreeLibrary(h); }
    #else
      void*   LoadLib(const char* p)            { return dlopen(p, RTLD_NOW | RTLD_LOCAL); }
      void*   GetSym(void* h, const char* s)    { return dlsym(h, s); }
      void    UnloadLib(void* h)                { dlclose(h); }
    #endif
    
    Wrap the handle type behind an opaque DynLibHandle typedef so callers don't see the difference.
  • 2.2 Update CvLoader.cpp, NvDynLoader.cpp, OvLoader.cpp, EPLoader.cpp to use the cross-platform helpers. Most logic is search-path discovery — that needs branching too:
    • Windows: C:/ANSLibs/... paths
    • Linux: /opt/ANSLibs/..., /usr/lib/x86_64-linux-gnu/, /usr/local/cuda/lib64/, and ${LD_LIBRARY_PATH}
  • 2.3 Naming convention: Windows .dll, Linux .so with lib prefix. Centralize in a PLATFORM_DLL_NAME("opencv_world") macro that expands to "opencv_world.dll" on Windows and "libopencv_world.so" on Linux.
  • 2.4 Symbol visibility: Linux .so exports everything by default unless built with -fvisibility=hidden. Apply -fvisibility=hidden globally in the top-level CMakeLists and use the ANSCORE_API macro to opt in to exports.
  • 2.5 Smoke test: ANSLibsLoader opens libopencv_world.so on Ubuntu and returns valid handles for a known set of OpenCV symbols.

Acceptance for Phase 2:

  • libANSLibsLoader.so builds and runs.
  • All four sub-loaders (CV/OV/NV/EP) load their respective libraries successfully on Linux.
  • No symbol-visibility regressions on Windows (verify with dumpbin /exports).

Phase 3 — Port core/ANSLicensingSystem (4–5 weeks)

The big one. Split into independently mergeable PRs.

3.1 — Misc Win32 cleanup (1 day)

  • GlobalMemoryStatusEx → read /proc/meminfo MemTotal / MemAvailable
  • GetProcessMemoryInfo → read /proc/self/status VmRSS, VmSwap, VmPeak
  • GetSystemDirectoryW + GetDiskFreeSpaceExW (line 1056-1064) → statvfs("/")
  • GetCurrentProcessId → getpid()
  • WideCharToMultiByte / WideToUtf8 → std::wstring_convert or just use std::string throughout the Linux path (no wide chars needed without WMI)

3.2 — CPU thermal (1 day)

Replace ReadCpuTempCelsiusViaWmi() (line 603) with a Linux reader:

double ReadCpuTempCelsiusLinux() {
    // Scan /sys/class/thermal/thermal_zone*/type for "x86_pkg_temp" (x86)
    // or "CPU-therm" / "thermal-fan-est" (Jetson)
    // Read corresponding /sys/class/thermal/thermal_zone*/temp (milli-Celsius)
    // Return max across all CPU zones, or -1 if none found
}

Keep the Windows function intact behind #ifdef _WIN32. Dispatch through a single ReadCpuTempCelsius() wrapper.

3.3 — System health sampler / PDH rewrite (1 week)

The HealthSampler class (lines 906–1089) is the largest single port. Build a Linux HealthSamplerLinux class with the same public API as the Windows one. Then dispatch at instantiation:

#ifdef _WIN32
using HealthSampler = HealthSamplerWin;
#else
using HealthSampler = HealthSamplerLinux;
#endif

PDH counter → Linux source mapping:

PDH counter Linux source
\Processor Information(_Total)\% Processor Time /proc/stat delta of (user+nice+system) vs idle
\Processor Information(_Total)\% Processor Performance /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq / base freq
\Processor Information(_Total)\% Processor Utility Same as Processor Time on Linux (no MS-specific util concept)
\PhysicalDisk(_Total)\% Disk Time /proc/diskstats field 13 (io_time ms / interval ms)
\PhysicalDisk(_Total)\Disk Read Bytes/sec /proc/diskstats field 6 × 512 / interval
\PhysicalDisk(_Total)\Disk Write Bytes/sec /proc/diskstats field 10 × 512 / interval
\Network Interface(*)\Bytes Received/Sent/sec /proc/net/dev rx_bytes / tx_bytes deltas
\Network Interface(*)\Current Bandwidth /sys/class/net/*/speed (Mbit/s)
\GPU Engine(*)\Utilization Percentage NVML nvmlDeviceGetUtilizationRates
\GPU Process Memory(*)\Dedicated Usage NVML nvmlDeviceGetMemoryInfo

The sampler keeps a prev_* snapshot for delta computation (no PDH built-in differencing on Linux). Sample interval: same 2-second cadence as Windows.

Acceptance: the populated ANSCENTER::SystemHealthInfo struct has all the same fields filled on Linux as on Windows (allowing -1 / empty for fields that genuinely don't exist).

3.4 — GPU adapter enumeration (1 week)

Replace EnumerateGpuAdapters (line 721) with NVML on systems with NVIDIA drivers, falling back to libdrm:

std::vector<GpuAdapter> EnumerateGpuAdaptersLinux() {
    std::vector<GpuAdapter> out;

    // Try NVML first (covers Jetson + dGPU x86)
    if (nvmlInit_v2() == NVML_SUCCESS) {
        unsigned int count = 0;
        nvmlDeviceGetCount_v2(&count);
        for (unsigned int i = 0; i < count; ++i) {
            nvmlDevice_t dev;
            nvmlDeviceGetHandleByIndex_v2(i, &dev);
            GpuAdapter a;
            // populate a.name, a.vendorId=0x10DE, a.dedicatedVramMB...
            out.push_back(a);
        }
        nvmlShutdown();
    }

    // Then enumerate non-NVIDIA via libdrm (/dev/dri/card*)
    // for Intel/AMD users on x86 Linux
    // ...

    return out;
}

AggregateGpuCounter (line 773) — the LUID-based attribution machinery — collapses on Linux because NVML hands you per-device handles directly. Replace with a simpler for (auto& dev : nvmlDevices) loop.

Caveat: nvmlDeviceGetUtilizationRates returns whole-device utilization, not per-process. Per-process GPU memory needs nvmlDeviceGetProcessUtilization (where supported) or nvmlDeviceGetComputeRunningProcesses. On Jetson, NVML support is partial — test early.

3.5 — License-server HTTP (1 day)

Delete the WinHttpHandle block (lines 1101–1166) on Linux. Reuse anslicensing/download.cpp's UrlDownloadToString libcurl path. The function signature is already compatible. One small wrinkle: UrlDownloadToString is in anslicensing.dll, so ANSLicensingSystem must link against it — it already does.

3.6 — DNS public-IP probe (0.5 day)

Replace DnsQuery_A (line 1228) with getaddrinfo:

struct addrinfo hints{}, *res = nullptr;
hints.ai_family = AF_INET;
if (getaddrinfo("myip.opendns.com", nullptr, &hints, &res) == 0 && res) {
    char buf[INET_ADDRSTRLEN];
    inet_ntop(AF_INET, &((sockaddr_in*)res->ai_addr)->sin_addr, buf, sizeof(buf));
    publicIp = buf;
    freeaddrinfo(res);
}

If the existing Windows query uses a TXT record specifically, fall back to libresolv res_query for parity. Verify with the user which probe is in use.

3.7 — CMake + linking (3 days)

Rewrite ANSLicensingSystem/CMakeLists.txt Linux branch:

if(WIN32)
    target_link_libraries(ANSLicensingSystem PRIVATE
        HWiNFO.lib OpenCL.lib OpenCLExt.lib
        bz2.lib zip.lib
        libboost_log-vc143-mt-x64-1_82.lib
        shlwapi.lib winhttp.lib pdh.lib psapi.lib
        wbemuuid.lib oleaut32.lib ole32.lib dxgi.lib dnsapi.lib
        ${WIN_COMMON_LIBS}
    )
else()
    find_package(Boost REQUIRED COMPONENTS log date_time)
    find_package(CURL REQUIRED)
    target_link_libraries(ANSLicensingSystem PRIVATE
        hwinfo::hwinfo                          # vendored or apt
        Boost::log Boost::date_time
        CURL::libcurl
        zip                                      # libzip-dev
        z                                        # zlib1g-dev
        nvidia-ml                                # libnvidia-ml-dev (NVML)
        drm                                      # libdrm-dev (optional, for non-NVIDIA)
        pthread dl
    )
endif()

target_compile_definitions(ANSLicensingSystem PRIVATE
    ANSLICENSE_EXPORTS
    ANSLICENSINGSYSTEM_EXPORTS
    $<$<PLATFORM_ID:Windows>:UNICODE _UNICODE>
)

Drop ANSLIBS_DIR/ANS-HWiNFO/lib and ANSLIBS_DIR/boost/lib from target_link_directories on Linux.

3.8 — End-to-end license activation (3 days)

Run the full activation flow from a Linux client against the staging license server:

  1. GenerateHardwareId() returns a string
  2. Operator pastes it into the activation portal
  3. Server returns license blob
  4. Linux client ValidateLicense(blob) returns SUCCESS
  5. Subsequent IsLicenseValid() calls return true
  6. Restart process — license still valid
  7. Move drive to second machine — license invalid (HWID mismatch detected)

The last item is the critical anti-piracy check. If it fails (license validates on second machine), the HWID is too lax — go back to Phase 1.1.

Acceptance for Phase 3 overall:

  • libANSLicensingSystem.so builds and links cleanly.
  • All public symbols (less _LV set) match Windows-side exports.
  • Full activation round-trip succeeds against staging server.
  • SystemHealthInfo struct populates all fields with real (non -1) data on Jetson and on x86 Ubuntu.
  • Anti-piracy test passes (HWID mismatch is detected).

Phase 4 — Integration & Hardening (1 week)

  • 4.1 Cross-arch CI: add an aarch64 build matrix entry. Cross-compile from x86 host using JetPack 6.x sysroot, or natively on a Jetson runner. Both options work; pick whichever the team prefers.
  • 4.2 Soak test: run an ANSLicensingSystem-based test harness on a Jetson for 24 hours. Watch for memory leaks (valgrind --leak-check=full for a short run, then top / smaps tracking long-term). NVML on Jetson has known leak patterns — defend against them.
  • 4.3 Documentation: write docs/LINUX_BUILD_GUIDE.md covering apt deps, Boost version notes, Jetson cross-compile, and the HWID format change (so support knows licenses don't transfer Windows↔Linux without re-issuance).
  • 4.4 Top-level CMake gating: in the root CMakeLists.txt, remove if(WIN32) gates around the three components — they now build everywhere. Engine modules stay Windows-only for now since this plan doesn't cover them.

Acceptance for Phase 4:

  • CI green on Windows, Ubuntu x86, Jetson aarch64.
  • 24h soak shows stable memory profile.
  • LINUX_BUILD_GUIDE.md merged and reviewed.

5. Risks & mitigations

Risk Likelihood Impact Mitigation
License server rejects Linux HWID format Medium Blocks Phase 1 acceptance Resolve Decision 1 before Phase 0; coordinate with backend team early
Jetson /sys/class/dmi/id/board_serial missing High Phase 1 HWID is weak on Jetson Decision 2: validate on real Jetson hardware; fall back to device-tree serial
NVML on Jetson missing some APIs Medium GPU telemetry sparse on Jetson Test nvmlDeviceGetUtilizationRates early; gracefully degrade fields that aren't available
Boost version mismatch (1.74 system vs 1.82 vendored) Medium Subtle behavioral differences Phase 0.5 spike build; switch to nlohmann/json if PropertyTree breaks
lfreist/hwinfo ARM support gaps Low HWID source incomplete on Jetson Read its cpuid.h Linux branch; have device-tree fallback ready
Symbol visibility differences cause ABI breakage Low Linker errors at integration time -fvisibility=hidden from day one; ANSCORE_API discipline
WMI thermal-zone has no Linux semantic equivalent Low cpuTempDegC field is less accurate Document field as "best-effort, may be -1 on hardware without thermal zones"
libnvidia-ml not present on dev-only x86 box Low Build fails on developer machines dynamic-load NVML via dlopen with weak symbol; fallback to "no GPU" state

6. Dependencies for Ubuntu / Jetson development

# Build essentials
sudo apt install -y \
    build-essential cmake ninja-build pkg-config git \
    libboost-all-dev libcurl4-openssl-dev libssl-dev \
    libzip-dev zlib1g-dev \
    libnvidia-ml-dev libdrm-dev libsensors4-dev \
    libgtest-dev cppcheck clang-tidy

# CUDA 12.x + cuDNN + TensorRT 10.x — from NVIDIA's apt repo (separate setup)
# JetPack 6.x — flash via SDK Manager onto target board

For Jetson cross-compile: install JetPack 6.x SDK on host, point CMake at /opt/nvidia/jetson-linux-sysroot/aarch64-ubuntu22.04.


7. Testing strategy

  • Unit tests (tests/anslicensing-unittest): exercise each platform-specific helper with known synthetic data. New tests: HWID-determinism, getrandom-fallback, /proc/meminfo parser, /proc/stat delta computation.
  • Integration tests (tests/anslicensingsystem-integration): in-process activation round-trip against a mock license server. Run on Windows + Linux + Jetson.
  • E2E tests: real staging server. Run once per phase acceptance, not on every commit (slow + flaky over real network).
  • Anti-piracy regression test: documented in Phase 3.8. Must run before merging Phase 3 to main.
  • Determinism test: generate HWID 10× across reboots on the same machine; assert all identical. Generate on two physically different Jetsons; assert different.

Appendix A — Per-file change checklist

Files marked NEW are created; MOD is modified; DELETE is removed.

core/anslicensing/

File Action Phase Change
hwid.cpp MOD 1.1 Linux branches: use hwinfo::MainBoard::serialNumber() for UUID slot; implement GetHDDPropertyList reading /sys/block/*/device/wwid
rand.cpp MOD 1.2 Replace srand/rand with getrandom(2) + /dev/urandom fallback
helper.cpp MOD 1.3 DetectClockManipulation Linux stub with ANS_DBG warning
download.cpp — — Already done — libcurl path exists
precomp.h — — Already done — POSIX shims exist
CMakeLists.txt MOD 1.4 Add find_package(hwinfo) on non-Windows

core/ANSLicensingSystem/

File Action Phase Change
ANSLicense.h MOD 0.2 Remove #include "LabVIEWHeader/extcode.h"; remove LDbl/LDblPtr/LDblHandle (moved to ANSLicense_LV.h)
ANSLicense_LV.h NEW 0.2 Windows-only header with all _LV exports, includes extcode.h
ANSLicense.cpp MOD 3.1–3.6 Replace each Win32 call site with #ifdef _WIN32 / #else branch
HealthSamplerLinux.cpp NEW 3.3 New file: /proc-based sampler
HealthSamplerLinux.h NEW 3.3 Class declaration matching HealthSampler's public API
Utility.h MOD 0.3 Strip any Windows-specific types from declarations
Utility.cpp MOD 3.1 Verify std::filesystem path operations work on Linux
CMakeLists.txt MOD 3.7 Add Linux branch with curl/boost/hwinfo/nvml

core/ANSLibsLoader/

File Action Phase Change
DynLibUtils.cpp MOD 2.1 dlopen/dlsym/dlclose Linux branches
CvLoader.cpp MOD 2.2 Linux search paths + .so naming
NvDynLoader.cpp MOD 2.2 Linux search paths
OvLoader.cpp MOD 2.2 Linux search paths
EPLoader.cpp MOD 2.2 Linux search paths
ANSLibsLoader.def — — Windows-only .def; leave alone, use __attribute__((visibility)) on Linux
CMakeLists.txt MOD 2.4 -fvisibility=hidden; link dl on Linux

Top-level

File Action Phase Change
CMakeLists.txt MOD 0.4, 4.4 ANSCORE_USE_VENDORED_HWINFO option; ungate three core components from if(WIN32)
cmake/Dependencies.cmake MOD 0.4, 3.7 Add hwinfo, NVML (CUDA::nvml), libdrm resolution
3rdparty/hwinfo/ NEW (submodule) 0.4 git submodule add https://github.com/lfreist/hwinfo 3rdparty/hwinfo
docs/LINUX_BUILD_GUIDE.md NEW 4.3 Developer onboarding

Appendix B — Symbol map (Win32 → Linux)

Reference table for the engineer porting ANSLicense.cpp:

Win32 symbol / API File:line Linux replacement
PdhOpenQueryW / PdhAddEnglishCounterW / PdhCollectQueryData ANSLicense.cpp:906–928 Custom /proc/stat, /proc/diskstats, /proc/net/dev delta sampler (Phase 3.3)
IWbemLocator::ConnectServer("ROOT\\WMI") + MSAcpi_ThermalZoneTemperature ANSLicense.cpp:618–663 /sys/class/thermal/thermal_zone*/temp (Phase 3.2)
CreateDXGIFactory1 / IDXGIAdapter1::GetDesc1 ANSLicense.cpp:721–747 nvmlDeviceGetCount_v2 + per-device queries; libdrm for non-NVIDIA (Phase 3.4)
WinHttpOpen / WinHttpSendRequest / etc. ANSLicense.cpp:1101–1166 Reuse anslicensing/download.cpp libcurl path (Phase 3.5)
DnsQuery_A ANSLicense.cpp:1228 getaddrinfo or res_query (Phase 3.6)
GlobalMemoryStatusEx ANSLicense.cpp:1036 /proc/meminfo parser (Phase 3.1)
GetProcessMemoryInfo ANSLicense.cpp:1048 /proc/self/status parser (Phase 3.1)
GetSystemDirectoryW + GetDiskFreeSpaceExW ANSLicense.cpp:1056–1064 statvfs("/") (Phase 3.1)
GetCurrentProcessId ANSLicense.cpp:993, 1026 getpid() (Phase 3.1)
WideCharToMultiByte / WideToUtf8 ANSLicense.cpp:712 drop on Linux — no wide chars needed without WMI
CoInitializeEx / CoSetProxyBlanket / CoUninitialize ANSLicense.cpp:604, 611, 669 delete on Linux — COM not needed
__declspec(dllexport) (everywhere) __attribute__((visibility("default"))) via ANSCORE_API macro (Phase 0.1)
LStrHandle, LDbl, extcode.h ANSLicense.h:75 + many move to ANSLicense_LV.h, Windows-only (Phase 0.2)

Appendix C — License-server coordination checklist

Before Phase 1 starts, the license-server team confirms in writing:

  • Server accepts HWID format generated by the new Linux hwid.cpp path
  • Server's HWID validation algorithm matches the new client-side hash inputs
  • Decision on license-pool separation: unified vs. Linux-only pool
  • Staging environment endpoint available for E2E testing in Phase 3.8
  • Activation portal supports pasting a Linux-generated HWID

Appendix D — What this plan deliberately does NOT cover

So a future session doesn't accidentally scope-creep:

  • MediaClient port to Linux — separate plan; ANSCV depends on this but licensing does not
  • GStreamer backend for ANSCV — separate plan
  • Engine modules (ANSODEngine, ANSFR, ANSLPR, ANSOCR, etc.) — separate plans, post-licensing
  • gRPC service layer (ANSService) — planned after engine modules are up
  • Qt QML UI — separate repo, depends on gRPC layer
  • macOS support — not in roadmap currently
  • Dropping LabVIEW on Windows — _LV exports stay on Windows builds untouched
  • License protocol changes — wire compatibility preserved; only the input data to the HWID hash changes on Linux

End of plan.