docs.sheetjs.com/docz/docs/03-demos/20-cli/index.md

521 lines
14 KiB
Markdown
Raw Normal View History

2022-07-31 23:45:34 +00:00
---
title: Command-Line Tools
2024-03-18 08:24:41 +00:00
pagination_prev: demos/desktop/index
2023-02-28 11:40:44 +00:00
pagination_next: demos/data/index
2022-07-31 23:45:34 +00:00
---
import current from '/version.js';
2022-08-01 08:15:50 +00:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-05-07 13:58:36 +00:00
import CodeBlock from '@theme/CodeBlock';
2024-03-18 08:24:41 +00:00
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
2022-07-31 23:45:34 +00:00
2024-05-28 05:20:05 +00:00
export const r = {style: {color:"red"}};
export const B = {style: {fontWeight:"bold"}};
2022-08-25 08:22:28 +00:00
With the availability of JS engines and the success of server-side platforms,
2024-03-18 08:24:41 +00:00
it is possible to build standalone command-line tools from JavaScript code.
2022-07-31 23:45:34 +00:00
2024-03-18 08:24:41 +00:00
[SheetJS](https://sheetjs.com) 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.
2024-05-28 05:20:05 +00:00
```bash title="Sample terminal session"
> xlsx-cli.exe pres.numbers
2024-03-18 08:24:41 +00:00
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:
<ul>{useCurrentSidebarCategory().items.map((item, index) => {
const listyle = (item.customProps?.icon) ? {
listStyleImage: `url("${item.customProps.icon}")`
} : {};
return (<li style={listyle} {...(item.customProps?.class ? {className: item.customProps.class}: {})}>
<a href={item.href}>{item.label}</a>{item.customProps?.summary && (" - " + item.customProps.summary)}
</li>);
})}</ul>
2022-07-31 23:45:34 +00:00
2023-10-11 02:18:57 +00:00
:::tip pass
The [`xlsx-cli`](https://cdn.sheetjs.com/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.
:::
2024-03-18 08:24:41 +00:00
:::caution pass
For most common deployment scenarios, it is possible to install a server-side
platform such as [NodeJS](/docs/getting-started/installation/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.
:::
2022-08-01 08:15:50 +00:00
## NodeJS
2022-08-25 08:22:28 +00:00
There are a few popular tools for compiling NodeJS scripts to CLI programs.
2022-08-01 08:15:50 +00:00
The demo script presents a friendly command line interface including flags:
```bash
$ ./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)
...
```
2023-12-02 08:39:35 +00:00
:::note Tested Deployments
2023-05-09 08:08:01 +00:00
This demo was tested in the following deployments:
2023-12-02 08:39:35 +00:00
<Tabs groupId="njs">
<TabItem value="nexe" label="Nexe">
2023-05-09 08:08:01 +00:00
2024-01-29 03:29:45 +00:00
| Architecture | Version | NodeJS | Source | Date |
|:-------------|:-------------|:----------|:----------|:-----------|
2024-03-16 16:04:18 +00:00
| `darwin-x64` | `4.0.0-rc.4` | `14.15.3` | Pre-built | 2024-03-15 |
2024-05-26 07:50:55 +00:00
| `darwin-arm` | `4.0.0-rc.6` | `18.20.3` | Compiled | 2024-05-25 |
| `win10-x64` | `4.0.0-rc.4` | `14.15.3` | Pre-built | 2024-04-18 |
2024-05-28 05:20:05 +00:00
| `win11-arm` | `4.0.0-rc.6` | `20.10.0` | Compiled | 2024-05-28 |
2024-03-22 04:45:40 +00:00
| `linux-x64` | `4.0.0-rc.4` | `14.15.3` | Pre-built | 2024-03-21 |
2024-05-28 05:20:05 +00:00
| `linux-arm` | `4.0.0-rc.6` | `18.20.3` | Compiled | 2024-05-26 |
2023-05-09 08:08:01 +00:00
2023-12-02 08:39:35 +00:00
</TabItem>
<TabItem value="pkg" label="pkg">
2024-01-29 03:29:45 +00:00
| Architecture | Version | NodeJS | Date |
|:-------------|:--------|:---------|:-----------|
2024-03-16 16:04:18 +00:00
| `darwin-x64` | `5.8.1` | `18.5.0` | 2024-03-15 |
2024-05-26 07:50:55 +00:00
| `darwin-arm` | `5.8.1` | `18.5.0` | 2024-05-25 |
| `win10-x64` | `5.8.1` | `18.5.0` | 2024-04-18 |
2024-05-28 05:20:05 +00:00
| `win11-arm` | `5.8.1` | `18.5.0` | 2024-05-28 |
2024-03-22 04:45:40 +00:00
| `linux-x64` | `5.8.1` | `18.5.0` | 2024-03-21 |
2024-05-28 05:20:05 +00:00
| `linux-arm` | `5.8.1` | `18.5.0` | 2024-05-26 |
2023-12-02 08:39:35 +00:00
</TabItem>
<TabItem value="boxednode" label="boxednode">
2023-05-09 08:08:01 +00:00
2024-01-29 03:29:45 +00:00
| Architecture | Version | NodeJS | Date |
|:-------------|:--------|:----------|:-----------|
2024-03-16 16:04:18 +00:00
| `darwin-x64` | `2.4.0` | `21.7.1` | 2024-03-15 |
2024-05-26 07:50:55 +00:00
| `darwin-arm` | `2.4.3` | `22.2.0` | 2024-05-25 |
| `win10-x64` | `2.4.2` | `16.20.2` | 2024-04-18 |
2024-03-22 04:45:40 +00:00
| `linux-x64` | `2.4.0` | `21.7.1` | 2024-03-21 |
2024-05-28 05:20:05 +00:00
| `linux-arm` | `2.4.3` | `20.13.1` | 2024-05-26 |
2023-05-09 08:08:01 +00:00
2023-12-02 08:39:35 +00:00
</TabItem>
</Tabs>
:::
2023-05-09 08:08:01 +00:00
2024-04-26 04:16:13 +00:00
0) Download the test file https://docs.sheetjs.com/pres.numbers:
2023-05-09 08:08:01 +00:00
```bash
2024-04-26 04:16:13 +00:00
curl -o pres.numbers https://docs.sheetjs.com/pres.numbers
2023-05-09 08:08:01 +00:00
```
2022-08-01 08:15:50 +00:00
1) Download [`xlsx-cli.js`](pathname:///cli/xlsx-cli.js)
2023-05-09 08:08:01 +00:00
```bash
2024-03-25 04:13:01 +00:00
curl -o xlsx-cli.js https://docs.sheetjs.com/cli/xlsx-cli.js
2023-05-09 08:08:01 +00:00
```
2022-08-01 08:15:50 +00:00
2) Install the dependencies:
2023-05-07 13:58:36 +00:00
<Tabs groupId="pm">
2022-08-01 08:15:50 +00:00
<TabItem value="npm" label="npm">
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2022-08-01 08:15:50 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-08-01 08:15:50 +00:00
</TabItem>
<TabItem value="pnpm" label="pnpm">
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2024-03-20 07:05:29 +00:00
pnpm install --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-08-01 08:15:50 +00:00
</TabItem>
<TabItem value="yarn" label="Yarn" default>
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2022-08-01 08:15:50 +00:00
yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2022-08-01 08:15:50 +00:00
</TabItem>
</Tabs>
3) Follow tooling steps:
2023-12-02 08:39:35 +00:00
<Tabs groupId="njs">
2022-08-01 08:15:50 +00:00
<TabItem value="nexe" label="Nexe">
2023-02-28 11:40:44 +00:00
Run `nexe` and manually specify NodeJS version 14.15.3
2022-08-01 08:15:50 +00:00
```bash
npx nexe -t 14.15.3 xlsx-cli.js
```
This generates `xlsx-cli` or `xlsx-cli.exe` depending on platform.
2023-09-24 03:59:48 +00:00
:::caution pass
2023-06-05 20:12:53 +00:00
2023-09-25 07:30:54 +00:00
When the demo was tested on ARM targets, the Nexe pre-built packages were
2023-06-05 20:12:53 +00:00
missing. The package must be built from source:
2024-05-28 05:20:05 +00:00
<Tabs groupId="os">
<TabItem value="unix" label="Linux/MacOS">
2023-06-05 20:12:53 +00:00
```bash
npx nexe xlsx-cli.js --build --python=$(which python3) --make="-j8"
```
2024-05-28 05:20:05 +00:00
</TabItem>
<TabItem value="win" label="Windows">
```bash
npx nexe xlsx-cli.js --build --make="-j8"
```
</TabItem>
</Tabs>
2023-12-02 08:39:35 +00:00
:::
:::caution pass
On Windows ARM, the target `windows-arm64-20.10.0` must be specified:
2023-09-25 07:30:54 +00:00
```bash
2023-12-02 08:39:35 +00:00
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
```cmd
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`:
```cmd
set PATH="C:\correct\path\to\python\three";%PATH%
2023-09-25 07:30:54 +00:00
```
2023-06-05 20:12:53 +00:00
:::
2022-08-01 08:15:50 +00:00
</TabItem>
<TabItem value="pkg" label="pkg">
:::danger pass
2023-12-02 08:39:35 +00:00
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:
```bash
sudo n 18
```
If `nvm` was used to install NodeJS:
```bash
nvm install 18
nvm use 18
```
:::
2023-02-28 11:40:44 +00:00
Run `pkg`:
2022-08-01 08:15:50 +00:00
```bash
npx pkg xlsx-cli.js
```
This generates `xlsx-cli-linux`, `xlsx-cli-macos`, and `xlsx-cli-win.exe` .
2023-05-09 08:08:01 +00:00
</TabItem>
<TabItem value="boxednode" label="boxednode">
Run `boxednode`:
2023-08-28 22:40:53 +00:00
<Tabs groupId="os">
<TabItem value="unix" label="Linux/MacOS">
```bash
2024-05-28 05:20:05 +00:00
npx boxednode@2.4.3 -s xlsx-cli.js -t xlsx-cli
```
:::caution pass
When this demo was last tested in `linux-arm`, the build failed with an error:
<pre>
../deps/v8/src/base/small-vector.h: In instantiation of <span {...B}>class v8::base::SmallVector&lt;std::pair&lt;const v8::internal::compiler::turboshaft::PhiOp*, const v8::internal::compiler::turboshaft::OpIndex&gt;, 16&gt;</span>:
<span {...B}>../deps/v8/src/compiler/turboshaft/loop-unrolling-reducer.h:444:11:</span> required from here
<span {...B}>../deps/v8/src/base/macros.h:206:55:</span> <span style={{...r.style,...B.style}}>error:</span> static assertion failed: T should be trivially copyable
{" 206 |"} static_assert(::v8::base::is_trivially_copyable&lt;T&gt;::<span style={{...r.style,...B.style}}>value</span>, \\
{" |"} ^~~~~
</pre>
This affects NodeJS `22.2.0`, but does not affect `20.13.1`. It affects the
[V8 JavaScript Engine](https://docs.sheetjs.com/docs/demos/engines/v8#build-v8)
and cannot easily be patched using `boxednode`.
The `-n` flag controls the target NodeJS version. For this demo, the following
command uses NodeJS `20.13.1`:
```bash
npx boxednode@2.4.3 -s xlsx-cli.js -t xlsx-cli -n 20.13.1
2023-08-28 22:40:53 +00:00
```
2024-05-28 05:20:05 +00:00
:::
2023-08-28 22:40:53 +00:00
</TabItem>
<TabItem value="win" label="Windows">
2023-05-09 08:08:01 +00:00
```bash
2024-05-28 05:20:05 +00:00
npx boxednode@2.4.3 -s xlsx-cli.js -t xlsx-cli.exe -n 16.20.2
2023-08-28 22:40:53 +00:00
```
:::info pass
The Windows 10 build requires Visual Studio with "Desktop development with C++"
2024-03-25 04:13:01 +00:00
workload, Python 3.11, and NASM[^1].
2023-08-28 22:40:53 +00:00
2024-03-25 04:13:01 +00:00
**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.
2023-10-10 08:40:16 +00:00
2023-08-28 22:40:53 +00:00
:::
:::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
2023-10-10 08:40:16 +00:00
In the most recent Windows test against NodeJS `20.8.0`, the build failed due
2023-08-28 22:40:53 +00:00
to an issue in the OpenSSL dependency:
```
2023-10-10 08:40:16 +00:00
...\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]
2023-05-09 08:08:01 +00:00
```
2023-08-28 22:40:53 +00:00
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.
:::
2022-08-01 08:15:50 +00:00
</TabItem>
</Tabs>
2023-05-09 08:08:01 +00:00
2023-08-28 22:40:53 +00:00
</TabItem>
</Tabs>
4) Run the generated program, passing `pres.numbers` as the argument. For
2023-06-05 20:12:53 +00:00
example, `nexe` generates `xlsx-cli` in macOS so the command is:
2023-05-09 08:08:01 +00:00
```bash
./xlsx-cli pres.numbers
```
2023-08-28 22:40:53 +00:00
`nexe` generates `xlsx-cli.exe` in Windows, so the command is:
```powershell
.\xlsx-cli.exe pres.numbers
```
2023-05-25 01:36:15 +00:00
## V8
The [V8](/docs/demos/engines/v8) demo covers standalone programs that embed the
V8 engine. This demo uses the Rust integration to generate a command line tool.
2023-12-02 08:39:35 +00:00
:::note Tested Deployments
2023-05-25 01:36:15 +00:00
This demo was last tested in the following deployments:
2023-10-10 08:40:16 +00:00
| Architecture | V8 Version | Crate | Date |
|:-------------|:--------------|:---------|:-----------|
2024-03-16 16:04:18 +00:00
| `darwin-x64` | `12.3.219.9` | `0.88.0` | 2024-03-15 |
2024-05-24 08:24:50 +00:00
| `darwin-arm` | `12.6.228.3` | `0.92.0` | 2024-05-23 |
2024-03-25 04:13:01 +00:00
| `win10-x64` | `12.3.219.9` | `0.88.0` | 2024-03-24 |
2024-05-26 07:50:55 +00:00
| `win11-x64` | `12.6.228.3` | `0.92.0` | 2024-05-23 |
2024-03-18 08:24:41 +00:00
| `linux-x64` | `12.3.219.9` | `0.88.0` | 2024-03-18 |
2024-05-28 05:20:05 +00:00
| `linux-arm` | `12.6.228.3` | `0.92.0` | 2024-05-26 |
2023-08-31 22:09:08 +00:00
:::
2023-05-25 01:36:15 +00:00
0) Make a new folder for the project:
```bash
mkdir sheetjs2csv
cd sheetjs2csv
```
1) Download the following scripts:
- [`Cargo.toml`](pathname:///cli/Cargo.toml)
- [`snapshot.rs`](pathname:///cli/snapshot.rs)
- [`sheet2csv.rs`](pathname:///cli/sheet2csv.rs)
```bash
2024-03-25 04:13:01 +00:00
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
2023-05-25 01:36:15 +00:00
```
2023-09-22 06:32:55 +00:00
2) Download the SheetJS Standalone script and move to the project directory:
<ul>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`}>xlsx.full.min.js</a></li>
</ul>
2023-05-25 01:36:15 +00:00
<CodeBlock language="bash">{`\
2024-03-25 04:13:01 +00:00
curl -o xlsx.full.min.js https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`}
2023-05-25 01:36:15 +00:00
</CodeBlock>
3) Build the V8 snapshot:
```bash
cargo build --bin snapshot
cargo run --bin snapshot
```
2023-12-02 08:39:35 +00:00
:::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.
:::
2023-05-25 01:36:15 +00:00
4) Build `sheet2csv` (`sheet2csv.exe` in Windows):
```bash
cargo build --release --bin sheet2csv
```
2024-04-26 04:16:13 +00:00
5) Download the test file https://docs.sheetjs.com/pres.numbers:
2023-05-25 01:36:15 +00:00
```bash
2024-04-26 04:16:13 +00:00
curl -o pres.numbers https://docs.sheetjs.com/pres.numbers
2023-05-25 01:36:15 +00:00
```
6) Test the application:
<Tabs groupId="os">
<TabItem value="unix" label="Linux/MacOS">
```bash
mv target/release/sheet2csv .
./sheet2csv pres.numbers
```
</TabItem>
<TabItem value="win" label="Windows">
```bash
mv target/release/sheet2csv.exe .
2023-08-31 22:09:08 +00:00
.\sheet2csv.exe pres.numbers
2023-05-25 01:36:15 +00:00
```
</TabItem>
</Tabs>
2024-03-18 08:24:41 +00:00
#### Deno
2023-05-09 08:08:01 +00:00
2024-03-18 08:24:41 +00:00
**[The exposition has been moved to a separate page.](/docs/demos/cli/deno)**
2023-05-09 08:08:01 +00:00
## Dedicated Engines
The following demos for JS engines produce standalone programs:
- [Duktape](/docs/demos/engines/duktape)
2023-05-23 06:28:14 +00:00
- [ChakraCore](/docs/demos/engines/chakra)
- [QuickJS](/docs/demos/engines/quickjs)
2023-05-09 08:08:01 +00:00
- [Goja](/docs/demos/engines/goja)
- [JavaScriptCore](/docs/demos/engines/jsc)
2023-08-28 22:40:53 +00:00
2024-03-18 08:24:41 +00:00
[^1]: Downloads can be found [at the main NASM project website](https://www.nasm.us/)