From fd2e4b1397c1a8bfa19e5edbb83d5b8b5c5faab7 Mon Sep 17 00:00:00 2001 From: Lawrence Woestman Date: Sun, 19 Oct 2025 16:24:41 -0700 Subject: [PATCH] CAM: Incorporated the first round of feedback --- .../Roadmap/Epics/ImprovePostprocessors.md | 62 ++++++++++++++----- 1 file changed, 48 insertions(+), 14 deletions(-) diff --git a/src/Mod/CAM/Roadmap/Epics/ImprovePostprocessors.md b/src/Mod/CAM/Roadmap/Epics/ImprovePostprocessors.md index 35de0368fc..4fa1f2dfaf 100644 --- a/src/Mod/CAM/Roadmap/Epics/ImprovePostprocessors.md +++ b/src/Mod/CAM/Roadmap/Epics/ImprovePostprocessors.md @@ -1,23 +1,27 @@ -# STATUS: +# Improve Postprocessors + +## STATUS Active -# Why it is a priority +## Why it is a priority Prior to 2022 it became clear that the existing postprocessors were hard to maintain and develop. An effort started in 2022 to develop a different approach to postprocessors to share as much code as possible. -## Legacy postprocessors +### Legacy postprocessors The older postprocessors (hereafter referred to as "legacy" postprocessors) were written with all of the code in a single file. This has the following advantages: + - You can make changes to a single postprocessor without affecting anything else. - You can copy and modify a single file to create a new postprocessor. This has the following disadvantages: + - There is a lot of duplicate code in the postprocessors which makes it hard to fix bugs or add new capabilities because changes must be made in many places. - It is hard to test the postprocessors without also duplicating many tests. @@ -25,12 +29,13 @@ to fix bugs or add new capabilities because changes must be made in many places. - The size and complexity of the postprocessor files makes it harder to figure out the differences between the postprocessors (what makes them unique). -## Refactored postprocessors +### Refactored postprocessors A different approach to postprocessors was started that shared as much code as possible (hereafter referred to as "refactored" postprocessors and the "refactored" code base). The "refactored" postprocessors have the following advantages: + - The "refactored" postprocessor files are smaller and easier to understand. - It is easier to figure out the differences between the "refactored" postprocessors. - It is easier to customize a "refactored" postprocessor as long as the desired changes @@ -46,14 +51,15 @@ which are used to change the behavior of the postprocessor rather than each postprocessor having its own (somewhat unique) list of command line options. The "refactored" postprocessors have the following disadvantages: + - To customize/modify a "refactored" postprocessor often requires making changes to the "shared" code in the "refactored" code base which affects all of the "refactored" postprocessors. The "refactored" code base must be modified to support making the needed changes without affecting the other "refactored" postprocessors. -# Scope +## Scope -## What has been done so far +### What has been done so far In 2022 the existing versions of the "centroid", "grbl", "linuxcnc" and "mach3_mach4" "legacy" postprocessors were copied and "merged" into the "starting" "refactored" code base. @@ -80,7 +86,7 @@ postprocessor code base into the rest of the CAM software. The "Masso" postprocessor was developed based on the "refactored" code base. As the refactoring continued the "Masso" postprocessor file became much simpler, inheriting -from the "refactored linuxcnc" postprocessor with one option set differently. +from the "refactored_linuxcnc" postprocessor with one option set differently. As of the time that this document was last modified, there are tests for many of the possible "G" and "M" g-code commands, many of the command line options, and tests for other areas @@ -91,7 +97,9 @@ covers a large part of the functionality. As of the time that this document was last modified, there are "refactored" postprocessors for "centroid", "grbl", "linuxcnc", "mach3_mach4", and "masso" controllers. -## What still needs to be done +### What still needs to be done + +#### Customizability The main pain point left is the ability to create new or modified "refactored" postprocessors without having to copy and modify lots of code. When we went from @@ -113,12 +121,9 @@ the "refactored" code base to improve its customizability as a result. It would be a good idea to look at porting or developing postprocessors that support laser cutters, drag knife cutters, and controllers that use something other than g-code as their control language (at least). Odds are that we would learn something from each -attempt and the "refactored" code base would improve it customizability as a result. +attempt and the "refactored" code base would improve its customizability as a result. -There will be bug fixes, tests, and new features that will need to be added -to the "refactored" code base. It is likely that the "rules will change" about what -the rest of the FreeCAD code will send to the postprocessors and/or the format of the -input to the postprocessors will change. +#### What about "legacy" postprocessors? We probably want to keep the ability to use "legacy" style postprocessors for a long time to come. Some "legacy" postprocessors may not be "ported" to the "refactored" code @@ -133,4 +138,33 @@ This puts extra emphasis on having "enough" customizability in the "refactored" base to meet "all" of the postprocessor needs so we can afford to deprecate and (eventually) remove "unnecessary" legacy postprocessors. -# Related Epics +#### Documentation + +We will need documentation about and working examples of "how to write a custom postprocessor" +based on the "refactored" code base. For example, a class hierarchy that shows what +methods are implemented where and which methods are able to be (or recommended to be) +overridden by child classes. In addition to the existing "refactored" postprocessors +"ported" versions of some of the other "legacy" postprocessors would be good examples +of "how to write a custom postprocessor". + +#### Testing + +We will need to end up with a testing framework for the "refactored" postprocessors that is: + + 1. Efficient + 1. Doesn't require loading files from the disk + 2. Atomic so we're only testing things once + 2. Documented well enough that new postprocessor authors can easily understand how to + add tests + 3. Extensible so new postprocessor authors can easily add tests + 4. Complete enough so that we can start recommending the "refactored" postprocessors + and deprecating the legacy postprocessors that also have a "refactored" version + +#### Other changes + +There will be bug fixes, new tests, and new features that will need to be added +to the "refactored" code base. It is likely that the "rules will change" about what +the rest of the FreeCAD code will send to the postprocessors and/or the format of the +input to the postprocessors will change. + +## Related Epics