Skip to content

Commit edb6b94

Browse files
chenneschennes
authored
Create dependencies.md
1 parent b7ccf96 commit edb6b94

File tree

1 file changed

+139
-0
lines changed

1 file changed

+139
-0
lines changed

‎gettingstarted/dependencies.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
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+
## Major dependencies
19+
20+
The following is a brief overview of what each of FreeCAD's most critical 3rd-party library dependencies provide.
21+
22+
### OpenCASCADE
23+
24+
OpenCASCADE Technology (OCCT) is a full-featured, professional grade CAD kernel. It was developed in 1993 and originally called
25+
CAS.CADE, by Matra Datavision in France for the Strim (Styler) and Euclid Quantum applications. In 1999 it was released as open
26+
source software, and since then it's been called OpenCASCADE.
27+
28+
OCCT is a big and complex set of C++ libraries that provide functionality required by a CAD application:
29+
* A complete STEP compliant geometry kernel.
30+
* A topological data model and needed functions to work with shapes (cut, fuse, extrude, and many others).
31+
* Standard import and export processors for files like STEP, IGES, VRML.
32+
* A 2D and 3D viewer with selection support.
33+
* 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.
34+
35+
Note that the "Community Edition" of OpenCASCADE is no longer supported by FreeCAD, you must install the first-party library.
36+
37+
### Python
38+
39+
Python is a popular all-purpose scripting language that is widely used in Linux and open source software.
40+
In FreeCAD, Python is used during compilation and also at runtime in different ways. FreeCAD itself contains
41+
hundreds of thousands of lines of Python code, and all FreeCAD Addons and Macros are written in Python.
42+
43+
### Qt
44+
45+
Qt is one of the most popular graphical user interface (GUI) toolkits available in the open source world.
46+
FreeCAD uses this toolkit to draw the interface of the program, as well as to provide some advanced networking functionality
47+
and translation facilities. FreeCAD currently provides primary support for Qt v5.12 - v5.15, and work is ongoing to support Qt v6.4 and
48+
later.
49+
50+
Further information about Qt libraries and their programming documentation are available at [Qt Documentation](https://doc.qt.io/).
51+
52+
### PySide and Shiboken
53+
54+
Shiboken is the Python binding generator that Qt for Python uses to create the PySide module, in other words, it is the system that
55+
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.
56+
FreeCAD provides primary support for PySide2 (corresponding to Qt5), and support for PySide6 (corresponding to Qt6) is in progress.
57+
Python developers should import `PySide` (with no numeric suffix) -- at compile-time FreeCAD's build system will generate the appropriate
58+
version.
59+
60+
### Coin3D
61+
62+
The dependencies Coin, Quarter, and Pivy are collectively part of the Coin3D library system. Coin3D is a high-level 3D graphics library
63+
with a C++ application programming interface. It uses scenegraph data structures to render real-time graphics suitable for all kinds
64+
of scientific and engineering visualization applications.
65+
66+
Coin3D (Open Inventor) is used as the 3D viewer in FreeCAD because the OpenCASCADE viewer (AIS and Graphics3D) has limitations and performance
67+
bottlenecks, especially with large-scale engineering rendering; other things like textures or volumetric rendering are not entirely supported
68+
by the OpenCASCADE viewer.
69+
70+
### Boost
71+
72+
The Boost C++ libraries are collections of peer-reviewed, open source libraries that extend the functionality of C++. They are intended to
73+
be widely useful across a broad spectrum of applications, and to work well with the C++ Standard Library. The Boost license is designed
74+
to encourage their use in both open source and closed source projects. Over time, many Boost libraries end up incorporated into the C++ standard
75+
library itself. As this happens, developers should work to transition their code to the `std::` variant rather than the `boost::` variant. Note
76+
that exception is made for `boost::regex`, which as of this writing is still considerably faster than its `std::regex` counterpart.
77+
78+
### Xerces-C++
79+
80+
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
81+
read and write XML data. A shared library is provided for parsing, generating, manipulating, and validating XML documents. Xerces-C++ is
82+
faithful to the XML 1.0 recommendation and associated standards. The parser is used for saving and restoring parameters in FreeCAD.
83+
84+
### Eigen3
85+
86+
Eigen is a C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms. If you just want to use Eigen,
87+
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
88+
defined in the headers. Eigen is used in FreeCAD for many vector operations in 3D space.
89+
90+
### Zipios++
91+
92+
Zipios++ is a C++ library for reading and writing .zip files. Access to individual entries is provided through standard C++ iostreams. A
93+
simple read-only virtual file system that mounts regular directories and .zip files is also provided. The structure and public interface
94+
of Zipios++ are loosely based on the java.util.zip package of Java.
95+
96+
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
97+
and XML files. Therefore, Zipios++ is used to save and open compressed archives, including FreeCAD files.
98+
99+
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++
100+
library, provided by your operating system, you may set `-DFREECAD_USE_EXTERNAL_ZIPIOS=ON` with cmake.
101+
102+
Zipios++ uses the Zlib library to perform the actual decompression of files.
103+
104+
### Zlib
105+
106+
Zlib is designed to be a free, general-purpose, lossless data-compression library for use on any computer hardware and operating system.
107+
It implements the DEFLATE compression algorithm commonly used in .zip and .gzip files.
108+
109+
A copy of this library is included in the source code of FreeCAD so it is compiled together with it.
110+
111+
## Dependency management
112+
113+
Each OS uses different mechanisms to supply dependencies. These mechanisms are typically designed such that installing a single dependency
114+
also automatically installs all of *its* dependencies, eliminating the need for you to manually install every single dependency by hand.
115+
116+
### Linux
117+
118+
As a general rule in Linux, you should use your system's package manager to install dependencies, including Python libraries, rather than using `pip`.
119+
Unfortunately, different distributions use different names for the various packages, so it is sometime challenging to determine exactly what needs
120+
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
121+
(usually provided under a different name).
122+
123+
A single command to install the dependendcies on Ubuntu-based systems is:
124+
```
125+
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 python3-pyside2uic qtbase5-dev qttools5-dev swig
126+
```
127+
128+
### Windows
129+
130+
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
131+
download provides a single source for all of FreeCAD's library dependencies.
132+
133+
### Mac OS
134+
135+
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
136+
this can be a very challenging process because Homebrew often updates libraries to new versions before downstream packages are updated to accomodate them:
137+
it is usually necessary for a developer to manually extract an old dependency for installation as a custom "tap".
138+
139+
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).

0 commit comments

Comments
 (0)