diff --git a/BUILD_OSX.md b/BUILD_OSX.md index f3a5aea919..0ebbcc8b1c 100644 --- a/BUILD_OSX.md +++ b/BUILD_OSX.md @@ -1,5 +1,27 @@ +# Contents + + + +- [Building FreeCAD on Mac OS 10.15.x -- Catalina](#build-freecad-macos-catalina) +- [Directions](#directions) + - [Install Xcode Command line tools](#install-xcode-cli-tools) + - [Install Conda](#install-conda) + - [Run the shell script](#run-the-shell-script) +- [Building FreeCAD on macOS using homebrew packages with & without formual file](#homebrew-build-fc-on-macos) +- [Requirements](#homebrew-requirements) + - [Install required FreeCAD dependencies](#homebrew-install-required-deps) +- [Limitations of using freecad formula file](#homebrew-limits-of-formula-file) +- [Directions, Installing FreeCAD using brew packages without formula file](#homebrew-install-no-form-file) + - [Expanded Directions](#homebrew-expanded-directions) + - [Boost v1.75 fix](#homebrew-boost-175-fix) +- [Errors, Issues, & Possible Solutions](#errors-issues-solutions) + + + # Building FreeCAD on Mac OS 10.15.x -- Catalina # + + General notes on how the tooling works: This setup uses [conda](https://docs.conda.io) for dependency management. @@ -15,18 +37,26 @@ that architecture. All of this, and some sanity checks, are in a unified shell script. See below. -# Directions # +# Directions + + ## Install XCode Command line tools ## + + Run `xcode-select --install` and click through. ## Install Conda ## + + Refer to [MiniConda Docs](https://docs.conda.io/en/latest/miniconda.html). ## Run the shell script ## + + Run the `./build_unix_dev_conda.sh` and go get coffee. Builds take an hour+ on a 2012 Retina MacBook. @@ -36,3 +66,237 @@ Output binaries will be in the `./build/bin/FreeCAD` *and* You can code/build/test using the cmake configuration folder `./build` in the standard way *from within the freecad_dev conda environment*. +--- + +# Building ⚙️ FreeCAD on macOS ⌘ using homebrew 🍺 with & without a formula file + + + +> The below procedure provides on alternative way to install FreeCAD from the git source on macOS without having to use conda, but rather rely on [**mac homebrew**][lnk1] to manage dependencies. + +## Requirements + + + +- macOS, running high sierra _10.13_ or later +- mac homebrew installed and working +- all required dependencies to build FreeCAD installed using `brew install` + +There is an official [**homebrew tap**][lnk2] that provides a list of formula along with freecad to setup all the dependencies to build FreeCAD from source on macOS, and also provides prebuilt bottles to install FreeCAD from a package rather than building from source. + +> 💡 The below steps will build a FreeCAD binary that will launch FreeCAD from a command line interface, and will **NOT** build the **FreeCAD.app** bundle, ie. a double clickable app icon that can be launched from a Finder window. + +### Install required FreeCAD dependencies + + + +- setup homebrew to use the official [**freecad-homebrew**][lnk2] tap. + +```shell +brew tap FreeCAD/freecad +``` + +- install FreeCAD dependencies provided by the tap + +```shell +brew install --only-dependencies freecad +``` + +> the above step will install FreeCAD dependencies provided by the tap, and if a _bottle_ is provided by the tap homebrew will install the bottled version of the dep rather than building from source, unless the `install` command explicitly uses a _flag_ to build from source. + +After all the dependencies have been installed, it should be possible to install freecad from the provided bottle. + +```shell +brew install freecad/freecad/freecad +``` + +> As of writing this, there are bottles provided for macOS Catalina and Big Sur +> > if running a different version of macOS then building freecad from source will be required. + +To explicitly build freecad from source using the formula file provided by the tap + +```shell +brew install freecad/freecad/freecad --build-from-source --HEAD --verbose +``` + +The above command will grab the latest git source of FreeCAD and output the build process to the terminal. + +> ⏲ On my MacBookPro 2013 late model it takes ~ 60 minutes to build FreeCAD from source. + +After the _make_ and _make install_ process completes it should be possible to launch FreeCAD from any directory using a terminal with the below commands, + +```shell +FreeCAD +FreeCADCmd +``` + +- `FreeCAD` will launch a GUI version of FreeCAD +- `FreeCADCmd` will launch **only** a command line version of FreeCAD + +## Limitations of using the freecad formula file + + + +If freecad is installed via the bottle then one will have to wait for a new bottle to be generated to install a later version of freecad. However, if freecad is built from source, then FreeCAD will have all the updates up to the time the build process was started. + +When installing FreeCAD from source using the formula file provided by brew each subsequent build will require a complete rebuild of FreeCAD thus requiring an additional 60 minutes to build (my Macbook), and if any of the dependencies FreeCAD relies on is updated then more than likely FreeCAD will require a rebuild. mac homebrew does provide a feature to pin packages at specific versions to prevent them from updating, and also allows setting of an environment variable to prevent homebrew from automatically checking of updates (which can slow things down). All that said, FreeCAD can be built using all the dependencies provided by mac homebrew, but not using the formula file but rather cloning the source to an arbitrary path on a local file system providing a couple of advantages + +- if `brew cleanup` is ran, and FreeCAD was installed using the above provided command then all the source tarballs or bottles that were _checked out_ or downloaded during the install process will be delete from the system, and thus if a reinstall or upgrade is required then homebrew will have to refetch the bottles, or reclone the git source again. +- mac homebrew does provide a method, _install flag_ for keeping the source regardless if the build succeeds or fails, thus allowing to navigate to the git clone of FreeCAD source however the options are limited IMHO, and performing a standard `git clone` outside of homebrew is **much** preferred. +- cloning the FreeCAD source allows passing **any** cmake flags not provided by the formula file + - allowing to use other build systems such as _ninja_ + - allowing the use of alternate compilers, ie. _ccache_ + - pulling in subsequent updates are quicker because the `git clone` of the FreeCAD source will remain on the local filesystem even if a `brew cleanup` is ran + - subsequent recompiles should not take 60 minutes if using a cachining strategy such as _ccache_. + +## Directions, Installing FreeCAD using brew packages without a formula file + + + +> ⚠️ the below directions assume macOS high sierra or later is being used, homebrew is setup properly and all dependencies have successfully been installed. + +**TL;DR** + +- clone the FreeCAD source, pass cmake args/flags within source dir, run make, and make install, then profit 💰 + +### Expanded Directions + + + +- clone the FreeCAD source from GitHub + +```shell +git clone https://github.com/freecad/freecad +cd ./freecad +git fetch --unshallow +``` + +> The above _fetch_ cmd will take some time to fetch the commit history for the repo, but if a shallow clone is performed then FreeCAD will not show to correct build number in the About dialog [**learn more**][lnk3] + +I used the below cmake flags to build FreeCAD from a clone, and I'd recommend building FreeCAD in a specific _build branch_ rather than the master branch to not pollute the master branch with build artifacts. Also I'd prefer using clang provided by mac homebrew rather than Xcode, and if possible, I'd prefer using ccache provided by homebrew over using homebrew clang to speed rebuilds when required. + +Set the path / environment variables for specifying the compilers to use + +``` +export CC="/usr/local/opt/llvm/bin/clang" +export CXX="/usr/local/opt/llvm/bin/clang++" +``` + +- linking the brew provided install of python 3 will be required, in order for cmake to find the proper python, and python libraries. + +```shell +brew link python@3.9 +``` + +#### Boost v1.75 fix + + + +- due to recent changes in boost ie. v1.75, building FreeCAD will fail with the below linking error message, for a more exhaustive error message, [**learn more**][lnk4] + +To work around the linking issue until the [**PR**][lnk5] is merged install boost will the patches applied within the PR. + +```shell +ld: library not found for -licudata +``` + +```shell +git checkout -b mybuild + +cmake \ +-DCMAKE_C_FLAGS_RELEASE=-DNDEBUG \ +-DCMAKE_CXX_FLAGS_RELEASE=-DNDEBUG \ +-DCMAKE_INSTALL_PREFIX=/opt/beta/freecad \ +-DCMAKE_INSTALL_LIBDIR=lib \ +-DCMAKE_BUILD_TYPE=Release \ +-DCMAKE_FIND_FRAMEWORK=LAST +-DCMAKE_VERBOSE_MAKEFILE=ON \ +-Wno-dev \ +-DCMAKE_OSX_SYSROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX10.14.sdk \ +-std=c++14 \ +-DCMAKE_CXX_STANDARD=14 \ +-DBUILD_ENABLE_CXX_STD:STRING=C++14 \ +-Wno-deprecated-declarations \ +-DBUILD_QT5=ON \ +-DUSE_PYTHON3=1 -DPYTHON_EXECUTABLE=/usr/local/bin/python3 \ +-DBUILD_FEM_NETGEN=1 \ +-DBUILD_FEM=1 \ +-DBUILD_TECHDRAW=0 \ +-DFREECAD_USE_EXTERNAL_KDL=ON \ +-DFREECAD_CREATE_MAC_APP=OFF +-DCMAKE_PREFIX_PATH="/usr/local/opt/qt/lib/cmake;/usr/local/opt/nglib/Contents/Resources;/usr/local/opt/vtk@8.2/lib/cmake;/usr/local;" . +``` + +After the configuration completes run the below commands to start the build & install process + +```shell +make +make install +``` + +> The above cmake build flags are the ones I've had good luck with, but that's not to say other ones can be added or removed. And for reasons unknown to me the above build process takes ~ twice along than using `brew install --build-from-source` + +If everything goes well FreeCAD should be able to launch from a terminal + +## Errors and Issues + possible solutions + + + +While going through the process of getting FreeCAD to compile on macOS using brew with a formula file and without a formula file I ran into several issues along the way, and I'll document them here in case anyone else is run into such error and may have a frame of reference why such error happens. All that said, I **can not** list every possible eror that could arrise, but hopefully these can help guide will troubleshooting a problematic build. + +--- + +
+error: no member named + +```shell +[ 18%] Building CXX object src/Gui/CMakeFiles/FreeCADGui.dir/DlgProjectInformationImp.cpp.o +cd /opt/code/github/public/forks/freecad/build/src/Gui && /usr/local/bin/ccache /usr/local/opt/llvm/bin/clang++ -DBOOST_ALL_NO_LIB -DBOOST_FILESYSTEM_DYN_LINK -DBOOST_PP_VARIADICS=1 -DBOOST_PROGRAM_OPTIONS_DYN_LINK -DBOOST_REGEX_DYN_LINK -DBOOST_SYSTEM_DYN_LINK -DBOOST_THREAD_DYN_LINK -DBUILD_ADDONMGR -DCMAKE_BUILD_TYPE=\"Release\" -DFreeCADGui_EXPORTS -DGL_SILENCE_DEPRECATION -DHAVE_CONFIG_H -DHAVE_FREEIMAGE -DHAVE_PYSIDE2 -DHAVE_RAPIDJSON -DHAVE_SHIBOKEN2 -DHAVE_TBB -DNDEBUG -DOCC_CONVERT_SIGNALS -DPYSIDE_QML_SUPPORT=1 -DQT_CORE_LIB -DQT_GUI_LIB -DQT_NETWORK_LIB -DQT_NO_DEBUG -DQT_OPENGL_LIB -DQT_PRINTSUPPORT_LIB -DQT_SVG_LIB -DQT_UITOOLS_LIB -DQT_WIDGETS_LIB -DQT_XML_LIB -D_OCC64 -I/opt/code/github/public/forks/freecad/build -I/opt/code/github/public/forks/freecad/build/src -I/opt/code/github/public/forks/freecad/src -I/opt/code/github/public/forks/freecad/src/Gui -I/opt/code/github/public/forks/freecad/src/Gui/Quarter -I/opt/code/github/public/forks/freecad/build/src/Gui -I/opt/code/github/public/forks/freecad/src/Gui/.. -I/opt/code/github/public/forks/freecad/build/src/Gui/.. -I/opt/code/github/public/forks/freecad/build/src/Gui/Language -I/opt/code/github/public/forks/freecad/build/src/Gui/propertyeditor -I/opt/code/github/public/forks/freecad/build/src/Gui/TaskView -I/opt/code/github/public/forks/freecad/build/src/Gui/Quarter -I/opt/code/github/public/forks/freecad/build/src/Gui/DAGView -I/usr/local/include/eigen3 -I/usr/local/include/PySide2/QtCore -I/usr/local/include/PySide2/QtGui -I/usr/local/include/PySide2/QtWidgets -isystem /usr/local/include -isystem /usr/local/Frameworks/Python.framework/Versions/3.9/include/python3.9 -iframework /usr/local/opt/qt/lib -isystem /usr/local/opt/qt/lib/QtCore.framework/Headers -isystem /usr/local/opt/qt/./mkspecs/macx-clang -isystem /usr/local/opt/qt/lib/QtWidgets.framework/Headers -isystem /usr/local/opt/qt/lib/QtGui.framework/Headers -isystem /Library/Developer/CommandLineTools/SDKs/MacOSX10.14.sdk/System/Library/Frameworks/OpenGL.framework/Headers -isystem /usr/local/opt/qt/lib/QtOpenGL.framework/Headers -isystem /usr/local/opt/qt/lib/QtPrintSupport.framework/Headers -isystem /usr/local/opt/qt/lib/QtSvg.framework/Headers -isystem /usr/local/opt/qt/lib/QtNetwork.framework/Headers -isystem /usr/local/opt/qt/include -isystem /usr/local/opt/qt/include/QtUiTools -isystem /usr/local/include/shiboken2 -isystem /usr/local/include/PySide2 -isystem /usr/local/opt/qt/lib/QtXml.framework/Headers -Wall -Wextra -Wpedantic -Wno-write-strings -Wno-undefined-var-template -DNDEBUG -isysroot /Library/Developer/CommandLineTools/SDKs/MacOSX10.14.sdk -fPIC -I/usr/local/Cellar/open-mpi/4.0.5/include -fPIC -std=gnu++14 -o CMakeFiles/FreeCADGui.dir/DlgProjectInformationImp.cpp.o -c /opt/code/github/public/forks/freecad/src/Gui/DlgProjectInformationImp.cpp +/opt/code/github/public/forks/freecad/src/Gui/DlgProjectInformationImp.cpp:56:9: error: no member named 'lineEditProgramVersion' in 'Gui::Dialog::Ui_DlgProjectInformation' + ui->lineEditProgramVersion->setText(QString::fromUtf8(doc->getProgramVersion())); + ~~ ^ +1 error generated. +make[2]: *** [src/Gui/CMakeFiles/FreeCADGui.dir/DlgProjectInformationImp.cpp.o] Error 1 +make[1]: *** [src/Gui/CMakeFiles/FreeCADGui.dir/all] Error 2 +make: *** [all] Error 2 +``` + +
+ +FreeCAD will fail to build if creating a build directory within the _src_ directory and running `cmake ..` within the newly created _build_ directory. As it currently stands, `cmake` needs run within the _src_ directory or the below error message will more than likely appear durning the build process. + +--- + +
+ ⚠️ warning: specified path differs in case from file name on disk + +``` +/opt/code/github/public/forks/FreeCAD/src/Gui/moc_DlgParameterFind.cpp:10:10: warning: non-portable path to file '"../../../FreeCAD/src/Gui/DlgParameterFind.h"'; specified path differs in case from file name on disk [-Wnonportable-include-path] +#include "../../../freecad/src/Gui/DlgParameterFind.h" + ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + "../../../FreeCAD/src/Gui/DlgParameterFind.h" +1 warning generated. +``` + +
+ +On macOS most if not all filesystems are case **insensitive** whereas most GNU+Linux distros use _case sensitive_ file systems. So if freecad source is cloned within a `FreeCAD` directory the build process on macOS will look for a `freecad` that is _case sensitive_ however the file system isn't case sensitive, thus the compiler will provide the above warning message. + +One way to resolve such error message is to rename `FreeCAD` to `freecad` + +```shell +mv FreeCAD freecadd; +mv freecadd freecad; +``` + +--- + +The text within this document is by no means exhaustive and aiming to cover every edge but does aim to serve as a decent starting point for setting up macOS to build FreeCAD from source. + + + +[lnk1]: +[lnk2]: +[lnk3]: +[lnk4]: +[lnk5]: