QGIS/doc/osx.t2t

= Building on MacOS X =

If you want to test QGIS, easiest option is to download and install all-in-one self-containing bundle directly from

https://qgis.org/downloads/macos

On the other hand, if you want to build or develop QGIS on your own, you need a set of dependencies and tools.
These instructions will use the same set of dependencies that are used for all-in-one QGIS bundle,
but you can build QGIS with Homebrew, MacPorts or Conda dependencies too.

https://github.com/qgis/QGIS-Mac-Packager

Included are notes for building on latest Mac OS X with latest updates installed.
The build uses clang compiler.

__Parallel Compilation:__ On multiprocessor/multicore Macs, it's possible to
speed up compilation, but it's not automatic.  Whenever you type "make" (but
NOT "make install"), instead type:

```
make -j [#cpus]
```

Replace [#cpus] with the number of cores and/or processors your Mac has.
To find out how many CPUs you have available, run the following in Terminal:

```
/usr/sbin/sysctl -n hw.ncpu
```

== Install Developer Tools ==

Developer tools are not a part of a standard OS X installation.
As minimum you require command line tools

```
sudo xcode-select --install
```

but installation of Xcode from the App Store is recommended too.

== Install CMake and other build tools ==

For example install Homebrew

```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```

and these development/build tools

```
brew install git
brew install cmake
brew install ninja
brew install pkg-config
brew install wget
brew install bash-completion
brew install curl
brew install gnu-sed
brew install coreutils
brew install ccache
brew install libtool
brew install astyle
brew install help2man
brew install autoconf
brew install automake
brew install txt2tags
```

if you have these tools installed from MacPorts or Conda, it is the same, but we will need to be able to
run `cmake` and others from Terminal in the following steps

== Install Qt5 and QGIS-Deps ==

To build QGIS, we need Qt5 and FOSS dependencies on hand. The Qt5 version ideally should match the version that was
used to build dependency package.

Download the latest QGIS-Deps install script, qt package and QGIS-Deps packages from

https://qgis.org/downloads/macos/deps

You should have one bash script and two tar archive in your download folder.
Run the install script to install Qt and QGIS-Deps to `/opt/` area. You need
root privileges or have write access to `/opt/Qt` and `/opt/QGIS`.

Alternatively you can download and install Qt Open Source for MacOS from the

https://www.qt.io/

in the same version as referenced in the install script.

Note that the QGIS-Deps package is not yet signed, so you may need to add Terminal
to System Preferences -> Security & Privacy -> Privacy -> Developer Tools or manually accept usage
of the libraries when asked by system.

== QGIS source ==

Unzip the QGIS source to a working folder of your choice.
If you are reading this from the source, you've already done this.

If you want to experiment with the latest development sources, go to the github
QGIS project page:

http://github.com/qgis/QGIS

It should default to the master branch.  Click the __Downloads__ button and
select __Download .tar.gz__. Double-click the tarball to unzip it.

//Alternatively//, use git and clone the repository by

```
git clone git://github.com/qgis/QGIS.git
```

== Configure the build ==

CMake supports out of source build so we will create a 'build' dir for the
build process. OS X uses ${HOME}/Applications as a standard user app folder (it
gives it the system app folder icon).  If you have the correct permissions you
may want to build straight into your /Applications folder. The instructions
below assume you are building into a ${HOME}/Applications directory.

In a Terminal cd to the qgis source folder previously downloaded, then:

```
cd ..
mkdir build
cd build

QGIS_DEPS_VERSION=0.3.0;\
QT_VERSION=5.14.1;\
PATH=/opt/QGIS/qgis-deps-${QGIS_DEPS_VERSION}/stage/bin:$PATH;\
cmake \
  -DCMAKE_INSTALL_PREFIX=~/Applications \
  -DCMAKE_BUILD_TYPE=Release \
  -DQGIS_MAC_DEPS_DIR=/opt/QGIS/qgis-deps-${QGIS_DEPS_VERSION}/stage \
  -DCMAKE_PREFIX_PATH=/opt/Qt/${QT_VERSION}/clang_64 \
  ../QGIS
```

__Note:__ Don't forget the `../QGIS` on the last line, which tells CMake to look for the source files.

__Note:__ Double check on the screen output that all libraries are picked from QGIS-Deps `/opt/QGIS`
and not from system `/usr/lib` or Homebrew's `/usr/local/` or system Frameworks `/Library/Frameworks/`.
Especially check Proj, GDAL, sqlite3 and Python paths.

After the initial Terminal configure, you can use ccmake to make further changes:

```
cd build
ccmake ..
```

== Building ==

Now we can start the build process (remember the parallel compilation note at
the beginning, this is a good place to use it, if you can):

```
make -j [#cpus]
```

Now you can run the QGIS from build directory by `./output/bin/QGIS.app/Contents/MacOS/QGIS`

If all built without errors you can then install it:

```
make install
```

or, for an /Applications build:

```
sudo make install
```

For running the installed QGIS, you need to keep the dependencies in `/opt/` folder in place.
If you want to create bundle that runs without these dependencies, please read the documentation in project

https://github.com/qgis/QGIS-Mac-Packager