Files
ANSCORE/docs/PLAN_Linux_Licensing_Port.md
T

574 lines
33 KiB
Markdown
Raw Normal View History

2026-05-23 17:29:57 +10:00
# 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`](https://github.com/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**:
```bash
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:
```cpp
#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)`:
```cpp
#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:
```cpp
#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:
```cpp
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:
```cpp
#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:
```cpp
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`:
```cpp
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:
```cmake
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
```bash
# 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.*