openscad-toolchain-setup

name	openscad-toolchain-setup
description	Install, upgrade, and verify an OpenSCAD toolchain for complex SCAD workflows. Use when setting up OpenSCAD, BOSL2, NopSCADlib, OPENSCADPATH, Manifold backend support, STL export smoke tests, or diagnosing missing include or library errors.
argument-hint	Target OS or distro, package manager, and whether to install, upgrade, or only verify

OpenSCAD Toolchain Setup

Use this skill when the task is to prepare or validate a serious OpenSCAD environment rather than edit one model. It covers OpenSCAD itself, user library placement, BOSL2, NopSCADlib, and repo-level smoke renders.

The current workspace does not require BOSL2 or NopSCADlib for its existing rack models, so treat those as toolchain capabilities to install and verify, not as hard repo dependencies.

Inputs To Confirm

Before changing anything, confirm:

• target OS and distro
• available package manager and whether elevated privileges are allowed
• whether the user wants stable OpenSCAD, a newer AppImage/nightly build, or verification only
• whether libraries should live in the default user library path or a custom path via OPENSCADPATH
• whether existing BOSL2 or NopSCADlib clones should be updated in place or left untouched
• whether the workflow depends on --backend=manifold for dense booleans, masks, or support-free geometry diagnostics

Procedure

1. Inspect the current state.

   • Check command -v openscad and openscad --version.
   • Check whether the build can run --backend=manifold if the workflow requires it.
   • Print OPENSCADPATH if it exists.
   • Check the default user library path for the platform.
   • If this is a repo task, note any existing smoke-test commands already known to work.

2. Choose the installation source.

   • If openscad is missing, install it with the platform package manager or an official AppImage.
   • If OpenSCAD is present but too old for the required feature set or lacks reliable Manifold support, prefer upgrading before touching library code.
   • On Linux, use the guidance in linux-install.md.

3. Normalize library placement.

   • Prefer the user library directory unless the user already standardizes on OPENSCADPATH.
   • Keep library folder names exact: BOSL2 and NopSCADlib.
   • If clones already exist and are locally modified, do not overwrite them without confirmation.

4. Install or update libraries.

   • Install BOSL2 and NopSCADlib as git clones or release archives in the OpenSCAD library path.
   • If the environment must be reproducible, record the commit hash or tag after installation.

5. Verify the toolchain.

   • Run the bundled verifier: verify-openscad-toolchain.sh.
   • The verifier checks plain OpenSCAD export, BOSL2 include resolution, NopSCADlib include resolution, and optional repo smoke renders.
   • If the design workflow expects boolean-heavy or support-free geometry work, run at least one smoke render with --backend=manifold as a separate confirmation.

6. Verify the project workflow.

   • Run the repo smoke renders in project-smoke-tests.md.
   • If an existing repo already has known-good renders, prefer those over inventing new checks.

7. Close out with reproducibility details.

   • Report OpenSCAD version.
   • Report where BOSL2 and NopSCADlib were found or installed.
   • State whether OPENSCADPATH was required.
   • State whether --backend=manifold was available and verified.
   • State which smoke renders passed.

Decision Points

• If OpenSCAD is installed and the task is verification only, do not reinstall it.
• If distro packages are too old for the requested feature or missing Manifold support, use a newer official build instead of forcing the repo to work around missing capabilities.
• If BOSL2 or NopSCADlib are already present under a nonstandard directory, prefer wiring that directory through OPENSCADPATH over duplicating the libraries.
• If the repo does not currently use BOSL2 or NopSCADlib, still verify them independently but do not rewrite repo code just to exercise them.
• If verification fails on library includes but the repo renders succeed, report that as a toolchain gap rather than a repo regression.
• If support-free workflows depend on dense booleans or masks, treat lack of Manifold support as a material capability gap rather than a minor convenience issue.

Completion Criteria

Consider the workflow complete only when all relevant checks pass:

• openscad --version succeeds
• OpenSCAD can export a plain STL from a trivial file
• OpenSCAD can render with --backend=manifold when that capability is required
• BOSL2 include resolution succeeds
• NopSCADlib include resolution succeeds
• repo smoke renders succeed when the repo files are present
• final report includes versions, library paths, Manifold status, and any remaining gaps

Resources

• Linux install guidance
• Repo smoke tests
• Verification script