Building from Source

Building from Source

This page covers supported developer launches, native runtime preparation, sidecar builds and isolated development app identities.

Run commands from the repository root unless a step says otherwise. Use a checkout or worktree for your own branch, and keep the stable installed ChemDraft separate. The commands here describe the checked-in scripts; a local development build is not proof that a release is signed, notarized or verified on another platform.

Prerequisites

Component	macOS	Windows
JavaScript tools	Node 24 and pnpm 10.12.1	Node 24 and pnpm 10.12.1
Rust	rustup with Cargo available; repository-pinned Rust 1.97.1, clippy, rustfmt	Same pinned toolchain
Native environment	macOS build/signing tools; launch scripts use codesign, security and ditto	Visual Studio 2022 Build Tools with the C++ workload; WebView2
OPSIN runtime build	JDK 21 or newer providing jlink	Same, built on Windows
Rebuilding the 3D sidecar	CMake 3.24 or newer and a C++17 toolchain	CMake 3.24 or newer and the MSVC toolchain

Windows targets are Windows 10/11 x64; WebView2 is preinstalled on Windows 11. The repository pins Rust in rust-toolchain.toml and pnpm in root package.json. It does not pin an Xcode version in those files.

For a fresh independent checkout, install the locked JavaScript dependencies:

pnpm install --frozen-lockfile

Do not repeatedly reinstall dependencies in a managed shared-checkout workflow. Use the dependency setup provided for that environment.

Launch on macOS

For a packaged local app:

./run-app

For Tauri development with Vite hot reload:

./run-app --dev

pnpm dev routes through the same macOS development helper. The launcher prepares Sparkle, selects a development port, and identifies the worktree in its banner. The packaged branch bundle is moved into <worktree>/app/, rather than copied into the stable application's location.

The first native build downloads the pinned Sparkle dependency and checks its SHA-256. For the same preparation used by native CI:

pnpm --filter @chemdraft/desktop build:web
pnpm --filter @chemdraft/desktop prepare:sparkle

Launch or package on Windows

Use the cross-platform Node launcher from PowerShell or your normal terminal:

pnpm dev

For an NSIS installer:

node scripts/build-opsin-runtime.mjs
pnpm --filter @chemdraft/desktop build --bundles nsis

Stable installer output is under apps/desktop/src-tauri/target/release/bundle/nsis/, named ChemDraft_<version>_x64-setup.exe. A branch build uses ChemDraft (dev) in the product and installer name. The current public Windows installer is not Authenticode-signed, so a manual download can trigger SmartScreen. An updater signature is a separate mechanism.

Keep Windows checkouts outside synchronized folders to avoid extra work on node_modules and Rust build output. The development launcher closes only a matching executable from this checkout before rebuilding, allowing its normal session-flush path to run.

Prepare OPSIN on each host

OPSIN's JAR is vendored; its trimmed Java runtime is generated locally and is never committed:

node scripts/build-opsin-runtime.mjs

The script locates jlink, builds apps/desktop/src-tauri/resources/opsin/jre, and checks a benzene conversion when the JAR is present. A successful check prints smoke ok. The runtime is host-native: a macOS runtime cannot be copied into a Windows installer. A build without it can report OPSIN unavailable; prepare it before release packaging.

The native 3D sidecar

Real target-specific binaries are committed for Apple Silicon macOS and Windows x64. Other target entries include recognized placeholders, which report the sidecar unavailable. Ordinary desktop builds do not require rebuilding those binaries.

To rebuild, first fetch the pinned sources from the repository root:

git clone https://github.com/OpenChemistry/avogadrolibs.git native/avogadro3d-sidecar/_deps/avogadrolibs
git -C native/avogadro3d-sidecar/_deps/avogadrolibs checkout 416651ddaef33a4e20392392e7c0b505d446491b
git clone --depth 1 --branch 3.4.0 https://gitlab.com/libeigen/eigen.git native/avogadro3d-sidecar/_deps/eigen

Then change into native/avogadro3d-sidecar. On macOS:

cmake --preset protocol-scout
cmake --build --preset protocol-scout

On Windows:

cmake --preset windows-msvc
cmake --build --preset windows-msvc

The presets require the real local dependencies and intentionally fail without them. Keep the Open Babel, GPL-plugin and diagnostic-viewport exclusions intact. Run pnpm audit:engine3d-sidecar and the relevant sidecar smokes after a rebuild.

Verify which app launched

Branch builds show <dir> [<branch>] in the title, build stamp and launcher banner through CHEMDRAFT_WORKTREE_LABEL. build.rs re-emits that value so native titles rebuild correctly. Record the actual label, bundle path or Vite port and launched binary in your report.

The stable identity is org.chemdraft.desktop, installed at /Applications/ChemDraft.app on macOS or %LOCALAPPDATA%\ChemDraft on Windows. Branch builds use org.chemdraft.desktop.dev.<worktree-slug>, separate data and a separate single-instance lock; Windows installs the development product beside the stable one. Never rename, overwrite or unregister the stable app from a branch.

Stable package builds from main, or release automation using CHEMDRAFT_STABLE_BUILD=1, omit the worktree label. Do not use that override to disguise ordinary branch development. A macOS --dev launch is a bare binary without a bundle identifier; identify it by its build stamp.

Next

• Testing and CI
• Contributing
• Releasing