33 KiB
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)
- 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. - No LabVIEW support on Linux. The
_LVexports andLabVIEWHeader/extcode.hincludes are stripped from the Linux build via#ifdef _WIN32. The C++ and C-string (_CS) entry points become the only Linux surface. lfreist/hwinfostays. It is already vendored atC:/ANSLibs/ANS-HWiNFO/and is cross-platform (verified — itsplatform.hdefinesHWINFO_UNIXon Linux). All 8hwinfo::call sites inANSLicense.cppare portable as-is. No replacement library needed.- HWID gains real signals on Linux. Today
hwid.cppLinux branches stub the SMBIOS UUID slot with"4294967296"and leaveGetHDDPropertyListempty (2-point HWID strength vs Windows 4-point). We will fill those slots usinghwinfo::MainBoard::serialNumber()andhwinfo::RAM::serialNumber()for parity. rand.cppLinux path is replaced withgetrandom(2). The currentsrand(time(NULL)) + rand()path is cryptographically broken and a security-correctness issue, not just a portability one.DetectClockManipulationon Linux ships as a best-effort stub. Readingjournalctlhistory is expensive and not always available (containers, no systemd). It will log a warning and returnfalse. Acceptable anti-tamper degradation; flagged for follow-up.- MediaClient and other non-licensing Windows surface stays Windows-only. This plan does not touch them.
- HWiNFO is NOT the commercial HWiNFO64. It's the open-source MIT-licensed
lfreist/hwinfoC++ library. No commercial license concern.
Pre-work already completed (discovery, not code)
- ✅ Confirmed
core/anslicensing/already has Linux scaffolding:CMakeLists.txtbranches onWIN32and linkscurl ssl crypto;precomp.hhas POSIX shims;download.cpphas a complete libcurl path;hwid.cpphas Linux CPU-ID and MAC code. - ✅ Inventoried Windows API surface in
ANSLicensingSystem/ANSLicense.cpp(4,021 LOC):- Only 2
#ifdef _WIN32blocks — the file assumes Windows top-to-bottom - 8 ×
hwinfo::calls — portable as-is - 12 × PDH counter sites — need
/procrewrite (Phase 3.3) - 7 × DXGI sites — need NVML/libdrm rewrite (Phase 3.4)
- 1 × WMI
MSAcpi_ThermalZoneTemperaturequery — 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 withgetaddrinfo(Phase 3.6) - Misc:
GlobalMemoryStatusEx,GetProcessMemoryInfo,GetSystemDirectoryW + GetDiskFreeSpaceExW,GetCurrentProcessId(Phase 3.7)
- Only 2
- ✅ Confirmed
lfreist/hwinfocross-platform support via itsplatform.hand the header set atC:/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 viaANSLIBS_DIR/nlohmann). Smaller dep surface but a code change inANSLicense.cppJSON 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:
- 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.
- 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 - 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.
- Ask the user which phase to start with. Default to Phase 0.1.
- 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.
- 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.
- Never modify a
*_LVfunction 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.mdand walk me through Phase 0."
"Continue the Linux licensing port. Read
docs/PLAN_Linux_Licensing_Port.mdand 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
aptor 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.soexports 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.cppon Linux usesgetrandom(2)instead of insecurerand().
3. Non-goals
- LabVIEW support on Linux.
- macOS port (separate effort).
DetectClockManipulationfeature 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_APIvisibility macro to all three components' public headers:Replace#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__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.hinto a newANSLicense_LV.hthat includes the LabVIEW header and declares only the_LVfunctions. Update Windows-sideANSLicense.cppto includeANSLicense_LV.h. Result:ANSLicense.hhas zero LabVIEW types, so Linux consumers don't drag inextcode.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 _WIN32where needed in implementation files only. - 0.4 Vendor
lfreist/hwinfoas a git submodule at3rdparty/hwinfo(or confirmC:/ANSLibs/ANS-HWiNFO/is the canonical copy and update CMake to point at it consistently). Add a top-level CMake optionANSCORE_USE_VENDORED_HWINFOthat 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/anslicensingshould 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.dllsymbol set is byte-identical to baseline.ANSLicense.hdoes not includeLabVIEWHeader/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 withhwinfo::MainBoard board; propList.push_back(board.serialNumber());. Falls back to/proc/device-tree/serial-numberon aarch64 if board_serial is missing. - Implement
GetHDDPropertyListon Linux at line 142: enumerate block devices via/sys/block/*/device/wwidor/sys/block/*/device/serial. Filter to non-removable (skip/sys/block/*/removable == 1). - Add the same source to the
MatchCurrentHardwareIdLinux branches (lines 416, 538). - Cross-test: HWID produced on Ubuntu must validate on the same machine across reboots.
- Replace the
- 1.2 Replace
rand.cppLinux RNG withgetrandom(2):Keep#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 }random::random()constructor cheap (no kernel call); makerandom::rand()the syscall site. Document the change in a header comment. - 1.3
DetectClockManipulationLinux stub inhelper.cpp— returnfalsewithANS_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)resolvestarget_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 callsHardwareId::MatchCurrentHardwareId(saved)and asserts true. Run on Ubuntu x86 AND a Jetson devkit.
Acceptance for Phase 1:
libanslicensing.sobuilds 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.cppcore helpers:Wrap the handle type behind an opaque#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); } #endifDynLibHandletypedef so callers don't see the difference. - 2.2 Update
CvLoader.cpp,NvDynLoader.cpp,OvLoader.cpp,EPLoader.cppto 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}
- Windows:
- 2.3 Naming convention: Windows
.dll, Linux.sowithlibprefix. Centralize in aPLATFORM_DLL_NAME("opencv_world")macro that expands to"opencv_world.dll"on Windows and"libopencv_world.so"on Linux. - 2.4 Symbol visibility: Linux
.soexports everything by default unless built with-fvisibility=hidden. Apply-fvisibility=hiddenglobally in the top-level CMakeLists and use theANSCORE_APImacro to opt in to exports. - 2.5 Smoke test:
ANSLibsLoaderopenslibopencv_world.soon Ubuntu and returns valid handles for a known set of OpenCV symbols.
Acceptance for Phase 2:
libANSLibsLoader.sobuilds 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/meminfoMemTotal / MemAvailableGetProcessMemoryInfo→ read/proc/self/statusVmRSS, VmSwap, VmPeakGetSystemDirectoryW + GetDiskFreeSpaceExW(line 1056-1064) →statvfs("/")GetCurrentProcessId→getpid()WideCharToMultiByte/WideToUtf8→std::wstring_convertor just usestd::stringthroughout 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:
GenerateHardwareId()returns a string- Operator pastes it into the activation portal
- Server returns license blob
- Linux client
ValidateLicense(blob)returnsSUCCESS - Subsequent
IsLicenseValid()calls return true - Restart process — license still valid
- 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.sobuilds and links cleanly.- All public symbols (less
_LVset) match Windows-side exports. - Full activation round-trip succeeds against staging server.
SystemHealthInfostruct 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
aarch64build 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=fullfor a short run, thentop/ smaps tracking long-term). NVML on Jetson has known leak patterns — defend against them. - 4.3 Documentation: write
docs/LINUX_BUILD_GUIDE.mdcovering 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, removeif(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.cpppath - 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 —
_LVexports 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.