Background
Klipper’s main-line code is published on GitHub. Upon start, Klipper checks if the locally installed code is the same as the code published in this official repository. If not, the code is marked as dirty, and a respective notification is placed in the klippy.log.
This warning can look like:
Git version: 'v0.12.0-439-g1fc6d214-dirty'
Untracked files: klippy/extras/autotune_tmc.py, klippy/extras/gcode_shell_command.py, klippy/extras/motor_constants.py
Modified files: klippy/chelper/serialqueue.c
Branch: master
Remote: origin
Tracked URL: https://github.com/Klipper3d/klipper
In Untracked files:, the files listed do not belong to the original repository, while Modified files: lists those files that belong to the repository but have been modified compared to their “original” counterparts.
If one builds and flashes a firmware from such a dirty repository, this status propagates to the firmware as well. In the log, it then looks like:
Loaded MCU 'MAG_TOOL' 121 commands (v0.12.0-447-g3c0d5600-dirty-20241217_104029-magnetox / gcc: (15:13.2.rel1-2) 13.2.1 20231009 binutils: (2.42-1ubuntu1+23) 2.42)
Additionally, the web interfaces show this notification in various places, for example:
Rationale for the Warning and the Klipper Team’s Position
Naturally, such modifications carry the risk of introducing issues or unwanted behavior. This is something that the main-line Klipper team typically does not follow up on for the reasons outlined below.
Currently, there is no “official” way to modify Klipper, for example, through a plug-in system. This means all modifications, whether direct or by adding/linking ‘extra’ modules, are essentially uncontrolled and may significantly alter Klipper’s default behavior - whether for the better or worse.
The Klipper software is maintained by a group of core developers and supported by forum and chat volunteers who donate their time and expertise. These individuals work on tasks they are passionate about and help where they feel they can. However, time and development capacities are very scarce and precious resources.
This is especially true in a non-profit, free-of-charge open-source initiative like Klipper, where all development, documentation, and support activities are carried out voluntarily.
This is why the core developers and forum volunteers cannot assume “responsibility” for issues arising from third-party modifications.
Hunting bugs in modified code is a tedious and time-consuming activity, often requiring the recreation of specific hardware and software environments.
Doing this for countless modifications and scenarios would divert all available resources, leaving no room for original improvements or support for the main-line product.
Support Implications
When users report issues, the contributors may request that the issue be reproduced in a pristine Klipper installation without any modifications. This helps ensure that the problem is related to the main-line code and not a third-party modification. If the issue stems from a modification, users may be directed to:
- Revert to the authors of the modification for further help or analysis.
- Contact the OEM of the printer if the modifications are part of the manufacturer’s design. More on this topic here.
Update Implications
Another very important aspect is that Klipper’s internal methods are not guaranteed to remain stable. As a result, Klipper’s internal functions may change with each update. This can easily lead to a non-functional system (errors at startup) or some hard-to-diagnose unexpected behavior after an update.
The main-line development has no control over this, so the authors of modifications are fully responsible for keeping their changes in line with Klipper’s current development.
Klipper’s Sensitivity to Modifications
Every software can be brought to its knees with one single wrong or misplaced line of code, but in Klipper’s case, this danger is particularly high due to its unique requirements and features:
- Strict timing across all printing-related activities
- Upholding this timing across multiple independent but connected MCUs over multiple different protocols, for example, serial connection, USB, and CAN
- Supporting a vast number of different hardware components, from MCUs to various ADC chips, IMUs, load cells, etc. Each of these components brings its own unique requirements and challenges.
- Countless “hot areas” in the code that are meticulously optimized for best performance, with optimizations going down to the assembly level to ensure that even the machine language conforms to the requirements after a compiler or interpreter has processed it.
These high-level topics boil down to a vast number of single “dos and don’ts.” As a consequence, modifying Klipper’s code requires:
- A high understanding of the current code and its concurrent requirements
- A solid understanding of what compilers and interpreters might do to the code
- Due diligence to ensure that all this is understood and adhered to in the modification. As such, a single modification is often much more involved and complex than would be expected by just looking at the feature itself.
Failing to do so can easily result in subtle and hard-to-diagnose issues, or the dreaded “Timer too close” errors. There is quite a history of ‘extras’ known to cause this.
Summary
Klipper is an open-source product, and everyone is allowed - even encouraged - to modify the sources, add functionality, or alter its behavior. This is highly appreciated by the team members, as it contributes to the overall growth and usefulness of the software.
However, it’s important to understand the following:
- The core developers endeavor to develop a properly quality-tested main-line product and fix bugs within its original, unmodified scope.
- Demonstrating that an issue or unwanted behavior exists in Klipper’s main-line code may significantly increase the chance that the core contributors will address it and invest their time.
- Each modification must follow the GPL v3 license principles. More on this here.
- Third-party contributors who modify Klipper are responsible for ensuring their changes respect the original code’s requirements or improve it in a compliant manner.
- If issues arise from a modification, the responsibility for addressing them lies with the modifying party.
It’s also crucial to recognize that:
- The team is not against modifications. On the contrary, we value community contributions and encourage discussions about modifications in the respective channels.
- The core developers strive to improve the code’s resilience where possible, even in combination with third-party modifications that may not have exercised the required diligence.
- Clear expectations are set: Modifying parties must take responsibility for their changes and any resulting issues.