Skip to main content

Contributing

Due to the precarious nature of the Open Specifications Promise, it is very important to ensure code is cleanroom. Contribution Notes

File organization (click to show)

Folders:

foldercontents
binserver-side bin scripts (xlsx.njs)
bitsraw source files that make up the final script
distdist files for web browsers and nonstandard JS environments
miscmiscellaneous supporting scripts
modulesTypeScript source files that generate some of the bits
packagesSupport libraries and tools
test_filestest files (pulled from the test files repository)
testsbrowser tests (run make ctest to rebuild)
typesTypeScript definitions and tests

After cloning the repo, running make help will display a list of commands.

Setup

These instructions will cover system configuration, cloning the source repo, building, reproducing official releases, and running NodeJS and browser tests.

Tested Deployments

These instructions were tested on the following platforms:

PlatformArchitectureTest Date
Linux (Steam Deck Holo x64)linux-x642024-03-21
Linux (Ubuntu 18 AArch64)linux-arm2023-12-01
MacOS 14.4 (x64)darwin-x642024-03-15
MacOS 14.1.2 (ARM64)darwin-arm2023-12-01
Windows 10 (x64) + WSL Ubuntuwin10-x642024-03-04
Windows 11 (x64) + WSL Ubuntuwin11-x642023-10-14
Windows 11 (ARM) + WSL Ubuntuwin11-arm2023-09-18

With some additional dependencies, the unminified scripts are reproducible and tests will pass in Windows XP with NodeJS 5.10.0.

Install dependencies

OS-Specific Setup

A) Ensure WSL ("WSL 2" in Windows 10) and the Ubuntu distribution are installed.

Installation Notes (click to hide)

In "Turn Windows features on or off", the following features must be enabled:

  • "Hyper-V" (including every sub-feature)
  • "Virtual Machine Platform"
  • "Windows Hypervisor Platform"
  • "Windows Subsystem for Linux"

The following command installs Ubuntu within WSL:

wsl --install Ubuntu

In some versions of wsl, the -d flag must be specified:

wsl --install -d Ubuntu

In the last Windows 11 test, there was a WSL_E_DEFAULT_DISTRO_NOT_FOUND error.

The resolution is to switch to WSL1, install, and switch back to WSL2:

wsl --set-default-version 1
wsl --install Ubuntu
wsl --set-default-version 2
wsl --install Ubuntu

WSL will not run in a Windows on ARM VM on computers with the M1 CPU

Apple Silicon M1 processors do not support nested virtualization.

M2 processors do support nested virtualization. SheetJS users have reported success with Windows on ARM running on computers with the M2 Max CPU.

B) Install mercurial and subversion from within WSL:

sudo apt-get update
sudo apt-get install mercurial subversion

In some Windows 10 runs, mercurial and subversion were not available in the default Ubuntu distro. A separate repository is available:

# Install support programs for the build and test commands
sudo add-apt-repository ppa:mercurial-ppa/releases
sudo apt-get update
sudo apt-get install mercurial subversion
sudo add-apt-repository --remove ppa:mercurial-ppa/releases

If the first command displays an error involving a missing release file, remove the repo before proceeding:

sudo add-apt-repository --remove ppa:mercurial-ppa/releases

C) Install NodeJS within WSL:

In the most recent test, the script showed a deprecation notice.

The script worked as expected.

The official workaround does not currently work with WSL. When the issues are resolved, the instructions will be updated.

# Install bootstrap NodeJS and NPM within the WSL
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs

D) Exit the WSL session and start a new session

E) Install the n package and switch NodeJS versions:

# Switch to `n`-managed NodeJS
sudo npm i -g n
sudo n 16

If npm is missing, it can be installed with

sudo apt-get install -y npm

F) Clone the js-crc32 repo

git clone https://git.sheetjs.com/sheetjs/js-crc32

On Windows 10, this clone may fail due to issues with core.filemode:

fatal: could not set 'core.filemode' to 'false'

The main drive must be remounted with the metadata option:

cd /
sudo umount /mnt/c
sudo mount -t drvfs C: /mnt/c -o metadata
cd -

If this clone fails with an error message that mentions SSL or secure connection or certificates, build and install a version of Git with proper SSL support:

# Git does not support OpenSSL out of the box, must do this
curl -LO https://github.com/niko-dunixi/git-openssl-shellscript/raw/main/compile-git-with-openssl.sh
chmod +x compile-git-with-openssl.sh
./compile-git-with-openssl.sh

G) Set git config core.autocrlf setting to false. The following commands should be run twice, once within PowerShell (if Git for Windows is installed) and once within WSL bash:

git config --global --add core.autocrlf false
git config --global --unset core.autocrlf true

H) Run unzip. If the program is missing, install manually:

sudo apt-get install -y unzip

