Build Instructions¶

This guide describes the supported development and packaging workflow for CodeXomics 0.722.0.

Supported Toolchain¶

Node.js 20 and 22 are exercised by CI. Use an active LTS release and avoid changing the Electron pin without testing both CI versions and an unpacked package build.

Platform Requirements¶

sudo apt-get update
sudo apt-get install -y build-essential libnss3 libatk-bridge2.0-0 \
  libatk1.0-0 libcups2 libgtk-3-0 libgbm1 libasound2 libxshmfence1 libxss1

Install¶

git clone https://github.com/Scilence2022/CodeXomics.git
cd CodeXomics
npm install

Use npm ci in clean CI or release environments when the lockfile is already current.

Do not manually edit package-lock.json. If dependencies change, update the lockfile through npm.

Run Locally¶

npm start
npm run dev

Optional combined services:

npm run mcp-server
npm run start-with-mcp
npm run marketplace:start
npm run start-with-marketplace
npm run start-full

Validate Before Packaging¶

npm run lint
npm run version-validate
npm run tool-registry:validate
npm run test:coverage
npm run docs:validate

The Electron smoke suite launches the real application and may require a display server on Linux:

npm run test:e2e

Package The Application¶

Fast unpacked package for the current platform:

npm run pack

Installer/package builds without publishing:

npm run dist
npm run build:mac
npm run build:win
npm run build:linux

Cross-platform packaging generally requires building on each target operating system. npm run build:all is available, but native signing and platform tooling still apply.

Generated packages are written to dist/, which is build output and should not be edited manually.

Configured targets:

Signing And Publishing¶

Release credentials are supplied through environment variables and must never be committed.

macOS signing and notarization:

export CSC_LINK="/path/to/DeveloperID.p12"
export CSC_KEY_PASSWORD="<certificate password>"
export APPLE_ID="you@example.com"
export APPLE_APP_SPECIFIC_PASSWORD="<app-specific password>"
export APPLE_TEAM_ID="XXXXXXXXXX"

Windows signing:

export CSC_LINK="/path/to/codesign.pfx"
export CSC_KEY_PASSWORD="<certificate password>"

GitHub publishing:

export GH_TOKEN="<token with repository release access>"
npx electron-builder --mac --win --linux --publish always

See the root RELEASING.md for the complete signed-release and auto-update workflow.

Documentation Builds¶

npm run docs:serve
npm run docs:validate
npm run docs:deploy

• docs:serve starts a local preview.
• docs:validate checks release metadata and runs a strict MkDocs build.
• docs:deploy publishes generated output to the gh-pages branch.

The source is always docs/ plus mkdocs.yml; never edit site/ directly.

Troubleshooting¶

Clean Dependency Reinstall¶

Prefer preserving the lockfile:

rm -rf node_modules
npm ci

Native Module Problems¶

npx electron-builder install-app-deps

Confirm the active Node.js version matches the supported matrix before rebuilding.

Build Memory¶

export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Linux Headless Smoke Test¶

xvfb-run --auto-servernum --server-args="-screen 0 1280x1024x24" npm run test:e2e

Version Mismatch¶

src/version.js is the application version source. After intentionally changing it, synchronize and validate:

npm run version-sync
npm run version-validate
npm run docs:validate