Internals
Contributing
Rules
Read AGENTS.md at the root of the repo. It has the rules for all contributors, people and agents:
- The goals of the project.
- Licenses and references: each source that you use goes in
REFERENCES.mdand in the header comment of the file. - The writing style for comments and docs.
- The checks before a commit.
Set up
zig version # must be 0.16.x
zig build test # the unit tests
zig build -Doptimize=ReleaseFast
Tests
There are three kinds of tests.
Unit tests
Each source file has test blocks at the end. zig build test runs all of them, with the leak-checking allocator. A test that leaks memory fails.
A good test for geometry code checks a number that you can compute by hand, for example an area:
test "shrink a square" {
var sq = try square(gpa, 10_000); // 10 mm x 10 mm
var r = try offset(gpa, sq, -1000, .{}); // in by 1 mm
try testing.expectApproxEqAbs(@as(f64, 64.0), r.areaMm2(), 1e-6); // 8 x 8
}
When you fix a bug, add a test that fails without the fix. Name the bug in a comment.
The corpus
tools/corpus.py slices each STL file in a folder (in a git repo, only the tracked files) and reports the failures, the time, and the peak memory:
zig build -Doptimize=ReleaseFast
python3 -I tools/corpus.py zig-out/bin/zslice ../printdeck report.tsv
Run it before you finish a change to the geometry or slicing code. Each file must slice with status ok.
Look at the output
A test can pass while the output is wrong. Look at the layers:
zslice preview part.stl --layer 20 -o layer20.svg
rsvg-convert -w 900 layer20.svg -o layer20.png # optional: a PNG
Check a bottom layer (all skin), a middle layer (walls and sparse infill), a layer just under a top surface (skin), and the top layer.
Add a setting
- Add a field with a default value to the correct struct in
src/settings.zig:Machine,Filament,Project, orEngineOptions. Choose the struct by the owner of the value (see The command line). - Add a
///doc comment that says what the setting does and its unit. - If the value has limits, check them in
Settings.resolve. - If code uses a derived value, compute it once in
resolveand add it toResolved. - Use the value in the stage.
- If the value can change per layer, read it from the settings of the layer, and add its name to
settings.layer_settings(see Settings for some layers). - Run
python3 -I tools/settings_doc.py > docs/user/settings.md.
Settings.set, the C API, the wasm API, and the command line get the new setting with no more code. They use comptime reflection on the struct. Supported field types: f64, u32 (and other integers), bool, enums, and []const u8.
Add a feature type
A feature is a kind of path, for example a wall, infill, or ironing. To add one (for example support):
- Add it to
Featureinsrc/settings.zig. - Add its speed ratio to
Projectand toResolved.speed. - Make its paths in
layer.plan, and add them withaddOrderedat the correct place in the print order. Ironing is a short example: see step 6 inlayer.zig. - Give it a
;TYPE:name ingcode.typeName. Use the CuraEngine name if one exists, so that G-code viewers know it. - Give it a color in
svg.color. - Add a test in
layer.zigthat checks the new paths.
The compiler finds each switch on Feature that does not handle the new value.
Add an infill pattern
- Add the pattern name to
InfillPatterninsrc/settings.zig, and describe it in the doc comment ofinfill_pattern. - Write the fill function in
src/infill.zig, or in a new file for a large pattern. Input: the region (closed polygons, material on the left), the spacing, and the layer index. Output: ageom.Pathsof open polylines. - Call it from the
switch (p.infill_pattern)inlayer.plan. - Add a test that fills a square and checks the total line length times the spacing against the area (see "diagonal lines cover the square").
- Look at a preview.
Rules for a pattern:
- The lines of one layer should be on top of the lines of the layer below, or cross them. Compute the lines from a fixed grid in bed coordinates, and not from the bounds of the region.
- The output must be the same on each run and on each thread. Do not use a random seed that changes.
Change the geometry code
clip.zig and offset.zig are the base of each stage. A bug there shows up as a missing wall or a filled hole in some layers of some parts.
- Keep the conventions in Architecture.
- Use the exact integer functions for each decision. Use floating point only to make a new point.
- Add a test with the shape that failed. Real failures often come from thin features and curves with many short edges.
- Run the corpus.
Commits
- One change for each commit.
- The subject says what changed, in under 72 characters.
- The body says why, if the reason is not clear from the subject.