Update dev docs (#9383)

* chore: update how to build doc * chore: add how to validate profiles doc * remove old build info from readme.md * fix: typo * fix: typo * chore: minor fix * fix: typo * chore: minor fix * chore: minor fix * chore: remove lfs * fix: note 2 procedure for repair build * fix: update CMake installation instructions for macOS to specify version 3.31.x * fix: clarify CMake installation instructions for macOS and remove outdated commands * fix: enhance documentation for profile structure and templates in OrcaSlicer * fix: update profile validation documentation and remove obsolete guide * chore: update path for building on mac
2025-07-06 06:27:33 -06:00 · 2025-06-05 10:17:56 +02:00 · 2025-06-05 10:17:56 +02:00 · 3900042280
commit 3900042280
parent 9bf5cf0fb9
4 changed files with 373 additions and 56 deletions
--- a/README.md
+++ b/README.md
@ -89,43 +89,11 @@ Explore the latest developments in Orca Slicer with our nightly builds. Feedback
 **Linux (Ubuntu)**:
 1. If you run into trouble executing it, try this command in the terminal:  
    `chmod +x /path_to_appimage/OrcaSlicer_Linux.AppImage`
-    
-# How to compile
- Windows 64-bit  
-  - Tools needed: Visual Studio 2019, Cmake, git, git-lfs, Strawberry Perl.
-      - You will require cmake version 3.14 or later, which is available [on their website](https://cmake.org/download/).
-      - Strawberry Perl is [available on their GitHub repository](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases/).
-  - Run `build_release.bat` in `x64 Native Tools Command Prompt for VS 2019`
-  - Note: Don't forget to run `git lfs pull` after cloning the repository to download tools on Windows
+ 
+# How to Compile
+All updated build instructions for Windows, macOS, and Linux are now available on the official [OrcaSlicer Wiki - How to build](https://github.com/SoftFever/OrcaSlicer/wiki/How-to-build) page.

- Mac 64-bit  
-  - Tools needed: Xcode, Cmake, git, gettext, libtool, automake, autoconf, texinfo
-      - You can install most of them by running `brew install cmake gettext libtool automake autoconf texinfo`
-      - If you haven't since upgrading Xcode, start Xcode and install macOS build support.
-  - run `build_release_macos.sh`
-  - open `build_arm64/OrcaSlicer/OrcaSlicer.app`
-  - To build and debug in Xcode:
-      - run `Xcode.app`
-      - open ``build_`arch`/OrcaSlicer.Xcodeproj``
-      - menu bar: Product => Scheme => OrcaSlicer
-      - menu bar: Product => Scheme => Edit Scheme...
-          - Run => Info tab => Build Configuration: `RelWithDebInfo`
-          - Run => Options tab => Document Versions: uncheck `Allow debugging when browsing versions`
-      - menu bar: Product => Run
-
- Linux (All Distros)
-    - Docker
-        - Dependencies: Docker [Installation Instructions](https://www.docker.com/get-started/), git
-        - clone this repository `git clone https://github.com/SoftFever/OrcaSlicer`
-        - run `cd OrcaSlicer`
-        - run `./DockerBuild.sh`
-        - To run OrcaSlicer:
-            - run `./DockerRun.sh`
-                - For most common errors, open `DockerRun.sh` and read the comments.  
-    - Ubuntu 
-      - Dependencies **Will be auto installed with the shell script**: `libmspack-dev libgstreamerd-3-dev libsecret-1-dev libwebkit2gtk-4.0-dev libosmesa6-dev libssl-dev libcurl4-openssl-dev eglexternalplatform-dev libudev-dev libdbus-1-dev extra-cmake-modules libgtk2.0-dev libglew-dev libudev-dev libdbus-1-dev cmake git texinfo`
-      - run `sudo ./BuildLinux.sh -u`
-      - run `./BuildLinux.sh -dsi`
+Please refer to the wiki to ensure you're following the latest and most accurate steps for your platform.

 # Note: 
 If you're running Klipper, it's recommended to add the following configuration to your `printer.cfg` file.
--- a/doc/Home.md
+++ b/doc/Home.md
@ -37,4 +37,5 @@ The guide below takes you through the key calibration tests in Orca - flow rate,
 - [How to build Orca Slicer](./How-to-build)
 - [Localization and translation guide](Localization_guide)
 - [Developer Reference](https://github.com/SoftFever/OrcaSlicer/blob/main/doc/developer-reference/Home.md)
- [How to create profiles](./How-to-create-profiles)
+- [How to create profiles](./How-to-create-profiles)
+- [How to validate profiles](./How-to-validate-profiles)
--- a/doc/How-to-build.md
+++ b/doc/How-to-build.md
@ -1,11 +1,140 @@
-# How to compile
- Windows 64-bit  
-  - Tools needed: Visual Studio 2019, Cmake, git, Strawberry Perl.
-  - Run `build_release.bat` in `x64 Native Tools Command Prompt for VS 2019`
+# How to Compile

- Mac 64-bit  
-  - Tools needed: Xcode, Cmake, git, gettext
-  - run `build_release_macos.sh`
+## Windows 64-bit

- Ubuntu  
-  - run `BuildLinux.sh -udisr`
+### Tools Required
+- [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) or Visual Studio 2019  
+- [CMake (version 3.31)](https://cmake.org/) — **⚠️ version 3.31.x is mandatory**
+- [Strawberry Perl](https://strawberryperl.com/)
+- [Git](https://git-scm.com/)
+
+### Instructions
+1. Clone the repository:
+   ```sh
+   git clone https://github.com/SoftFever/OrcaSlicer
+   ```
+2. Open the appropriate command prompt:
+   - For Visual Studio 2019:  
+     Open **x64 Native Tools Command Prompt for VS 2019** and run:
+     ```sh
+     build_release.bat
+     ```
+   - For Visual Studio 2022:  
+     Open **x64 Native Tools Command Prompt for VS 2022** and run:
+     ```sh
+     build_release_vs2022.bat
+     ```
+
+**⚠️ Note 1:** Make sure that CMake version 3.31.x is actually being used. Run `cmake --version` and verify it returns a **3.31.x** version.
+If you see an older version (e.g. **3.29), it's likely due to another copy in your system's PATH (e.g. from Strawberry Perl).
+You can run where cmake to check the active paths and rearrange your System Environment Variables > PATH, ensuring the correct CMake (e.g. C:\Program Files\CMake\bin) appears before others like C:\Strawberry\c\bin.
+
+**⚠️ Note 2:** ⚠️ Note: If the build fails, try deleting the `build/` and `deps/build/` directories to clear any cached build data. Rebuilding after a clean-up is usually sufficient to resolve most issues. 
+
+## macOS 64-bit
+
+### Tools Required
+- Xcode
+- CMake (version 3.31.x is mandatory)
+- Git
+- gettext
+- libtool
+- automake
+- autoconf
+- texinfo
+
+You can install most dependencies via Homebrew:
+```sh
+brew install git gettext libtool automake autoconf texinfo
+```
+
+Homebrew currently only offers the latest version of CMake (e.g. **4.x**), which is not compatible. To install the required version **3.31.x**, follow these steps:
+
+1. Download CMake **3.31.7** from: [https://cmake.org/download/](https://cmake.org/download/)
+2. Install the application (drag it to `/Applications`).
+3. Add the following line to your shell configuration file (`~/.zshrc` or `~/.bash_profile`):
+```sh
+export PATH="/Applications/CMake.app/Contents/bin:$PATH"
+```
+4. Restart the terminal and check the version:
+```sh
+cmake --version
+```
+5. Make sure it reports a **3.31.x** version.
+
+
+**⚠️ Note 1:** If you've recently upgraded Xcode, be sure to open Xcode at least once and install the required macOS build support.
+
+### Instructions
+1. Clone the repository:
+   ```sh
+   git clone https://github.com/SoftFever/OrcaSlicer
+   cd OrcaSlicer
+   ```
+2. Build the application:
+   ```sh
+   ./build_release_macos.sh
+   ```
+3. Open the application:
+   ```sh
+   open build/arm64/OrcaSlicer/OrcaSlicer.app  
+   ```
+
+### Debugging in Xcode
+To build and debug directly in Xcode:
+
+1. Open the Xcode project:
+   ```sh
+   open build/arm64/OrcaSlicer.xcodeproj
+   ```
+2. In the menu bar:
+   - **Product > Scheme > OrcaSlicer**
+   - **Product > Scheme > Edit Scheme...**
+     - Under **Run > Info**, set **Build Configuration** to `RelWithDebInfo`
+     - Under **Run > Options**, uncheck **Allow debugging when browsing versions**
+   - **Product > Run**
+
+## Linux
+
+### Using Docker (Recommended)
+
+#### Dependencies
+- Docker
+- Git
+
+#### Instructions
+```sh
+git clone https://github.com/SoftFever/OrcaSlicer
+cd OrcaSlicer
+./DockerBuild.sh
+./DockerRun.sh
+```
+
+To troubleshoot common Docker-related errors, refer to the comments in `DockerRun.sh`.
+
+## Ubuntu
+
+### Dependencies
+All required dependencies will be installed automatically by the provided shell script, including:
+- libmspack-dev
+- libgstreamerd-3-dev
+- libsecret-1-dev
+- libwebkit2gtk-4.0-dev
+- libosmesa6-dev
+- libssl-dev
+- libcurl4-openssl-dev
+- eglexternalplatform-dev
+- libudev-dev
+- libdbus-1-dev
+- extra-cmake-modules
+- libgtk2.0-dev
+- libglew-dev
+- cmake
+- git
+- texinfo
+
+### Instructions
+```sh
+sudo ./BuildLinux.sh -u      # Install dependencies
+./BuildLinux.sh -dsi         # Build OrcaSlicer
+```
--- a/doc/How-to-create-profiles.md
+++ b/doc/How-to-create-profiles.md
@ -29,8 +29,10 @@ Naming conventions:
 4. Filament profile: `filament_vendor_name` + `filament_name` + " @" + `vendor_name` + `printer_name`/`printer_variant_name` + `.json`
 5. Process profile: `layer_height` + `preset_name` + " @" + `vendor_name` + `printer_name`/`printer_variant_name` + `.json` (`preset_name` typically includes "standard," "fine," "fast," "draft," etc.)

+## File Structure and Templates
+
+Profiles should be structured in the following way under the OrcaSlicer installation directory:

-A typical file structure for a vendor:
 ```
 resources\profiles\
    - Orca 3D.json
@ -46,9 +48,17 @@ resources\profiles\
            - Generic PLA @Orca 3D Fuse1@.json
 ```

+**⚠️ NOTE 1**: Use short vendor names in filenames to avoid excessive length.

-**NOTE 1**: Use short vendor names in filenames to avoid excessive length.
-**NOTE 2**: Filament profiles are **optional**. Create them only if the vendor has specifically tuned profiles for the given printer. See [Filament profiles](#filament-profiles) for details.
+**⚠️ NOTE 2**: Filament profiles are **optional**. Create them only if the vendor has specifically tuned profiles for the given printer. See [Filament profiles](#filament-profiles) for details.
+
+Template files for profiles are available in:
+
+```
+OrcaSlicer\resources\profiles_template\Template
+```
+
+These templates can be used as a starting point for new printer, filament, and process profiles.

 ## Filament Profiles
 OrcaSlicer features a global filament library called `OrcaFilamentLibrary`, which is automatically available for all printers. It includes generic filaments like `Generic PLA @System` and `Generic ABS @System` etc.
@ -107,9 +117,9 @@ The following sample JSON file shows how to create a new generic filament profil
 }
 ```

-3. The last step is to validate the newly added filament profiles. You can run OrcaSlicer to verify if the filament you just added is available and usable. You can also use the [Orca profile validator](https://github.com/SoftFever/Orca_tools/releases/tag/1) tool to help debug any errors. **NOTE**: You need to delete the `%appdata%/OrcaSlicer/system` folder to force OrcaSlicer to reload your lastest changes.
+3. The last step is to validate the newly added filament profiles. 

-The process is the same if you want to add a new brand filament profile into the global library. You need to create a new file in the `resources\profiles\OrcaFilamentLibrary\filament\brand_name` folder. The only difference is that you should put the file into the brand's own subfolder.`resources\profiles\OrcaFilamentLibrary\filament\brand_name`.
+**⚠️ NOTE 1**: If the filament is compatible with AMS, ensure that the `filament_id` value **does not exceed 8 characters** to maintain AMS compatibility.

 ### Adding Filament Profiles to Printer Vendor Library
 In this section, we will discuss how to add a new filament profile for a certain vendor.
@ -170,11 +180,220 @@ Please note that here we must leave the compatible_printers field non-empty, unl
 }
 ```

-## Process Profiles
-WIP...
+**⚠️ NOTE 1**: If the filament is compatible with AMS, ensure that the `filament_id` value **does not exceed 8 characters** to maintain AMS compatibility.

-## Printer Profiles
-WIP...
+## Process Profiles
+
+Process profiles define print quality and behavior. They follow a structure similar to filament profiles:
+
+* A common base file, e.g., `fdm_process_common.json`, acts as the parent.
+* Vendor-specific process profiles should inherit from the base using the `inherits` field.
+* Profiles are stored under:
+
+```
+resources\profiles\vendor_name\process\
+```
+
+* **There are no global process profiles**.
+* Each process profile includes a `"compatible_printers"` field with an array of compatible printer variant names.
+
+Example:
+
+```json
+{
+  "type": "process",
+  "name": "0.10mm Standard @ExampleVendor Printer 0.2",
+  "inherits": "fdm_process_common",
+  "from": "system",
+  "instantiation": "true",
+  "compatible_printers": [
+    "ExampleVendor Printer 0.2 nozzle"
+  ]
+}
+```
+
+## Printer Model Profiles
+
+* Printer model profiles (type `machine_model`) describe the general printer information.
+* Example fields: `nozzle_diameter`, `bed_model`, `bed_texture`, `model_id`, etc.
+* Stored in:
+
+```
+resources\profiles\vendor_name\machine\
+```
+
+* Each vendor's folder may contain an image named:
+
+```
+[machine_model_list.name]_cover.png
+```
+
+This image will be used in the UI.
+
+Example model profile:
+
+```json
+{
+  "type": "machine_model",
+  "name": "Example M5",
+  "nozzle_diameter": "0.2;0.25;0.4;0.6",
+  "bed_model": "M5-Example-bed.stl",
+  "bed_texture": "M5-Example-texture.svg",
+  "model_id": "V1234",
+  "family": "Example",
+  "machine_tech": "FFF",
+  "default_materials": "Example Generic PLA;Example Generic PETG"
+}
+```

 ## Printer Variant Profiles
-WIP...
+
+* Printer variants (type `machine`) define specific nozzle configurations and mechanical details.
+* Each variant must inherit from a common base like `fdm_machine_common.json`.
+* Must list the compatible nozzle diameter in the `nozzle_diameter` array.
+* Example fields include `printer_model`, `printer_variant`, `default_print_profile`, `printable_area`, etc.
+
+Example variant profile:
+
+```json
+{
+  "type": "machine",
+  "name": "Example M5 0.2 nozzle",
+  "inherits": "fdm_machine_common",
+  "from": "system",
+  "setting_id": "GM001",
+  "instantiation": "true",
+  "nozzle_diameter": ["0.2"],
+  "printer_model": "Example M5",
+  "printer_variant": "0.2",
+  "default_filament_profile": ["Example Generic PLA"],
+  "default_print_profile": "0.10mm Standard 0.2mm nozzle @Example",
+  "printable_area": ["0x0", "235x0", "235x235", "0x235"],
+  "nozzle_type": "brass"
+}
+```
+
+## Models
+
+* The `model` directory under the vendor folder is intended to behave similarly to `machine` profiles.
+* Used for additional printer-related 3D models or definitions, stored at:
+
+```
+resources\profiles\vendor_name\model\
+```
+
+## Vendor Meta File
+
+Each vendor must include a JSON file in the `resources\profiles` directory, named `vendor_name.json`. This file lists all available models, variants, processes, and filaments:
+
+Example:
+
+```json
+{
+  "name": "ExampleVendor",
+  "version": "01.00.00.00",
+  "force_update": "1",
+  "description": "Example configuration",
+  "machine_model_list": [
+    {
+      "name": "Example M5",
+      "sub_path": "machine/Example M5.json"
+    }
+  ],
+  "machine_list": [
+    {
+      "name": "fdm_machine_common",
+      "sub_path": "machine/fdm_machine_common.json"
+    }
+  ],
+  "process_list": [
+    {
+      "name": "fdm_process_common",
+      "sub_path": "process/fdm_process_common.json"
+    }
+  ],
+  "filament_list": [
+    {
+      "name": "fdm_filament_common",
+      "sub_path": "filament/fdm_filament_common.json"
+    }
+  ]
+}
+```
+
+## Validate Profiles
+
+You can validate your profiles using both the **OrcaSlicer profile validator** and the **Python validation script**. These tools are designed to check different aspects of the profiles, so both should be executed and pass without errors to ensure full compatibility.
+
+**✅ Recommendation**: Always run **both** the OrcaSlicer validator and the Python script to ensure all aspects of the profiles are valid.
+
+### 1. OrcaSlicer Profile Validator
+
+You can run OrcaSlicer to verify if the filament you just added is available and usable. You can also use the [Orca profile validator](https://github.com/SoftFever/Orca_tools/releases/tag/1) tool to help debug any errors.
+
+**⚠️ NOTE 1**: You need to delete the `%appdata%/OrcaSlicer/system` folder to force OrcaSlicer to reload your latest changes.
+
+The process is the same if you want to add a new brand filament profile into the global library. You need to create a new file in the `resources\profiles\OrcaFilamentLibrary\filament\brand_name` folder. The only difference is that you should put the file into the brand's own subfolder.
+
+#### Usage
+
+```
+-h [ --help ] help
+-p [ --path ] arg profile folder
+-v [ --vendor ] arg Vendor name. Optional, all profiles present in the folder will be validated if not specified
+-l [ --log_level ] arg (=2) Log level. Optional, default is 2 (warning). Higher values produce more detailed logs.
+```
+
+#### Example
+
+```
+./OrcaSlicer_profile_validator -p ~/codes/OrcaSlicer/resources/profiles -l 2 -v Custom
+```
+
+#### Sample result with errors
+
+```
+PS D:\codes\OrcaSlicer> ."D:/codes/OrcaSlicer/build/src/Release/OrcaSlicer_profile_validator.exe" --path d:\codes\OrcaSlicer\resources\profiles -l 2 -v Custom
+[2024-02-28 21:23:06.102138] [0x0000a4e8] [error]   Slic3r::ConfigBase::load_from_json: parse d:\codes\OrcaSlicer\resources\profiles/Custom/machine/fdm_klipper_common.json got a nlohmann::detail::parse_error, reason = [json.exception.parse_error.101] parse error at line 9, column 38: syntax error while parsing object - unexpected string literal; expected '}'
+...
+Validation failed
+```
+
+#### Sample result with success
+
+```
+PS D:\codes\OrcaSlicer\build\src\RelWithDebInfo> ."D:/codes/OrcaSlicer/build/src/Release/OrcaSlicer_profile_validator.exe" --path d:\codes\OrcaSlicer\resources\profiles -l 2 -v Custom
+Validation completed successfully
+```
+
+**⚠️ NOTE 2**: Use `OrcaSlicer_profile_validator` on Ubuntu and `OrcaSlicer_profile_validator.exe` on Windows.
+
+---
+
+### 2. Python Profile Validation Script
+
+In addition to the Orca validator, you should run the `orca_extra_profile_check.py` script. This script performs additional checks like:
+
+- Validation of `compatible_printers` in filament profiles
+- Consistency of filament names
+- Validation of default materials in machine profiles (optional)
+
+#### Example command
+
+```bash
+python ./orca_extra_profile_check.py
+```
+
+You can also enable or disable specific checks:
+
+- `--vendor` (optional): checks only the specified vendor. If omitted, all vendors are checked.
+- `--check-filaments` (enabled by default): checks `compatible_printers` fields in filament profiles
+- `--check-materials`: checks default material names in machine profiles
+
+#### Sample usage with all checks enabled
+
+```bash
+python ./orca_extra_profile_check.py --vendor="vendor_name" --check-filaments --check-materials
+```
+
+The script will output the number of errors found and exit with a non-zero status code if any issues are detected.