├── .bundle └── config ├── .gitignore ├── .pre-commit-config.yaml ├── Gemfile ├── README.md ├── _config.yml ├── _includes ├── anchor_headings.html └── markdown-enhancements │ └── mermaid.html ├── _layouts └── default.html ├── bestpractices ├── c++practices.md ├── codereview.md ├── index.md └── pythonpractices.md ├── codeformatting ├── c++.md ├── index.md └── python.md ├── designguide ├── elements.md ├── glossary.md ├── history-and-purpose.md ├── images │ ├── focus.svg │ └── zones.svg ├── index.md ├── laws-of-ux.md ├── logo.md ├── naming.md ├── principles.md └── zones.md ├── favicon.ico ├── gettingstarted ├── CLion.md ├── VSCode.md ├── dependencies.md ├── index.md └── resources │ ├── CLionPixi1.png │ ├── CLionPixi2.png │ ├── CLionPythonDebug1.png │ ├── CLionPythonDebug10.png │ ├── CLionPythonDebug11.png │ ├── CLionPythonDebug2.png │ ├── CLionPythonDebug3.png │ ├── CLionPythonDebug4.png │ ├── CLionPythonDebug5.png │ ├── CLionPythonDebug6.png │ ├── CLionPythonDebug7.png │ ├── CLionPythonDebug8.png │ ├── CLionPythonDebug9.png │ ├── build.mp4 │ ├── configure.mp4 │ ├── debug.mp4 │ ├── extensions.png │ ├── testing.mp4 │ ├── vs2019-cpp.png │ └── vs2019-modify.png ├── images ├── FreeCAD-symbol.svg ├── FreeCAD-wordmark.svg ├── guidelines-4.svg ├── guidelines.pdf └── logo_kit.zip ├── index.md ├── maintainersguide ├── git.md ├── index.md └── teams.md ├── roadmap ├── index.md ├── next.md └── rationale.md └── technical ├── ChecklistForNewFeatureC++.md ├── CreatePythonBindingForCpp.md ├── DevBook.md ├── FPAweb.md ├── FreeCADweb.md ├── MajorRelease.md ├── MinorRelease.md ├── ObjectDeletion.md ├── PropertyChanges.md ├── PythonStubsPackage.md ├── ReferenceLibrary.md ├── ReleasePackages.md ├── ReleaseProcess.md ├── SourceTreeBasics.md ├── TheApplicationModule.md ├── Websites.md ├── automated_testing.md ├── codesigning.md ├── developerglossary.md ├── index.md ├── libpack.md ├── preferences.md ├── resources ├── FreeCADweb_01.jpg ├── FreeCADweb_02.jpg ├── FreeCADweb_03.jpg ├── FreeCADweb_05.jpg ├── FreeCADweb_06.jpg ├── FreeCADweb_07.jpg ├── SourceTreeBasics.svg └── TheApplicationModule.svg ├── snap.md └── translation.md /.bundle/config: -------------------------------------------------------------------------------- 1 | --- 2 | BUNDLE_PATH: "vendor/bundle" 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | Gemfile.lock 2 | 3 | # Ignore metadata generated by Jekyll 4 | _site/ 5 | .sass-cache/ 6 | .jekyll-cache/ 7 | .jekyll-metadata 8 | 9 | # Ignore folders generated by Bundler 10 | .bundle/** 11 | !.bundle/config 12 | vendor/ 13 | 14 | # Ignore IDE directories 15 | .idea/ 16 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | # See https://pre-commit.com for more information 2 | # See https://pre-commit.com/hooks.html for more hooks 3 | 4 | exclude: | 5 | (?x)^( 6 | .*.svg| 7 | .*.po| 8 | .*.ts 9 | ) 10 | 11 | repos: 12 | - repo: https://github.com/pre-commit/pre-commit-hooks 13 | rev: v5.0.0 14 | hooks: 15 | - id: trailing-whitespace 16 | - id: end-of-file-fixer 17 | - id: check-yaml 18 | - id: check-added-large-files 19 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | gem 'github-pages', group: :jekyll_plugins 3 | gem "webrick", ">= 1.8" 4 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Developers Handbook 2 | 3 | This is the repo for the [Developers Handbook](https://freecad.github.io/DevelopersHandbook/). 4 | 5 | ## Install and run locally 6 | 7 | This handbook uses Jekyll, a static site generator written in Ruby. There are several options for setting up local development. Examples below illustrate the process using Bundler on a Debian-based system, or using a Docker container to keep things separate from the host system. After setup, the handbook will be available at `http://127.0.0.1:4000`. 8 | 9 | ### Debian-based system setup 10 | 11 | Although Jekyll is packaged in Debian, the `github-pages` gem is not, so Bundler is required to handle dependencies. It is not necessary to `apt install jekyll`. 12 | 13 | Bundler requires `ruby-dev` and `build-essential` to build Ruby gem native extensions. 14 | 15 | ```bash 16 | $ sudo apt install ruby-bundler ruby-dev build-essential 17 | $ bundle install 18 | $ bundle exec jekyll serve 19 | ``` 20 | 21 | ### Docker container setup 22 | 23 | Docker bind mounts the handbook source directory inside the container and marks it as private & unshared with any other container, before calling `jekyll serve` as in the instructions above. 24 | 25 | ```bash 26 | $ docker run --rm --volume="$PWD:/srv/jekyll:Z" -it jekyll/jekyll jekyll serve 27 | ``` 28 | 29 | ### References 30 | 31 | - [Jekyll installation guidelines](https://jekyllrb.com/docs/installation/) 32 | - [Ruby 101 notes](https://jekyllrb.com/docs/ruby-101/) 33 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | gist: 2 | noscript: false 3 | remote_theme: pages-themes/slate 4 | 5 | title: [FreeCAD Developers Handbook] 6 | description: [A handbook about FreeCAD development] 7 | 8 | # Where things are 9 | source : . 10 | destination : ./_site 11 | collections_dir : . 12 | plugins_dir : _plugins # takes an array of strings and loads plugins in that order 13 | layouts_dir : _layouts 14 | data_dir : _data 15 | includes_dir : _includes 16 | sass: 17 | sass_dir: _sass 18 | collections: 19 | posts: 20 | output : true 21 | permalink: /:collection/:name 22 | 23 | # Handling Reading 24 | safe : true 25 | include : [".htaccess"] 26 | exclude : ["Gemfile", "Gemfile.lock", "node_modules", "vendor/bundle/", "vendor/cache/", "vendor/gems/", "vendor/ruby/"] 27 | keep_files : [".git", ".svn"] 28 | encoding : "utf-8" 29 | markdown_ext : "markdown,mkdown,mkdn,mkd,md" 30 | strict_front_matter : false 31 | 32 | # Filtering Content 33 | show_drafts : null 34 | limit_posts : 0 35 | future : false 36 | unpublished : false 37 | 38 | # Plugins 39 | whitelist : [] 40 | plugins : [] 41 | 42 | # Conversion 43 | markdown : kramdown 44 | highlighter : rouge 45 | lsi : false 46 | excerpt_separator : "\n\n" 47 | incremental : false 48 | 49 | # # Serving 50 | # detach : false 51 | # port : 4000 52 | # host : 127.0.0.1 53 | # baseurl : "" # does not include hostname 54 | # show_dir_listing : false 55 | 56 | # Outputting 57 | permalink : date 58 | paginate_path : /page:num 59 | timezone : null 60 | 61 | quiet : false 62 | verbose : false 63 | defaults : [] 64 | 65 | liquid: 66 | error_mode : warn 67 | strict_filters : false 68 | strict_variables : false 69 | 70 | # Markdown Processors 71 | kramdown: 72 | auto_ids : true 73 | entity_output : as_char 74 | toc_levels : [1, 2, 3, 4, 5, 6] 75 | smart_quotes : lsquo,rsquo,ldquo,rdquo 76 | input : GFM 77 | hard_wrap : false 78 | footnote_nr : 1 79 | show_warnings : false 80 | math_engine: mathjax 81 | syntax_highlighter: rouge 82 | -------------------------------------------------------------------------------- /_includes/anchor_headings.html: -------------------------------------------------------------------------------- 1 | {% capture headingsWorkspace %} 2 | {% comment %} 3 | Copyright (c) 2018 Vladimir "allejo" Jimenez 4 | 5 | Permission is hereby granted, free of charge, to any person 6 | obtaining a copy of this software and associated documentation 7 | files (the "Software"), to deal in the Software without 8 | restriction, including without limitation the rights to use, 9 | copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the 11 | Software is furnished to do so, subject to the following 12 | conditions: 13 | 14 | The above copyright notice and this permission notice shall be 15 | included in all copies or substantial portions of the Software. 16 | 17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 18 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 19 | OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 20 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 21 | HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 22 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 23 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 24 | OTHER DEALINGS IN THE SOFTWARE. 25 | {% endcomment %} 26 | {% comment %} 27 | Version 1.0.13 28 | https://github.com/allejo/jekyll-anchor-headings 29 | 30 | "Be the pull request you wish to see in the world." ~Ben Balter 31 | 32 | Usage: 33 | {% include anchor_headings.html html=content anchorBody="#" %} 34 | 35 | Parameters: 36 | * html (string) - the HTML of compiled markdown generated by kramdown in Jekyll 37 | 38 | Optional Parameters: 39 | * beforeHeading (bool) : false - Set to true if the anchor should be placed _before_ the heading's content 40 | * headerAttrs (string) : '' - Any custom HTML attributes that will be added to the heading tag; you may NOT use `id`; 41 | the `%heading%` and `%html_id%` placeholders are available 42 | * anchorAttrs (string) : '' - Any custom HTML attributes that will be added to the `` tag; you may NOT use `href`, `class` or `title`; 43 | the `%heading%` and `%html_id%` placeholders are available 44 | * anchorBody (string) : '' - The content that will be placed inside the anchor; the `%heading%` placeholder is available 45 | * anchorClass (string) : '' - The class(es) that will be used for each anchor. Separate multiple classes with a space 46 | * anchorTitle (string) : '' - The `title` attribute that will be used for anchors 47 | * h_min (int) : 1 - The minimum header level to build an anchor for; any header lower than this value will be ignored 48 | * h_max (int) : 6 - The maximum header level to build an anchor for; any header greater than this value will be ignored 49 | * bodyPrefix (string) : '' - Anything that should be inserted inside of the heading tag _before_ its anchor and content 50 | * bodySuffix (string) : '' - Anything that should be inserted inside of the heading tag _after_ its anchor and content 51 | * generateId (true) : false - Set to true if a header without id should generate an id to use. 52 | 53 | Output: 54 | The original HTML with the addition of anchors inside of all of the h1-h6 headings. 55 | {% endcomment %} 56 | 57 | {% assign minHeader = include.h_min | default: 1 %} 58 | {% assign maxHeader = include.h_max | default: 6 %} 59 | {% assign beforeHeading = include.beforeHeading %} 60 | {% assign headerAttrs = include.headerAttrs %} 61 | {% assign nodes = include.html | split: ' 76 | {% if headerLevel == 0 %} 77 | 78 | {% assign firstChunk = node | split: '>' | first %} 79 | 80 | 81 | {% unless firstChunk contains '<' %} 82 | {% capture node %}{% endcapture %} 90 | {% assign _workspace = node | split: _closingTag %} 91 | {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %} 92 | {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %} 93 | {% assign escaped_header = header | strip_html | strip %} 94 | 95 | {% assign _classWorkspace = _workspace[0] | split: 'class="' %} 96 | {% assign _classWorkspace = _classWorkspace[1] | split: '"' %} 97 | {% assign _html_class = _classWorkspace[0] %} 98 | 99 | {% if _html_class contains "no_anchor" %} 100 | {% assign skip_anchor = true %} 101 | {% else %} 102 | {% assign skip_anchor = false %} 103 | {% endif %} 104 | 105 | {% assign _idWorkspace = _workspace[0] | split: 'id="' %} 106 | {% if _idWorkspace[1] %} 107 | {% assign _idWorkspace = _idWorkspace[1] | split: '"' %} 108 | {% assign html_id = _idWorkspace[0] %} 109 | {% assign h_attrs = headerAttrs %} 110 | {% elsif include.generateId %} 111 | 112 | {% assign html_id = escaped_header | slugify %} 113 | {% if html_id == "" %} 114 | {% assign html_id = false %} 115 | {% endif %} 116 | 117 | {% capture h_attrs %}{{ headerAttrs }} id="%html_id%"{% endcapture %} 118 | {% endif %} 119 | 120 | 121 | {% capture anchor %}{% endcapture %} 122 | 123 | {% if skip_anchor == false and html_id and headerLevel >= minHeader and headerLevel <= maxHeader %} 124 | {% if h_attrs %} 125 | {% capture _hAttrToStrip %}{{ _hAttrToStrip | split: '>' | first }} {{ h_attrs | strip | replace: '%heading%', escaped_header | replace: '%html_id%', html_id }}>{% endcapture %} 126 | {% endif %} 127 | 128 | {% capture anchor %}href="#{{ html_id }}"{% endcapture %} 129 | 130 | {% if include.anchorClass %} 131 | {% capture anchor %}{{ anchor }} class="{{ include.anchorClass }}"{% endcapture %} 132 | {% endif %} 133 | 134 | {% if include.anchorTitle %} 135 | {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', escaped_header }}"{% endcapture %} 136 | {% endif %} 137 | 138 | {% if include.anchorAttrs %} 139 | {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', escaped_header | replace: '%html_id%', html_id }}{% endcapture %} 140 | {% endif %} 141 | 142 | {% capture anchor %}{{ include.anchorBody | replace: '%heading%', escaped_header | default: '' }}{% endcapture %} 143 | 144 | 145 | {% if beforeHeading %} 146 | {% capture anchor %}{{ anchor }} {% endcapture %} 147 | {% else %} 148 | {% capture anchor %} {{ anchor }}{% endcapture %} 149 | {% endif %} 150 | {% endif %} 151 | 152 | {% capture new_heading %} 153 | 162 | {% endcapture %} 163 | 164 | 167 | {% assign chunkCount = _workspace | size %} 168 | {% if chunkCount > 1 %} 169 | {% capture new_heading %}{{ new_heading }}{{ _workspace | last }}{% endcapture %} 170 | {% endif %} 171 | 172 | {% capture edited_headings %}{{ edited_headings }}{{ new_heading }}{% endcapture %} 173 | {% endfor %} 174 | {% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }} 175 | -------------------------------------------------------------------------------- /_includes/markdown-enhancements/mermaid.html: -------------------------------------------------------------------------------- 1 | {% if page.mermaid == true %} 2 | 3 | 11 | {% endif %} 12 | -------------------------------------------------------------------------------- /_layouts/default.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | {% seo %} 11 | {% include head-custom.html %} 12 | 13 | 14 | 15 | 16 | 17 |
18 |
19 | {% if site.github.is_project_page %} 20 | View on GitHub 21 | {% endif %} 22 | 23 |

{{ site.title | default: site.github.repository_name }}

24 |

{{ site.description | default: site.github.project_tagline }}

