mirror of https://github.com/SoftFever/OrcaSlicer.git synced 2025-12-25 17:18:49 -07:00

* re-enable tests

* Add comprehensive testing guide for OrcaSlicer in CLAUDE.md

* fix build errors on Win

* fix appimage errors

2025-08-24 20:58:18 +08:00

9.8 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

OrcaSlicer is an open-source 3D slicer application forked from Bambu Studio, built using C++ with wxWidgets for the GUI and CMake as the build system. The project uses a modular architecture with separate libraries for core slicing functionality, GUI components, and platform-specific code.

Build Commands

Building on Windows

# Build everything
build_release_vs2022.bat

# Build with debug symbols
build_release_vs2022.bat debug

# Build only dependencies
build_release_vs2022.bat deps

# Build only slicer (after deps are built)
build_release_vs2022.bat slicer

Building on macOS

# Build everything (dependencies and slicer)
./build_release_macos.sh

# Build only dependencies
./build_release_macos.sh -d

# Build only slicer (after deps are built)
./build_release_macos.sh -s

# Use Ninja generator for faster builds
./build_release_macos.sh -x

# Build for specific architecture
./build_release_macos.sh -a arm64    # or x86_64 or universal

# Build for specific macOS version target
./build_release_macos.sh -t 11.3

Building on Linux

# First time setup - install system dependencies
./build_linux.sh -u

# Build dependencies and slicer
./build_linux.sh -dsi

# Build everything (alternative)
./build_linux.sh -dsi

# Individual options:
./build_linux.sh -d    # dependencies only
./build_linux.sh -s    # slicer only  
./build_linux.sh -i    # build AppImage

# Performance and debug options:
./build_linux.sh -j N  # limit to N cores
./build_linux.sh -1    # single core build
./build_linux.sh -b    # debug build
./build_linux.sh -c    # clean build
./build_linux.sh -r    # skip RAM/disk checks
./build_linux.sh -l    # use Clang instead of GCC

Build System

Uses CMake with minimum version 3.13 (maximum 3.31.x on Windows)
Primary build directory: build/
Dependencies are built in deps/build/
The build process is split into dependency building and main application building
Windows builds use Visual Studio generators
macOS builds use Xcode by default, Ninja with -x flag
Linux builds use Ninja generator

Testing

Tests are located in the tests/ directory and use the Catch2 testing framework. Test structure:

tests/libslic3r/ - Core library tests (21 test files)
- Geometry processing, algorithms, file formats (STL, 3MF, AMF)
- Polygon operations, clipper utilities, Voronoi diagrams
tests/fff_print/ - Fused Filament Fabrication tests (12 test files)
- Slicing algorithms, G-code generation, print mechanics
- Fill patterns, extrusion, support material
tests/sla_print/ - Stereolithography tests (4 test files)
- SLA-specific printing algorithms, support generation
tests/libnest2d/ - 2D nesting algorithm tests
tests/slic3rutils/ - Utility function tests
tests/sandboxes/ - Experimental/sandbox test code

Run all tests after building:

cd build && ctest

Run tests with verbose output:

cd build && ctest --output-on-failure

Run individual test suites:

# From build directory
./tests/libslic3r/libslic3r_tests
./tests/fff_print/fff_print_tests
./tests/sla_print/sla_print_tests

Architecture

Core Libraries

libslic3r/: Core slicing engine and algorithms (platform-independent)
- Main slicing logic, geometry processing, G-code generation
- Key classes: Print, PrintObject, Layer, GCode, Config
- Modular design with specialized subdirectories:
  - GCode/ - G-code generation, cooling, pressure equalization, thumbnails
  - Fill/ - Infill pattern implementations (gyroid, honeycomb, lightning, etc.)
  - Support/ - Tree supports and traditional support generation
  - Geometry/ - Advanced geometry operations, Voronoi diagrams, medial axis
  - Format/ - File I/O for 3MF, AMF, STL, OBJ, STEP formats
  - SLA/ - SLA-specific print processing and support generation
  - Arachne/ - Advanced wall generation using skeletal trapezoidation
src/slic3r/: Main application framework and GUI
- GUI application built with wxWidgets
- Integration between libslic3r core and user interface
- Located in src/slic3r/GUI/ (not shown in this directory but exists)

Key Algorithmic Components

