Develop

Develop and contribute

NativeCAM is GPL-3.0-or-later and developed in the open on GitHub. Bug reports, results from your own machine and code reviews are all welcome. This page mirrors the repository's development notes.

Ways to help

  • Run the acceptance test on your machine and report the result, good or bad. It's the only way a controller moves from "from documentation" to tested.
  • Report bugs with the project file (.nativecam) and, for G-code problems, the exported file and your controller's name and version.
  • Review code. NativeCAM was written almost entirely by an AI coding assistant (Anthropic's Claude, using Claude Code) from the maintainer's requirements and design decisions, and checked with the tests and simulator rather than line by line. Careful human review, especially of the posts and export checks, is valuable.
  • Send pull requests against main. The "Test and build" check has to pass before a change can merge.

Project layout

Sources/
  CAMCore/        The engine, pure Swift with no UI: geometry, model, importers,
                  toolpaths, simulation, posts
  CClipper2/      Vendored Clipper2 2.0.1 (polygon offsetting) behind a small C bridge
  NativeCAM/      The SwiftUI app; Viewport/ is the Metal renderer
  nativecam-cli/  Command-line front end
Tests/CAMCoreTests/  Swift Testing suite and fixtures
examples/         Demo projects and the G-code they produce
docs/             Documentation and README images
scripts/          build-app.sh, test.sh, capture-window.sh, make-icon.swift, measure/

Inside CAMCore, all lengths are millimetres, design XY is relative to the material's lower-left corner, and Z = 0 is the material top. Posts convert to the chosen work origin and units. Each controller is described by a Dialect (what it accepts and how it reads files); PostProcessors.post(for:) picks the post for a project's machine, and GCodeCheck reads exported files back against the dialect.

Tests

The suite uses Swift Testing:

scripts/test.sh

The script adds the flags Swift Testing needs when only the Command Line Tools are installed, and builds the tests optimized in their own folder, because the geometry and simulation run about 100× slower unoptimized. Extra arguments pass through to swift test, for example scripts/test.sh --filter PostTests. For a debuggable, unoptimized run, use NATIVECAM_TEST_DEBUG=1 scripts/test.sh.

GitHub Actions runs the same script, then builds the app and the command-line tool, on every pull request and every push to main, on an Apple-silicon macOS runner. When a golden file differs, the run keeps the new output as a golden-actual download on the run's page.

Golden G-code

Golden-file tests compare posted files byte for byte, line endings included, for a hand-written job that reaches every branch of a post, the demo jobs, each controller's acceptance program, and project files saved by earlier builds, which must keep loading and posting the same bytes. Every golden file also has to pass the export checks.

When a test fails, the new output is saved to .build/golden-actual/. If the change is intended, accept it with NATIVECAM_UPDATE_GOLDENS=1 scripts/test.sh --filter GoldenPostTests and review git diff Tests/CAMCoreTests/Fixtures before committing. Saved project files are never regenerated: add a new one when the format changes.

Developer aids

  • Offscreen snapshots. build/NativeCAM.app/Contents/MacOS/NativeCAM -NativeCAMSnapshotProject <project> -NativeCAMSnapshotOut <dir> renders the main window, the finished simulation, the toolpaths and each inspector to PNGs, logs the job's checks and export checks, then quits.
  • Window captures. With the app running, scripts/capture-window.sh saves PNGs of its windows as composited on screen, and can put the window in a state first, for example tag=sim simulate=0.5, select=op:0, tools=1 or machinesetup=avid-pro6060:controller. Most screenshots on this site were taken that way.
  • Icon and logo. scripts/make-icon.swift draws the app icon, logo and social preview from one piece of artwork.

Measuring toolpath changes

  • Timing. scripts/measure/analyze.py job.tap breaks a posted job down per toolpath (cutting and rapid length, retracts, plunges, segment sizes) and times it with and without an acceleration model.
  • Part comparison. Simulate the before and after G-code with the same grid, nativecam-cli sim job.tap --cell 0.25 --heights out.bin, then scripts/measure/compare_parts.py before.bin after.bin --rect x0 y0 x1 y1 reports how much of the finished part changed.

Test data from other projects

Copy fixtures only from permissively licensed projects (MIT, BSD, Apache, Boost) and record the source in a SOURCE.md beside them. Tests for behaviour found in GPL or LGPL projects are re-derived, not copied. Never commit vendor tool libraries or Vectric posts: they aren't licensed for redistribution, so tests use fixtures written for them.

License and credits

NativeCAM is free software under the GNU General Public License, version 3 or later. Use it for anything, including commercial work. If you distribute NativeCAM or a modified version, you must license it under the GPL too and provide the complete source.

It builds on Clipper2 by Angus Johnson (Boost Software License 1.0), with test fixtures from dxf-parser (MIT) and resvg (MIT / Apache-2.0).