diff --git a/src/Mod/CAM/Roadmap/Epics/ImprovePostprocessors.md b/src/Mod/CAM/Roadmap/Epics/ImprovePostprocessors.md new file mode 100644 index 0000000000..35de0368fc --- /dev/null +++ b/src/Mod/CAM/Roadmap/Epics/ImprovePostprocessors.md @@ -0,0 +1,136 @@ +# STATUS: + +Active + +# 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 + +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. +- The size and complexity of the postprocessor files makes them harder to understand. +- 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 + +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 +have already been "designed in" to the "refactored" code base. +- It is easier to test the "refactored" code base since most of the code has one copy +and can be tested just once for many "refactored" postprocessors. +- It is easier to add new functionality to all (or many) of the "refactored" +postprocessors by adding code just once to the shared code in the "refactored" code base. +- Many bugs can be fixed for many "refactored" postprocessors by making changes +just once to the shared code in the "refactored" code base. +- The "refactored" postprocessors can share a single list of "command line options" +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 + +## 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. + +Much refactoring of the "refactored" code base was done to identify shared code +and move the shared code to several shared files. +This "shrank" the sizes of the "refactored" postprocessor files a lot. + +Some refactoring of the "refactored" code base was done to make the code style, +variable names, and function/routine/class parameters more consistent. +The "legacy" code was written and/or adapted by multiple people, each with their +own way of doing things. The combination of code from multiple people was hard +to understand and maintain. + +Many tests were written. A "refactored_test" postprocessor was created which was +used to test the shared code base. Very few additional tests were needed to test +the individual "refactored" postprocessors since most of the tests and code were shared. + +Some of the shared code in the "refactored" code base was rewritten to an object +oriented style that allowed the "refactored" postprocessor files to get much smaller +and simpler by using inheritance. Eventually this (object oriented) code was added +to the "PostProcessor" class in the "Processor.py" file to integrate the "refactored" +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. + +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 +of particular interest such as A, B, and C axis handling and F parameter handling. +While there are still some tests that might need to be written, the test suite now +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 + +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 +having all of the code in a separate file for each postprocessor to having most code +being shared between the "refactored" postprocessors we lost a lot of customizability. +We need to get "enough" customizability back into the "refactored" code base. + +Much or all of the shared code in the "refactored" code base should be rewritten in +an object oriented style enough so that inheritance can be used to customize some +"refactored" postprocessors. This should be a "light" rewrite since we have working +code with existing tests to exercise it in many cases and we don't need to make it +"more object oriented than necessary" :-) + +It would be a good idea to look at the next few "most used" "legacy" postprocessors +and try to "port" them to the "refactored" code base one at a time. Odds are that we +will learn something from each "legacy" postprocessor that is "ported" and will modify +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. + +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. + +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 +base. Other "legacy" postprocessors may need the full flexibility of having all of +their code in one file with no other postprocessors depending on their code. + +Once we have working and tested (by the test suite and by people actually using +them) "refactored" postprocessors, do we still need to keep and maintain the "legacy" +versions of the same postprocessors? It would be nice to reduce the support burden, +but we don't want to remove/reduce the ability to create new or modified postprocessors. +This puts extra emphasis on having "enough" customizability in the "refactored" code +base to meet "all" of the postprocessor needs so we can afford to deprecate and +(eventually) remove "unnecessary" legacy postprocessors. + +# Related Epics