QIDISlicer1.0.0

doc/How to build - Mac OS.md

@@ -0,0 +1,109 @@
+
+# Building QIDISlicer on Mac OS
+
+To build QIDISlicer on Mac OS, you will need the following software:
+
+- XCode
+- CMake
+- git
+- gettext
+
+XCode is available through Apple's App Store, the other three tools are available on
+[brew](https://brew.sh/) (use `brew install cmake git gettext` to install them).
+
+### Dependencies
+
+QIDISlicer comes with a set of CMake scripts to build its dependencies, it lives in the `deps` directory.
+Open a terminal window and navigate to QIDISlicer sources directory and then to `deps`.
+Use the following commands to build the dependencies:
+
+    mkdir build
+    cd build
+    cmake ..
+    make
+
+This will create a dependencies bundle inside the `build/destdir` directory.
+You can also customize the bundle output path using the `-DDESTDIR=<some path>` option passed to `cmake`.
+
+**Warning**: Once the dependency bundle is installed in a destdir, the destdir cannot be moved elsewhere.
+(This is because wxWidgets hardcodes the installation path.)
+
+FIXME The Cereal serialization library needs a tiny patch on some old OSX clang installations
+https://github.com/USCiLab/cereal/issues/339#issuecomment-246166717
+
+
+### Building QIDISlicer
+
+If dependencies are built without errors, you can proceed to build QIDISlicer itself.
+Go back to top level QIDISlicer sources directory and use these commands:
+
+    mkdir build
+    cd build
+    cmake .. -DCMAKE_PREFIX_PATH="$PWD/../deps/build/destdir/usr/local"
+
+The `CMAKE_PREFIX_PATH` is the path to the dependencies bundle but with `/usr/local` appended - if you set a custom path
+using the `DESTDIR` option, you will need to change this accordingly. **Warning:** the `CMAKE_PREFIX_PATH` needs to be an absolute path.
+
+The CMake command above prepares QIDISlicer for building from the command line.
+To start the build, use
+
+    make -jN
+
+where `N` is the number of CPU cores, so, for example `make -j4` for a 4-core machine.
+
+Alternatively, if you would like to use XCode GUI, modify the `cmake` command to include the `-GXcode` option:
+
+    cmake .. -GXcode -DCMAKE_PREFIX_PATH="$PWD/../deps/build/destdir/usr/local"
+
+and then open the `QIDISlicer.xcodeproj` file.
+This should open up XCode where you can perform build using the GUI or perform other tasks.
+
+### Note on Mac OS X SDKs
+
+By default QIDISlicer builds against whichever SDK is the default on the current system.
+
+This can be customized. The `CMAKE_OSX_SYSROOT` option sets the path to the SDK directory location
+and the `CMAKE_OSX_DEPLOYMENT_TARGET` option sets the target OS X system version (eg. `10.14` or similar).
+Note you can set just one value and the other will be guessed automatically.
+In case you set both, the two settings need to agree with each other. (Building with a lower deployment target
+is currently unsupported because some of the dependencies don't support this, most notably wxWidgets.)
+
+Please note that the `CMAKE_OSX_DEPLOYMENT_TARGET` and `CMAKE_OSX_SYSROOT` options need to be set the same
+on both the dependencies bundle as well as QIDISlicer itself.
+
+Official macOS QIDISlicer builds are currently (as of QIDISlicer 2.5) built against SDK 10.12 to ensure compatibility with older Macs.
+
+_Warning:_ XCode may be set such that it rejects SDKs bellow some version (silently, more or less).
+This is set in the property list file
+
+    /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Info.plist
+
+To remove the limitation, simply delete the key `MinimumSDKVersion` from that file.
+
+
+# TL; DR
+
+Works on a fresh installation of MacOS Catalina 10.15.6
+
+- Install [brew](https://brew.sh/):
+- Open Terminal
+    
+- Enter:
+
+```
+brew update
+brew install cmake git gettext
+brew upgrade
+git clone https://github.com/qidi3d/QIDISlicer/
+cd QIDISlicer/deps
+mkdir build
+cd build
+cmake ..
+make
+cd ../..
+mkdir build
+cd build
+cmake .. -DCMAKE_PREFIX_PATH="$PWD/../deps/build/destdir/usr/local"
+make
+src/qidi-slicer
+```