A repository of peer-reviewed FreeCAD macros.
This repository hosts FreeCAD macros that volunteers have vetted and added for use to the whole community in general available through the FreeCAD Addon Manager.
- The best way to submit a macro is to post it to the FreeCAD Python Scripting and Macros subforum for review. After a green light is given then:
- Fork this repository
- Clone your fork locally
git clone https://github.com/your-gh-username/FreeCAD-macros - Go to the newly-created local repository
cd FreeCAD-macros - Setup the upstream
git remote add upstream https://github.com/FreeCAD/FreeCAD-macros - Create a branch to work in
git checkout -b your_branch - Follow our guidelines below on how to add a macro
- When you're ready to push your changes:
git push -u origin your_branch - Create a PR (pull request) against upstream
- Achieve global fame once PR is merged
To include a macro into the macro listing of FreeCAD's Addon Manager you have three mutually-exclusive options:
- Submit the macro and its auxiliary files to this repo, this is what is described here.
Do not include a
package.xmlfile, this is for macros or workbenches in repositories other that this one. You must list your auxiliary files in the__Files__global at the top of your macro so that the Addon Manager can install them together with your macro. - Add your macro to the FreeCAD wiki.
- Host the macro in your own git repo, with a
package.xmlfile.
Please add a complete description how to use the macro near the top of your macro as normal Python comments. Ideally write a Wiki page explaining what your macro does and how to use it by following the instructions on the Wiki. It's a good habit to write a changelog, especially when bringing API breaking changes, from latest to oldest.
Please follow the CamelCase.FCMacro convention for the macro name (other associated files except the macro icon don't need to follow this convention).
Please do not start your macro name with Macro or FC or similar (we already know it's a macro for FreeCAD).
Use one of the predefined categories (directories) for your macro, or create a new one if needed.
Also, if possible, start the macro name with the type of object it's working on, e.g. use ViewRotation instead of RotateView, so that all macros related to View will be together when sorting alphabetically.
You can use __Name__ to set a nice name for your macro, which will be used by the Addon Manager.
Please add the following metadata in your macro after the Macro description (mentioned above).
__Name__ = ''
__Comment__ = ''
__Author__ = ''
__Date__ = ''
__Version__ = ''
__License__ = ''
__Web__ = ''
__Wiki__ = ''
__Icon__ = ''
__Xpm__ = ''
__Help__ = ''
__Status__ = ''
__Requires__ = ''
__Communication__ = ''
__Files__ = ''NOTE: All metadata elements are simple strings, and may not contain code to evaluate. The FreeCAD Addon Manager parses these strings by searching for an equals sign followed by something inside quotes (single or double), all on a single line. Lines may not wrap. For example:
# Good, valid
__Comment__ = "When run, this macro reads your mind and creates the thing your are imagining."
# Bad, contains code:
__Author__ = ",".join(author_list)
# Bad, not a single string:
__Comment__ = "Some descriptive text" + " and more text"
# Bad, multiple lines:
__Files__ = "MyFirstFile.FCMacro \
MySecondFile.FCMacro"
# EXCEPTION: __Version__ may be set to __Date__ as long as __Date is defined first
__Date__ = 2022.05.19
__Version__ = __Date__
# EXCEPTION: XPM data must be a triple-quoted multi-line string
__Xpm__ = """
/* XPM */
static char * XFACE[] = {
"48 4 2 1",
"a c #ffffff",
"b c #000000",
"abaabaababaaabaabababaabaabaababaabaaababaabaaab",
"abaabaababaaabaabababaabaabaababaabaaababaabaaab",
"abaabaababaaabaabababaabaabaababaabaaababaabaaab",
"abaabaababaaabaabababaabaabaababaabaaababaabaaab"
};
"""
__Name__- The name of the macro, for display by the Addon Manager. Generally the filename of the macro without extension, and with spaces between words. For example, the macro file "DxfToSketchLayers.FCMacro" becomes "DXF to Sketch Layers"__Comment__- A description of what the macro does. Displayed and searched by the Addon Manager.__Author__- Comma-separated list of authors (as a single string, e.g. "Jane Doe, John Smith, Bobbi Jones")__Version__- Use semantic versioning (1.2.3-beta), or CalVer (2022.05.19)__Date__- The date of the last update, YYYY-MM-DD__License__- 'License identifier from https://spdx.org/licenses/, e.g. LGPL-2.0-or-later as FreeCAD, MIT, CC0-1.0'__Web__- A URL to fetch the macro from__Wiki__- The wiki page (generally at https://wiki.freecad.org) describing the macro, and displayed as the "Details" page in the Addon Manager.__Icon__- Either a relative path to an icon file included in the FreeCAD macros repository, or a URL where the icon may be downloaded from. Must be a direct download of an image file.__Xpm__- (OPTIONAL) Instead of specifying an__Icon__, icon data may be set directly as a triple-quoted string containing XPM data.__Help__- A short explanation how to use the macro, e.g. what to select before launching__Status__- Stable|Alpha|Beta__Requires__- e.g. FreeCAD >= v0.17, there is no programmatic use of this for now__Communication__- e.g. https://github.com/FreeCAD/FreeCAD-macros/issues/__Files__- comma-separated list of files that should be installed together with this file, use paths relative to this file, do not include this file, and do not wrap the line, all files must be listed in the same single-line quoted string. I you have the impression that the list is too long, please consider submitting your macro in a separate repository.
Some checks of coding standards can be found in .pre-commit-config.yaml.
To use them, you need to install pre-commit and run pre-commit install in the repository.
This will install the hooks and run them on every commit.
If you want to run the checks manually, you can use pre-commit run --all-files.
These checks are applied on each pull request and failing checks will prevent merging.