I) Run make. If the program is missing, install manually:

sudo apt-get install -y make

Build from source tree

0) Clone the project:

git clone https://git.sheetjs.com/sheetjs/sheetjs
cd sheetjs

On older platforms, the clone may fail due to SSL certificate problems:

fatal: unable to access 'https://git.sheetjs.com/sheetjs/sheetjs/': SSL certificate problem: certificate has expired

The simplest workaround is to disable SSL verification:

git config --global http.sslVerify false

It is strongly recommended to re-enable SSL verification after cloning:

git config --global http.sslVerify true

1) Install NodeJS modules for building the scripts:

npm i
npm i -g [email protected] voc @sheetjs/uglify-js

If npm i -g fails with a permissions issue, run the command with sudo:

npm i
sudo npm i -g [email protected] voc @sheetjs/uglify-js
Older Versions of Dependencies

Some of the dependencies are wildly out of date. While SheetJS aims to run in older versions of NodeJS and browsers, some libraries have chosen to break backwards compatibility. The specific versions are used because they are known to work and known to produce consistent results.

2) Initialize the test files:

rmdir test_files
curl -LO https://test-files.sheetjs.com/test_files.zip
unzip test_files.zip
mkdir -p tmp

The rmdir command may fail if the folder is missing. The error can be ignored.

This step may take a few minutes as the current test snapshot is large.

3) Run the esbuild tool once:

4) Run a build and verify with a short test:

# Full Build
cd modules; make clean; make; cd ..
make
make dist

# Short test
make test_misc

# Reset repo
git checkout -- .

In some tests on older releases of macOS, the build failed with an error:

ReferenceError: n is not defined

The first error in the call stack points to dist/xlsx.zahl.js.

Older versions of macOS sed are known to misinterpret newline characters. The workaround is to upgrade to a newer version of sed. On macOS:

brew install gnu-sed
echo 'export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"' >> ~/.profile
. ~/.profile

Reproduce official builds

5) Run git log and search for the commit that matches a particular release version. For example, version 0.20.1 can be found with:

git log | grep -B4 "version bump 0.20.1"

The output should look like:

$ git log | grep -B4 "version bump 0.20.1"
commit 29d46c07a895bdfd948d15b5115529ae697ccb48 <-- this is the commit hash
Author: SheetJS <[email protected]>
Date: Tue Dec 5 03:19:42 2023 -0500

version bump 0.20.1

6) Switch to that commit:

git checkout 29d46c07a895bdfd948d15b5115529ae697ccb48

7) Run the full build sequence

make clean; make
cd modules; make clean; make; cd ..
make
make dist

8) To verify that the files are intact, use md5sum (md5 on MacOS).

The local checksum for the browser script can be computed with:

md5sum dist/xlsx.full.min.js

The checksum for the CDN version can be computed with:

curl -L https://cdn.sheetjs.com/xlsx-0.20.1/package/dist/xlsx.full.min.js | md5sum -

When the demo was last tested on macOS, against version 0.20.1:

$ md5 dist/xlsx.full.min.js
MD5 (dist/xlsx.full.min.js) = c5db4b1d2a1985a4ebfbaa500243f593
$ curl -k -L https://cdn.sheetjs.com/xlsx-0.20.1/package/dist/xlsx.full.min.js | md5
c5db4b1d2a1985a4ebfbaa500243f593

The two hashes should match.

9) Return to the HEAD commit:

git checkout master

Test in web browsers

10) Start local server:

make ctestserv

The terminal will display a port number. For example:

Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)

11) Open a browser window and access http://localhost:8000, replacing 8000 with the port number from the terminal window.

Development

The xlsx.js and xlsx.mjs files are constructed from the files in the bits subfolder. The build script (run make) will concatenate the individual bits to produce the scripts.

When changing the .js scripts in bits, the following sequence rebuilds the xlsx.js and xlsx.mjs scripts:

make

When changing the .ts scripts in modules, the following sequence rebuilds the xlsx.js and xlsx.mjs scripts:

cd modules; make clean; make; cd ..

To produce the dist files, run make dist.

The various xlsx.* scripts in the base folder and the files in the dist folder are updated on each version release.

They should not be committed between versions!

Tests

The test_misc target runs the targeted feature tests. It should take 5-10 seconds to perform feature tests without testing against the full test battery. New features should be accompanied with tests for the relevant file formats.

For tests involving the read side, an appropriate feature test would involve reading an existing file and checking the resulting workbook object. If a parameter is involved, files should be read with different values to verify that the feature is working as expected.

For tests involving a new write feature which can already be parsed, appropriate feature tests would involve writing a workbook with the feature and then opening and verifying that the feature is preserved.

For tests involving a new write feature without an existing read ability, please add a feature test to the kitchen sink tests/write.js.