fix(nrf52): make node-lzma an optional dep, handle dynamic import (#140)

For development environments that don't have xz utils available for the node-lzma native bindings, that dependency is now optional until attempting to setup the nrf52 tooling on Linux or MacOS. If node-lzma is not available, a helpful error message will be displayed.

docs/astro.config.mjs

@@ -38,6 +38,10 @@ export default defineConfig({
           label: 'Guide',
           autogenerate: { directory: 'guide' },
         },
+        {
+          label: 'Troubleshooting',
+          link: '/troubleshooting',
+        }
       ],
     }),
   ],

docs/src/content/docs/troubleshooting.md

@@ -0,0 +1,34 @@
+---
+title: Troubleshooting
+description: Tips for resolving known issues
+---
+
+## `symbol not found in flat namespace '_lzma_stream_encoder_mt'`
+
+Other error messages can include: 
+
+- "Unable to extract Arm Embedded Toolchain without XZ utils (https://tukaani.org/xz/). Please install that dependency on your system and reinstall xs-dev before attempting this setup again."
+
+If you encounter an error message related to lzma or node-lzma, this is likely due to a missing system dependency required to setup the tooling to program nrf52-based devices. This is only required on MacOS and Linux development environments.
+
+To resolve this, install the [XS Utils](https://tukaani.org/xz/) for your system.
+
+On MacOS, [Homebrew](https://brew.sh) can be used:
+
+```
+brew install xz
+```
+
+For Debian-based systems like Ubuntu:
+
+```
+sudo apt-get -y install xz-utils
+```
+
+If using `yum`:
+
+```
+sudo yum -y install xz
+```
+
+Once this is dependency has been installed, please re-install xs-dev to ensure the CLI is built correctly with the native bindings to xz-utils.

package.json

@@ -44,7 +44,6 @@
     "@octokit/rest": "^19.0.3",
     "axios": "^1.2.1",
     "gluegun": "^5.1.2",
-    "node-liblzma": "^1.1.9",
     "serialport": "^10.3.0",
     "serve-handler": "^6.1.3",
     "simple-plist": "^1.3.1",
@@ -53,6 +52,9 @@
     "usb": "^2.2.0",
     "windows-shortcuts": "^0.1.6"
   },
+  "optionalDependencies": {
+    "node-liblzma": "^1.1.9"
+  },
   "devDependencies": {
     "@astrojs/starlight": "^0.7.2",
     "@babel/core": ">=7.20.12 <8.0.0",

src/toolbox/setup/nrf52.ts

@@ -6,9 +6,6 @@ import { finished } from 'stream'
 import { extract } from 'tar-fs'
 import { promisify } from 'util'
 import { Extract as ZipExtract } from 'unzip-stream'
-// eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
-// @ts-ignore
-import { createUnxz } from 'node-liblzma'
 import { Device } from '../../types'
 import { DEVICE_ALIAS } from '../prompt/devices'
 import { execWithSudo, sourceEnvironment } from '../system/exec'
@@ -55,6 +52,18 @@ export default async function(): Promise<void> {
     await ensureModdableCommandPrompt(spinner)
   }
 
+  let createUnxz: any;
+  if (!isWindows) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
+      // @ts-ignore
+      ({ createUnxz } = await import('node-liblzma'))
+    } catch (error) {
+      spinner.fail("Unable to extract Arm Embedded Toolchain without XZ utils (https://tukaani.org/xz/). Please install that dependency on your system and reinstall xs-dev before attempting this setup again. See https://xs-dev.js.org/troubleshooting for more info.")
+      process.exit(1)
+    }
+  }
+
   spinner.info('Ensuring nrf52 directory')
   filesystem.dir(NRF52_DIR)