25 | 26 | 31 | 32 | {% if site.show_downloads %} 33 |
34 | Download this project as a .zip file 35 | Download this project as a tar.gz file 36 |
37 | {% endif %} 38 |
39 | 56 |
57 | 58 | 59 |
60 |
61 | {% include anchor_headings.html html=content anchorBody="#" %} 62 |
63 |
64 | 65 | 66 | 73 | 74 | {% if page.mermaid %} 75 | {% include markdown-enhancements/mermaid.html %} 76 | {% endif %} 77 | 78 | -------------------------------------------------------------------------------- /bestpractices/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Best Practices 6 | 7 | Although this chapter is not FreeCAD specific, it is provided here to help both developers and code reviewers to ensure 8 | clean and easily maintainable code. The practices presented should be treated like food recipes - you can play with them, 9 | alter them - but every change should be thoughtful and intentional. 10 | 11 | While this guideline might not be consistently followed throughout all of the existing codebase, adhering to these practices 12 | moving forward will help improve the overall quality of the code and make future contributions more maintainable. Consider it 13 | as inspiration for the better future. 14 | 15 | ## For Developers 16 | If you are a developer and want to read what we consider as good code please consult practices mentioned below. These guidelines 17 | try to define what the good code is and how it should be written. 18 | 19 | - For C++ see [C++ practices](./c++practices.md) 20 | - For Python see [Python practices](./pythonpractices.md) 21 | 22 | ## For Reviewers 23 | For reviews it is good to have a set of concrete rules that are easy to follow. If you want to learn how to review code, or 24 | simply want to learn how we check code please consult the [reviewer guide](./codereview.md). 25 | -------------------------------------------------------------------------------- /bestpractices/pythonpractices.md: -------------------------------------------------------------------------------- 1 | # Python Practices 2 | 3 | Work in Progress - looking for help! 4 | -------------------------------------------------------------------------------- /codeformatting/c++.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # C++ Code Code Formatting Guidelines 6 | 7 | Guidelines for code formatting in Python 8 | 9 | Content goes here 10 | -------------------------------------------------------------------------------- /codeformatting/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Code Formatting Guidelines 6 | 7 | Guidelines for code formatting in C++ and Python 8 | 9 | FreeCAD is written primarily in C++ and Python (with a few files in other languages such as CMake). To smooth the process of merging new contributions it is desirable to minimize formatting changes to existing code, and to use a uniform code formatting style when writing new code. Eventually we expect to standardize the codebase on specific coding styles using Clang Format for C++ and a Python code-formatter (such as Black), but that is a work-in-progress and _should not_ be applied to existing otherwise-untouched code. 10 | 11 | ## Setting up pre-commit 12 | 13 | For the sections of the code that have already been auto-formatted, we use [git pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) to enforce that formatting. We use the [pre-commit](https://pre-commit.com/) framework to install and manage our hooks. All developers should install pre-commit following the [instructions here](https://freecad.github.io/DevelopersHandbook/gettingstarted/). When making a new commit, the hooks examine your changed files and ensure that they follow the appropriate formatting for the section of code you are working on. You do not need to manually yourself with your code's formatting as you develop, and may code it as you like (or as your IDE likes...). The hook will ensure that your finished code conforms to project requirements. 14 | 15 | Not all of FreeCAD currently uses these hooks: it is up to the Maintainers in charge of a particular Workbench or subdirectory to work with their development team to migrate their code's formatting to the automated tools, and to then enable the hooks on their subdirectory. 16 | 17 | Currently the following sections of code are covered by pre-commit: `src/Mod/AddonManager`, `src/Tools`, and `tests/src`. 18 | 19 | ## C++ 20 | 21 | FreeCAD's codebase currently includes a [.clang-format](https://github.com/FreeCAD/FreeCAD/blob/master/.clang-format) file. Many IDEs will automatically apply these settings when editing files. To minimize disruption of other developers, only new or significantly-refactored code should have the formatting automatically applied. Code not being worked on should not be automatically formatted at this time. 22 | 23 | ### C++ Copyright Header 24 | 25 | The following is the standard C++ copyright header that should be included in all new C++ files (and backported to files a developer is making significant changes to if they do not already have this format). 26 | 27 | ```cpp 28 | // SPDX-License-Identifier: LGPL-2.1-or-later 29 | /**************************************************************************** 30 | * * 31 | * Copyright (c) * 32 | * * 33 | * This file is part of FreeCAD. * 34 | * * 35 | * FreeCAD is free software: you can redistribute it and/or modify it * 36 | * under the terms of the GNU Lesser General Public License as * 37 | * published by the Free Software Foundation, either version 2.1 of the * 38 | * License, or (at your option) any later version. * 39 | * * 40 | * FreeCAD is distributed in the hope that it will be useful, but * 41 | * WITHOUT ANY WARRANTY; without even the implied warranty of * 42 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 43 | * Lesser General Public License for more details. * 44 | * * 45 | * You should have received a copy of the GNU Lesser General Public * 46 | * License along with FreeCAD. If not, see * 47 | * . * 48 | * * 49 | ***************************************************************************/ 50 | ``` 51 | 52 | ## Python 53 | 54 | There is no unified Python coding style agreed upon for the FreeCAD codebase: each module currently has its own style. Developers working on an existing module should format their code in the prevailing style of the module they are working in. 55 | 56 | ### Python Copyright Header 57 | 58 | The following is the standard Python copyright header that should be included in all new Python files (and backported to files a developer is making significant changes to if they do not already have this format). 59 | 60 | ```python 61 | # SPDX-License-Identifier: LGPL-2.1-or-later 62 | # *************************************************************************** 63 | # * * 64 | # * Copyright (c) * 65 | # * * 66 | # * This file is part of FreeCAD. * 67 | # * * 68 | # * FreeCAD is free software: you can redistribute it and/or modify it * 69 | # * under the terms of the GNU Lesser General Public License as * 70 | # * published by the Free Software Foundation, either version 2.1 of the * 71 | # * License, or (at your option) any later version. * 72 | # * * 73 | # * FreeCAD is distributed in the hope that it will be useful, but * 74 | # * WITHOUT ANY WARRANTY; without even the implied warranty of * 75 | # * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 76 | # * Lesser General Public License for more details. * 77 | # * * 78 | # * You should have received a copy of the GNU Lesser General Public * 79 | # * License along with FreeCAD. If not, see * 80 | # * . * 81 | # * * 82 | # *************************************************************************** 83 | ``` 84 | 85 | ## Inline documentation 86 | 87 | You will find a mix of different generations of comment-based inline documentation systems in the code base depending on when the code was written. As of 2024 it is preferred that you write [doxygen](https://www.doxygen.nl/manual/docblocks.html) compatible comment documentation. For methods, including the @param and @return as appropriate is highly recommended. 88 | -------------------------------------------------------------------------------- /codeformatting/python.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Python Code Code Formatting Guidelines 6 | 7 | Guidelines for code formatting in Python 8 | 9 | Use Black. 10 | -------------------------------------------------------------------------------- /designguide/elements.md: -------------------------------------------------------------------------------- 1 | # Primary Elements 2 | 3 | - [Toolbars](#toolbars) 4 | 5 | - [Dock Windows](#dock-windows) 6 | 7 | - [Task Panels](#task-panels) 8 | 9 | ## Toolbars 10 | 11 | Toolbar management in complex technical software such as CAD poses unique challenges as there are often hundreds of potential tools, functions, or features which may require ready access within the GUI. The [Pareto-Principle]((laws-of-ux.md#pareto-principle)) (80/20 rule) should be the basis for how toolbars are populated. The 80/20 rule states that 20% of the input results in 80% of the output. This would imply that 20% of a set of tools get 80% of the use. While this may not be a perfect correlating principle, it should help guide a critical thought process about which tools go onto a toolbar and also how they are organized. 12 | 13 | **Toolbar Organization Guidelines:** 14 | 15 | - Inverse functions (example: functionally similar additive and subtractive operations) should be combined into single tools wherever practicable. Switching between inverse modes should be done with a boolean control such as a toggle/checkbox within the related TaskPanel rather than resulting in separate tools. It minimizes space on toolbars and simplifies icon development. 16 | 17 | - In accordance with the [Pareto Principle](laws-of-ux.md#pareto-principle.md), where a group of related functions consist of one which covers a majority of cases, a Menu Button should be formed to group those related functions into a single toolbar slot. The most common or likely to be used function should be presented as the default from that group on the toolbar. 18 | 19 | - Toolbars should be broken into logical groupings, both visually(iconography), and functionally. Avoid use of many specialized toolbars in favor of more moderate sized toolbars. ie. one for basic functionality, and one for advanced. (80/20 rule helps here as well. Ideally there would be no more than 3 QToolBars in horizontal orientation or 2 toolbars in a vertical. Those are not hard requirements however. 20 | 21 | **Toolbar Buttons:** 22 | 23 | - Should consist of only QToolButton or QMenuButton widgets. Other widgets may be used in special circumstances. The developer must ensure that the introduced widget is visually consistent and does not stand out above other tools. Features adding custom widget to toolbars shall be reviewed by the design working group. 24 | 25 | - Toolbars which toggle/indicate a funtional state can do so via change in icon (color or inclusion of an indicator) 26 | 27 | - Deviations in prescribed widget types allocated to a tool bar must only be accepted after consensus is reached between applicable developers and a thorough review by the design team. 28 | 29 | ## Dock Windows 30 | 31 | These are the dockable panels that typically reside docked to the left, right or bottom edges of the FreeCAD UI. 32 | 33 | #### Task Panels: 34 | 35 | These panels are a quintessential component of FreeCAD's interface. A task panel is the means by which a user interacts with the current task being performed. Ranging from controlling sketch elements, defining parameters for a feature such as a Chamfer or set up parameters for CNC machining. These critical components **must** be uniform in both layout and sizing. A default width, in accordance with the UI [zones and layout](zones.md) definitions is established at 360 pixels. 36 | 37 | Here are general guidelines to be followed for a task panel: 38 | 39 | - "Ok" and "Cancel" buttons *shall* be located at the top of each panel with a centered alignment.\ 40 | Alternative button configurations are inconsistent and not acceptable. 41 | 42 | - Minimize the width of the panel as much as possible through good use of space, arrangement of widgets, and [naming](naming.md). 43 | 44 | - Developers should use the approriate [interactive control](interactive.md) widgets to ensure a consistent experience throughout 45 | 46 | - Task Panels can potentially include enormous amounts of information and advanced settings/controls. Utilizing FreeCAD's custom [QSInt](https://freecad.github.io/SourceDoc/d9/d11/namespaceQSint.html) widget class, which provides a 'rolling up' of portions of the panel, is encouraged. Follow the [80/20 rule](laws-of-ux.md#pareto-principle), and by default only expose the most commonly needed controls/data to avoid overwhelming users with information/settings when they are not needed. This allows the user to expand more advanced settings, controls or information when the need arises. 47 | 48 | [Return to Design Guide Main Page](index.md) 49 | -------------------------------------------------------------------------------- /designguide/glossary.md: -------------------------------------------------------------------------------- 1 | ## Glossary of Terms: 2 | 3 | - **Widget:** Widgets are the individual components for creating user interfaces in FreeCAD. Widgets can display data and status information, receive user input, and provide a container for other widgets that should be grouped together. FreeCAD uses the QtWidget toolkit. 4 | 5 | - **Element:** A primary component of the FreeCAD User Interface consisting of a combination of widgets to support navigation and feature execution providing a means for user interaction. 6 | 7 | - **Panel:** A window element which can be docked to the edge of the screen in a static position. 8 | 9 | - **Main View / 3D View:** This is the main view area of the users screen where work is displayed and these two terms are largely interchangeable within FreeCAD. 10 | 11 | - **Contrast:** Difference between colors. For accessibility, contrast refers strictly to the difference in tone. A difference of 40 in tone guarantees a [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) contrast ratio ≥ 3.0; a difference of 50 in tone guarantees a contrast ratio ≥ 4.5. FreeCAD makes extensive use of colors and high contrast ratios should be a developers goal. 12 | 13 | - **Design guidelines:** Guidelines are descriptive written and illustrated docs that demonstrate usage and behavior mainly through examples. They're the long-form discussion of specs that help designers and developers with problem-solving and decision-making. 14 | 15 | [Return to Design Guide Main Page](index.md) 16 | -------------------------------------------------------------------------------- /designguide/history-and-purpose.md: -------------------------------------------------------------------------------- 1 | ## History and Purpose: 2 | 3 | FreeCAD is a highly modular, complex piece of design software which has been developed for over [20 years](https://wiki.freecad.org/History) by volunteer contributors from across the globe. Due to the nature of this organic growth, individuals have injected their own ideas and implementations without following a uniform design language for how the application should present itself to users as well as flow through its many features. As a result user feedback regarding aesthetic and usability were generally poor, despite a robust set of features. 4 | 5 | This *Design Guide* is intended to present developers/designers a series of concepts and guidelines through which they may expand, extend and improve FreeCAD through improved user interactions and general consistency of appearance, structure, and behavior. As such, this should be considered a living document which may change to meet the needs of developers, designers, and users. It can potentially also help those who write documentation use consistent terminology. 6 | 7 | This guide is the product of a Design Working Group consisting of community members; ensuring decisions made regarding the User Interface and User Experience are consistent with the needs of people who actually use FreeCAD in both professional and hobbyist environments. This working group will also be involved with review of interface/experience related changes to FreeCAD to provide input to developers and maintainers regarding the merits and consistency of features which may impact interaction and/or workflows. 8 | 9 | [Return to Design Guide Main Page](index.md) 10 | -------------------------------------------------------------------------------- /designguide/images/focus.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 19 | 38 | 40 | 44 | 52 | 60 | 68 | 75 | Resolution: 1920 * 1080Desired Main View areais 50% in center of screen. 96 | 102 | 108 | 114 | 120 | 121 | 122 | -------------------------------------------------------------------------------- /designguide/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Design Guide 6 | 7 | **This Design Guide is organized into the following sections** 8 | 9 | - [History and Purpose](history-and-purpose.md) 10 | 11 | - [Glossary of Terms](glossary.md) 12 | 13 | - [Principles](principles.md) 14 | 15 | - [Zones](zones.md) 16 | 17 | - [Primary Elements](elements.md) 18 | 19 | - Interactive Controls (Still under development) 20 | 21 | - [Naming Convention](naming.md) 22 | 23 | - Colors and Accessibility (Still under development) 24 | 25 | - Theme/Styling (Still under development) 26 | 27 | - Icons/Art (Still under development) 28 | 29 | - [FreeCAD Brand Guidelines](logo.md) 30 | 31 | *The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt).* 32 | 33 | ## How to use this guide: 34 | 35 | This guide is organized into multiple documents as outlined above, for the purpose of aiding developers in finding relevant content without excess information. Newcomers to FreeCAD, and this Design Guide, should familiarize themselves with the principles and assumptions which were used as the foundation on which these guidelines were built before progressing to more targeted content. The rest of the sections are organized in a manner of logical hierarchy of concepts and guidlines starting with more conceptual matter and moving on towards greater levels of detail. 36 | 37 | ## Assumptions: 38 | 39 | The interface is tailored around a 1920 x 1080 standard resolution. 40 | 41 | According to the [*Steam monthly hardware survey*](https://store.steampowered.com/hwsurvey/Steam-Hardware-Software-Survey-Welcome-to-Steam), over 90% of all computer displays utilize 1920x1080 or higher resolution. The user interface for FreeCAD shall be optimized for this recommended resolution at 100% scaling. This shall be the "reference resolution" for the remainder of this design guide. 42 | 43 | **Note:** For operating system specific elements Windows is considered the standard due to market share (70% in 2023). Every effort should be made to maintain a uniform appearance across platforms. 44 | 45 | **Note:** Deviations from the prescriptive guidelines in this design document require justification utilizing sound reasoning and require a design review that such deviation(s) are both warranted and fit within the needs of the user without degrading the overall consistency of the user experience. 46 | -------------------------------------------------------------------------------- /designguide/laws-of-ux.md: -------------------------------------------------------------------------------- 1 | # Principles and Laws of UI/UX 2 | 3 | *Understand that UI/UX is closely linked to human psychology and tendencies* 4 | 5 | ## Aesthetic-Usability Effect 6 | 7 | - An aesthetically pleasing design nets a positive response about usability and makes the UI design appear better even in the absence of any other differences. 8 | 9 | - This is a low-hanging fruit for FreeCAD's GUI as the default themes presented can be carefully curated for a visually pleasing effect. 10 | 11 | - Visually pleasing design masks usability problems and keeps problems from being discovered. 12 | 13 | - While this is a benefit when considering the end-user, it can also pose a problem when seeking feedback from users about problems and proposed solutions. 14 | 15 | - Testing UX design improvements a simplified and bland theme/stylesheet should be used. 16 | 17 | - People are more tolerant of usability issues when the design aesthetic is appealing 18 | 19 | - "During usability testing, one user encountered many issues while shopping on the FitBit site, ranging from minor annoyances in the interaction design to serious flaws in the navigation. She was able to complete her task, but with difficulty. However, in a post-task questionnaire, she rated the site very highly in ease of use. *"It's the colors they used,"* she said. *"Looks like the ocean, it's calm. Very good photographs."* The positive emotional response caused by the aesthetic appeal of the site helped mask its usability issues."\ 20 | ([The Aesthetic-Usability Effect](https://www.nngroup.com/articles/aesthetic-usability-effect/)) 21 | 22 | - **Takeaway:** Aesthetically pleasing interfaces are worth the investment. Visual designs that appeal to your users have the side effects of making your site appear orderly, well designed, and professional. Users are more likely to want to try a visually appealing site, and they're more patient with minor issues. 23 | 24 | ## Doherty Threshold 25 | 26 | - Summarized as user interactions and software response time hits a psychological 'addictive' state when response is roughly 400ms or slightly less. 27 | 28 | - In the case of FreeCAD, appears to be less relevant, and is incredibly difficult to quantify. 29 | 30 | ## Fitt's Law 31 | 32 | - The time to acquire a target is a function of the distance to and size of the target. 33 | 34 | - The bigger the distance to the target, the longer it will take for the pointer to move to it. In other words, closer targets are faster to acquire. 35 | 36 | - The larger the target, the shorter the movement time to it. In other words, bigger targets are better. 37 | 38 | - Complements the concepts of the "Two Component Model" 39 | 40 | - Initial movement fast, imprecise 41 | 42 | - Final movement slower for precision 43 | 44 | - **Takeaways** 45 | 46 | - Size matters, interactive/clickable elements should be large enough to reduce errors/miss-clicks. 47 | 48 | - Minimizing travel distance to relevant targets also reduces the incidence of errors. 49 | 50 | ## Goal-Gradient Effect 51 | 52 | - This effect implies that giving users a sense of progress through visual indicators increases productivity. 53 | 54 | - Seems to apply to linear task type applications and is not likely to be applicable to most work done in CAD. 55 | 56 | ## Hick-Hyman Law 57 | 58 | - Hick's Law is a simple idea that says that the more choices you present your users with, the longer it will take them to reach a decision. It's common sense, but often neglected in the rush to cram too much functionality into a site or application. 59 | 60 | - "The time it takes to make a decision increases with the number and complexity of choices." 61 | 62 | - Minimize choices to decrease and simplify decision making and increase efficiency 63 | 64 | - Reducing displayed options increases efficiency and keeps users engaged in their task. 65 | 66 | - Avoid Overwhelming Users by highlighting recommended options 67 | 68 | - Be careful not to simplify to the point of abstraction 69 | 70 | - **Takeaway:** K.I.S.S. - Keep it Simple, Stupid 71 | 72 | ## Jakob's Law 73 | 74 | - Effectively states users spend most of their time using other software (or websites/web apps) This means that users prefer to work within established conventions that they are already used to. 75 | 76 | - Closely related to "The Power Law of Learning" 77 | 78 | - Repetition and consistency improve and reduce learning curves 79 | 80 | - **Takeaways:** 81 | 82 | - Common functions found in most other software should work generally the same way new users can reasonably expect based on preexisting experiences. 83 | 84 | - Consistency in behavior and element location is paramount to good UI/UX design 85 | 86 | - When making major changes, minimize discontent by empowering users to continue using a familiar version for a limited time. 87 | 88 | ## Law of Common Region 89 | 90 | - UI elements tend to be perceived into groups if they are sharing an area with a clearly defined boundary 91 | 92 | - Humans naturally perceive objects as organized patterns. 93 | 94 | - Gestalt laws organize based on the following categories: 95 | 96 | - Proximity 97 | 98 | - Similarity 99 | 100 | - Continuity 101 | 102 | - Closure 103 | 104 | - Connectedness 105 | 106 | ## Law of Proximity 107 | 108 | - Proximity helps to establish a relationship with nearby objects. 109 | 110 | - Elements in close proximity are perceived to share similar functionality or traits. 111 | 112 | - Proximity helps users understand and organize information faster and more efficiently. 113 | 114 | ## Law of Pragnanz 115 | 116 | - The human eye likes to find simplicity and order in complex shapes because it prevents us from becoming overwhelmed with information. 117 | 118 | - Research confirms that people are better able to visually process and remember simple figures than complex figures. 119 | 120 | - The human eye simplifies complex shapes by transforming them into a single, unified shape. 121 | 122 | - **Takeaway:** Icons should be reviewed with this principle in mind. 123 | 124 | ## Law of Similarity 125 | 126 | - Elements that are visually similar will be perceived as related 127 | 128 | - Color, shape, size, orientation and movement can signal that elements belong to the same group and likely share a common meaning or functionality. 129 | 130 | - Ensure that links and navigation systems are visually differentiated from normal text elements. 131 | 132 | ## Law of Uniform Connectedness 133 | 134 | - Elements that are visually connected are perceived as more related than elements with no connection 135 | 136 | - Group functions of a similar nature so they are visually connected via colors, lines, frames or other shapes. 137 | 138 | - Use uniform connectedness to show context or to emphasize the relationship between similar items. 139 | 140 | - Use tangible connecting reference (line, arrow, etc) from one element to the next to also create a visual connection 141 | 142 | ## Miller's Law 143 | 144 | - The average person can only keep 7 (+/- 2) items in their working memory 145 | 146 | - Takeaways 147 | 148 | - Don't impose unnecessary design limitations just for the sake of hitting '7' 149 | 150 | - Organize content into smaller chunks to help users process, understand and memorize more easily. 151 | 152 | - Short Term memory capacity will vary per individual based on prior knowledge and contextual understanding 153 | 154 | ## Occam's Razor 155 | 156 | - Among competing hypothesis that predict equally well, the one with the fewest assumptions should be selected 157 | 158 | - **Takeaways:** 159 | 160 | - The best method for reducing complexity is to avoid it in the first place 161 | 162 | - Consider completion only when no additional items can be removed 163 | 164 | - Analyze each element and remove as many as possible, without compromising the overall function 165 | 166 | ## Pareto Principle 167 | 168 | - For many events, roughly 80% of the effects from 20% of the causes. 169 | 170 | - Takeaways: 171 | 172 | - Inputs and outputs are commonly not distributed evenly 173 | 174 | - A large group may contain only a few meaningful contributors to the desired outcome 175 | 176 | - Focus the majority of effort on the areas that will be the largest benefits to the most users. 177 | 178 | ## Parkinson's Law 179 | 180 | - Any task will inflate until all of the available time is spent 181 | 182 | - **Takeaways:** 183 | 184 | - Limit the time it takes to complete a task to what users could reasonably expect it will take. 185 | 186 | - Reducing the actual duration to complete a task from the expected duration will improve the overall user experience 187 | 188 | - Leveraging types of features such as autofill to save the user time allows for quick completion of tasks 189 | 190 | ## Peak-End Rule 191 | 192 | - People judge an experience largely based on how they felt at its peak and at its end rather than the total sum or average of every moment of the experience. 193 | 194 | - **Takeaways:** 195 | 196 | - Pay attention to the most intense points and final moments of the user 'journey' 197 | 198 | - Identify the moments when your product is the most helpful, valuable or entertaining and design to delight the end user. 199 | 200 | - Remember that users recall negative experiences more vividly than positive ones 201 | 202 | ## Additional Resources: 203 | 204 | [Laws of UX](https://lawsofux.com) 205 | 206 | [Nielsen Norman Group](https://nngroup.com) 207 | 208 | [10 Jakob Nielsen's UI heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) 209 | 210 | [Return to Design Guide Main Page](index.md) 211 | -------------------------------------------------------------------------------- /designguide/logo.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "FreeCAD brand guidelines" 3 | layout: default 4 | --- 5 | # FreeCAD Brand Guidelines 6 | 7 | The brand guidelines describe the proper use of the FreeCAD logo and other FPA branded resources. 8 | This is an excerpt of the official [FPA site for the FreeCAD brand guidelines](https://fpa.freecad.org/handbook/process/logo.html). 9 | 10 | 11 | - [Logos](#logos) 12 | 13 | - [Logo Kit](#logo-kit) 14 | 15 | - [Wordmark](#wordmark) 16 | 17 | - [Symbol](#symbol) 18 | 19 | - [Colors](#colors) 20 | 21 | - [Use](#use) 22 | 23 | - [Scale and Whitespace](#scale-and-whitespace) 24 | 25 | - [Do nots](#do-nots) 26 | 27 | - [PDF Guidelines](#pdf-guidelines) 28 | 29 | 30 | ## Logos 31 | 32 | ### Logo Kit 33 | 34 | The logo is being used to brand and identify official FPA projects (FreeCAD) and content. 35 | Third parties can only use it to provide credit for FreeCAD or to link to [freecad.org](http:/freecad.org). 36 | 37 | You can download the logo kit including guidelines: 38 | 39 | [Download Logo Kit](../images/logo_kit.zip) 40 | 41 | 42 | ### Wordmark 43 | 44 | 45 | 46 | The logo consists of two elements: the *F* symbol and the wordmark. The text uses the [Evolventa](https://evolventa.github.io/) font family, in regular weight for "Free" and in bold weight for "CAD". It should not be recreated but instead used as provided, either in the dark or light version. 47 | 48 | 49 | ### Symbol 50 | 51 | 52 | 53 | The symbol has two versions: 54 | 1. Full color (primary) which is the preferred version 55 | 2. Mono / 1C (secondary) as fallback and only used in the color *Tufts Blue*, *Light Red*, *Off Black*, or *White*. No other colors or gradients and effects should be used 56 | 57 | 58 | ## Colors 59 | 60 | The FreeCAD logos must always appear as one of the primary brand colors. This includes *Tufts Blue*, *Light Red*, *Dark Red*, *Off Black*, and *White*. These colors should also be used for other branded applications. 61 | Regardless of the used symbol, the wordmark *FreeCAD* must always be used in either *Off Black* or *White* as provided in the logo kit. 62 | 63 | - **Tufts Blue**, [#418FDE, RGBA(65,143,222,1), CMYK(73,36,0,13), PMS 279 C](https://encycolorpedia.com/418fde) 64 | 65 | - **Light Red**, [#FF585D, RGBA(255,88,93,1), CMYK(0,64,64,0), PMS 178 C](https://encycolorpedia.com/ff585d) 66 | 67 | - **Dark Red**, [#CB333B, RGBA(203,51,59,1), CMYK(0,75,72,18), PMS 1797 C](https://encycolorpedia.com/cb333b) 68 | 69 | - **Off Black**, [#212529, RGBA(33,37,41,1), CMYK(20,10,0,84), PMS BLACK C](https://encycolorpedia.com/212529) 70 | 71 | 72 | ## Uses 73 | 74 | The FreeCAD logo is provided in several distinct flavors for the following applications: 75 | 76 | * Primary (full color): the primary version of the logo should be used the majority of the time, on any background so long as it is clearly legible 77 | * 1C (mono) in Off Black or White 78 | * 1C (mono) in Tufts Blue or Light Red 79 | 80 | Each of the 1C (mono) variants consists of one solid color, with the *F* as negative space. Use the provided symbols, do **not** fill the *F* with white, and always choose the version of the logo that achieves the most desirable contrast against the background and other elements in a given design. 81 | 82 | When using other text elements in association with FreeCAD, use the [Evolventa](https://evolventa.github.io/) font family, but don't recreate the wordmark manually. 83 | 84 | 85 | ## Scale and Whitespace 86 | 87 | To retain legibility and integrity, the primary and secondary FreeCAD logo should be displayed not smaller than 32px and 16px, respectively. 88 | 89 | To ensure that the logo is clearly visible in all applications, surround it with sufficient clear space. 90 | It must be used with enough space around the logo and should not touch the borders of the image / application or other artwork elements and text. 91 | Don't add text directly next to the logo and don't use a slogan next or under the wordmark. 92 | 93 | When used with other logos and partner brands, all logos should be of equal size and have enough distance to each other. 94 | 95 | 96 | ## Do nots 97 | 98 | To maintain consistency, the FreeCAD logo should only be used as suggested above and provided in the logo kit. 99 | You should **not** alter colors, shape, style, or apply any effects such as gradients, borders, shadows, or outlines. 100 | 101 | We have made some examples of what **not** to do when using the logo: 102 | 103 | 104 | 105 | ## PDF Guidelines 106 | 107 | Download the [FreeCAD brand guidelines](../images/guidelines.pdf) as a PDF. These are also included in the logo kit at the top of the page. 108 | 109 | 110 | [Return to Design Guide Main Page](index.md) 111 | -------------------------------------------------------------------------------- /designguide/naming.md: -------------------------------------------------------------------------------- 1 | ## Naming Convention 2 | 3 | Due to the technical nature associated with CAD and advanced programming, it is easy to fall into the trap of using terminology that is either overly descriptive or seems obvious as a developer but is obscure to the layman. Additionally, with so many functions at a user's disposal within FreeCAD, screen space comes at a high premium, and text strings can quickly change a UI/UX from being concise and efficient to awkwark and unpleasant. The following guidelines should be considered when naming/labeling functions, features and other various addons. 4 | 5 | *NOTE: This area is highly subjective as FreeCAD is translated into many languages, however english is considered the standard by which naming will be assessed. It will be up to various translators to best adhere to these guidlines as best as possible.* 6 | 7 | - Use the shortest descriptive words possible for a function. Single words are preferred, however this will not always be possible. 8 | 9 | - Broadly accepted and understood acronyms can be used in place of full words, however, these should be scrutinized closely by the design and development teams to avoid obscure references. 10 | 11 | - Avoid using common programming terms, preference should be given towards more plain language words. 12 | 13 | - For concepts already used within FreeCAD, use the same wording so those concepts remain consistent wherever possible. 14 | 15 | Efforts should be made to conserve space within the UI in order to prevent elements from needing to be resized from workbench-to-workbench or dialog-to-dialog. Word choices should be reviewed before merging a pull-request with text elements in the GUI. 16 | 17 | [Return to Design Guide Main Page](index.md) 18 | -------------------------------------------------------------------------------- /designguide/principles.md: -------------------------------------------------------------------------------- 1 | ## Principles: 2 | 3 | The following guiding principles are based on various established [Laws of UX outlined here](laws-of-ux.md). 4 | 5 | - Aesthetics - Not a replacement for good design, but helps compensate for minor flaws. Poor aesthetics can ruin an otherwise well designed functional flow.\ 6 | ([*Aesthetic-Usability Effect*](laws-of-ux.md#aesthetic-usability-effect)) 7 | 8 | - Avoid providing multiple ways to achieve the same goal within a singular workbench. Providing alternative methods seems like a benefit to the user but requires the user to process/understand why two methods exist and how they may differ.\ 9 | "There should be one-- and preferably only one --obvious way to do it."\ 10 | ([The Zen of Python](https://peps.python.org/pep-0020/#the-zen-of-python)) 11 | 12 | - When implementing functionality which is common within other workbenches, a developer should make every effort to ensure behavior of those functions remains consistent with pre-existing implementations. 13 | 14 | - Attempt to make user interactions and software responses as fluid and quick as possible. Ideally below 400ms.\ 15 | ([*Doherty threshold*](laws-of-ux.md#doherty-threshold)) 16 | 17 | - Avoid making interactive elements too small. The size of elements should be large enough to prevent a majority of 'miss-clicks'.\ 18 | ([*Fitts's Law*](laws-of-ux.md#fitts-law)) 19 | 20 | - Travel distance between functions and related interactive elements should be minimized to reduce incidence of errors.\ 21 | ([*Fitts's Law*](laws-of-ux.md#fitts-law)) 22 | 23 | - Only expose the most common/likely settings or options a user may need by default. Advanced, or infrequently used controls should be hidden but readily accessible. This minimizes time required to make choices and increases efficiency.\ 24 | ([*Hick-Hyman Law*](laws-of-ux.md#hick-hyman-law)) 25 | 26 | - Minimize superfluous options in exchange for broadly effective defaults. Advanced preferences shall be accessible via the parameter editor instead of the preferences dialog.\ 27 | ([*Hick-Hyman Law*](laws-of-ux.md#hick-hyman-law)) 28 | 29 | - When implementing features or functions which are commonly found in other software, one should consider the method by which they function. Deviations from '*reasonably expected behavior*' shall be clearly justified.\ 30 | ([*Jakob's Law*](laws-of-ux.md#jakobs-law)) 31 | 32 | - Behavior and element use across an application must remain consistent. Deviations shall be clearly justified.\ 33 | ([*Jakob's Law*](laws-of-ux.md#jakobs-law)) 34 | 35 | - Ensure functions and options are grouped logically and not dispersed randomly.\ 36 | ([*Law of Common Region*](laws-of-ux.md#law-of-common-region)) 37 | 38 | - Proper organization of like functionality in close proximity together help users understand and organize information better.\ 39 | Related elements/functions should share similar visual symbology\ 40 | ([*Law of Proximity*](laws-of-ux.md#law-of-proximity) / [*Law of Uniform Connectedness*](laws-of-ux.md#law-of-uniform-connectedness)) 41 | 42 | [Return to Design Guide Main Page](index.md) 43 | -------------------------------------------------------------------------------- /designguide/zones.md: -------------------------------------------------------------------------------- 1 | ## Zones 2 | 3 | The circle shown in the image below can be considered a 'hot zone' where a user should be able to focus attention on the work/task being performed. 4 | 5 | ![](images/focus.svg) 6 | 7 | *Note: the corners have ease of positioning of the mouse cursor. Special use of screen corners should be reserved for global application functionality only and not implemented without careful deliberation.* 8 | 9 | Below is the notional zone layout of the FreeCAD user interface, specific sizes mentioned for each zone are to be considered critical to the goal of reserving 50% of a user's display for the Main 3D View (or document area) while still providing easy access to information, navigation and tools. Each zone is described below. 10 | 11 | ![](images/zones.svg) 12 | 13 | **Title Bar:** Windows 10 standard is a height of 32 pixels. Any modifications to this area has to be carefully considered because of cross-platform compatibility and should only be done in the core of FreeCAD. Individual workbenches should not attempt to modify it. 14 | 15 | **Task Bar:** Windows 10 standard is a height of 48 pixels. This element is a fixed size and follows the same rationale and guidelines provided for the Title Bar. 16 | 17 | **Menu Bar:** Standard height is established as 32 pixels in the stylesheet. There shall be no insertion of non-standard elements (ie. QComboBox) in this area by individual workbenches. New menus can be added, however they should ideally be confined to the menu named after your specific workbench. Simple addons should insert entries into a menu titled "Accessories" if applicable. 18 | 19 | **Global Function Toolbar:** By default, FreeCAD uses a height for horizontal toolbars of 40 pixels with icons size of 24px. Total icons displayed on this toolbar shall not exceed a total of 44 in order to prevent clipping on a 1080p display. This toolbar is primarily designated for global functions across any workbench. Unused space can be populated with workbench related settings and controls (ie. grid, snap, unit, controls) rather than work features. 20 | 21 | **Workbench Navigation Bar:** This zone is reserved for a tab-bar style widget (default 32 pixels high) intended to provide easy navigation between active workbenches with a single click. This area shall remain dedicated for this purpose only. 22 | 23 | **Main View:** This area is dedicated for displaying the work being performed. Overlaying of minimal elements is allowed. Widgets overlaid in this area should be limited to the outer edges and corners, such elements shall be used sparingly and be sized and positioned with consideration for the reference resolution (1920 x 1080). 24 | 25 | **Left Dock Area:** This zone shall be used for document and/or library data access. By default this area will contain the document "Tree View". Use of overlay transparency is preferred to maximize visibility of the Main View and allow greater emphasis and focus on the work being performed. Other persistent state panels should have intermittent visibility. A toggleable state 'slide-out' panel would be preferred for such elements. All efforts should be made to constrain panels docked in this zone to 300 pixels in width. 26 | 27 | **Right Dock Area:** This zone is for interactive 'tasks' panels. Overlay transparency mode is the recommended default state for this element. These 'tasks' are for displaying options relative to workbench functions. All efforts should be made to constrain panels docked in this zone to 360 pixels in width. 28 | 29 | **Function Bar 1, 2, etc:** By default, FreeCAD will set these toolbars at a width of 40px assuming an icon size of 24px These toolbars are for holding the features/functions of a given workbench. These are docked to the far-right edge of the screen in accordance with the law of proximity in order to minimize mouse travel distance from starting a feature/task to modifying its settings. 30 | 31 | **Document Tab Bar:** This is used for tab navigation of various document windows only. By default, a height of 32px is adhered to. This area shall not be modified in order to avoid user confusion while navigating multiple open documents. 32 | 33 | **Status Bar:** The status bar provides contextual information about the position of the mouse cursor in relation to the objects in the main view. This section of the UI is also home to some global controls within FreeCAD. They are "Notifications", "Navigation Style", and "Unit Selector". Developers shall not insert non-global elements or widgets into this area. 34 | 35 | [Return to Design Guide Main Page](index.md) 36 | -------------------------------------------------------------------------------- /favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/favicon.ico -------------------------------------------------------------------------------- /gettingstarted/CLion.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Getting Started 6 | 7 | If you don't already have CLion installed, download it, license it, install it per JetBrains instructions. 8 | 9 | ### Checking out FreeCAD 10 | 11 | **Command line:** `git clone --recurse-submodules https://github.com/FreeCAD/FreeCAD` and then File -> Open or New Project on that directory. 12 | 13 | **IDE:** From upper left, choose Project from Version Control. Use https://github.com/FreeCAD/FreeCAD 14 | ![Pict8](./resources/CLionPythonDebug8.png) 15 | 16 | ### Configure Pixi Toolchain (Optional) 17 | If you choose to use Pixi to get the dependencies then you need to configure a CLion toolchain and assign it to your CMake profile. 18 | 1. Run `pixi shell` in the local FreeCAD directory to get all packages, this is also needed to update the environment after the `pixi.toml` has been changed. 19 | 2. Go to Settings → Build, Execution, Deployment → Toolchains. 20 | 3. Create a new "System" toolchain. 21 | 4. Click on "Add environment" and select "From file". 22 | 5. Enter the location of the `pixi-default.bat` for Windows or otherwise the `pixi-default.bash` script in the "Environment file" field. The file can be found in the FreeCAD repository in contrib/clion/pixi 23 | 24 | ![PixiPict1](./resources/CLionPixi1.png) 25 | 26 | 6. Go to Settings → Build, Execution, Deployment → CMake. 27 | 7. Select the "conda-[your os]-debug" or "conda-[your os]-release" preset and duplicate it. 28 | 8. Enable the duplicated profile and assign the created toolchain to this profile. 29 | 9. If on Windows, you also need to select the Visual Studio generator. 30 | 31 | ![PixiPict2](./resources/CLionPixi2.png) 32 | 33 | Note: If CMake does not detect any packages from the .pixi folder then the toolchain script may have failed. 34 | This may be resolved by using the absolute path to your FreeCAD repository in the `pixi-default.bash` script. 35 | 36 | 37 | ### Building CMake 38 | 39 | CLion should automatically refresh the CMake build for the application. You see results or rerun using the cmake 40 | selection at the lower right 41 | ![Pict9](./resources/CLionPythonDebug9.png) 42 | 43 | ### Building Application 44 | 45 | Choose a configuration ( Debug ) and a target ( FreeCADMain ) from the top bar. First time through, use the menus to 46 | run 'Build All in Debug' from the Build Menu. After that point you can generally just Run or Debug and it will build 47 | any dependencies for you. Note that if you switch branches you may sometimes need to "Rebuild All in Debug" to force 48 | a clean full rebuild. 49 | 50 | ![Pict10](./resources/CLionPythonDebug10.png) 51 | ![Pict11](./resources/CLionPythonDebug11.png) 52 | 53 | ### Running Application 54 | 55 | Use the Run or Debug Icons from the top bar shown in the prior image. 56 | 57 | ## Debugging 58 | 59 | *note* This depends on https://github.com/FreeCAD/FreeCAD/pull/16850 getting merged! 60 | 61 | While CLion supports both a C++ debugger and a Python debugger, it generally does not support 62 | embedded Python interpreters, nor debugging both simultaneously. However, there are workaround 63 | procedures that will allow this. 64 | 65 | ### Basic C++ concept 66 | 67 | CLion invokes an underlying debugger that launches or connects to the program under 68 | test. You can see this in the "Attach to Process" dialog under the Run menu. After 69 | choosing a process, you will be asked to attach with GDB or LLDB; CLion uses the 70 | appropriate API to communicate with the debugger, which uses OS specific mechanisms 71 | to control the program under test. 72 | 73 | ### Basic Python concept 74 | 75 | The pydevd debugger is run inside of the python interpreter under test. This provides 76 | a network socket, normally connected _from_ the interpreter under test to a listening 77 | socket in the controlling debugger UI. This port defaults to 5678 for non-CLion uses. CLion 78 | generates a random port number, and then passes this into the pydevd initialization code; 79 | if you run a python program then this is accomplished by directly running a shim with 80 | parameters that include the port number and the program to be debugged. In an attach 81 | scenario, CLion _launches a C++ debugger_ to inject the pydevd initialization into the 82 | running python interpreter and cause it to make the socket connection back to the UI. Note 83 | that since you generally cannot have more than one c++ debugger attached to a program, 84 | this mechanism cannot work for a program already under c++ debugging, and since it assumes 85 | that the c++ program is in fact a python process, it won't work for embedded python either. 86 | 87 | ### Technique for getting Python testing working 88 | 89 | The challenge here is to get CLion to listen on a port for the incoming connection from pydevd, 90 | and to execute pydevd on that port in the program under test. Since CLion does not support this 91 | natively, we trick it. To do this we need to have a pydevd installed in the python interpreter in 92 | FreeCAD. 93 | 94 | ### Running a basic c++ debug 95 | 96 | Simply choose the debug option to start FreeCAD, and you're good to go. 97 | 98 | ### Setting up for python debugging in CLion 99 | 100 | Install pydevd in the interpreter that FreeCAD is using. 'pip3 install pydevd' from the correct 101 | venv is one way to accomplish this. 102 | 103 | Use the settings button in the upper right, the File Menu -> Settings, or the Ctrl-Alt-S shortcut 104 | to open the settings dialog, expand the Build, Execution, Deployment tree item, and select a Python 105 | Interpreter: 106 | 107 | ![Pict1](./resources/CLionPythonDebug1.png) 108 | 109 | Switch to the Python Debugger settings, and change the Attach To Process name from python to 'Freecad' 110 | You may need to change this back if you use the IDE for other applications. 111 | 112 | ![Pict2](./resources/CLionPythonDebug2.png) 113 | 114 | Now there are three approaches here: 115 | 1. Wait for CLion 2024.3 which is supposed to have a static port listener option with a 116 | configurable port available in the 'Python Debugger' pane of the CMake profile you use. 117 | [see context](https://youtrack.jetbrains.com/issue/CPP-5797/Cross-debugging-Python-and-C#focus=Comments-27-10655987.0-0) 118 | and [see planned fix.](https://youtrack.jetbrains.com/issue/PY-21325/Add-an-ability-to-specify-debugger-port) Port should be 5679 if you use the macro below. 119 | 2. Find the attach_pydevd.py file in your CLion installation, and modify it using the 120 | contrib/clion/attach_pydevd.py.patch in the source code. Then use the macro below. 121 | 3. Use this elaborate work around: 122 | 123 | ### Running a python or simultaneous debug using the non intrusive procedure 124 | 125 | 1. You can start your FreeCAD independently, via CLion, or in c++ debug mode under CLion. 126 | 127 | 2. Regardless of the starting technique, once FreeCAD is up, if there is no code in your FreeCAD supporting 128 | CLion debugging, then: 129 | 1. Go to the python console and import pydevd. 130 | Then go ahead and pretype in the settrace call, leaving the cursor poised to enter a port name but not executing the line. 131 | 2. Alternatively, go to the Macro -> Attach to remote debugger dialog and switch to the CLion tab. 132 | 133 | ![Pict1](./resources/CLionPythonDebug6.png) 134 | 135 | 3. Return to CLion, and start Attach to Process from the run menu: 136 | 137 | ![Pict1](./resources/CLionPythonDebug3.png) 138 | 139 | 4. Find the Freecad process, which may be well down at the bottom of the list. It is the configuration 140 | from earlier that makes Freecad processes appear in the list as Python debuggable. Highlight this entry 141 | and press the Attach with Python Debugger button. 142 | 143 | ![Pict1](./resources/CLionPythonDebug4.png) 144 | 145 | 5. Now it's time to move FAST. You have about 10 to 15 seconds to complete the following: 146 | Scroll to the top of the console window and find the (random) port number that CLion has chosen to listen 147 | on. Ignore everything else: 148 | 149 | ![Pict1](./resources/CLionPythonDebug5.png) 150 | 151 | 6. Switch to the FreeCAD window and complete the port number in either the console's settrace line or the attach dialog 152 | and execute it: 153 | 154 | ![Pict1](./resources/CLionPythonDebug6.png) 155 | 156 | 7. Note the appearance of a "Connected to pydev debugger" line in the CLion console. Shortly before or after that 157 | message, you will also see the timeout of CLion's attempt to use a debugger to trigger an attach. Ignore this 158 | error. 159 | 160 | ![Pict1](./resources/CLionPythonDebug7.png) 161 | 162 | 8. Proceed to debug normally: any existing breakpoints you have either in c++ code or python code will be hit, you 163 | can step, examine variables, the whole deal. 164 | 165 | ### Running a python or simultaneous debug using updated CLion or the patched attach_pydevd.py 166 | 167 | 1. Start FreeCAD running. You can do this from any place for just a python debug; or you can launch a c++ debug 168 | in CLion for simultaneous debugging. 169 | 2. Run the contrib/clion/GetCLionDebugPort.FCMacro in FreeCAD. The cleanest way to do this is just to add it as 170 | first parameter of the FreeCAD or FreeCADCmd command line. Editing your FreeCADMain run/debug configuration in 171 | CLion is the best way to do this - set it once, and python debugging is always there whether you run a c++ debug 172 | or not, with no effective performance penalty. 173 | 174 | #### Caveats 175 | 176 | - Sometimes you may get one spurious breakpoint hit in the python debugger. Just hit the continue run button to keep 177 | going. FreeCAD triggers a python exception during startup, and the default CLion debugger settings are to break on this 178 | - condition. 179 | - The python files are copied from the source into the build directory. You must use these build directory versions 180 | of the python files if you want to set breakpoints. So if you're built to `cmake-build-debug` for instance, then you 181 | - want `cmake-debug-build/Mod/BIM/Arch.py` and not `src/Mod/BIM/Arch.py`. This also means that you need to be careful 182 | when editing files - anything in the build directory is essentially temporary and will be overwritten on the next build, 183 | but if you change something in the source directory then you need to run a build on an appropriate target to copy the 184 | changed python file to the build directory. CLion does not support specifying mapping directories for this python code, 185 | and there is no evidence of it changing soon. 186 | -------------------------------------------------------------------------------- /gettingstarted/VSCode.md: -------------------------------------------------------------------------------- 1 | 2 | # Getting started with VSCode 3 | 4 | A convenient way of working with the FreeCAD source code is to use an IDE or Integrated Development Environment. The FreeCAD repository contains a VSCode configuration which makes it particularly easy to get started with. 5 | 6 | Get VSCode here https://code.visualstudio.com/download and Git here https://git-scm.com/downloads 7 | 8 | After that go to github and create your own fork of the FreeCAD repository by clicking the fork button. Once that's done, clone your fork to your local computer that you will be using for development. 9 | 10 | Note: if you are using VSCode on an Ubuntu based Linux, please avoid using the snap version - it won't work properly with FreeCAD. 11 | 12 | ``` 13 | git clone https://github.com/YourUsername/FreeCAD --recurse-submodules 14 | ``` 15 | 16 | Open VSCode and select `File > Open Folder`, then select the folder where you have cloned your fork of the repo. 17 | 18 | Be sure to copy the `.vscode` folder inside `/contrib` to the root directory of the repo (`/.vscode`) 19 | 20 | VSCode will probably ask to install the recommended extensions: say `yes`. If it doesn't you'll need to manually install these extensions 21 | ``` 22 | ms-vscode.cpptools-extension-pack 23 | ms-python.python 24 | ``` 25 | 26 | ## Select build configuration 27 | 28 | 29 | 30 | First on the bottom left corner, in the status bar, select the build type. Options are: 31 | - debug 32 | - release 33 | - conda debug 34 | - conda release 35 | 36 | If you are using conda please select one of the respective ones. 37 | 38 | Cmake should automatically configure the project with the selected configuration. 39 | 40 | ## First build 41 | 42 | 43 | 44 | To build, either: 45 | 46 | - Run [Pixi](./index.md#pixi) (**Recommended**), or 47 | - Press `Ctrl + Shift + B`, or 48 | - Click the build button with the cog icon in the status bar, or 49 | - Run the `CMake: build` task 50 | 51 | **NOTE:** The first build takes a while. 52 | 53 | **NOTE:** If you change configuration (see step above) you will have to build again. 54 | 55 | ## Launching the built executable and debugging 56 | 57 | 58 | 59 | On the left panel go to the debug section and click the little green play button. Alternatively press `F5`. Every time you launch the debugger a build is triggered, to ensure all the latest changes you made to the code are compiled in. 60 | 61 | You should see freecad launching and the debugger attaching to the process. If an error pops up the python debugger failed to attach (there's 30 second timeout). 62 | Close FreeCAD and try launching it again. If it still fails try increasing the timeout located in the file `.vscode/scripts/WaitForDebugpy.py` 63 | 64 | To debug please refer to the [documentation](https://code.visualstudio.com/docs/editor/debugging#_debug-actions) or search for a tutorial online. 65 | 66 | **NOTE:** VSCode has an option called 'run without debugging'. This doesn't work, don't use it. If you just want to run the application launch with `F5` and ignore the debugger. 67 | 68 | **NOTE:** There's actually two debuggers: on the top panel you can see a dropdown to select either the c++ debugger or the python one. 69 | 70 | **NOTE:** Don't use the restart button. It only restarts the selected debugger, which definitely is not what you want. Instead press the stop button (which stops both debuggers) and launch again. 71 | 72 | ## Running tests 73 | 74 | 75 | 76 | The IDE supports running FreeCAD tests as well. On the left panel go to the testing section and click the play button. A build takes place and then all the tests are run and results reported. 77 | 78 | **NOTE:** This is much slower than running the `Tests_run` executable directly (run `path/to/the/build-dir/tests/Tests_run`). The video above is sped up. 79 | 80 | **NOTE:** Only c++ tests are currently integrated. Python tests are run from the `Test workbench`, or with the command `FreeCAD -t 0`, or `pixi run freecad -t 0` if you're using Pixi. 81 | 82 | Alternatively, there are two vscode tasks that can be used to run the cpp and python tests directly. 83 | 84 | **NOTE:** The debug tests button does not currently work. More configuration is needed to get that to work. 85 | 86 | ## General features of VSCode 87 | 88 | On the left panel you can see the following sections: 89 | 90 | - File manager: here you can control fils and search them with `Ctrl+F`. Press `F2` to rename the selected file. 91 | - Source control: here you can control git from the graphical user interface. 92 | - Search: powerful tool that can search all files and replace text. 93 | 94 | In the status bar on the bottom: 95 | - You can see which branch you are on and change it from there 96 | - Click the error/warning counter to open the `PROBLEMS` panel. Here you will have a convenient collection of all the compiler warnings, cmake warnings, and problems from the workspace. 97 | 98 | General editor useful shortcuts: 99 | - Rename all occurrencies of a symbol (e.g. a function name) with `F2` 100 | - Easily navigate code with the tools in the right click menu. For example `Go to definition` and `Find all references`. 101 | - Press `Ctrl+P` and type a file name to jump to that file. 102 | - Press `Ctrl+F` to search the current file. 103 | - Use `Alt+Up/Down` to move rows of text up and down. 104 | - Use `Ctrl+C/X/V` without selecting any text to copy/cut/paste entire rows. 105 | - Use `Ctrl+Shift+Up/Down` to create more cursors and edit many rows at the same time. Press `Esc` to go back to one cursor. 106 | - Hold `Ctrl` while moving left/right to move the cursor entire words at a time. 107 | - Hold `Shift` while moving left/right/up/down to select text with the cursor. 108 | 109 | Read the documentation for more: 110 | 111 | - [basic editing](https://code.visualstudio.com/docs/editor/codebasics) 112 | - [code navigaton](https://code.visualstudio.com/docs/editor/editingevolved) 113 | - [refactoring](https://code.visualstudio.com/docs/editor/refactoring) 114 | 115 | Other useful extensions, recommended but not necessary are 116 | - ```gruntfuggly.todo-tree```: Scans all the files and reports where particular keywords appear. For example `TODO`, `FIXME`, `BUG`... 117 | 118 | - ```mhutchie.git-graph```: Helps visualize git commits and branches. 119 | 120 | - ```donjayamanne.githistory```: Adds two buttons to the right-click menu: `git: view file history` and `git: view line history` 121 | 122 | 123 | ![](resources/extensions.png) 124 | 125 | - On the very left you can see the `Todo-Tree` extension reporting `TODO`s and `FIXME` 126 | - On the left half you can see the `git graph` extension showing all the commits on different branches. You can click a commit to see exactly what was modified by it. 127 | - On the right half you can see the `git history` of the DocumentObject.cpp file. 128 | -------------------------------------------------------------------------------- /gettingstarted/dependencies.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Dependencies 6 | 7 | Information about the dependencies in FreeCAD 8 | 9 | ## Overview 10 | 11 | Like most software projects, FreeCAD depends on many other packages. Most critical among these is [OpenCASCADE](https://www.opencascade.com/), 12 | the actual CAD kernel that FreeCAD is built upon. Of course, OpenCASCADE itself has its own dependencies. Many of which have *their* own 13 | dependencies, etc. The dependency graph quickly become overwhelming if you have to manually install each one. This is where package managers come 14 | in. Depending on what platform you are developing on, you have a variety of tools at your disposal to resolve these dependencies. A brief overview 15 | of the most common ones is included below. The main purpose of this document is to highlight the primary dependencies and describe what they do and 16 | why FreeCAD needs them. 17 | 18 | ## Supported versions 19 | 20 | The head of the main branch of FreeCAD, currently used for the development of FreeCAD 1.1, can be compiled from source on systems as old as the 21 | oldest currently-supported [Ubuntu LTS](https://packages.ubuntu.com/) at the time of its expected release, Ubuntu 22.04 LTS. This ties FreeCAD 22 | development to the C++20 standard, Python 3.10 and later, Qt 5.15, and the versions of the required libraries available on that system. We 23 | plan to update to requiring Ubuntu 24.04 LTS upon release of FreeCAD 1.1, with FreeCAD 1.2 only supporting compiling on that system and newer. 24 | 25 | ## Major dependencies 26 | 27 | The following is a brief overview of what each of FreeCAD's most critical 3rd-party library dependencies provide. 28 | 29 | ### OpenCASCADE 30 | 31 | OpenCASCADE Technology (OCCT) is a full-featured, professional grade CAD kernel. It was developed in 1993 and originally called 32 | CAS.CADE, by Matra Datavision in France for the Strim (Styler) and Euclid Quantum applications. In 1999 it was released as open 33 | source software, and since then it's been called OpenCASCADE. 34 | 35 | OCCT is a big and complex set of C++ libraries that provide functionality required by a CAD application: 36 | * A complete STEP compliant geometry kernel. 37 | * A topological data model and needed functions to work with shapes (cut, fuse, extrude, and many others). 38 | * Standard import and export processors for files like STEP, IGES, VRML. 39 | * A 2D and 3D viewer with selection support. 40 | * A document and project data structure with support for save and restore, external linking of documents, recalculation of design history (parametric modeling) and a facility to load new data types as an extension package dynamically. 41 | 42 | Note that the "Community Edition" of OpenCASCADE is no longer supported by FreeCAD, you must install the first-party library. 43 | The current minimum supported version is OCCT 7.3. 44 | 45 | ### Python 46 | 47 | Python is a popular all-purpose scripting language that is widely used in Linux and open source software. 48 | In FreeCAD, Python is used during compilation and also at runtime in different ways. FreeCAD itself contains 49 | hundreds of thousands of lines of Python code, and all FreeCAD Addons and Macros are written in Python. 50 | 51 | The current minimum supported version is 3.8. 52 | 53 | ### Qt 54 | 55 | Qt is one of the most popular graphical user interface (GUI) toolkits available in the open source world. 56 | FreeCAD uses this toolkit to draw the interface of the program, as well as to provide some advanced networking functionality 57 | and translation facilities. FreeCAD currently provides primary support for Qt v5.14 - v5.15, and Qt 6.4 and later. 58 | 59 | Further information about Qt libraries and their programming documentation are available at [Qt Documentation](https://doc.qt.io/). 60 | 61 | ### PySide and Shiboken 62 | 63 | Shiboken is the Python binding generator that Qt for Python uses to create the PySide module, in other words, it is the system that 64 | is used to expose the Qt C++ API to the Python language. FreeCAD's Python code uses the PySide library to draw its user interface elements. 65 | FreeCAD provides primary support for PySide2 (corresponding to Qt5) and PySide6 (corresponding to Qt6). 66 | Python developers should import `PySide` (with no numeric suffix) -- at compile-time FreeCAD's build system will generate the appropriate 67 | version. 68 | 69 | ### Coin3D 70 | 71 | The dependencies Coin, Quarter, and Pivy are collectively part of the Coin3D library system. Coin3D is a high-level 3D graphics library 72 | with a C++ application programming interface. It uses scenegraph data structures to render real-time graphics suitable for all kinds 73 | of scientific and engineering visualization applications. 74 | 75 | Coin3D (Open Inventor) is used as the 3D viewer in FreeCAD because the OpenCASCADE viewer (AIS and Graphics3D) has limitations and performance 76 | bottlenecks, especially with large-scale engineering rendering; other things like textures or volumetric rendering are not entirely supported 77 | by the OpenCASCADE viewer. 78 | 79 | ### Boost 80 | 81 | The Boost C++ libraries are collections of peer-reviewed, open source libraries that extend the functionality of C++. They are intended to 82 | be widely useful across a broad spectrum of applications, and to work well with the C++ Standard Library. The Boost license is designed 83 | to encourage their use in both open source and closed source projects. Over time, many Boost libraries end up incorporated into the C++ standard 84 | library itself. As this happens, developers should work to transition their code to the `std::` variant rather than the `boost::` variant. Note 85 | that exception is made for `boost::regex`, which as of this writing is still considerably faster than its `std::regex` counterpart. 86 | 87 | ### Xerces-C++ 88 | 89 | Xerces-C++ is a validating XML parser written in a portable subset of C++. Xerces-C++ makes it easy to give your application the ability to 90 | read and write XML data. A shared library is provided for parsing, generating, manipulating, and validating XML documents. Xerces-C++ is 91 | faithful to the XML 1.0 recommendation and associated standards. The parser is used for saving and restoring parameters in FreeCAD. 92 | 93 | ### Eigen3 94 | 95 | Eigen is a C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms. If you just want to use Eigen, 96 | you can use the header files right away. There is no binary library to link to, and no configured header file. Eigen is a pure template library 97 | defined in the headers. Eigen is used in FreeCAD for many vector operations in 3D space. 98 | 99 | ### Zipios++ 100 | 101 | Zipios++ is a C++ library for reading and writing .zip files. Access to individual entries is provided through standard C++ iostreams. A 102 | simple read-only virtual file system that mounts regular directories and .zip files is also provided. The structure and public interface 103 | of Zipios++ are loosely based on the java.util.zip package of Java. 104 | 105 | FreeCAD's native file format .FCstd is in reality a .zip file that stores and compresses other types of data within it, such as BREP 106 | and XML files. Therefore, Zipios++ is used to save and open compressed archives, including FreeCAD files. 107 | 108 | A copy of Zipios++ is included in the source code of FreeCAD so it is compiled together with it. If you want to use an external Zipios++ 109 | library, provided by your operating system, you may set `-DFREECAD_USE_EXTERNAL_ZIPIOS=ON` with cmake. 110 | 111 | Zipios++ uses the Zlib library to perform the actual decompression of files. 112 | 113 | ### Zlib 114 | 115 | Zlib is designed to be a free, general-purpose, lossless data-compression library for use on any computer hardware and operating system. 116 | It implements the DEFLATE compression algorithm commonly used in .zip and .gzip files. 117 | 118 | A copy of this library is included in the source code of FreeCAD so it is compiled together with it. 119 | 120 | ## Dependency management 121 | 122 | Each OS uses different mechanisms to supply dependencies. These mechanisms are typically designed such that installing a single dependency 123 | also automatically installs all of *its* dependencies, eliminating the need for you to manually install every single dependency by hand. 124 | 125 | ### Linux 126 | 127 | As a general rule in Linux, you should use your system's package manager to install dependencies, including Python libraries, rather than using `pip`. 128 | Unfortunately, different distributions use different names for the various packages, so it is sometime challenging to determine exactly what needs 129 | to be installed. It is very common to have to adjust the one-line command below for your system by removing failing packages and locating alternates 130 | (usually provided under a different name). 131 | 132 | A single command to install the dependencies on 22.04.3 LTS Ubuntu-based systems: 133 | ```sh 134 | sudo apt install cmake cmake-gui libboost-date-time-dev libboost-dev libboost-filesystem-dev libboost-graph-dev libboost-iostreams-dev libboost-program-options-dev libboost-python-dev libboost-regex-dev libboost-serialization-dev libboost-thread-dev libcoin-dev libeigen3-dev libgts-bin libgts-dev libkdtree++-dev libmedc-dev libocct-data-exchange-dev libocct-ocaf-dev libocct-visualization-dev libopencv-dev libproj-dev libpyside2-dev libqt5opengl5-dev libqt5svg5-dev qtwebengine5-dev libqt5x11extras5-dev libqt5xmlpatterns5-dev libshiboken2-dev libspnav-dev libvtk7-dev libx11-dev libxerces-c-dev libzipios++-dev occt-draw pyside2-tools python3-dev python3-matplotlib python3-packaging python3-pivy python3-ply python3-pyside2.qtcore python3-pyside2.qtgui python3-pyside2.qtsvg python3-pyside2.qtwidgets python3-pyside2.qtnetwork python3-pyside2.qtwebengine python3-pyside2.qtwebenginecore python3-pyside2.qtwebenginewidgets python3-pyside2.qtwebchannel python3-markdown python3-git qtbase5-dev qttools5-dev swig libyaml-cpp-dev 135 | ``` 136 | A single command to install the dependencies on 24.04 LTS Ubuntu-based systems: 137 | ```sh 138 | sudo apt install cmake cmake-qt-gui libboost-date-time-dev libboost-dev libboost-filesystem-dev libboost-graph-dev libboost-iostreams-dev libboost-program-options-dev libboost-python-dev libboost-regex-dev libboost-serialization-dev libboost-thread-dev libcoin-dev libeigen3-dev libgts-bin libgts-dev libkdtree++-dev libmedc-dev libocct-data-exchange-dev libocct-ocaf-dev libocct-visualization-dev libopencv-dev libproj-dev libpyside2-dev libqt5opengl5-dev libqt5svg5-dev qtwebengine5-dev libqt5x11extras5-dev libqt5xmlpatterns5-dev libshiboken2-dev libspnav-dev libvtk9-dev libx11-dev libxerces-c-dev libzipios++-dev occt-draw pyside2-tools python3-dev python3-matplotlib python3-packaging python3-pivy python3-ply python3-pyside2.qtcore python3-pyside2.qtgui python3-pyside2.qtsvg python3-pyside2.qtwidgets python3-pyside2.qtnetwork qtbase5-dev qttools5-dev swig libyaml-cpp-dev 139 | ``` 140 | To install dependencies on Fedora systems (Derived from the [RPM spec](https://src.fedoraproject.org/rpms/freecad)): 141 | ```sh 142 | sudo dnf install clang cmake gcc-c++ gettext dos2unix doxygen swig graphviz gcc-gfortran desktop-file-utils freeimage-devel libXmu-devel mesa-libGL-devel mesa-libGLU-devel libglvnd-devel opencascade-devel Coin4-devel python3-devel python3-matplotlib python3-pivy boost-devel eigen3-devel tbb-devel qt5-qtbase-devel qt5-qtsvg-devel qt5-qtxmlpatterns-devel qt5-qttools-devel qt5-qttools-static qt5-qtwebengine-devel xerces-c xerces-c-devel libspnav-devel python3-shiboken2-devel python3-pyside2-devel pyside2-tools smesh-devel zipios++-devel python3-pycxx-devel libicu-devel vtk-devel med-devel libkdtree++-devel libappstream-glib python3-pivy python3-matplotlib python3-collada python3-pyside2 qt5-assistant 143 | ``` 144 | To install dependencies on Arch Linux based systems: 145 | ```sh 146 | sudo pacman -S boost boost-libs cgns cmake coin eigen fmt git glew graphviz jsoncpp libharu liblas libspnav med-openmpi netcdf ninja nlohmann-json openmpi openvdb opencascade openvr ospray pdal pugixml pyside2 pyside2-tools python-gitpython python-markdown python-matplotlib python-mpi4py python-pip python-pivy python-ply python-shiboken2 python-yaml qt5-svg qt5-tools qt5-webengine qt5-x11extras qt5-xmlpatterns shiboken2 swig utf8cpp verdict xerces-c 147 | ``` 148 | 149 | ### Windows 150 | 151 | By far the easiest way to install the dependencies for Windows is to download the pre-packaged "LibPack" from https://github.com/FreeCAD/FreeCAD-LibPack/releases. This 152 | download provides a single source for all of FreeCAD's library dependencies. 153 | 154 | ### Mac OS 155 | 156 | Mac OS does not have a built-in package management system, but it is possible to use [Homebrew](https://brew.sh) to install FreeCAD's dependencies. Note however that 157 | this can be a very challenging process because Homebrew often updates libraries to new versions before downstream packages are updated to accomodate them: 158 | it is usually necessary for a developer to manually extract an old dependency for installation as a custom "tap". 159 | 160 | An alternative is to use Conda to create your Mac OS build system. Documentation of this process is a [work-in-progress by several users on the FreeCAD Forum](https://forum.freecad.org/viewtopic.php?t=70038). 161 | -------------------------------------------------------------------------------- /gettingstarted/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Getting Started 6 | 7 | Covers how to set up a build environment for contributing to FreeCAD 8 | 9 | Working on FreeCAD is similar to working on may other open-source projects. This guide provides a short overview of the process. Much more information can be found at https://wiki.freecad.org. 10 | 11 | ## Build Environment 12 | 13 | To work on FreeCAD you will need CMake, git, a code editor, a C++ compiler, and a Python interpreter. Many different combinations work: 14 | 15 | - On Linux, it's common to use vim, emacs, KDevelop, or CLion as your editor. Compilation with GCC and Clang is supported. 16 | - On Windows we support Visual Studio, Visual Studio Code, and CLion for development, all using the MSVC compiler toolchain. 17 | - On MacOS you will need to install the XCode command line tools, and can use XCode, Visual Studio Code, or CLion as your editor. 18 | 19 | Other combinations may work as well, these are just the ones that you will be able to get help with most readily on the [FreeCAD Forum](https://forum.freecad.org). 20 | 21 | ## Dependencies 22 | 23 | See also [Dependencies](dependencies.md) 24 | 25 | FreeCAD depends on many other open source projects to provide the basic foundations of the program. There are many ways of installing these dependencies: for details and the complete list, see the following Wiki pages: 26 | 27 | - Linux: [https://wiki.freecad.org/Compile_on_Linux](https://wiki.freecad.org/Compile_on_Linux) 28 | - Windows: [https://wiki.freecad.org/Compile_on_Windows](https://wiki.freecad.org/Compile_on_Windows) 29 | - Mac: [https://wiki.freecad.org/Compile_on_MacOS](https://wiki.freecad.org/Compile_on_MacOS) 30 | 31 | ### Pixi 32 | 33 | One of the easiest ways of creating a standalone FreeCAD build environment with its dependencies in a way that does not affect the rest of your system is to use 34 | [Pixi](https://pixi.sh/latest/). 35 | 36 | 1. Install `pixi` using the following command: 37 | 38 | - Windows (PowerShell): `iwr -useb https://pixi.sh/install.ps1 | iex` 39 | - Linux/macOS: `curl -fsSL https://pixi.sh/install.sh | bash` 40 | 41 | 2. Configure FreeCAD for your platform. There are additional steps necessary on Windows outlined in the next subsection. 42 | 43 | `pixi run configure` 44 | 45 | 3. Build FreeCAD 46 | 47 | `pixi run build` 48 | 49 | If your computer has less ram than is necessary to run a compiler per processor core, then you can reduce the number of parallel compiler jobs. For example, if you wish to limit to 4 parallel compiler processes use the following command: 50 | 51 | `pixi run build -j 4` 52 | 53 | 4. Run FreeCAD 54 | 55 | `pixi run freecad` 56 | 57 | In general, there will be no need to re-run the configure command as it will be automatically run by `pixi run build` if needed. However, there may be times in which a git submodule is added or updated. To integrate these changes, the command `pixi run initialize` will run the commands necessary. 58 | 59 | ### Pixi on Windows 60 | 61 | Pixi uses the `conda-forge` packages, including the `compilers` metapackage to bring in the platform-specific compiler support. On Windows, it is expected that Microsoft Visual C++ has been installed and matches the version used by the `conda-forge` team, which is [Visual Studio Community 2019](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products). 62 | 63 | The Visual Studio Installer may be used to install Visual Studio Community 2019 alongside newer versions of Visual Studio. Ensure all of the necessary components are installed: 64 | 65 | 1. Open the Visual Studio Installer 66 | 2. Click `modify` for Visual Studio 2019. 67 | 68 | ![Visual Studio 2019](resources/vs2019-modify.png) 69 | 70 | 3. Make sure to select `Desktop development with C++` under the `Desktop & Mobile` section. Ensure that the necessary optional items are selected on the right. 71 | 72 | ![vs2019-dev-C++](resources/vs2019-cpp.png) 73 | 74 | ## Setting up for Development 75 | 76 | 1. Fork [https://github.com/FreeCAD/FreeCAD](https://github.com/FreeCAD/FreeCAD) on GitHub 77 | 2. Clone your fork: for example, on the command line you can use `git clone --recurse-submodules https://github.com/YourUsername/FreeCAD FreeCAD-src` 78 | 3. Set up `pre-commit` (our automatic code-formatter and checker): 79 | 80 | 81 | - Install `pre-commit` (either using your system package manager or pip): 82 | - Debian/Ubuntu: `apt install pre-commit` 83 | - Fedora: `dnf install pre-commit` (Fedora) 84 | - Arch Linux: `pacman -S pre-commit` 85 | - Other (pip in PATH): `pip install pre-commit` 86 | - Other (pip not in PATH): `python -m pip install pre-commit` 87 | - On a command line, change into your FreeCAD clone, e.g. `cd FreeCAD-src` 88 | - Run `pre-commit install` (or `python -m pre-commit install`, depending on your PATH) 89 | 90 | 91 | 92 | 4. We **strongly** recommend doing an out-of-source build, that is, build FreeCAD and put all generated files in a separate directory. Otherwise, the build files will be spread all over the source code and it will be much harder to sort out one from the other. A build directory can be created outside the FreeCAD source folder or inside: 93 | 94 | - `mkdir build` 95 | - `cd build` 96 | 97 | 5. Run CMake, either in via the CMake GUI or on the command line see the wiki compilation page for your operating system for a detailed list of options. 98 | 6. CMake will generate project files that can be read by your IDE of choice. See your IDE's documentation for details. In general: 99 | 100 | - On Linux, compile with a command like `cmake --build /path/to/FreeCAD-src` run from your build directory ( or `cmake --build ..` if your build directory is inside FreeCAD-src). 101 | - On Windows with Visual Studio, build the "ALL_BUILD target" (you will have to change the path to the final executable the first time you try to run that target). 102 | - On Mac on the command line use `cmake --build /path/to/FreeCAD-src` from your build directory, or if using CLion be sure to "Build All" the first time you run. 103 | 104 | 7. If you plan on submitting a PR, create a branch: 105 | 106 | - `git branch fixTheThing` 107 | - `git checkout fixTheThing` (or both commands in one go: `git checkout -b fixTheThing`) 108 | 109 | ## Running and Debugging 110 | 111 | - [Visual Studio Code](./VSCode.md) 112 | - [CLion](./CLion.md) 113 | 114 | ## Submitting a PR 115 | 116 | The basic process is: 117 | 118 | 1. Write some code (and possibly some unit tests) 119 | 2. `git add file1.cpp file2.cpp` 120 | 3. `git commit -m "Sketcher: Fixed bug in constraints" -m "Added foo to bar. Fixes #1234."` 121 | - When running `git commit` our pre-commit hooks will run to check your code. If the scripts had to make changes, you will have to `git add` the changed files and run `git commit` again. 122 | 4. `git push` to send your changes to GitHub 123 | 5. Visit https://github.com/FreeCAD/FreeCAD -- at the top of the screen you should see a yellow banner suggesting you create a Pull Request. Follow the instructions on the site to get the process started. 124 | 125 | ## PR Review Process ## 126 | 127 | Maintainers review PRs on a rolling basis throughout the week, and also in a more concentrated review meeting on Mondays 128 | (see the [FreeCAD Events Calendar](https://freecad.org/events.php) for the exact date and time in your timezone). When reviewing, 129 | Maintainers strive to uphold the tenets of the [CONTRIBUTING.md](https://github.com/FreeCAD/FreeCAD/blob/main/CONTRIBUTING.md) 130 | document. These meetings are open to the public and all developers are welcome to attend: particularly if you have a PR under review, 131 | you may be able to accelerate that process by being present to address and questions or concerns that arise. You can also participate 132 | in the process by reviewing PRs yourself. Although only Maintainers may merge PRs, anyone is welcome to test and provide feedback, and 133 | Maintainers take that feedback into consideration when evaluating PRs. Any time you can contribute to the project is appreciated! 134 | 135 | To expedite the PR review process, consider the following guidelines: 136 | 1) If your PR is still a work-in-progress, please mark it as a "Draft" so that Maintainers don't spend time reviewing something that is not yet ready to be merged. 137 | 2) If you get a question on your PR, it is unlikely to be merged until you respond to that question (particularly if the question is from a Maintainer). 138 | 3) The PR review meeting proceeds by going linearly through a list of ready-to-review PRs sorted by least-recently-updated: the goal is that no under-review PR ever sits for more than a week without action. 139 | 4) Adding automated tests (in Python or C++) can greatly expedite the review process by providing clear demonstration of how the new code works, and what problem it solves. 140 | 5) A good description in your PRs submission text helps Maintainers determine who is best suited to evaluate a PR, and prevents wasting time sorting through the code itself to figure out who should be looking at it. 141 | 6) FreeCAD's Maintainer team is currently quite small, and sometimes the Maintainer responsible for a certain part of the code is unable to attend the review meeting: this sometimes unavoidably delays the merge process through no fault of the submitter. We ask for your patience as we work to grow our team. 142 | 7) It helps the merge process if you can ensure you have a clean commit history in your PR, squashing any intermediate work and only retaining separate commits for logically separate parts of the PR (in most cases we hope that this is only a single commit). 143 | -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPixi1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPixi1.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPixi2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPixi2.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug1.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug10.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug11.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug2.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug3.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug4.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug5.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug6.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug7.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug8.png -------------------------------------------------------------------------------- /gettingstarted/resources/CLionPythonDebug9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/CLionPythonDebug9.png -------------------------------------------------------------------------------- /gettingstarted/resources/build.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/build.mp4 -------------------------------------------------------------------------------- /gettingstarted/resources/configure.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/configure.mp4 -------------------------------------------------------------------------------- /gettingstarted/resources/debug.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/debug.mp4 -------------------------------------------------------------------------------- /gettingstarted/resources/extensions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/extensions.png -------------------------------------------------------------------------------- /gettingstarted/resources/testing.mp4: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/testing.mp4 -------------------------------------------------------------------------------- /gettingstarted/resources/vs2019-cpp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/vs2019-cpp.png -------------------------------------------------------------------------------- /gettingstarted/resources/vs2019-modify.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/gettingstarted/resources/vs2019-modify.png -------------------------------------------------------------------------------- /images/FreeCAD-symbol.svg: -------------------------------------------------------------------------------- 1 | 2 | 14 | FreeCAD-symbol 16 | 18 | 20 | 21 | 23 | FreeCAD-symbol 24 | 25 | 26 | Sebastian Tabares Amaya (sytabaresa), Max Wilfinger (maxwxyz) 27 | 28 | 29 | 30 | 31 | The FreeCAD project association AISBL (FPA) 32 | 33 | 34 | 2024-06-01 35 | A white letter F on a background that is split diagonally in half, blue on the bottom with a shape of a gear and red on the top. 36 | 37 | 38 | 39 | 43 | 47 | 51 | 55 | 56 | -------------------------------------------------------------------------------- /images/FreeCAD-wordmark.svg: -------------------------------------------------------------------------------- 1 | 2 | 14 | FreeCAD-wordmark 16 | 18 | 23 | 25 | 26 | 28 | FreeCAD-wordmark 29 | 2024-06-01 30 | 31 | 32 | Sebastian Tabares Amaya (sytabaresa), Max Wilfinger (maxwxyz) 33 | 34 | 35 | 36 | 37 | The FreeCAD project association AISBL (FPA) 38 | 39 | 40 | 41 | 42 | 43 | 46 | 50 | 54 | 58 | 62 | 63 | 64 | -------------------------------------------------------------------------------- /images/guidelines.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/images/guidelines.pdf -------------------------------------------------------------------------------- /images/logo_kit.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/images/logo_kit.zip -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | # FreeCAD Developers Guide 2 | 3 | Welcome to the FreeCAD Developer's Guide! This is a work-in-progress, so please feel free to submit Issues and Pull Requests when you find areas that need work. 4 | 5 | ### [Roadmap](./roadmap/index.md) 6 | Describes the broad objectives for FreeCAD Development 7 | 8 | ### [Getting Started](./gettingstarted/index.md) 9 | How to set up a development environment to work on FreeCAD. 10 | 11 | ### [Design Guide](./designguide/index.md) 12 | Covers guidelines for User Experience, Interaction and Interface in FreeCAD. 13 | 14 | ### [Code Formatting Guide](./codeformatting/index.md) 15 | Covers the C++ and Python code formatting guidelines. 16 | 17 | ### [Good Practices / Code Review Guide](./bestpractices/index.md) 18 | Covers the C++ and Python code best practices and tips for code reviewers. 19 | 20 | ### [Maintainers Guide](./maintainersguide/index.md) 21 | Gives guidelines to maintainers about code reviews and merge procedures. 22 | 23 | ### [Technical Guide](./technical/index.md) 24 | A guide for developers learning their way around the FreeCAD codebase. 25 | -------------------------------------------------------------------------------- /maintainersguide/git.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Git and Github 6 | 7 | ## Checking out PRs locally for review 8 | 9 | Git can [checkout pull requests from a remote repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally). This makes it easier to review pull requests locally, and to run tests against them. 10 | 11 | ## Configuring Git to make checkout easier. 12 | 13 | You can modify your .gitconfig file to include the PR namespace. This allows easier checkout of PRs and also 14 | shows the PRs in graphical tools like gitk. 15 | 16 | ### edit the .git/config file 17 | 18 | Make sure that you have a remote defined in your .git/config file that corresponds to the main FreeCAD repo. 19 | Ideally, this remote is named "upstream". If you don't have this remote defined, you can add it like this: 20 | 21 | ```bash 22 | [remote "upstream"] 23 | url = git@github.com:FreeCAD/FreeCAD.git 24 | fetch = +refs/heads/*:refs/remotes/upstream/* 25 | ``` 26 | 27 | ### add the PR namespace 28 | add a second fetch line to the upstream remote definition. This line will fetch the PR namespace from the upstream repo. 29 | ``` 30 | fetch = +refs/pull/*/head:refs/remotes/upstream/pr/* 31 | ``` 32 | 33 | ### now you can fetch PRs with the command 34 | ```bash 35 | git fetch upstream 36 | ``` 37 | 38 | ### checkout a PR 39 | ```bash 40 | git checkout upstream/pr/1234 41 | ``` 42 | -------------------------------------------------------------------------------- /maintainersguide/teams.md: -------------------------------------------------------------------------------- 1 | There are several working groups which assist the maintainers by focusing on key areas. While these groups do not have formal oversight of the FreeCAD code base, the maintainers frequently ask them to review Pull Requests and may defer to the working groups for expert opinion. The working groups are self-governing and generally open to contributors. 2 | 3 | ## Design Working Group (DWG) 4 | ### Mission 5 | The Design Working Group provides comment, review, and feedback for interface changes while working with developers and project maintainers proposing solutions to improve the overall consistency, coherence, and flow of FreeCAD's user experience across all platforms. 6 | ### Contact Info 7 | The DWG coordinates and engages in real-time discussions on the FreeCAD Discord server and GitHub. 8 | https://discord.gg/Juv7cwN85R 9 | 10 | ## CAD Working Group (CWG) 11 | ### Mission 12 | The role of the CAD working group is to provide input from professional CAD users (both mechanical background and achitectural background). The goal is to propose new features to follow industrial practice, find issues about existing features, and give advice to contributors wanting to solve issues or implement new features. Opinions of the CWG are non-binding. 13 | ### Contact Info 14 | The DWG coordinates and engages in real-time discussions on the FreeCAD Discord server and GitHub. 15 | https://discord.gg/DePggHgxcx 16 | 17 | ## Code Quality Working Group (CQWG) 18 | 19 | ### Mission 20 | <--TBD--> 21 | ### Contact Info 22 | <--TBD--> 23 | -------------------------------------------------------------------------------- /roadmap/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Roadmap 6 | 7 | The roadmap provides broad objectives for the direction of FreeCAD development. 8 | 9 | # Development Roadmap 10 | 11 | This document describes several high-level objectives for the FreeCAD project. Rather than being a laundry list of development tasks, it focuses on a small set of strategic initiatives that, if achieved, will move FreeCAD closer to an ideal future state. 12 | 13 | You can read more about the [rationale for having a roadmap](rationale.md). 14 | 15 | This roadmap outlines broad strategic objectives. Code contributions from developers will always be evaluated on their merits but are more likely to receive timely attention and be successfully merged if they are consistent with the stated objectives of this roadmap. 16 | 17 | # The "Next" Release 18 | 19 | These objectives described here are very broad. Some of them are very ambitious and will take a long time to achieve. Others will never be fully achieved or 'done'. For that reason, it's helpful to pick a specific set of goals to focus on for the next release. [This page](next.md) broadly describes the major goals for the next release. 20 | 21 | ## Objective: Model stability 22 | 23 | Robust, stable models are a necessary precursor to widespread adoption of FreeCAD. Some types of breakage are the unavoidable result of poor design practices by the user but FreeCAD must commit itself to reducing or eliminating as many causes of breakage as possible. Focus areas include: 24 | 25 | 1. Toponaming Resolution and Optimization 26 | 2. Reduction of sketcher solver errors 27 | 3. UI/UX features that promote better modeling practices and avoid brittleness. 28 | 29 | 1. Make good practices easier 30 | 2. Remove / replace tools that allow unstable results 31 | 4. Improved stability around linked documents 32 | 33 | ## Objective: Assembly 34 | 35 | Assembly is a core feature of modern CAD systems. Without an integrated assembly capability, users are forced to use one of several add-on options. With competing alternatives available, collaboration and interoperability is negatively affected. Adoption of an assembly workbench should consider, at a minimum, a base set of features including 36 | 37 | 1. An assembly data format. A data standard for the representation of assembly information in the FreeCAD document. The standard should be well thought-out and usable both by the integrated solution as well as add-on options. 38 | 2. A license-compatible solver or the option to include a solver at a later date 39 | 3. A minimum set of features to satisfy the 80+% of requirements of typical users 40 | 41 | ## Objective: Flatten the learning curve 42 | 43 | CAD is hard. These are complicated and powerful tools and the user should be expected to invest appropriate time to learn to use them well. However, UI/UX inconsistency makes the learning process more difficult than it need be. The FreeCAD community must pursue a program of UI normalization to make learning FreeCAD easier. 44 | 45 | The first step in this process is to stop making things worse by accepting UI submissions that are poorly designed or implemented. Focus areas: 46 | 47 | 1. Creation of a UI/UX ‘style book’. This would be a guidebook for developers to follow when creating core and add-on functionality. The style book would also be useful when evaluating new submissions that affect user experience. Eventually, the style book standards can be used to ‘score’ existing workbenches and identify opportunities for improvement. 48 | 2. A ‘first run’ wizard to familiarize the user with essential customizations and features. 49 | 3. Reduce confusing UI elements 50 | 1. Eliminate redundant tools 51 | 2. Suppress infrequently-used workbenches 52 | 3. Consolidate settings, preferences, and other customization tools 53 | 4. Make toolbar placement more predictable and stable 54 | 4. Toolbar placement consistency 55 | 5. Make tasks fail safe. Tasks should always be in transactions and ‘undo’ cleanly. Red errors in the console are unacceptable for normal workflow. 56 | 6. Normalize the use of terminology both within FreeCAD and, when possible, with external standards. 57 | 7. Improve support for materials and implement consistently across all workbenches 58 | 59 | ## Objective: Seamless Extensibility 60 | 61 | FreeCAD has an addon manager to allow the user to add niche features. This provides two important functions. First, it allows the core application to remain leaner and avoid bloat. Second, it allows for competing solutions early on. Our approach to addons, however, has been somewhat undisciplined. As a result, the quality of addons is very uneven. Some are excellent and behave like native parts of the application. Others feel and behave inconsistently. Still others are completely broken or unmaintained. If we want the addon capability to serve both purposes, additional development is needed. Focus areas include: 62 | 63 | 1. Improve the Addon Manager workbench to make it easier for users to find good well-maintained addons. Maybe a ‘Featured’ section if addon workbench has a responsive maintainer, minimum open bugs. Maybe a user review? Without some status, we could end up with lots of cruft polluting the the manager. 64 | 2. Establish standards for addons to meet to achieve a ‘recommended’ or ‘featured’ status. Featured Addons should 65 | 1. Have an engaged maintainer 66 | 2. Have minimal high priority open issues tickets 67 | 3. Comply with published style book 68 | 4. Support translation 69 | 5. Support unit schema 70 | 6. Install and function cleanly with only the addon manager. 71 | 3. Improve Scriptability 72 | 1. Improved editor / support external editor 73 | 2. Native debugger 74 | 3. Improved API 75 | 76 | ## Objective: Have the best documentation possible 77 | 78 | Documentation has become as important as the FreeCAD application itself. Good documentation can offer a bridge to new users and smooth the learning curve. It can make all the difference between an application that is hard to use and one that is easy to learn. 79 | 80 | The FreeCAD documentation is generally in a very good state already. But it could, and should, go much further. Focus areas include 81 | 82 | 1. Low-friction to revision through the browser 83 | 2. Git-trackable 84 | 3. Versions of the documentation that match software versions 85 | 4. Good translation support 86 | 5. Support for off-line readers 87 | 6. Natural integration of Developer / API documentation 88 | 89 | ## Objective: UI modernization and beautification 90 | 91 | We want the FreeCAD application to be both efficient and attractive. We want it to integrate well with the rest of the desktop experience, to be responsive and to be delightful to use. Focus areas include: 92 | 93 | 1. User customization 94 | 1. themes 95 | 2. Modern UI concepts 96 | 1. Eg “pie menu” 97 | 2. Context menus 98 | 3. Ribbon Bar 99 | 3. Efficient use of screen area 100 | 1. Transparency 101 | 2. Multi-screen support 102 | 4. Enhanced visualizaton 103 | 1. Shadows 104 | 2. Simplified ray tracing and rendering 105 | 106 | ## Objective: Streamlined workflow 107 | 108 | Performing common and repetitive tasks should be as effortless as possible. FreeCAD developers should commit themselves to building efficient workflows throughout the application. This means minimizing clicks and unnecessary dialogs. It means adding dedicated tools for routine functions rather than relying on generalized tools that may require more steps. It means anticipating and giving the user efficient access to information when and where they need it. Focus areas include: 109 | 110 | 1. Better and consistent measuring tools 111 | 2. Improve sketcher : 112 | 1. Missing tools : 113 | 1. Offset tool. 114 | 2. Circular pattern 115 | 3. Usable rectangular array. 116 | 4. Constrain contextually. 117 | 3. Seamless copy-paste of geometries/sketches 118 | 4. Uniform selection modes 119 | 5. Uniform approach to user parameters 120 | 6. Simplified access to commonly needed data 121 | 1. Volume 122 | 2. Mass 123 | 3. Moment 124 | 4. Center of Gravity 125 | 5. Surface area 126 | 7. Text alignment tool 127 | 128 | ## Objective: Lower Barriers to Entry 129 | 130 | FreeCAD has an enormous number of functions and for a new user, there is no obvious way to use just a task oriented subset. It should be possible for new users to access a subset of FreeCAD functionality, say on the level of a TinkerCAD. As they gain experience, they can use additional functions. 131 | 132 | FreeCAD has a major terminology problem for new users. We have a Part workbench that doesn't make Parts and a Part Design workbench that isn't used to design Parts. We have Pads and Extrudes, Pockets and Cuts, Fuses and Unions, etc. We have a Part container and a Group container(?) but no core functions to populate a container (ex a core assembly function).. 133 | 134 | Forum comment regarding nomenclature: [https://forum.freecad.org/viewtopic.php?p=669869#p669869](https://forum.freecad.org/viewtopic.php?p=669869#p669869) 135 | 136 | ## Objective: Prevent Shooting Yourself in the Foot 137 | 138 | FreeCAD allows users to do things that are known to build fragile models, such as building features based on variable foundations (ex Sketches on Faces, Dimensions based on drawing lines). We even have icons and commands for doing this. FreeCAD should prevent "dangerous" actions, convert them behind the scenes to safe actions or at least provide a warning about unsafe practices. 139 | -------------------------------------------------------------------------------- /roadmap/next.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | 6 | # Next Release 7 | 8 | Releasing an official 1.0 release is a major milestone as well as a psychologically important event for the project. It is a signal to the world that FreeCAD is ready for production use, and that it is a mature, stable, and reliable tool for the job. 9 | 10 | The criteria for when FreeCAD would be ready for 1.0 status has been debated for a long time. In general, the consensus has been that the software should be both feature complete and stable. Feature completeness means that it has the major features a user would expect from a mature CAD application, not that it has ALL the features we desire or can imagine. 11 | 12 | Stability means that the software does not crash routinely and that user models are not corrupted by normal use. It does not mean that the software is bug free, or that it is perfect. It does mean that the software is reliable enough to be used in production, and that it is not likely to cause data loss or other major problems. 13 | 14 | At this time, we are setting four major goals to be completed for version 1.0. When 1.0 is released, it will likely contain many more features and improvements than these four but we will not release 1.0 until these four are achieved. 15 | 16 | - Mitigating the topological naming problem 17 | - An integrated assembly workbench 18 | - A unified Material system 19 | - Improved initial user experience 20 | 21 | ## Topological Naming Problem 22 | 23 | The toponaming problem has been widely discussed and work is proceeding to resolve it. 24 | 25 | ### Reference 26 | - [original issue](https://github.com/FreeCAD/FreeCAD/issues/8432) 27 | - [Github Project](https://github.com/orgs/FreeCAD/projects/2) 28 | 29 | 30 | 31 | ## Assembly Workbench 32 | 33 | Building multi-part assemblies is something users expect a modern CAD system to do. FreeCAD has multiple add-on options but lacks an integrated Assembly workbench. Version 1.0 will address this deficiency. The integrated workbench delivered in 1.0 will be minimally viable. It will provide the core functionality users need but will likely be less capable than the addon options currently available. Goals for this release are modest and include 34 | - An intuitive and user-friendly user interface 35 | - An integrated solver to resolve assembly constraints 36 | - A standard API for assemblies that external workbench authors can use to be compatible with both that workbench and each other. 37 | 38 | ### Reference 39 | - [Ondsel Blog Series](https://ondsel.com/blog/default-assembly-workbench-1/) 40 | - [Github Project](https://github.com/orgs/FreeCAD/projects/7) 41 | 42 | 43 | ## Material System 44 | 45 | The existing material capability is limited and does not meet the needs of many users. Version 1.0 will start the process of improving the material system. A new material system will address needs in many different workbenches include FEM, Arch, Path, and Render. Like the assembly workbench, goals for 1.0 are modest. We will provide minimum viable functionality with a solid foundation for future improvment. 46 | 47 | ### Reference 48 | - [original issue](https://github.com/FreeCAD/FreeCAD/issues/10174) 49 | - [Github Project](https://github.com/orgs/FreeCAD/projects/17) 50 | - [Ondsel Blog post](https://ondsel.com/blog/freecad-needs-a-better-materials-system) 51 | - [Forum topic](https://forum.freecad.org/viewtopic.php?style=4&t=78242) 52 | 53 | 54 | ## Initial User Experience 55 | 56 | FreeCAD is often criticized as being hard to learn. This is understandable because it is a complex application with many features. However, we can do better, especially for first-time users who struggle to get started. 57 | 58 | The goals for 1.0 are 59 | 60 | - A First Run Wizard 61 | - Improved Start Page 62 | - UI / UX improvements to improve discoverability and usability. 63 | 64 | ### Reference 65 | - [Github Project for the Customization and Preference Cleanup](https://github.com/orgs/FreeCAD/projects/1/views/1) 66 | - [Github Project for the Toolbar stability and modernization](https://github.com/orgs/FreeCAD/projects/15/views/1) 67 | - [Github Project for the Workbench Selector Cleanup](https://github.com/orgs/FreeCAD/projects/16/views/1) 68 | -------------------------------------------------------------------------------- /roadmap/rationale.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Roadmap Rationale 6 | 7 | The page describes the big ideas that guide the creation of the roadmap. 8 | 9 | People may, _and probably will_ argue about _which_ future state FreeCAD should pursue. For the purposes of this document we assume the following: 10 | 11 | 1. We want FreeCAD to have a healthy development community where new features are regularly added, bugs are quickly resolved, and performance is maintained. 12 | 2. We want a large and diverse community of people using FreeCAD to do real work, including commercial, academic, and hobby pursuits. 13 | 3. We want the code-base to be maintainable, understandable, and testable. 14 | 4. We want the user interface to be beautiful, intuitive, and efficient. 15 | 5. We want high-quality and relevant documentation. 16 | 6. We want the software to be well-designed to support a variety of use-cases including scripted operation. 17 | 7. We want a stable and well-designed API to allow FreeCAD to be included in other workflows and tools. 18 | 19 | ## Why build a roadmap? 20 | 21 | Technical discussions often become contentious because the decisions made have real consequences. Well-meaning people may disagree because they have differing priorities or goals. 22 | 23 | A well-designed roadmap is beneficial because it _first_ focuses on the priorities and then encourages technical decision-making in context. 24 | 25 | A good roadmap will be useful to many different kinds of people: 26 | 27 | 1. Developers will be able to make better decisions about which features should be addressed first and which bugs are worth fixing. 28 | 2. Maintainers can prioritize PR code-review and merge activity. 29 | 3. New contributors can get a sense of where and how their efforts would be most useful. 30 | 4. Non-developer Contributors can prepare better documentation, support users more effectively, and advocate for appropriate changes. 31 | 5. The FPA can allocate resources to encourage key development efforts, plan events, and raise funds. They can encourage sponsors appropriately and push back on sponsors with goals that are not consistent with project goals. 32 | 6. Content Creators can build curriculum, prepare tutorials, and aid with educating users about new features. 33 | 7. Ondsel and other commercial partners can plan their product offerings effectively. 34 | 8. GSoC and other mentors will be able to define projects that are consistent with the general project direction. 35 | 9. Other Open-Source projects can identify opportunities for partnership and co-development. 36 | 37 | ## Why Now? 38 | 39 | FreeCAD releases have never followed a predictable routine. Instead, the project’s unofficial motto, “It’s done when it’s done” has dictated when official releases are prepared. This model has served the project very well for many years but not without controversy and consequences. 40 | 41 | Within the last couple of years many things in the FreeCAD ecosystem have changed. 42 | 43 | The user community has grown dramatically. It has spread far beyond the forum and it includes far more non-developer users. 44 | 45 | The FPA was formed to protect the FreeCAD project and encourage its growth. The FPA has started receiving donations. Deploying those funds well is becoming a challenge itself. 46 | 47 | Ondsel was formed as an open-core public benefit corporation building around the FreeCAD project. As a commercial enterprise, they have a strong need for predictabiilty in the development process and project goals. 48 | 49 | Interest by commercial users to deploy FreeCAD in production environments is increasing. 50 | 51 | FreeCAD is reaching a state of feature-completeness that suggests a 1.0 release. After that point, backwards compatibility and document stability will become increasingly important. 52 | 53 | Universities, trade-schools, and online educators have shown interest in teaching FreeCAD and offering some form of certification. 54 | 55 | 56 | ## Who gets to write/change it? 57 | 58 | The roadmap is, in a sense, a living document. It should be frequently reviewed and revised. The FPA is the steward of the document itself and takes the lead on drafting and revising its content, but it should reflect the will of the whole FreeCAD community. The FPA actively seeks input from the community members and other stakeholders, partners and industry experts. 59 | -------------------------------------------------------------------------------- /technical/ChecklistForNewFeatureC++.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Checklist for adding a new feature to an existing workbench in C++ 6 | 7 | This checklist is intended as an aid to contributors. 8 | 9 | The checklist itemizes the tasks involved in adding a wholly new feature to an 10 | existing module (workbench). It assumes that the existing workbench (myModule) 11 | and the new feature are written in C++. 12 | 13 | The module code is divided into an App portion that deals with the document and 14 | its objects and a Gui portion that deals with visual aspects. Our source tree looks 15 | like this: 16 | 17 | ```txt 18 | FreeCAD/src 19 | Mod 20 | myModule 21 | myModuleTest 22 | TestmyModuleApp.py 23 | TestmyModuleGui.py 24 | myFeatureTest.py 25 | App 26 | AppmyModule.cpp 27 | myFeature.cpp 28 | myFeature.h 29 | myFeaturePy.xml 30 | myFeaturePyImp.cpp 31 | Gui 32 | GuimyModule.cpp 33 | ViewProvidermyFeature.cpp 34 | ViewProvidermyFeature.h 35 | TaskmyFeature.cpp 36 | TaskmyFeature.h 37 | TaskmyFeature.ui 38 | ``` 39 | 40 | ## App changes 41 | 42 | - new myModule/App/myFeature.cpp 43 | - new myModule/App/myFeature.h 44 | - new myModule/App/myFeaturePy.xml 45 | - new myModule/App/myFeaturePyImp.cpp 46 | 47 | - edit myModule/App/CMakeLists.txt 48 | + add new source files 49 | - edit myModule/App/AppmyModule.cpp 50 | + add include(s) for new objects 51 | + add init calls for new objects 52 | 53 | ## Gui changes 54 | 55 | - new myModule/Gui/ViewProvidermyFeature.cpp 56 | - new myModule/Gui/ViewProvidermyFeature.h 57 | - new myModule/Gui/TaskmyFeature.cpp 58 | - new myModule/Gui/TaskmyFeature.h 59 | - new myModule/Gui/TaskmyFeature.ui 60 | 61 | - edit myModule/Gui/CMakeLists.txt 62 | + add new source files 63 | - edit myModule/Gui/AppmyModuleGui.cpp 64 | + add includes for new objects 65 | + add init calls for new objects 66 | - edit myModule/Gui/CommandXXXX.cpp 67 | + add new command 68 | - edit myModule/Gui/Workbench.cpp 69 | + add new command to menu & toolbar 70 | 71 | - new myModule/Gui/Resources/icons/myModule_myFeature.svg 72 | - edit myModule/Gui/Resources/myModule.qrc 73 | + add icon to list 74 | 75 | ## Test changes 76 | 77 | - new test script myModule/myModuleTest/myFeatureTest.py 78 | - edit myModule/myModuleTest/TestmyModuleApp.py _and/or_ myModule/myModuleTest/TestmyModuleGui.py 79 | + add import for myFeatureTest 80 | - edit myModule/CMakeLists.txt 81 | + add myFeatureTest.py to list 82 | - new unit tests 83 | + ???? 84 | 85 | ## Documentation changes 86 | 87 | - new wiki.freecad.org/myModule_myFeature 88 | - edit wiki.freecad.org/myModule_Workbench 89 | + add new entry in module overview 90 | - edit predecessor and successor wiki entries 91 | + update next and previous article pointers 92 | -------------------------------------------------------------------------------- /technical/CreatePythonBindingForCpp.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Create a Python Binding for C++ 6 | 7 | ## Background 8 | 9 | It becomes necessary at times to expand the FreeCAD API further by exposing functions that are available in the source code in c++ to the python. This process is generally referred to as creating a binding. 10 | 11 | FreeCAD uses a custom XML-based system to create the Python wrapper for a C++ class. To wrap a C++ class for use in Python, two files must be manually created, and two files are automatically generated by the CMake build system (in addition to the C++ header and implementation files for the class). 12 | 13 | You must create: 14 | * YourClassPy.xml 15 | * YourClassPyImp.cpp 16 | 17 | Edit the appropriate CMakeLists.txt file to add references to these two files. From the XML file, the build system will then create: 18 | * YourClassPy.cpp 19 | * YourClassPy.h 20 | 21 | ## Class Description XML File 22 | 23 | The XML file YourClassPy.xml provides information about the functions and attributes that the Python class implements, as well as the user documentation for those items that displays in the **FreeCAD Python console**. 24 | 25 | For this example, we will look at the wrapper for the Base::Axis C++ class. The XML description file begins with: 26 | 27 | ```xml 28 | 29 | 40 | 41 | 42 | User documentation here 43 | 44 | 45 | Developer documentation here 46 | 47 | ``` 48 | 49 | Following this preamble, a list of methods and attributes is given. The format of a method is: 50 | 51 | ```xml 52 | 53 | 54 | 55 | move(Vector) 56 | Move the axis base along the vector 57 | 58 | 59 | 60 | ``` 61 | 62 | The format of an attribute is: 63 | 64 | ```xml 65 | 66 | 67 | Direction vector of the Axis 68 | 69 | 70 | 71 | ``` 72 | 73 | For an attribute, if "ReadOnly" is false, you will provide both a getter and a setter function. If it is true, only a getter is allowed. In this case we will be required to provide two functions in the implementation C++ file: 74 | 75 | ```cpp 76 | Py::Object AxisPy::getDirection(void) const 77 | ```` 78 | 79 | and: 80 | 81 | ```cpp 82 | void AxisPy::setDirection(Py::Object arg) 83 | ``` 84 | 85 | ## Implementation C++ File 86 | 87 | The implementation C++ file `YourClassPyImp.cpp` provides the "glue" that connects the C++ and Python structures together, effectively translating from one language to the other. The FreeCAD C++-to-Python system provides a number of C++ classes that map to their corresponding Python type. The most fundamental of these is the incode `Py::Object` class - rarely created directly, this class provides the base of the inheritance tree, and is used as the return type for any function that is returning Python data. 88 | 89 | ### Include Files 90 | 91 | Your C++ implementation file will include the following files: 92 | 93 | ```cpp 94 | #include "PreCompiled.h" 95 | 96 | #include "YourClass.h" 97 | 98 | // Inclusion of the generated files (generated out of [YourClassPy.xml) 99 | #include "YourClassPy.h" 100 | #include "YourClassPy.cpp" 101 | ``` 102 | 103 | Of course, you may include whatever other C++ headers your code requires to function as well. 104 | 105 | ### Constructor 106 | 107 | Your C++ implementation must contain the definition of the PyInit function: for example, for the Axis class wrapper, this is 108 | 109 | ```cpp 110 | int AxisPy::PyInit(PyObject* args, PyObject* /*kwd*/) 111 | 112 | //Within this function you will most likely need to parse incoming arguments to the constructor: the most important function for this purpose is the Python-provided incode|PyArg_ParseTuple. It takes in the 113 | //passed argument list, a descriptor for the expected arguments that it should parse, and type information and storage locations for the parsed results. For example: 114 | 115 | PyObject* d; 116 | if (PyArg_ParseTuple(args, "O!O", &(Base::VectorPy::Type), &o, 117 | &(Base::VectorPy::Type), &d)) { 118 | // NOTE: The first parameter defines the base (origin) and the second the direction. 119 | *getAxisPtr() ## Base::Axis(static_cast(o)->value(), 120 | static_cast(d)->value()); 121 | return 0; 122 | } 123 | ``` 124 | 125 | For a complete list of format specifiers see [https://docs.python.org/3/c-api/arg.html Python C API documentation]. Note that several related functions are also defined which allow the use of keywords, etc. The complete set is: 126 | 127 | * PyArg_Parse (PyObject *, const char *, ...); 128 | * PyArg_ParseTuple (PyObject *, const char *, ...); 129 | * PyArg_ParseTupleAndKeywords (PyObject *, PyObject *, const char *, char **, ...); 130 | * PyArg_VaParse (PyObject *, const char *, va_list); 131 | * PyArg_VaParseTupleAndKeywords (PyObject *, PyObject *, const char *, char **, va_list); 132 | 133 | ## Another Explanation 134 | 135 | The basic structure of a program to expose functionality to Python is something like this: 136 | 137 | * get the Py object parameters and convert them to c++ variables using PyArg_ParseTuple(), 138 | * use various c++ routines from OpenCascade and/or FreeCAD to produce the desired result, 139 | * convert the c++ result into Py object using routines like PyLong_AsLong(), Py::asObject(), etc, 140 | * return the Py object. 141 | 142 | There are two source files required to implement a new Python binding. Assuming we wanted to expose some methods from https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/TopoShape.cpp, we would need to make: 143 | * TopoShapePy.xml - definitions of the functions for be exposed in XML format. This file is used to generate header files for our next file... 144 | * TopoShapePyImp.cpp - the actual C++ code that bridges from Python to C++. 145 | 146 | These 2 files need to be added to ../Mod/yourModule/App/CMakeLists.txt. See https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/AppPartPy.cpp and FreeCAD/src/Mod/Part/App/CMakeLists.txt for examples. 147 | 148 | You can extend the Python version of your module by adding to ../Mod/yourModule/App/AppmyModulePy.cpp (see https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/AppPartPy.cpp and FreeCAD/src/Mod/Part/AppPartPy.cpp]). The additions are accessed in Python by "import myModule". 149 | 150 | Note: 151 | 152 | There is a convention for return values from our C++/Python connections: 153 | * xxxxxPyImp routines return a PyObject* pointer (see TopoShapePyImp.cpp) 154 | * AppmyModulePy.cpp routines return a Py::Object (see https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/App/AppPartPy.cpp and FreeCAD/src/Mod/Part/AppPartPy.cpp. 155 | 156 | ## See also 157 | 158 | * [https://forum.freecadweb.org/viewtopic.php?p##314796#p314617] 159 | * [https://forum.freecadweb.org/viewtopic.php?p##560639#p560639] Forum discussion: Adding Commands in Python to C++ Workbench 160 | * [https://forum.freecadweb.org/viewtopic.php?f##10&t##70750] Another forum thread 161 | * (./Workbench creation.md) 162 | * [https://github.com/FreeCAD/FreeCAD/commit/20b86e55b8dd1873f4c19e036d047528c9ff7f4e] Commit 20b86e5, exposing OCC's precision methods to Python 163 | -------------------------------------------------------------------------------- /technical/DevBook.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Contributing to the Developer Handbook 6 | 7 | Technical information for contributors interested to work on Developer Handbook. 8 | 9 | 10 | 11 | ## Running locally 12 | 13 | To run the Developer Handbook locally, Jekyll, the Ruby static site generator, must be executed on the corresponding folder.\ 14 | On a Debian or Ubuntu GNU/Linux system, Bundler is used : 15 | 16 | ``` 17 | $ sudo apt install ruby-bundler ruby-dev build-essential 18 | $ bundle install 19 | $ cd path/to/your/local/fork/of/the/devhandbook 20 | $ bundle exec jekyll serve 21 | ``` 22 | 23 | Open then the link to `127.0.0.1:4000` (or `localhost:4000`) in you web browser. 24 | 25 | 26 | 27 | 28 | -------------------------------------------------------------------------------- /technical/FPAweb.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Contributing to the FreeCAD Project Association website 6 | 7 | Technical information for contributors interested to work on FreeCAD Project Association website. 8 | 9 | 10 | 11 | ## Running locally 12 | 13 | To run the FPA website locally, Jekyll, the Ruby static site generator, must be executed on the corresponding folder.\ 14 | On a Debian or Ubuntu GNU/Linux system, Bundler is used : 15 | 16 | ``` 17 | $ sudo apt install ruby-bundler ruby-dev build-essential 18 | $ bundle install 19 | $ cd path/to/your/local/fork/of/the/FPA/website 20 | $ bundle exec jekyll serve 21 | ``` 22 | 23 | Open then the link to `127.0.0.1:4000` (or `localhost:4000`) in you web browser. 24 | 25 | 26 | 27 | 28 | -------------------------------------------------------------------------------- /technical/FreeCADweb.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Contributing to the FreeCAD main website 6 | 7 | Technical information for contributors interested to work on FreeCAD main website. 8 | 9 | 10 | 11 | ## Running locally 12 | 13 | During development and before committing your changes, you may want to display the website in your web browser locally, without installing a full web server solution stack like XAMPP.\ 14 | You can instead just transcribe the PHP files into HTML that your web broswer can read. 15 | 16 | 1) To do so, fork the original FreeCAD-Homepage repository to your personal GitHub account : 17 | 18 | ![Fork the repository](./resources/FreeCADweb_01.jpg) 19 | 20 | 2) If you don't have an account or prefer to inspect and modify files locally without relying on GitHub's features, download the compressed folder and unzipp it : 21 | 22 | ![Download the repository](./resources/FreeCADweb_02.jpg) 23 | 24 | 3) From GitHub Desktop app, clone the fork you just created (skip this step if you downloaded the zip in step 2) : 25 | 26 | ![Clone the fork](./resources/FreeCADweb_03.jpg) 27 | 28 | 4) Make sure PHP is installed on your system (on GNU/Linux in 2023, install the PHP8 CLI package). 29 | 30 | 5) Go to your local cloned copy of the repository, in the folder you specified previously ("FreeCAD-Homepage" in this case), and open the terminal at working-directory location : 31 | 32 | ![Open Terminal in cloned local repo](./resources/FreeCADweb_05.jpg) 33 | 34 | 6) Paste `php -S 127.0.0.1:8000` (or `php -S localhost:8000`) to start the PHP server locally: 35 | 36 | ![Start PHP server](./resources/FreeCADweb_06.jpg) 37 | 38 | 7) Open a new tab in your web browser with `127.0.0.1:8000` (or `localhost:8000`) to display the "index.php" file of the web page correctly.\ 39 | If you want to reach a particular file, use `localhost:8000/MyFile.php`. 40 | 41 | ![Start PHP server](./resources/FreeCADweb_07.jpg) 42 | 43 | N.B: the translation of the web pages does not work. 44 | 45 | 46 | 47 | ## Managing translations 48 | 49 | In order for the language and translation management system to work, each text that potentially needs to be translated must be encapsulated as follows: 50 | 51 | `` 52 | 53 | The site administrators regularly run a script that updates the translatable strings on the Crowdin platform. The added texts can then be translated by contributors. The newly translated content is then forwarded back to the website. 54 | 55 | 56 | -------------------------------------------------------------------------------- /technical/MajorRelease.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Major Releases 6 | 7 | Each major release goes through the following milestones and stages: 8 | 9 | ## Announcement Preparation 10 | 11 | A release may be triggered for several reasons. 12 | - An event or dependency in the development roadmap may require a release. 13 | - There may be a desire to have a major release included in a major platform release like the next version of Ubuntu. 14 | - Or it may be that a significant set of features has matured to the point that they are ready for general usage. 15 | 16 | Whatever the reason, the first step in the determination by the maintainers that a release is needed. 17 | 18 | The maintainers will create a Github project to track the release. 19 | The maintainers will schedule a meeting to review outstanding Pull Requests. 20 | 21 | 22 | ## Announcment milestone 23 | 24 | Next, the maintainers will make a formal announcment on the forum. The announcement will layout the expected timeline for the release and call for final submissions. The announcment should be further communicated through official and unofficial channels like Twitter and Reddit. 25 | 26 | ## Final Feature Submission Stage 27 | 28 | The purpose of the announcment is to let contributors know that a feature freeze is imminent. Any work in process should be finalized and a Pull Request submitted. 29 | 30 | At this point, a PR may not be ready to merge and can be marked as _draft_. Creating the PR makes the maintainer community aware of pending changes that the contributor would like to have considered for the release. The maintainers will allow time (typically 1-2 weeks) for Pull Requests to be submitted. 31 | 32 | The announcment should include a date for the PR Review meeting. 33 | 34 | The announcment should also announce a splash-screen contest and provide a forum thread for submissions. 35 | 36 | ## PR Review Milestone 37 | 38 | After the Submission Stage is closed, the maintainers will review all outstanding Pull Requests. For each one, they will determine if the feature is sufficiently mature to include in the release. Specifically they will consider: 39 | 40 | - How significant is the feature 41 | - How likely is the feature to negatively impact user workflow 42 | - How well documented is the new feature 43 | - How much additional testing and stabilization is likely required 44 | 45 | Maintainers will strive to include as many mature features as possible while minimizing the time needed to resolve bugs, complete documentation, and stabilize the release. 46 | 47 | Each PR will be tagged with the current release if it is to be included. 48 | 49 | Following the PR Review, any new feature Pull Requests will be held for a later version. Contributors should adjust their expectations about code reviews. 50 | 51 | ## PR Merge Phase 52 | 53 | During this phase, development focus will turn towards merging the remaining tagged outstanding PRs. 54 | After the PR Merge phase, only bug-fix PRs will be merged. 55 | 56 | ## Release Candidates 57 | 58 | After all outstanding PRs are merged and all critical bugs are resolved, a Release Candidate (RC) version will be created and a public announcment made. This is a request to the community for intentional and deliberate testing with the goal of uncovering as many bugs as possible. This is the point at which the formal branch is created for the releases. First, create a branch called "releases/FreeCAD-X-Y" where X and Y are the major and minor release numbers. Next use the GitHub "Draft new release" button on the Releases page to create a new release. Set it up to create a new tag with the release number in it, e.g. "0.21rc1" and ensure that the release is based on the "releases/FreeCAD-X-Y" branch. Mark the release as a "pre-release" so that it does not display as the latest version. Attach all of the necessary installers, appimages, packages, etc. to this release. Note that the release can be edited after creation, so assets can be added as they become available. 59 | 60 | Translation files will be pushed to CrowdIn and a public call for translation assistance should be made. 61 | 62 | Release notes should be reviewed at this point and any ommisions corrected. 63 | 64 | Any problems identified with the release candidate should be addressed via PRs made to the release branch. If necessary, multiple release candidates may be tagged using the same "Draft new release" process described above, and incrementing the release candidate number. 65 | 66 | ## Final Release 67 | 68 | - The result of the splash screen contest is announced and the new splash screen is added to the source, if that was not done in earlier stages. 69 | - Update all versions in a number of source code locations where they are not automatically generated: 70 | - README.md 71 | - CMakeLists.txt 72 | - Manually tag the release on the appropriate branch using semantic versioning for the tag name, e.g. "1.2.3". Launch the various build-creation tasks based on this tag. 73 | - Conda builds for all platforms 74 | - Manual compilation of a Windows LibPack-based binary and NSIS-created installer 75 | - Sign and notarize the Mac OS Conda builds once they are complete (See [Code signing](./codesigning.md)) 76 | - (Future work) Sign the Windows builds 77 | - Create a new release on GitHub, this time marking the "Set as latest release" box and not marking it as a pre-release, and setting the release to use the tag created above. It's best to ensure all assets are attached prior to publication of the final release, so save the release as a draft as necessary until all builds are completed. The release contains a release announcement text that should be appropriate for the general user audience (not targeted at developers). 78 | - Prepare a packager's release files and alert the packagers. 79 | - Update the website [downloads page](https://www.freecad.org/downloads.php) to point to the new files 80 | - Update the website [features page](https://www.freecad.org/features.php) to point to the new release notes 81 | - Update the stable branch of the [Snap package](https://github.com/FreeCAD/FreeCAD-snap) to the new version number by editing snap/snapcraft.yaml 82 | 83 | ## Release Announcment 84 | 85 | Once all release files are in place, a release announcement should be posted to all "official" FreeCAD channels: 86 | 87 | - FreeCAD News (https://blog.freecad.org) 88 | - The FreeCAD Forum (https://forum.freecad.org) 89 | - Facebook 90 | - X 91 | - Mastodon (automatic from the blog post) 92 | - Discord 93 | - LinkedIn 94 | 95 | There are also other active communities where FreeCAD does not maintain any sort of official presence, but where nevertheless users are likely to benefit from an announcement: 96 | 97 | - Yorik's blog 98 | - Ondsel blog 99 | - Reddit 100 | -------------------------------------------------------------------------------- /technical/MinorRelease.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Minor Releases 6 | 7 | Between major releases, bugs are occasionally found and repaired. These fixes may be urgent enough or isolated enough that applying them incrementally to the existing ‘stable’ version is both possible and desirable. A set of such changes may be grouped together and released as a ‘minor’ version. 8 | 9 | Usually these fixes have already been applied to the development branch. The process of applying them to the previous stable version is called 'backporting' 10 | 11 | Each minor release goes through the following stages: 12 | 13 | ## Creation of Release Milestone 14 | 15 | The need for a minor release is triggered by a PR or commit which is deemed worth backporting to the stable version. The consideration is based on a couple factors 16 | 17 | - Does the bug result in the loss of data under normal circumstances? 18 | - Does the bug expose user data or present the possibility of user data being 19 | exposed? 20 | - Does the bug create a significant inconvenience for the user? 21 | 22 | When a PR or commit is found worth backporting, a maintainer will create a new issue. The issue should have suitable title like [BACKPORT REQUEST] 23 | 24 | The issue should link to the PR in question. 25 | 26 | The issue should be labeled with a Milestone label for the next minor release. If the milestone label doesn't exist, the maintainer will create it. 27 | 28 | ## Create a backport PR 29 | 30 | A maintainer will create a new PR targeting the stable branch. The relevant commits can be cherry-picked and added to the new PR. 31 | 32 | The backport PR will go through the same process as any other PR. 33 | 34 | ## Creating the Minor version release 35 | 36 | Minor bugs may be gathered together for a period of days or weeks to batch them together. A significant bug or one that risks user data may require an expedited release. 37 | 38 | When the determination is made to proceed with the release, the following things happen: 39 | 40 | 41 | -------------------------------------------------------------------------------- /technical/ObjectDeletion.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # How to control object deletion 6 | 7 | It is possible for a user to attempt to delete a DocumentObject while a Task 8 | Dialog is attempting to update that object. Handling this in a Task Dialog 9 | is not tidy. 10 | 11 | ## Recommended reading: 12 | - ViewProviders 13 | - In/Out Lists 14 | 15 | There are two methods in the ViewProvider that deal with this situation. 16 | 17 | ```c++ 18 | bool canDelete(App::DocumentObject *obj) 19 | ``` 20 | is called when Std_Delete is asked to delete obj, BUT it is called for each of 21 | obj's parent in the InList. This is where you would decide if you will allow 22 | one of your children can be deleted. In effect, the is canDeleteMyChildObject(). 23 | Return true to allow the child to be deleted, or false to prevent the deletion. 24 | 25 | ```c++ 26 | bool onDelete(const std::vector & parms) 27 | ``` 28 | is also called when when Std_Delete is asked to delete a DocumentObject, but in 29 | this case it is the DocumentObject's ViewProvider that is called. Return true 30 | to allow deletion of the DocumentObject, or false to prevent the deletion. 31 | 32 | Note that it is possible to circumvent these methods via scripting. 33 | -------------------------------------------------------------------------------- /technical/PropertyChanges.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | 6 | # Dealing with Property Changes 7 | 8 | A brief introduction 9 | 10 | Recommended reading: 11 | - The Application Module 12 | - [Property in the wiki](https://wiki.freecad.org/Property) 13 | 14 | ## The App side 15 | - When a Property's value changes, its PropertyContainer (eventually a DocumentObject) executes the onChanged method with the Property as a parameter. This is where you will take appropriate action based on the new property value. 16 | - Be cautious when inserting logic into onChanged and execute as it is possible to create a loop. 17 | 18 | ```c++ 19 | void myFeature::execute() 20 | { 21 | MyProperty->setValue(foo()); 22 | } 23 | void myFeature::onChanged(App::Property property) 24 | { 25 | if (property == MyProperty) { 26 | execute(); 27 | } 28 | } 29 | ``` 30 | - The other interesting method involving property changes is mustExecute. This is where you control whether or not your object participates in the next recompute cycle. 31 | 32 | 33 | ## The Gui side 34 | - On the Gui side, we must look first at your derived ViewProvider, which is attached to your DocumentObject. The ViewProvider is notified of changed properties for both itself and the DocumentObject it belongs to. 35 | - For properties belonging to the ViewProvider (those on the View tab in the PropertyEditor), the relevant method is again onChanged. 36 | - Whenever a DocumentObject Property changes, the updateData method of its attached ViewProvider is called. 37 | -------------------------------------------------------------------------------- /technical/PythonStubsPackage.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Python stubs 6 | 7 | Python is a dynamically typed language, so there is no error when compiling 8 | (Yes, Python can compile. 9 | Compiling/interpreting is an abstract concept, language independent. 10 | See more on [stackoverflow](https://stackoverflow.com/a/6889798)). 11 | Instead, an error is reported at runtime 12 | which may significantly slow down developing process. 13 | 14 | To overcome this problem, Python introduced 15 | [Type Hints](https://peps.python.org/pep-0484/). 16 | Using an external tool (type checker like 17 | [Mypy](https://mypy-lang.org/), 18 | [Pyright](https://github.com/RobertCraigie/pyright-python) 19 | ) it is possible to detect runtime errors. 20 | 21 | Also, stub files allow IDE (integrated development environment) 22 | detect possible names for imported classes or method names. 23 | 24 | # Installation 25 | 26 | ## PyPi 27 | 28 | It is possible to install stubs directly from 29 | [PyPI](https://pypi.org/project/freecad-stubs/): 30 | 31 | ```shell 32 | pip install FreeCAD-stubs 33 | ``` 34 | 35 | ## From GitHub repo (especially older versions) 36 | 37 | To install stubs for older FreeCAD version 38 | (replace `FreeCAD-0-20` with tag/branch you want), 39 | you can run: 40 | 41 | ```shell 42 | pip install git+https://github.com/ostr00000/freecad-stubs.git@FreeCAD-0-20 43 | ``` 44 | 45 | Or manually using cloning repo: 46 | 47 | 1. Clone [repo](https://github.com/ostr00000/freecad-stubs): 48 | 49 | ```shell 50 | git clone https://github.com/ostr00000/freecad-stubs 51 | ``` 52 | 53 | 2. Choose desired version: 54 | 55 | ```shell 56 | git checkout FreeCAD-0-20 57 | ``` 58 | 59 | 3. And install directly: 60 | 61 | ```shell 62 | pip install freecad-stubs 63 | ``` 64 | 65 | # False positives in stubs 66 | 67 | Probably not all types are correctly detected. 68 | [Reporting issues](https://github.com/ostr00000/freecad-stubs/issues) are very welcome. 69 | -------------------------------------------------------------------------------- /technical/ReferenceLibrary.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Reference Library 6 | 7 | The FPA maintains a small reference library that is available to contributors. 8 | 9 | Current Holdings: 10 | - ASME Y14_3_2012_R2018 - Orthographic and pictorial views 11 | - ISO 128-3_2022 - Technical product documentation part 3 12 | 13 | To borrow a volume from the library send a message to fpa@freecad.org. If the volume is available, 14 | you will be given access instructions. 15 | 16 | To have a required volume added to the reference library, submit a request specifying the volume, 17 | price and vendor to fpa@freecad.org. You should also include a brief summary of why the volume is 18 | required. The FPA will evaluate the request and, if funds are available, the volume will be 19 | purchased and added to the library. 20 | 21 | Note that many reference works have limitations on copying and concurrent usage. For example, ISO 22 | Standards are restricted to a single user and copying is prohibited. Please respect these limitations. 23 | -------------------------------------------------------------------------------- /technical/ReleasePackages.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Building release packages 6 | 7 | This page describes how to build FreeCAD packages for the different supported platforms. 8 | 9 | ## Windows Installer 10 | 11 | The main entry point to build a Windows installer is within the FreeCAD sources, at https://github.com/FreeCAD/FreeCAD/tree/master/src/WindowsInstaller . To build the installer: 12 | 13 | ### Creating a Windows installer for FreeCAD 14 | 15 | These are instructions for building an NSIS-based installer for FreeCAD. They were designed for FreeCAD 0.21 and later, 16 | and presume that you have cloned a copy of FreeCAD's source code, and therefore have the directory *src/WindowsInstaller*. 17 | 18 | #### Install NSIS 19 | To set up your system for building an NSIS installer: 20 | 1. Install the latest version 3.x of NSIS (https://nsis.sourceforge.io/Download) 21 | 2. Download these special release files of NSIS that support large strings:
22 | https://nsis.sourceforge.io/Special_Builds#Large_strings
23 | and copy the contained files into the corresponding NSIS installation folders 24 | 3. Download these special release files of NSIS that support logging:
25 | https://nsis.sourceforge.io/Special_Builds#Advanced_logging
26 | and copy the contained files into the corresponding NSIS installation folders 27 | 4. Download and install the nsProcess plugin from https://nsis.sourceforge.io/NsProcess_plugin -- you will need the version that supports Unicode, so make sure to follow the appropriate instructions on their site to install that one (as of this writing it involves manually copying and renaming the plugin DLL file). 28 | 29 | #### Build the installer 30 | Next, update the installer settings for the current version of FreeCAD. Starting from the *src/WindowsInstaller* folder in the FreeCAD source tree: 31 | 1. Set the appropriate version strings for the release you are creating. These are used to construct the filename of the installer, among other things. If you have to upload a new version of the installer for the exact same release of FreeCAD, increment `APP_VERSION BUILD` as needed. 32 | ``` 33 | !define APP_VERSION_MAJOR 0 34 | !define APP_VERSION_MINOR 21 35 | !define APP_VERSION_REVISION 0 36 | !define APP_VERSION_EMERGENCY "RC1" 37 | !define APP_VERSION_BUILD 1 38 | ``` 39 | 2. Within the folder *src/WindowsInstaller*, create a new folder called MSVCRedist and copy the following files from your MSVC installation into it: 40 | ``` 41 | vcruntime140.dll 42 | concrt140.dll 43 | msvcp140.dll 44 | vcamp140.dll 45 | vccorlib140.dll 46 | vcomp140.dll 47 | ``` 48 | 3. Open the file *Settings.nsh* with a text editor (both jEdit and Visual Studio Code are good editors for NSIS files). Edit the following paths to correspond to your system: `FILES_FREECAD` corresponds to your installation directory (e.g. `CMAKE_INSTALL_PREFIX` if you self-compiled) and `FILES_DEPS` is the folder you created with the MSVC redistributable files in it. 49 | ``` 50 | !define FILES_FREECAD "C:\FreeCAD\Installer\FreeCAD" 51 | !define FILES_DEPS "C:\FreeCAD\Installer\MSVCRedist" 52 | ``` 53 | 4. Ensure the FreeCAD files are in place. Here you have two options: 54 | * If you are working from an already-compiled version of FreeCAD provided to you by an outside source: in this case, simply ensure that `FILES_FREECAD` is set to the directory containing those files. 55 | * If you compiled FreeCAD on your own as described [here](https://wiki.freecad.org/Compile_on_Windows) (and using the Install option outlined there). Then: 56 | * Open the file *Settings.nsh* as described in step 3. above and set there
57 | `!define FILES_FREECAD` to the folder you specified as `CMAKE_INSTALL_PREFIX` 58 | * Copy into that folder the file *Delete.bat* that is part of the installer 59 | * open a command line in Windows and change to the folder 60 | * run the comamand
61 | `Delete.bat` 62 | * (These steps assure that the installer only contains files users need. Moreover it assures that the 63 | overall files size is below 2 GB and we can use the most compact compression for the installer.) 64 | 5. Right-click on the file *FreeCAD-installer.nsi* and choose **Compile NSIS script** 65 | to compile the installer. 66 | 67 | 68 | NOTE: For test builds of the installer you can turn off the LZMA compression and use the much faster default compression. This speeds up 69 | the build time for the installer but significantly increases the final installer file size. The LZMA compression is turned off by commenting 70 | out the line 71 | ``` 72 | !SetCompressor lzma 73 | ``` 74 | in the file *Settings.nsh*. 75 | 76 | 77 | ## Conda builds for Linux, Mac, and Windows 78 | 79 | The same system that builds the "Development Weekly" builds is used to build the release versions of the Linux AppImages, Mac app bundles, and a standalone Windows executable (e.g. a non-installer version). 80 | 81 | **To be expanded** 82 | 83 | It is also possible to build a FreeCAD package for Windows with [conda](https://conda.io). This is produced as a .7z package that can be unzipped and run directly, without installation. The scripts needed to produce such a package are located in a separate Git repository at [FreeCAD/FreeCAD-Bundle](https://github.com/FreeCAD/FreeCAD-Bundle). The main script to run is [conda/win/create_bundle.bat](https://github.com/FreeCAD/FreeCAD-Bundle/blob/master/conda/win/create_bundle.bat). 84 | 85 | You will need: 86 | 87 | 1. **Mambaforge** from [GitHub - conda-forge/miniforge: A conda-forge distribution.](https://github.com/conda-forge/miniforge#mambaforge) 88 | 2. **7zip** from https://www.7-zip.org/ 89 | 90 | To use the script: 91 | 92 | 1. TODO document how to install Mambaforge 93 | 2. Clone the FreeCAD-Bundle repository 94 | 3. Run the create_bundle.bat script 95 | 96 | ## MacOS 97 | 98 | ### Conda 99 | 100 | **To be expanded** 101 | 102 | MacOS packages are also built with [conda](https://conda.io). 103 | 104 | ## Linux 105 | 106 | ### Conda 107 | 108 | On Linux, we mostly let distributions produce packages themselves from the FreeCAD source code. However, we also produce an [AppImage](https://appimage.org/) package, that runs on (hopefully) all Linux distributions. AppImages achieve that by embedding the largest part of the libraries FreeCAD depends on, and rely only on a few very standard system libraries. 109 | 110 | The most complex part, when building an AppImage, is therefore to gather those libraries. FreeCAD therefor uses [conda](https://conda.io) which is at the same time a build system and a package manager, to locate, download and organize these libraries. After this is done, the official AppImage tool is used to actually build the AppImage. Note that FreeCAD itself is built and made available on conda, so the process of building an AppImage does not compile FreeCAD. It rather uses a compiled version of FreeCAD already available on the conda platform. 111 | 112 | The main structure used to gather FreeCAD and its dependencies and build appimages is located in a separate Git repository at [FreeCAD/FreeCAD-Bundle](https://github.com/FreeCAD/FreeCAD-Bundle). The main script to run is [conda/linux/create_bundle.sh](https://github.com/FreeCAD/FreeCAD-Bundle/blob/master/conda/linux/create_bundle.sh). This script will do all the process of assembling and producing an AppImage. 113 | 114 | You will need: 115 | 116 | 1. **Mambaforge** from https://github.com/conda-forge/miniforge#mambaforge 117 | 2. **appimagetool** from https://appimage.github.io/appimagetool/ 118 | 119 | To use the script: 120 | 121 | 1. Clone the FreeCAD-Bundle repository 122 | 2. Download and place the appimagetool Appimage in the root of the repo, make it executable with `chmod +x` 123 | 3. If you chose to not install the conda environment when installing Mambaforge, you will need to enable a conda environment now. Do it by running the following in your terminal: `eval "$(/$USER/Mambaforge/bin/conda shell.sh hook)"` (replace the Mambaforge path by yours if you installed it somewhere else and sh by your shell name if not sh). This will make the **conda** and **mamba** commands available in this terminal session 124 | 4. Run `create_bundle.sh` 125 | 126 | Note that appimages produced by that script are by default not signed. It is generally seen on the AppImage website as not very widely used to sign AppImages. If you wish to sign the package, add `--sign-key you@yourdomain.com` to the appimage line in the create_bundle.sh script. You will need to have a gpg key configured for that email. 127 | -------------------------------------------------------------------------------- /technical/ReleaseProcess.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Release Process 6 | 7 | This page describes a high-level overview of the release planning and management process. 8 | 9 | We recognize signficant wisdom in the philosophy to ["Release Early and Release Often"](https://en.wikipedia.org/wiki/Release_early,_release_often). However, releases can require significant coordinated work within the community. FreeCAD aspires to produce a major release every 3-6 months. In order to meet this goal, we will work to make releases more predicatable and automated. 10 | 11 | ## Major and Minor Releases 12 | 13 | A major release introduces new features and introduces key improvements. Major releases may also introduce breaking changes that invalidate documentation or change existing APIs. They may also deprecate older functionality. 14 | 15 | Between major releases, bugs are occasionally found and repaired. These fixes may be urgent enough or isolated enough that applying them incrementally to the existing 'stable' version is both possible and desirable. A set of such changes may be grouped together and released as a 'minor' version. 16 | 17 | Major and minor releases have slightly different processes. 18 | 19 | - [Major Releases](./MajorRelease.md) 20 | - [Minor Releases](./MinorRelease.md) 21 | -------------------------------------------------------------------------------- /technical/SourceTreeBasics.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | mermaid: true 4 | --- 5 | 6 | # Partial View of the FreeCAD Source Tree 7 | 8 | A picture of the most commonly encountered branches of the tree. 9 | 10 | The full FreeCAD source tree has many other branches, but most Contributors will 11 | only need to deal with these: 12 | 13 | ![The FreeCAD Source Tree](./resources/SourceTreeBasics.svg) 14 | 15 | ```mermaid 16 | graph LR 17 | A[src] --- B[App: Documents, DocumentObjects, EventPropagation] 18 | A --- C[Base: FundamentalTypes, Utilities] 19 | A --- D[Gui: Windows, Menus, Dialogs] 20 | A --- E[Mod: ApplicationLogic] 21 | subgraph Mod: ApplicationLogic 22 | E[Mod] --- F[Arch: Buildings] 23 | E --- G[Draft: 2DDesign] 24 | E --- H[Part: BasicShapes, BooleanOps] 25 | E --- I["..."] 26 | end 27 | ``` 28 | -------------------------------------------------------------------------------- /technical/TheApplicationModule.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # The Application Module 6 | 7 | An overview of application module structure. 8 | 9 | The functionality of FreeCAD is separated into Modules. Some Modules are built into FreeCAD and some are Extension Modules (a form of plug-in). Once installed, Extension Modules behave exactly as built-in Modules. 10 | 11 | Application Modules provide specialized functions and may store specialized data. Examples of Application Modules are Arch (for buildings) and Sketcher (for drawing Sketches). 12 | 13 | Application Modules are almost always divided into two parts: App which manages the relevant document objects and operations on them, and Gui which handles the display. 14 | 15 | ![Overview of an Application Module](./resources/TheApplicationModule.svg) 16 | -------------------------------------------------------------------------------- /technical/Websites.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Contributing to FreeCAD websites 6 | 7 | Technical information for contributors interested to work on FreeCAD websites. 8 | 9 | ## The Ecosystem 10 | 11 | Currently, the websites infrastructure of FreeCAD consists of the following : 12 | 13 | - [The FreeCAD website](https://www.freecad.org) acts as the main entry point into FreeCAD's universe for all users, contributors and interested parties. 14 | 15 | - [The News Blog](https://blog.freecad.org/) brings together development news, tutorials and use cases from the community. 16 | 17 | - [The Wiki](https://wiki.freecad.org/) gathers all the documentation about FreeCAD, from usage to installation, development, release notes and much more. Historically, this has been the all-purpose place for all FreeCAD-related matters. A more development-oriented portion of it has been migrated to this Developer Handbook. 18 | 19 | - [The Developer Handbook](https://freecad.github.io/DevelopersHandbook/) is the very site you are currently in. 20 | 21 | - [The Forum](https://forum.freecad.org/) is one of the many places where the community meets and exchanges. 22 | 23 | - [The FreeCAD Project Association website](https://fpa.freecad.org/) groups everything that relates to the association overseeing the FreeCAD project. 24 | 25 | In addition to the implemented websites listed above, several external platforms are used : 26 | 27 | - [The Repositories](https://github.com/FreeCAD) of FreeCAD main codebase, building and packaging, continuous integration, addons, macros, library, websites and more are on GitHub. 28 | 29 | - [The Translations](https://crowdin.com/project/freecad) of the software interface and the main website are on Crowdin. 30 | 31 | Moreover, here are the current implementation initiatives not yet used : 32 | 33 | - [The FreeCAD Documentation](https://freecad-documentation.netlify.app/) overhaul as part of the GSOC 2023 34 | 35 | ## Technical details 36 | 37 | ### FreeCAD website 38 | 39 | The website mainly uses HTML/PHP, CSS, the Bootstrap and jQuery JavaScript libraries, the Font Awesome toolkit.\ 40 | To contribute to the main website, find [here a few advices and ressources](./FreeCADweb.md). 41 | 42 | ### News Blog 43 | 44 | The News Blog is based on WordPress.\ 45 | 46 | 47 | ### Wiki 48 | 49 | The News Blog is based on MediaWiki.\ 50 | 51 | 52 | ### Developer Handbook 53 | 54 | The Developer Handbook uses Jekyll, a Ruby static site generator, and Markdown.\ 55 | To contribute to the Developer Handbook, find [here a few advices and ressources](./DevBook.md). 56 | 57 | ### Forum 58 | 59 | The News Blog is based on phpBB.\ 60 | 61 | 62 | ### FreeCAD Project Association website 63 | 64 | The FreeCAD Project Association website also uses Jekyll, a Ruby static site generator, and Markdown.\ 65 | To contribute to the FreeCAD Project Association website, find [here a few advices and ressources](./FPAweb.md). 66 | -------------------------------------------------------------------------------- /technical/automated_testing.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Automated Testing 6 | 7 | FreeCAD uses two different automated testing mechanisms, depending on the language being tested. The oldest, and most well-used test framework is the Python `unittest` system, which hooks directly into the FreeCAD Test Workbench, but can only test Python code (and Python wrappers to C++ code). The second is the standalone Google Test C++ testing framework, which generates individual executables for each part of the test suite, and is used to directly test C++ code without having to wrap it in Python. 8 | 9 | ## References 10 | 11 | Some good references about automated testing... 12 | 13 | Videos: 14 | * [Back to Basics: C++ Testing - Amir Kirsh - CppCon 2022 - YouTube.](https://www.youtube.com/watch?v=SAM4rWaIvUQ) 15 | * [Practical Advice for Maintaining and Migrating Working Code - Brian Ruth - CppCon 2021 - YouTube.](https://www.youtube.com/watch?v=CktRuMALe2A) 16 | * [The Science of Unit Tests - Dave Steffen - CppCon 2020 - YouTube.](https://www.youtube.com/watch?v=FjwayiHNI1w) 17 | * [TDD, Where Did It All Go Wrong (Ian Cooper)](https://www.youtube.com/watch?v=EZ05e7EMOLM) 18 | 19 | Books: 20 | * [Kent Beck. Test Driven Development by Example. ISBN 9780321146533](https://www.amazon.com/Test-Driven-Development-Kent-Beck/dp/0321146530) 21 | * [Michael Feathers. Working Effectively with Legacy Code. ISBN 0131177052.](https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052) 22 | * [Jeff Langr. Modern C++ Programming with Test-Driven Development: Code Better, Sleep Better. ISBN 1937785483.](https://www.amazon.com/Modern-Programming-Test-Driven-Development-Better/dp/1937785483/) 23 | 24 | ## Terminology 25 | 26 | Test writers have a few terms that are often used, but whose precise definitions aren't well-agreed-upon. The internet is full of arguments about what a "unit" is in 27 | "unit testing" for example. To Kent Beck, author of Test Driven Development (the seminal book on the subject), the "unit" is *the test itself*. In his concept, every test must be wholly isolated from 28 | every other test. They must be able to be run singly, or as part of an entire suite. While that advice has remained, in later years various TDD advocates have suggested that the 29 | function, method, or class under test is the "unit". Consider that if you don't feel like getting into a flame war on the internet, just don't use the word "unit" at all! 30 | 31 | A "Mock" is a replacement class or method that is simpler to construct, easier to reason about, contains code for inspection of who called it with what arguments, and ideally is faster than the class or method it replaces. 32 | For example, writing tests of code that normally downloads files from an internet location, a Mock class will typically be implemented to fake those returns results so the tests don't require a network connection 33 | (and run more quickly and reliably). In Python most test writers use the `unittest.Mock.MagicMock` class to automatically generated any needed mock on the fly. In Google Test you can use the 34 | [`MOCK_METHOD`](https://google.github.io/googletest/reference/mocking.html) macro to achieve some of the same effect. 35 | 36 | A "Fake" is similar to a mock, but typically doesn't bother with the introspection code, it is there simply to replace the existing class, but the test is not interested in how it is used. Rarely used in Python because 37 | of the ease of generating a Mock. 38 | 39 | A "Stub" is a method that simply provides a canned answer for a given input. Sometimes instrumented, but often simply used to replace a more complex function with a simple, predictable response. For example, a random-number 40 | generator may be replaced with a function that simply returns "42" every time so that the results are deterministic (and therefore more easily testable). 41 | 42 | ## Python Testing 43 | 44 | Most Python workbenches in FreeCAD already have at least a rudimentary test suite, so no additional cMake setup should be required beyond simply adding your test file(s) to the cMakeLists.txt file. In addition, in Python it is very easy 45 | to create Mock functions and objects to reduce the dependency on external code, and/or to ensure you are testing only the isolated bit of code that you mean to. A typical Python test file might look like this: 46 | ```python 47 | # SPDX-License-Identifier: LGPL-2.1-or-later 48 | 49 | import unittest 50 | import unittest.mock 51 | 52 | # Optional, allows your IDE to locate the appropriate test files to run outside FreeCAD if the code doesn't 53 | # depend on a FreeCAD import 54 | sys.path.append("../../") 55 | 56 | # Here "Version" is the name of the class being tested 57 | class TestVersion(unittest.TestCase): 58 | 59 | MODULE = "test_metadata" # file name without extension 60 | 61 | def setUp(self) -> None: 62 | pass # Or do any setup you want to run before every test, creating objects, etc. 63 | 64 | def tearDown(self) -> None: 65 | pass # Or to any cleanup work you need 66 | 67 | def test_from_file(self) -> None: 68 | """When loading from a file, the from_bytes function is called with the expected data""" 69 | from addonmanager_metadata import MetadataReader 70 | 71 | MetadataReader.from_bytes = Mock() 72 | with tempfile.NamedTemporaryFile(delete=False) as temp: 73 | temp.write(b"Some data") 74 | temp.close() 75 | MetadataReader.from_file(temp.name) 76 | self.assertTrue(MetadataReader.from_bytes.called) 77 | MetadataReader.from_bytes.assert_called_once_with(b"Some data") 78 | os.unlink(temp.name) 79 | ``` 80 | 81 | If you are developing a FreeCAD module, place the above in a file inside your module, and register your test with FreeCAD's Test Workbench by adding this in your Init.py file: 82 | 83 | ``` 84 | FreeCAD.__unit_test__ += ["my_file"] 85 | ``` 86 | 87 | Then you can run your tests either from inside FreeCAD, using the Test workbench and running the "Self Test" command, or from the command line by issuing: 88 | 89 | ``` 90 | FreeCAD -t my_file 91 | ``` 92 | 93 | ## C++ Testing 94 | 95 | In an ideal world, a C++ test would be perfectly isolated from any external dependencies, which would be replaced with minimal, instrumented "mock" versions of themselves. However, 96 | this almost always requires that the code under test has been *designed* for testing, which is usually not the case for our existing code. In many cases you must add tests for the existing 97 | functionality and implementation, with all its deficiencies, before you can begin to refactor the code to make the tests better. There are many strategies for doing those "dependency injections", 98 | and over time we aspire to refactor FreeCAD such that it is possible, but developers are also encouraged to remember that: 99 | * "A journey of a thousand miles begins with a single step" 100 | * "How do you eat an elephant? One bite at a time." 101 | * "Perfect is the enemy of good" 102 | 103 | A single not-perfect test is better than no test at all (in nearly 100% of cases). As a general rule, a single test should verify a single piece of functionality 104 | of the code (though sometimes that "functionality" is encompassed by multiple functions. For example, you will typically test getters and setters in pairs). Because your test functions will not 105 | themselves be "under test" it is critical that they be as short, simple, and self-explanatory as possible. A common idiom to use is "Arrange-Act-Assert", which in our test 106 | framework looks like this: 107 | ```c++ 108 | // TEST(ClassName, testMethodName), where "testMethodName" is some desciptive indication 109 | // of what is being tested. In simple cases in may simply be the name of the method being 110 | // tested. In more complex cases, it may be a longer statement of the input and expected 111 | // test result (e.g. `toConstStringWithBadDataThrowsException`) 112 | TEST(MappedName, toConstString) 113 | { 114 | // Arrange 115 | // create a MappedName instance and a size variable 116 | Data::MappedName mappedName(Data::MappedName("TEST"), "POSTFIXTEST"); 117 | int size {0}; 118 | 119 | // Act 120 | // invoke the method 121 | const char* temp = mappedName.toConstString(0, size); 122 | 123 | // Assert 124 | // compare the actual result to expected results 125 | EXPECT_EQ(QByteArray(temp, size), QByteArray("TEST")); 126 | EXPECT_EQ(size, 4); 127 | } 128 | ``` 129 | 130 | While you can write a series of standalone tests, it is often more convenient to group them together into a "test fixture." This is a class that your test is derived from, which can 131 | be used both to do setup and teardown, as well as to easily run all tests in the fixture without running the entire suite. Most IDEs recognize Google Test code and will offer the ability 132 | to run both individual tests as well as entire fixtures very easily from the IDE's interface. An example test fixture and associated tests: 133 | ```c++ 134 | // SPDX-License-Identifier: LGPL-2.1-or-later 135 | 136 | #include "gtest/gtest.h" 137 | 138 | #include "App/IndexedName.h" 139 | #include "App/MappedElement.h" // This is the class under test 140 | 141 | // This class is the "Test Fixture" -- each test below is subclassed from this class 142 | class MappedElementTest: public ::testing::Test 143 | { 144 | protected: 145 | // void SetUp() override {} 146 | 147 | // void TearDown() override {} 148 | 149 | static Data::MappedElement givenMappedElement(const char* index, const char* name) 150 | { 151 | Data::IndexedName indexedName {index}; 152 | Data::MappedName mappedName {name}; 153 | return {indexedName, mappedName}; 154 | } 155 | }; 156 | 157 | // Use the TEST_F macro to set up your test's subclass, derived from MappedElementTest 158 | TEST_F(MappedElementTest, constructFromNameAndIndex) 159 | { 160 | // Arrange 161 | Data::IndexedName indexedName {"EDGE1"}; 162 | Data::MappedName mappedName {"OTHER_NAME"}; 163 | 164 | // Act 165 | Data::MappedElement mappedElement {indexedName, mappedName}; 166 | 167 | // Assert 168 | EXPECT_EQ(mappedElement.index, indexedName); 169 | EXPECT_EQ(mappedElement.name, mappedName); 170 | } 171 | 172 | TEST_F(MappedElementTest, moveConstructor) 173 | { 174 | // Arrange 175 | auto originalMappedElement = givenMappedElement("EDGE1", "OTHER_NAME"); 176 | auto originalName = originalMappedElement.name; 177 | auto originalIndex = originalMappedElement.index; 178 | 179 | // Act 180 | Data::MappedElement newMappedElement {std::move(originalMappedElement)}; 181 | 182 | // Assert 183 | EXPECT_EQ(originalName, newMappedElement.name); 184 | EXPECT_EQ(originalIndex, newMappedElement.index); 185 | } 186 | ``` 187 | To run the tests, either directly run the executables that are generated (they are placed in the `$BUILD_DIR/test` subdirectory), or use your IDE's test discovery functionality to run just the tests for 188 | the code you are working on. FreeCAD's Continuous Integration (CI) suite will always run the full test suite, but it is advisable that before submitting a PR you run all tests on your local 189 | machine first. 190 | 191 | The test directory structure exactly matches that of FreeCAD as a whole. To prevent ever having to link the entirety of FreeCAD and all of its tests into a single executable (at some point in the future 192 | when we have better test coverage!), the breakdown of the test executables mimics that of FreeCAD itself, with individual workbenches being compiled into their own test runners. To add a test runner to 193 | a workbench that does not have one, a developer should add a new target for their WB to the end of the cMakeLists.txt file at the top of the `tests` directory structure, e.g. 194 | ```cmake 195 | add_executable(Sketcher_tests_run) 196 | add_subdirectory(src/Mod/Sketcher) 197 | target_include_directories(Sketcher_tests_run PUBLIC ${EIGEN3_INCLUDE_DIR}) 198 | target_link_libraries(Sketcher_tests_run gtest_main ${Google_Tests_LIBS} Sketcher) 199 | ``` 200 | Note that it can be tempting to further group functionality using [value parameterized tests](https://google.github.io/googletest/advanced.html#value-parameterized-tests). A key measure here is to assess whether the grouping benefits the writer or the reader of the tests. Since a test is for use by a future programmer to figure out why it failed, it's okay and often preferred to be more pedantic and more repetitive rather than super efficient. The reader should be able to figure out your test just by reading it, and maybe the test fixture. If more work is required then the test is likely too complex. 201 | -------------------------------------------------------------------------------- /technical/codesigning.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Signing the FreeCAD executables and installers 6 | 7 | ## Mac OS 8 | 9 | ### Prerequisites 10 | 11 | You must be a member of Apple's Developer program to generate and use signing keys. Information can be found at https://developer.apple.com 12 | 13 | To sign an app you must have a "Developer ID Application" certificate. These can be created on the 14 | Certificates, Identifiers & Profiles page of your Apple Developer account. Once it is created, download the certificate onto your computer 15 | and install it into one of your Keychains (double-click on the certificate to open and install it). 16 | 17 | The easiest way to upload an app for notarization is to create an App Store Connect API Key at https://appstoreconnect.apple.com . This is 18 | a file that resides on your computer and can be referenced by the notarization upload tool. Run `xcrun notarytool store-credentials` to store 19 | the credentials and allow the signing script to access them when running the notary tool. 20 | 21 | Note that the Intel bundles must be signed on an Intel machine, and the ARM bundles must be signed on an ARM machine. 22 | 23 | ### Signing process 24 | 25 | Once the prerequisites above are met, actually signing the FreeCAD.app bundle is straightforward: 26 | 1. Create a folder that represents the final disk image. In general it should have the FreeCAD.app bundle in it, and an alias to /Applications. 27 | 2. Copy the file *src/Tools/macos_sign_and_notarize.sh* to the location that contains that folder (not to within the folder itself). 28 | 3. Edit the script to set the name of the folder as well as the release number information and architecture of your machine. 29 | 4. Set an environment variable called `FREECAD_SIGNING_KEY_ID` to the ID of your "Developer ID Application" certificate. You can find the 30 | ID by running `security find-identity -p basic -v`. 31 | 5. Run the script. This will take several minutes, as it scans the bundle for all shared library and executable objects and signs them with 32 | the specified certificate. It will automatically createa DMG, submit it for notarization, and staple the final authorization from Apple to 33 | the disk image. 34 | 35 | Once complete, the disk image is ready for distribution. 36 | 37 | ## Windows 38 | 39 | TBD 40 | -------------------------------------------------------------------------------- /technical/developerglossary.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Developer's Glossary 6 | 7 | Some terms that a developer may run across. 8 | 9 | Note that there may be subtle differences in how some terms are used by developers vs how they are used by users. 10 | 11 | * Binding: the mechanism for linking C++ functionality to and from Python. 12 | * CI (Continuous Integration): the mechanism by which Pull Requests are automatically built and unit tested. 13 | * Feature: generally, an object derived from App::DocumentObject. Also used to refer to a single step in the evolution of a PartDesign Body. 14 | * LibPack: a library of FreeCAD dependencies used on the Windows platform. 15 | * Preference: an entry in user.cfg. Also called a parameter. 16 | * Quarter: a widget which uses the Qt QGraphicsView to display Coin3d scenegraphs. 17 | * Pull Request: how a contributor indicates that they have a change to be merged 18 | * ViewProvider: an object that provides painting services for a Feature. The ViewProvider is notified of changes in a Features properties and, if the change affects the visual representation of the Feature, updates the display. Note that in some modules (ex TechDraw with the Qt GraphicsFramework) there is another layer of functionality that manages the painting. 19 | 20 | ## See Also 21 | 22 | * [FreeCAD glossary wiki entry](https://wiki.freecad.org/Glossary) 23 | * [Contributing](https://github.com/FreeCAD/FreeCAD/blob/master/CONTRIBUTING.md) 24 | -------------------------------------------------------------------------------- /technical/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Technical 6 | 7 | Technical information of interest to Contributors. 8 | 9 | ## The Basics 10 | 11 | - [Developer's Glossary](./developerglossary.md) 12 | 13 | - [Source Tree Basics](./SourceTreeBasics.md) 14 | 15 | - [The Application Module](./TheApplicationModule.md) 16 | 17 | - [The Source Code in More Depth](https://wiki.freecad.org/The_FreeCAD_source_code) 18 | 19 | - [Writing Code for Translation](./translation.md) 20 | 21 | - [Automated Testing](./automated_testing.md) 22 | 23 | - [Dealing with Property Changes](./PropertyChanges.md) 24 | 25 | - The FreeCAD developer's tool set: 26 | 27 | - C++ and Python 28 | - [Qt](https://www.qt.io/): a cross platform development framework 29 | - [OpenCascade](https://www.opencascade.com/open-cascade-technology/): a geometry library 30 | - [Coin3d](https://www.coin3d.org/): a [scenegraph](https://wiki.freecad.org/Scenegraph) manager based on OpenInventor that handles drawing in the 3d window. 31 | - [Pivy](https://wiki.freecad.org/Pivy): a Python binding for Coin3d 32 | 33 | - [Contributing to FreeCAD websites](./Websites.md) 34 | 35 | - [Reference Library](./ReferenceLibrary.md) 36 | 37 | ## Modifying FreeCAD 38 | 39 | - Contributing to FreeCAD 40 | 41 | - The process for submitting changes to FreeCAD is described in the [CONTRIBUTING.md](https://github.com/FreeCAD/FreeCAD/blob/master/CONTRIBUTING.md) 42 | file in the root of the source tree. 43 | 44 | - [Creating a WorkBench](https://wiki.freecad.org/Workbench_creation) 45 | 46 | - The [PowerUser's hub](https://wiki.freecad.org/Power_users_hub) in the FreeCAD wiki contains good information about Python scripting and workbench creation 47 | 48 | - [Python stubs package](./PythonStubsPackage.md) 49 | 50 | - [Accessing User Preferences](./preferences.md) 51 | 52 | - [Controlling Object Deletion](./ObjectDeletion.md) 53 | 54 | - [Create a Python Binding for C++ Class](./CreatePythonBindingForCpp.md) 55 | 56 | - [Checklist for Adding a Feature to a Workbench in C++](./ChecklistForNewFeatureC++.md) 57 | 58 | ## Release Management 59 | 60 | - [Overview](./ReleaseProcess.md) 61 | 62 | - [Major Releases](./MajorRelease.md) 63 | - [Minor Releases](./MinorRelease.md) 64 | - [Building Release Packages](./ReleasePackages.md) 65 | 66 | ## See Also 67 | 68 | - [Wiki Developer Hub](https://wiki.freecad.org/Developer_hub) 69 | 70 | - [Compiling](https://wiki.freecad.org/Developer_hub#Compiling_FreeCAD) 71 | 72 | - [Useful Python Modules](https://wiki.freecad.org/Extra_python_modules) 73 | 74 | - [OpenCascade Tutorials](http://opencascade.wikidot.com/romansarticles) 75 | - [OpenCascade overview presentation](https://dev.opencascade.org/sites/default/files/pdf/Topology.pdf) 76 | - [OpenCasacde_online_documentation](https://dev.opencascade.org/doc/overview/html/index.html) 77 | 78 | - [Scripted Objects](https://wiki.freecad.org/Scripted_objects) 79 | -------------------------------------------------------------------------------- /technical/preferences.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Handling Preferences 6 | 7 | How to retrieve and update user preferences. 8 | 9 | The `user.cfg` XML file contains a hierarchical list of all the preferences used by FreeCAD. 10 | 11 | Each module has its own branch of the hierarchy starting under Preferences/Mod. 12 | 13 | There are two ways of updating preferences: 14 | * the Tools > Edit parameters menu entry 15 | * this is a general purpose preference editor that can change any parameter in the hierarchy. This editor does not perform any validation or suggest valid values. 16 | * custom preference dialogs 17 | * [a sample dialog](https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Part/Gui/DlgSettingsMeasure.cpp) 18 | * these dialogs use [custom FreeCAD widgets](https://wiki.freecad.org/Compile_on_Windows/en#Qt_Designer_plugin) to update preference values. Each preference widget has two special properties: prefEntry and prefPath. prefPath is the identifies the branch of the preference hierarchy and prefEntry identifies the leaf node to be updated. 19 | * two entries are needed in the dialog for each preference value - onSave() in saveSettings and onRestore() in loadSettings(). 20 | 21 | Preference values are retrieved (and sometimes set) using functions from [Base/Parameter.cpp](https://github.com/FreeCAD/FreeCAD/blob/master/src/Base/Parameter.cpp). 22 | 23 | Good examples of retrieving parameters can be found in: 24 | * Python: [get_param()](https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Draft/draftutils/utils.py) in /Mod/Draft/draftutils/util.py 25 | * C++: [various methods](https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/TechDraw/App/Preferences.cpp) in /Mod/TechDraw/App/Preferences.cpp 26 | 27 | ## See also 28 | 29 | * [Preference Editor wiki entry](https://wiki.freecad.org/Preferences_Editor) 30 | -------------------------------------------------------------------------------- /technical/resources/FreeCADweb_01.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/technical/resources/FreeCADweb_01.jpg -------------------------------------------------------------------------------- /technical/resources/FreeCADweb_02.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/technical/resources/FreeCADweb_02.jpg -------------------------------------------------------------------------------- /technical/resources/FreeCADweb_03.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/technical/resources/FreeCADweb_03.jpg -------------------------------------------------------------------------------- /technical/resources/FreeCADweb_05.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/technical/resources/FreeCADweb_05.jpg -------------------------------------------------------------------------------- /technical/resources/FreeCADweb_06.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/technical/resources/FreeCADweb_06.jpg -------------------------------------------------------------------------------- /technical/resources/FreeCADweb_07.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FreeCAD/DevelopersHandbook/4057a127b9a44ee3c6e3787a2573c92305921280/technical/resources/FreeCADweb_07.jpg -------------------------------------------------------------------------------- /technical/resources/TheApplicationModule.svg: -------------------------------------------------------------------------------- 1 | 2 | 17 | 19 | 20 | 22 | image/svg+xml 23 | 25 | 26 | 27 | 28 | 29 | 31 | 52 | 55 | 57 | 66 | 72 | Application 76 | Module 80 | 81 | 82 | 84 | 93 | 99 | Gui 103 | 104 | 105 | 107 | 116 | 122 | App 126 | 127 | 128 | 130 | 139 | 145 | Commands 149 | 150 | 151 | 153 | 162 | 168 | Task 172 | Dialogs 176 | 177 | 178 | 180 | 189 | 195 | Viewproviders 199 | 200 | 201 | 203 | 212 | 218 | Features 222 | 223 | 224 | 226 | 230 | 234 | 235 | 237 | 241 | 245 | 246 | 248 | 252 | 256 | 257 | 259 | 263 | 267 | 268 | 270 | 274 | 278 | 279 | 281 | 285 | 289 | 290 | 296 | The Application Module 300 | 301 | 303 | 312 | 318 | Utilities 322 | 323 | 324 | 326 | 330 | 334 | 335 | 336 | 337 | -------------------------------------------------------------------------------- /technical/snap.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 | # Maintaining the Snap package 6 | 7 | FreeCAD is provided as a Snap package in multiple versions: 8 | * stable -- built from the latest full release 9 | * beta -- built weekly from master 10 | * edge -- built daily from master 11 | * freecad-realthunder -- a convenience build of the LinkStage3 branch 12 | 13 | Each of these is represented by a branch at https://github.com/FreeCAD/FreeCAD-snap -- to make changes,edit [the snapcraft.yaml file](https://github.com/FreeCAD/FreeCAD-snap/blob/master/snap/snapcraft.yaml) on the branch you want to update. 14 | 15 | GitHub actions are used to do the actual building of each of these branches. 16 | 17 | ## Routine maintenance 18 | 19 | The most common thing to break is the KDE Neon extension, which periodically needs to reference an update version of 20 | the kde-frameworks (e.g. kde-frameworks-5-99-qt-5-15-7-core20): 21 | if the snap-building logs contain errors about being unable to locate neon, check for the correct version number at 22 | https://snapcraft.io/docs/kde-neon-extension and update it everywhere it appears in the snapcraft.yaml file. 23 | 24 | Snaps are built based on specific "cores" -- the base operating system whose libraries they use. From time to time 25 | we have to update to a new core. The current builds use "core22", or Ubuntu 22.04 LTS. Updating the core will likely 26 | require updating many of the other version numbers in the snap YAML file. 27 | 28 | ## Dependencies 29 | 30 | Several of FreeCAD's dependencies take a long time to build and seldomly change: the two largest culprits here are 31 | OCCT and GMSH. These two packages have been split into their own "unlisted" snap, called freecad-deps-core22. To 32 | update the versions of those libraries, that snap is the one that must be updated, ratheer than freecad-snap itself. 33 | 34 | ## Important links 35 | 36 | * https://snapcraft.io/freecad 37 | * https://ubuntu.com/tutorials/create-your-first-snap 38 | --------------------------------------------------------------------------------