LankyMoose/docs.sheetjs.com
1
Fork 0
forked from sheetjs/docs.sheetjs.com
Code Pull Requests Activity
ac6e3daa1c
docs.sheetjs.com/docz/docs/03-demos/20-cli/index.md
SheetJS 92e3c5aa72 mdx cleanup in preparation for v2 
- use autolinks (e.g <https://sheetjs.com> -> https://sheetjs.com)
- move <summary> blocks to separate lines
2024-04-08 00:57:39 -04:00

12 KiB
Raw Blame History

title pagination_prev pagination_next
Command-Line Tools demos/desktop/index demos/data/index

import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

With the availability of JS engines and the success of server-side platforms, it is possible to build standalone command-line tools from JavaScript code.

SheetJS is a JavaScript library for reading and writing data from spreadsheets.

This demo covers a number of strategies for building standalone spreadsheet processors. The ultimate goal is to use SheetJS libraries to generate CSV output from arbitrary spreadsheet files. The generated command-line tool will accept an argument, parse the specified workbook, and print CSV rows to the terminal.

Sample terminal session

$ xlsx-cli.exe pres.numbers
Name,Index
Bill Clinton,42
GeorgeW Bush,43
Barack Obama,44
Donald Trump,45
Joseph Biden,46

Demos for common standalone CLI tools are included in separate pages:

    {useCurrentSidebarCategory().items.map((item, index) => { const listyle = (item.customProps?.icon) ? { listStyleImage: `url("${item.customProps.icon}")` } : {}; return (
  • {item.label}{item.customProps?.summary && (" - " + item.customProps.summary)}
    • ); })}

:::tip pass

The xlsx-cli NodeJS script is available as a package on the SheetJS CDN. It is an easy-to-use command-line tool for translating files between supported spreadsheet file formats.

:::

:::caution pass

For most common deployment scenarios, it is possible to install a server-side platform such as NodeJS.

It is strongly recommended to use a dedicated platform when possible.

The standalone programs generated in this demo are useful when a dedicated server-side scripting platform cannot be installed on the target computer.

:::

NodeJS

There are a few popular tools for compiling NodeJS scripts to CLI programs.

The demo script presents a friendly command line interface including flags:

$ ./xlsx-cli -h
Usage: xlsx-cli [options] <file> [sheetname]

Options:
  -V, --version            output the version number
  -f, --file <file>        use specified workbook
  -s, --sheet <sheet>      print specified sheet (default first sheet)
...

:::note Tested Deployments

This demo was tested in the following deployments:

Architecture Version NodeJS Source Date
darwin-x64 4.0.0-rc.4 14.15.3 Pre-built 2024-03-15
darwin-arm 4.0.0-rc.2 18.18.0 Compiled 2023-12-01
win10-x64 4.0.0-rc.4 14.15.3 Pre-built 2024-03-04
win11-arm 4.0.0-rc.2 20.10.0 Compiled 2023-12-01
linux-x64 4.0.0-rc.4 14.15.3 Pre-built 2024-03-21
linux-arm 4.0.0-rc.2 20.10.0 Compiled 2023-12-01
Architecture Version NodeJS Date
darwin-x64 5.8.1 18.5.0 2024-03-15
darwin-arm 5.8.1 18.5.0 2023-12-01
win10-x64 5.8.1 18.5.0 2024-03-24
win11-arm 5.8.1 18.5.0 2023-12-01
linux-x64 5.8.1 18.5.0 2024-03-21
linux-arm 5.8.1 18.5.0 2023-12-01
Architecture Version NodeJS Date
darwin-x64 2.4.0 21.7.1 2024-03-15
darwin-arm 2.3.0 21.3.0 2023-12-01
win10-x64 2.4.0 16.20.2 2024-03-24
linux-x64 2.4.0 21.7.1 2024-03-21
linux-arm 2.3.0 21.3.0 2023-12-01

:::

  1. Download the test file https://sheetjs.com/pres.numbers:
curl -o pres.numbers https://sheetjs.com/pres.numbers
  1. Download xlsx-cli.js
curl -o xlsx-cli.js https://docs.sheetjs.com/cli/xlsx-cli.js
  1. Install the dependencies:
{`\ npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`} {`\ pnpm install --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`} {`\ yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`}
  1. Follow tooling steps:

Run nexe and manually specify NodeJS version 14.15.3

npx nexe -t 14.15.3 xlsx-cli.js

This generates xlsx-cli or xlsx-cli.exe depending on platform.

:::caution pass

When the demo was tested on ARM targets, the Nexe pre-built packages were missing. The package must be built from source:

npx nexe xlsx-cli.js --build --python=$(which python3) --make="-j8"

:::

:::caution pass

On Windows ARM, the target windows-arm64-20.10.0 must be specified:

npx nexe xlsx-cli.js --build --make="-j8" --target=windows-arm64-20.10.0

The Windows build may fail with a vcbuild.bat error:

Error: vcbuild.bat nosign release arm64 exited with code: 1

Pass the -v flag for more details. In the most recent test, the error stemmed from a Python version mismatch:

Node.js configure: found Python 2.7.18
Please use python3.11 or python3.10 or python3.9 or python3.8 or python3.7 or python3.6

The resolved version of Python can be found with

where python

In the most recent test, a Python 2 version appeared first. This was fixed by finding the Python 3 location and prepending it to PATH:

set PATH="C:\correct\path\to\python\three";%PATH%

:::

:::warning pass

When this demo was last tested, pkg failed with an error referencing node20:

> Targets not specified. Assuming:
  node20-linux-arm64, node20-macos-arm64, node20-win-arm64
> Error! No available node version satisfies 'node20'

pkg does not support NodeJS 20!

The local NodeJS version must be rolled back to version 18.

If n is installed:

sudo n 18

If nvm was used to install NodeJS:

nvm install 18
nvm use 18

:::

Run pkg:

npx pkg xlsx-cli.js

This generates xlsx-cli-linux, xlsx-cli-macos, and xlsx-cli-win.exe .

Run boxednode:

npx boxednode@2.4.0 -s xlsx-cli.js -t xlsx-cli

npx boxednode@2.4.0 -s xlsx-cli.js -t xlsx-cli.exe -n 16.20.2

:::info pass

The Windows 10 build requires Visual Studio with "Desktop development with C++" workload, Python 3.11, and NASM1.

The build command must be run in "x64 Native Tools Command Prompt"

:::

:::caution pass

When the demo was last tested, the build failed:

Not an executable Python program
Could not find Python.

By default, Windows aliases python to a Microsoft Store installer. If the official installer was used, the alias should be disabled manually:

  1. Open Start menu and type "app alias". Click "Manage app execution aliases".

  2. Disable the App Installer for all items with python in the name.

Using Python 3.12, the build fails with an error:

Please use python3.11 or python3.10 or python3.9 or python3.8 or python3.7 or python3.6.

In the most recent test, Python 3.11.8 was installed from the official site.

:::

:::caution pass

When the demo was last tested on Windows, the build failed:

error MSB8020: The build tools for Visual Studio 2019 (Platform Toolset = 'v142') cannot be found. To build using the v142 build tools, please install Visual Studio 2019 build tools.

This error was fixed by installing the v142 build tools through the Visual Studio installer.

:::

:::caution pass

In the most recent Windows test against NodeJS 20.8.0, the build failed due to an issue in the OpenSSL dependency:

...\node-v20.8.0\deps\openssl\openssl\crypto\cversion.c(75,33): error C2153: integer literals must have at least one digit [...\node-v20.8.0\deps\openssl\openssl.vcxproj]

SheetJS libraries are compatible with NodeJS versions dating back to v0.8. The workaround is to select NodeJS v16.20.2 using the -n flag. This version was was chosen since NodeJS v18 upgraded the OpenSSL dependency.

:::

  1. Run the generated program, passing pres.numbers as the argument. For example, nexe generates xlsx-cli in macOS so the command is:
./xlsx-cli pres.numbers

nexe generates xlsx-cli.exe in Windows, so the command is:

.\xlsx-cli.exe pres.numbers

V8

The V8 demo covers standalone programs that embed the V8 engine. This demo uses the Rust integration to generate a command line tool.

:::note Tested Deployments

This demo was last tested in the following deployments:

Architecture V8 Version Crate Date
darwin-x64 12.3.219.9 0.88.0 2024-03-15
darwin-arm 11.8.172.13 0.79.2 2023-10-18
win10-x64 12.3.219.9 0.88.0 2024-03-24
win11-x64 11.8.172.13 0.79.2 2023-10-14
linux-x64 12.3.219.9 0.88.0 2024-03-18
linux-arm 12.0.267.8 0.82.0 2023-12-01

:::

  1. Make a new folder for the project:
mkdir sheetjs2csv
cd sheetjs2csv
  1. Download the following scripts:
curl -o Cargo.toml https://docs.sheetjs.com/cli/Cargo.toml
curl -o snapshot.rs https://docs.sheetjs.com/cli/snapshot.rs
curl -o sheet2csv.rs https://docs.sheetjs.com/cli/sheet2csv.rs
  1. Download the SheetJS Standalone script and move to the project directory:
  • xlsx.full.min.js

{\ curl -o xlsx.full.min.js https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js}

  1. Build the V8 snapshot:
cargo build --bin snapshot
cargo run --bin snapshot

:::caution pass

With some versions of the v8 crate, the Linux AArch64 build failed with an error:

error[E0080]: evaluation of constant value failed

     |
1715 |   assert!(size_of::<TypeId>() == size_of::<u64>());
     |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the evaluated program panicked at 'assertion failed: size_of::<TypeId>() == size_of::<u64>()'

Versions 0.75.1 and 0.82.0 are known to work.

:::

  1. Build sheet2csv (sheet2csv.exe in Windows):
cargo build --release --bin sheet2csv
  1. Download the test file https://sheetjs.com/pres.numbers:
curl -o pres.numbers https://sheetjs.com/pres.numbers
  1. Test the application:
mv target/release/sheet2csv .
./sheet2csv pres.numbers

mv target/release/sheet2csv.exe .
.\sheet2csv.exe pres.numbers

Deno

The exposition has been moved to a separate page.

Dedicated Engines

The following demos for JS engines produce standalone programs:

  1. Downloads can be found at the main NASM project website ↩︎