Addon: Difference between revisions

From FreeCAD Documentation
(Icon File:Std_AddonMgr.svg)
No edit summary
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<languages/>
<languages/>
{{TOCright}}
<translate>
<translate>


Line 10: Line 11:


<!--T:3-->
<!--T:3-->
There are roughly three types of addons:
There are three types of addons:
* [[Macros|Macro]]: short snippet of [[Python|Python]] code that provides a new tool or functionality in a single file ending with {{incode|.FCMacro}}.
* [[Macros|Macros]]: short snippet of [[Python|Python]] code that provides a new tool or functionality in a single file ending with {{incode|.FCMacro}}.
* [[External_workbenches|Workbenches]]: collections of Python files that provide related [[Gui_Command|Gui Commands]] (tools) centered around a particular topic, for example, tools to design cabinets, or tools to work with architecture, or tools to design boats, etc. These workbenches usually define new toolbars where [[Gui_Command|commands]] are placed as buttons.
* Module: a single Python source file, or a collection of Python files, that extends the software in some way. Modules don't necessarily define a graphical "workbench" but may provide a supporting feature, for example, a library that performs conversion of formats, or code that modifies the graphical [[interface|interface]].
* [[Preference_Packs|Preference Packs]]: distributable collections of user preferences. {{Version|0.20}}
* [[External_workbenches|Workbench]]: collections of Python files that provide related [[Gui_Command|Gui Commands]] (tools) centered around a particular topic, for example, tools to design cabinets, or tools to work with architecture, or tools to design boats, etc. These workbenches usually define new toolbars where [[Gui_Command|commands]] are placed as buttons.

<!--T:12-->
Macros as installed under the user's {{incode|Macro/}} directory, while modules and workbenches are under the {{incode|Mod/}} directory.
</translate>
{{Code|lang=bash|code=
$HOME/.FreeCAD/Macro/
$HOME/.FreeCAD/Mod/
}}
<translate>

<!--T:4-->
Macros usually start as a way to simplify or automate the task of drawing or editing a particular object. If many of these macros are collected inside a directory, and structure is provided to collect those tools, then the entire directory may be distributed as a workbench.

<!--T:5-->
In other words, macros, modules, and workbenches are essentially the same thing, pieces of Python code that extend the base installation. Macros are usually short and focused on a single task, modules usually provide new functions or interfaces, and workbenches are collections of tools (buttons, menus) and graphical interfaces to perform related tasks.

<!--T:6-->
If a workbench is sufficiently developed and is well documented, it may be included as one of the base [[workbenches|workbenches]] in FreeCAD.


== Installation == <!--T:7-->
== Installation == <!--T:7-->


<!--T:8-->
<!--T:8-->
Starting from FreeCAD 0.17, the recommended way to install addons is with the [[File:Std_AddonMgr.svg|24px]] [[Std_AddonMgr|Addon Manager]].
The recommended way to install addons is with the [[File:Std_AddonMgr.svg|24px]] [[Std_AddonMgr|Addon Manager]].


<!--T:9-->
<!--T:9-->
However, manual installation is still possible.
But for macros and workbenches manual installation is also possible:
* [[How_to_install_macros|How to install macros]]
* [[How_to_install_macros|How to install macros]]
* [[Installing_more_workbenches|Installing more workbenches]]
* [[Installing_more_workbenches|Installing more workbenches]]

== Information for developers == <!--T:13-->

<!--T:14-->
If you have developed a macro or workbench, and want to see it included in the Addon manager, read how to do so on the repository pages: ([https://github.com/FreeCAD/FreeCAD-addons/ FreeCAD-addons] and [https://github.com/FreeCAD/FreeCAD-macros/ FreeCAD-macros]). If you add your macro to the [[Macros_recipes|Macros recipes]] page, there is nothing else to do, it will automatically be picked up by the Addon manager.

=== Python workbenches === <!--T:15-->

<!--T:16-->
For Python workbenches, you don't need any specific approval to have your workbench added to the Addon Manager. In addition, because your Addon is outside the FreeCAD source code, you can choose the license you want. If you request for your workbench to be added to the Addon Manager's default list (we will not add any new workbench without a request from its authors), either by asking so on the forum or by opening an issue on the [https://github.com/FreeCAD/FreeCAD-addons/ FreeCAD-addons] repository, your code will stay on your own git repository, we will just add it as a submodule to the [https://github.com/FreeCAD/FreeCAD-addons/ FreeCAD-addons] repository. Of course, before adding your workbench, we will take a look at it and make sure there is nothing potentially problematic with it. For more details about structuring your Addon, including information about metadata used by the Addon Manager, see [[Workbench_creation|Workbench creation]].

=== C++ workbenches === <!--T:17-->

<!--T:18-->
If you develop a workbench in C++, it cannot be run directly by users and must be compiled first. You then have two options, either you provide precompiled versions of your workbench yourself, for the different operating systems, or you should request to have your code merged into the FreeCAD source code. For that, you should use the LGPL license (or a fully compatible license like MIT or BSD), and you must present your new tools to the community in the [https://forum.freecadweb.org FreeCAD forum] for review. Once your code has been tested and approved, you should fork the FreeCAD repository, if not done yet, create a new branch, push your code to it, and open a pull request so that your branch is merged into the main repository.



</translate>
</translate>

Revision as of 10:59, 12 June 2022

Introduction

In FreeCAD and in this documentation, an addon is any component that is not part of the base installation, but that can be added to the system by certain methods.

Different types

There are three types of addons:

  • Macros: short snippet of Python code that provides a new tool or functionality in a single file ending with .FCMacro.
  • Workbenches: collections of Python files that provide related Gui Commands (tools) centered around a particular topic, for example, tools to design cabinets, or tools to work with architecture, or tools to design boats, etc. These workbenches usually define new toolbars where commands are placed as buttons.
  • Preference Packs: distributable collections of user preferences. introduced in version 0.20

Installation

The recommended way to install addons is with the Addon Manager.

But for macros and workbenches manual installation is also possible:

Information for developers

If you have developed a macro or workbench, and want to see it included in the Addon manager, read how to do so on the repository pages: (FreeCAD-addons and FreeCAD-macros). If you add your macro to the Macros recipes page, there is nothing else to do, it will automatically be picked up by the Addon manager.

Python workbenches

For Python workbenches, you don't need any specific approval to have your workbench added to the Addon Manager. In addition, because your Addon is outside the FreeCAD source code, you can choose the license you want. If you request for your workbench to be added to the Addon Manager's default list (we will not add any new workbench without a request from its authors), either by asking so on the forum or by opening an issue on the FreeCAD-addons repository, your code will stay on your own git repository, we will just add it as a submodule to the FreeCAD-addons repository. Of course, before adding your workbench, we will take a look at it and make sure there is nothing potentially problematic with it. For more details about structuring your Addon, including information about metadata used by the Addon Manager, see Workbench creation.

C++ workbenches

If you develop a workbench in C++, it cannot be run directly by users and must be compiled first. You then have two options, either you provide precompiled versions of your workbench yourself, for the different operating systems, or you should request to have your code merged into the FreeCAD source code. For that, you should use the LGPL license (or a fully compatible license like MIT or BSD), and you must present your new tools to the community in the FreeCAD forum for review. Once your code has been tested and approved, you should fork the FreeCAD repository, if not done yet, create a new branch, push your code to it, and open a pull request so that your branch is merged into the main repository.