Lesson 1. Setting up the Development Environment

📘 Tutorial: Creating Addons for FreeCAD

Lesson Goal: Set up everything necessary to create, test, and debug addons effortlessly.

---

🔧 Step 1. Make sure you have FreeCAD installed

Requirements:

• FreeCAD version 0.20 or newer (1.0+ is better)
• Runs on Windows, Linux, or macOS

👉 If you don’t have FreeCAD yet, download it from the official website:
🔗 https://www.freecad.org/downloads.php

Choose:

• Windows: .exe (installer) or .7z (portable)
• Linux: AppImage or package from repository
• macOS: .dmg

💡 Tip: For learning, it’s better to use an installed version (via installer), as it’s more stable and easier to set up.

---

📁 Step 2. Find the Addon Folder

FreeCAD looks for user-defined addons in a special Mod folder.
The path depends on your OS and installation type.

✅ How to find the folder precisely?

1. Launch FreeCAD.
2. Open the Python Console:
   View → Panels → Python console
3. Enter the command:

import FreeCAD
print(FreeCAD.getUserAppDataDir())

4. Press Enter.

You will see a path, for example:

• Windows (installed version):
  C:\Users\YourName\AppData\Roaming\FreeCAD\
• Windows (portable):
  D:\FreeCAD\data\
• Linux:
  /home/your_name/.local/share/FreeCAD/
• macOS:
  /Users/your_name/Library/Application Support/FreeCAD/

➕ Create the Mod folder

Inside this directory, there must be a Mod folder.
If it doesn’t exist, create it manually.

Example for Windows:

C:\Users\YourName\AppData\Roaming\FreeCAD\Mod\

💡 Quick way to open the folder on Windows:
Press Win + R → type %APPDATA%\FreeCAD → Enter

---

🖥 Step 3. Configure a Text Editor (optional, but highly recommended)

While you can write code in Notepad, it’s more convenient to use an editor with:

• Python syntax highlighting
• Autocompletion
• Ability to run scripts

🔹 We recommend: Visual Studio Code (VS Code)

1. Download and install: https://code.visualstudio.com/
2. Install the Python extension (from Microsoft)
3. (Optional) Install the FreeCAD for VS Code extension – it adds FreeCAD API hints

🔹 How to open the addon folder in VS Code?

1. Launch VS Code
2. File → Open Folder
3. Select the Mod folder (or a specific addon within it)

Now you can see the project structure and edit files comfortably.

---

🛠 Step 4. Explore FreeCAD’s Built-in Tools

FreeCAD already contains everything you need for development.

1. Python Console

• Menu: View → Panels → Python console
• Allows executing commands in real-time
• Example: type App.newDocument() → a new document will be created

2. Report View

• Menu: View → Panels → Report view
• Shows errors, warnings, logs
• Always keep it open when testing an addon!

3. Macro Recorder

• Menu: Macro → Macros...
• Record button – records your actions as Python code
• An excellent way to learn the FreeCAD API

💡 Try this:

1. Click Macro → Start recording
2. Create a box (Part → Box)
3. Stop recording
4. Open the macro – you’ll see the actual code for creating the object!

---

🧪 Step 5. Verification: Create a Test Folder

To ensure everything is working:

1. In the Mod folder, create a subfolder:

   TestAddon

2. Inside, create an __init__.py file (it can be empty) – this tells Python that the folder is a module.
3. Restart FreeCAD.
4. Open the Report view.

If you don’t see any errors – it means FreeCAD successfully scanned the Mod folder.

❗ If an ImportError appears – check:

• Correctness of the folder name (no spaces or Cyrillic characters)
• Presence of __init__.py (not always mandatory in newer versions, but safer to add)

---

🗂 Developer Folder Structure (Summary)

By the end of this lesson, you should have this structure:

(FreeCAD user folder)
└── Mod/
    └── TestAddon/
        └── __init__.py   ← can be empty

And you know:

• Where Mod is located
• How to open Python Console and Report View
• How to use the Macro Recorder
• How to set up VS Code (optional)

---

✅ Practical Task

1. Find the Mod folder via FreeCAD.getUserAppDataDir()
2. Create a MyFirstAddon folder inside Mod
3. Add an empty __init__.py file to it
4. Restart FreeCAD
5. Make sure there are no errors in the Report view

🎯 Goal: FreeCAD should launch without errors and “see” your folder.

---

▶️ What’s next?

In Lesson 2, we will create a real working addon:

• Add a button
• Make it do something
• Learn to register commands and workbenches