Pieter Hijma

Emacs Setup for FreeCAD and OCCT

In this section we discuss how to set up Emacs for FreeCAD and Open CASCADE Technology (OCCT). With a proper Emacs setup, the experience of debugging FreeCAD and OCCT can be much improved. We discuss a setup for Emacs that allows jumping through FreeCAD’s C++ code and through its Python code.

C++

In Emacs we will install Eglot and the language server clangd. Together with information from the compilation process, it will provide Emacs with IDE-like capabilities.

In the previous section we defined scripts for CMake and in the debug versions we added the flag -DCMAKE_EXPORT_COMPILE_COMMANDS=1, which results in the file compile_commands.json in both $BUILD_DIR_OCCT and $BUILD_DIR_FREECAD. These files contain information on how the respective software was compiled. In the source directories of OCCT and FreeCAD we symlink these files to acquire IDE-like capabilities in Emacs.

cd $SRC_DIR_OCCT
ln -s $BUILD_DIR_OCCT/compile_commands.json

We then exclude these files from tracking by Git:

echo "/compile_commands.json" >> .git/info/exclude

We install the package clang that contains the language server clangd. In Emacs we install the Eglot package and configure it as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

(use-package eglot
  :config
  (progn
    (add-to-list 'eglot-server-programs
                 '((c++-mode c-mode) "clangd"))
    (add-hook 'c-mode-hook
              'eglot-ensure)
    (add-to-list 'auto-mode-alist
                 '("\\.gxx\\'" . c++-mode))
    (add-hook 'c++-mode-hook
              'eglot-ensure)))

Note that using clangd as a language server works even though the software is compiled with GCC. Below you see a short demonstration of the resulting capabilities in Emacs. You can see Emacs showing a summary of the function, jumping directly in the function from the call, jumping back, and jumping into a function from the FreeCAD file directly into the source base of OCCT and back to FreeCAD again.

Python

To achieve the same kind of capabilities in Python, we can install the Emacs elpy package. It requires the following packages on my system: flake8 to check the Python style and Python pip for package management for elpy:

pacman -S flake8 python-pip

We can then configure Emacs to use elpy:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

(use-package python
  :mode ("\\.py" . python-mode)
  :config
  (use-package elpy
    :init
    (add-to-list 'auto-mode-alist '("\\.py$" . python-mode))
    :requires projectile
    :config
    (setq elpy-rpc-backend "jedi")
    :bind (:map elpy-mode-map
              ("M-." . elpy-goto-definition)
              ("M-," . pop-tag-mark)))
  (elpy-enable))

The elpy package will suggest to use a virtual environment when we attempt to configure it with M-x elpy-config that we then can activate with M-x pyvenv-activate. So, let’s create a virtual environment:

python -m venv elpy-venv

We can then activate this environment with the above command.

The following video shows the capabilities of Emacs in FreeCAD’s Python code. You can see Emacs being able to jump into another module and jumping into the definition of the function from the call of the function.

While browsing source code in the FreeCAD repository works well, it is sometimes necessary to load the Python FreeCAD API in another environment as well, for example in an external workbench. This can be accomplished with the following Python commands:

1
2
3
4
5
6
7
8

import os
FREECADPATH = os.environ.get['BUILD_DIR_FREECAD'] + '/lib'

import sys
sys.path.append(FREECADPATH)

import FreeCAD as App
import FreeCADGui as Gui

Last updated: 1 May 2022