Skip to content

Getting started on macOS

Jump to bottom
Jasmin B. Maglic edited this page Aug 8, 2022 · 14 revisions

MoloVol is distributed through .dmg installation files. These files are commonly used for installing applications on macOS. If you simply want to used the software "out-of-the-box" without needing access to the source code you can simply download the appropriate installation file for your platform. This article covers how to download the source code and compile it from scratch.

This article provides a detailed explanation of how to set up a command line development environment on macOS and compile MoloVol. You may want to do this if the installation file is not available for your platform or macOS version or if you would like to contribute to the project.

This guide has been tested with Catalina and Big Sur.

Requirements

You will need:

  • Xcode command line tools
  • Git
  • CMake
  • wxWidgets 3.1.5

Installing Xcode command line tools

You may need to first install Xcode command line tools, if you haven't already. This should be as easy as running the following command in the terminal.

$ xcode-select --install

Afterwards you should have clang installed. You can check whether clang is installed by requesting the version.

$ gcc -v
Configured with: ...
Apple clang version 12.0.5 (clang-1205.0.22.9)
Target: ...
Thread model: ...
InstalledDir: /Library/Developer/CommandLineTools/usr/bin

Installing wxWidgets

To install wxWidgets visit https://www.wxwidgets.org and download the appropriate source files for macOS. Unzip the download file and place it in a directory of your choice, such as your user directory Users/myname/wx. Then enter that directory.

myname:~$ cd wx/wxWidgets-3.1.5

In order to compile wxWidgets and not risk overwriting it upon recompilation, create a new directory and enter it.

myname:wxWidgets-3.1.5$ mkdir build-debug
myname:wxWidgets-3.1.5$ cd build-debug

Afterwards run the configuration executable in the parent folder with the following flags:

  • Enable building for debugging.
  • Disable "shared" to obtain a static library.
  • Enable unicode support.
  • Minimum supported macOS version.
  • Build a universal library for 64 bit and ARM architectures. Needed for compiling the code on CPU chips with ARM architecture such as Apple M1.
myname:build-debug$ ../configure --enable-debug --disable-shared --enable-unicode --with-macosx-version-min=10.11 --enable-universal_binary=arm64,x86_64

Now you're ready to compile. Simply run:

myname:build-debug$ make

This step will take a while. Once compilation has finished, you can place the library files in your system's default library folder.

myname:build-debug$ make install

You can check whether your installation was successful by running the wx-config command.

$ wx-config --list
    Default config is osx_cocoa-unicode-static-3.1
  Default config will be used for output

Finally, you can remove the build files. They are no longer needed and take up disk space.

myname:build-debug$ make clean

If you ever wish to remove the installation, run the following command from your build folder.

myname:build-debug$ make uninstall

Downloading and compiling the source code

You will need to install Git if you haven't already. Visit https://git-scm.com. Once you have Git installed on your computer you can clone the repository to download all files to your local machine.

myname:~$ git clone https://github.com/jmaglic/MoloVol
myname:~$ cd MoloVol

Compilation requires CMake. Visit https://cmake.org/install/ to download the installation files, or install CMake through homebrew. Assuming you are in the root directory of the cloned repository, create a new build directory and enter it. Afterwards, run cmake with your desired options.

myname:MoloVol$ mkdir build
myname:MoloVol$ cd build
myname:build$ cmake -DCMAKE_BUILD_TYPE=RELEASE ..

It is recommended to build the release build, because running calculations can take a long time without the optimisation flags enabled. CMake now creates a Makefile for compilation. To compile the code run make inside your build folder.

myname:build$ make

The compiled binary file, i.e., executable, will be located in the same directory and can be executed.

myname:build$ ./MoloVol

CMake options

CMake options can be set either when creating the build files for the first time (1) or afterwards (2) by changing cache variables. This is done with a leading -D and by specifying the value with an equals sign.

(1) myname:build$ cmake -DCMAKE_OPTION=ON ..
(2) myname:build$ cmake . -DCMAKE_OPTION=OFF

If you are building on a Mac with Apple Silicon (arm64 architecture), you need to manually set the target architecture to arm64. Otherwise, the executable will be built for x86_64 architecture.

myname:build$ cmake . -DCMAKE_OSX_ARCHITECTURES=arm64

There are three additional build options. Each is set to OFF by default.

  • ABS_RESOURCE_PATH - If enabled, the paths to the 'elements' and space group files are set to a platform specific absolute path
  • OSX_FAT_FILE - Builds an arm64/x86_64 fat file on macOS
  • MOLOVOL_BUILD_TESTING - Enables MoloVol unit tests

For unit tests to work, it is additionally necessary to enable the higher level option BUILD_TESTING.

For development it is recommended to use the following configuration:

myname:build$ cmake .. -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_BUILD_TYPE=RELEASE -DMOLOVOL_BUILD_TESTING=ON -DBUILD_TESTING=ON

Creating an installation file (.dmg) - DEPRECIATED

This section relies on the use of a custom Makefile. This Makefile is being depreciated in favour of a CMake-based approach.

You can create your own .dmg file with which to easily install MoloVol. First make sure that there are no binaries or build files left anywhere.

myname:MoloVol$ make cleanall

Then simply run the following command and a .dmg file should be created inside the bin/ folder.

myname:MoloVol$ make dmg

In order to open the newly created file from the command line use the open command.

myname:MoloVol$ open bin/MoloVol_macOS_version.dmg
Clone this wiki locally