docs.sheetjs.com/09-cli.md at 073f8a3be3d510348a6ecbe55c062437d3013614

LankyMoose/docs.sheetjs.com

Fork 0

forked from sheetjs/docs.sheetjs.com

SheetJS 2505d3b639 darwin-arm

2023-10-19 14:45:29 -04:00

10 KiB

Raw Blame History

title

pagination_prev

pagination_next

sidebar_custom_props

Command-Line Tools

demos/mobile/index

demos/data/index

cli
true

import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';

With the availability of JS engines and the success of server-side platforms, it is feasible to build command-line tools for various workflows.

This demo covers a number of strategies for building standalone processors. The goal is to generate CSV output from an arbitrary spreadsheet file.

:::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.

:::

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)
...

Tested Deployments (click to show)

This demo was tested in the following deployments:

pkg

Architecture	Version	Node Target	Date
`darwin-x64`	`5.8.1`	`18.5.0`	2023-10-11
`darwin-arm`	`5.8.1`	`18.5.0`	2023-09-25
`win10-x64`	`5.8.1`	`18.5.0`	2023-10-09
`win11-arm`	`5.8.1`	`18.5.0`	2023-09-25
`linux-x64`	`5.8.1`	`18.5.0`	2023-10-11
`linux-arm`	`5.8.1`	`18.5.0`	2023-09-25

nexe

Architecture	Version	Node Target	Date
`darwin-x64`	`4.0.0-rc.2`	`14.15.3`	2023-10-10
`darwin-arm`	`4.0.0-rc.2`	`20.7.0`	2023-09-25
`win10-x64`	`4.0.0-rc.2`	`14.15.3`	2023-10-09
`win11-arm`	`4.0.0-rc.2`	`18.17.1`	2023-09-25
`linux-x64`	`4.0.0-rc.2`	`14.15.3`	2023-10-11
`linux-arm`	`4.0.0-rc.2`	`20.7.0`	2023-09-25

boxednode

Architecture	Version	Node Target	Date
`darwin-x64`	`2.1.2`	`20.8.0`	2023-10-12
`darwin-arm`	`2.1.1`	`20.7.0`	2023-09-25
`win10-x64`	`2.1.2`	`16.20.2`	2023-10-09
`linux-x64`	`2.1.2`	`20.8.0`	2023-10-11
`linux-arm`	`2.1.1`	`20.7.0`	2023-09-25

Download the test file https://sheetjs.com/pres.numbers:

curl -LO https://sheetjs.com/pres.numbers

Download xlsx-cli.js

curl -LO https://docs.sheetjs.com/cli/xlsx-cli.js

Install the dependencies:

{`\ npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`} {`\ pnpm install 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`}

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"

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

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

:::

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.1.2 -s xlsx-cli.js -t xlsx-cli

npx boxednode@2.1.2 -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, and NASM¹.

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

:::

:::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.

:::

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.

Tested Deployments (click to show)

This demo was last tested in the following deployments:

Architecture	V8 Version	Crate	Date
`darwin-x64`	`11.8.172.13`	`0.79.2`	2023-10-12
`darwin-arm`	`11.8.172.13`	`0.79.2`	2023-10-18
`win10-x64`	`11.8.172.13`	`0.79.2`	2023-10-09
`win11-x64`	`11.8.172.13`	`0.79.2`	2023-10-14
`linux-x64`	`11.8.172.13`	`0.79.2`	2023-10-11
`linux-arm`	`11.7.439.6`	`0.75.1`	2023-08-30

:::caution pass

Using crate version 0.71.2, 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>()'

This was fixed in version 0.75.1 of the crate.

:::

Make a new folder for the project:

mkdir sheetjs2csv
cd sheetjs2csv

Download the following scripts:

curl -LO https://docs.sheetjs.com/cli/Cargo.toml
curl -LO https://docs.sheetjs.com/cli/snapshot.rs
curl -LO https://docs.sheetjs.com/cli/sheet2csv.rs

Download the SheetJS Standalone script and move to the project directory:

xlsx.full.min.js

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

Build the V8 snapshot:

cargo build --bin snapshot
cargo run --bin snapshot

Build sheet2csv (sheet2csv.exe in Windows):

cargo build --release --bin sheet2csv

Download the test file https://sheetjs.com/pres.numbers:

curl -LO https://sheetjs.com/pres.numbers

Test the application:

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

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

Deno

deno compile generates a standalone executable that includes the entire JS runtime as well as user JS code.

When compiling, the --allow-read option must be specified to allow the script to read files from the filesystem with Deno.readFileSync.

https://docs.sheetjs.com/cli/sheet2csv.ts can be compiled and run from Deno.

Tested Deployments (click to show)

This demo was last tested in the following deployments:

Architecture	Version	Date
`darwin-x64`	`1.37.1`	2023-10-12
`darwin-arm`	`1.37.2`	2023-10-18
`win10-x64`	`1.37.1`	2023-10-09
`win11-x64`	`1.37.2`	2023-10-14
`win11-arm`	`1.37.0`	2023-09-26
`linux-x64`	`1.37.1`	2023-10-11
`linux-arm`	`1.36.3`	2023-08-30

Download the test file https://sheetjs.com/pres.numbers:

curl -LO https://sheetjs.com/pres.numbers

Test the script with deno run:

deno run -r --allow-read https://docs.sheetjs.com/cli/sheet2csv.ts pres.numbers

If this worked, the program will print a CSV of the first worksheet.

Compile and run sheet2csv:

deno compile -r --allow-read https://docs.sheetjs.com/cli/sheet2csv.ts
./sheet2csv pres.numbers

Dedicated Engines

The following demos for JS engines produce standalone programs:

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

10 KiB Raw Blame History

NodeJS

V8

Deno

Dedicated Engines

10 KiB

Raw Blame History