Arachne Wall Generation: Variable-width perimeter generation using skeletal trapezoidation
Tree Supports: Organic support generation algorithm
Lightning Infill: Sparse infill optimization for internal structures
Adaptive Slicing: Variable layer height based on geometry
Multi-material: Multi-extruder and soluble support processing
G-code Post-processing: Cooling, fan control, pressure advance, conflict checking

File Format Support

3MF/BBS_3MF: Native format with extensions for multi-material and metadata
STL: Standard tessellation language for 3D models
AMF: Additive Manufacturing Format with color/material support
OBJ: Wavefront OBJ with material definitions
STEP: CAD format support for precise geometry
G-code: Output format with extensive post-processing capabilities

External Dependencies

Clipper2: Advanced 2D polygon clipping and offsetting
libigl: Computational geometry library for mesh operations
TBB: Intel Threading Building Blocks for parallelization
wxWidgets: Cross-platform GUI framework
OpenGL: 3D graphics rendering and visualization
CGAL: Computational Geometry Algorithms Library (selective use)
OpenVDB: Volumetric data structures for advanced operations
Eigen: Linear algebra library for mathematical operations

File Organization

Resources and Configuration

resources/profiles/ - Printer and material profiles organized by manufacturer
resources/printers/ - Printer-specific configurations and G-code templates
resources/images/ - UI icons, logos, calibration images
resources/calib/ - Calibration test patterns and data
resources/handy_models/ - Built-in test models (benchy, calibration cubes)

Internationalization and Localization

localization/i18n/ - Source translation files (.pot, .po)
resources/i18n/ - Runtime language resources
Translation managed via scripts/run_gettext.sh / scripts/run_gettext.bat

Platform-Specific Code

src/libslic3r/Platform.cpp - Platform abstractions and utilities
src/libslic3r/MacUtils.mm - macOS-specific utilities (Objective-C++)
Windows-specific build scripts and configurations
Linux distribution support scripts in scripts/linux.d/

Build and Development Tools

cmake/modules/ - Custom CMake find modules and utilities
scripts/ - Python utilities for profile generation and validation
tools/ - Windows build tools (gettext utilities)
deps/ - External dependency build configurations

Development Workflow

Code Style and Standards

C++17 standard with selective C++20 features
Naming conventions: PascalCase for classes, snake_case for functions/variables
Header guards: Use #pragma once
Memory management: Prefer smart pointers, RAII patterns
Thread safety: Use TBB for parallelization, be mindful of shared state

Common Development Tasks

Adding New Print Settings

Define setting in PrintConfig.cpp with proper bounds and defaults
Add UI controls in appropriate GUI components
Update serialization in config save/load
Add tooltips and help text for user guidance
Test with different printer profiles

Modifying Slicing Algorithms

Core algorithms live in libslic3r/ subdirectories
Performance-critical code should be profiled and optimized
Consider multi-threading implications (TBB integration)
Validate changes don't break existing profiles
Add regression tests where appropriate

GUI Development

GUI code resides in src/slic3r/GUI/ (not visible in current tree)
Use existing wxWidgets patterns and custom controls
Support both light and dark themes
Consider DPI scaling on high-resolution displays
Maintain cross-platform compatibility

Adding Printer Support

Create JSON profile in resources/profiles/[manufacturer].json
Add printer-specific start/end G-code templates
Configure build volume, capabilities, and material compatibility
Test thoroughly with actual hardware when possible
Follow existing profile structure and naming conventions

Dependencies and Build System

CMake-based with separate dependency building phase
Dependencies built once in deps/build/, then linked to main application
Cross-platform considerations important for all changes
Resource files embedded at build time, platform-specific handling

Performance Considerations

Slicing algorithms are CPU-intensive, profile before optimizing
Memory usage can be substantial with complex models
Multi-threading extensively used via TBB
File I/O optimized for large 3MF files with embedded textures
Real-time preview requires efficient mesh processing

Important Development Notes

Use search tools extensively - codebase has 500k+ lines
Key entry points: src/OrcaSlicer.cpp for application startup
Core slicing: libslic3r/Print.cpp orchestrates the slicing pipeline
Configuration: PrintConfig.cpp defines all print/printer/material settings

Compatibility and Stability

Backward compatibility maintained for project files and profiles
Cross-platform support essential (Windows/macOS/Linux)
File format changes require careful version handling
Profile migrations needed when settings change significantly

Quality and Testing

Regression testing important due to algorithm complexity
Performance benchmarks help catch performance regressions
Memory leak detection important for long-running GUI application
Cross-platform testing required before releases

9.8 KiB Raw Blame History