Skip to content

Commit a8e05f0

Browse files
3nids3nids
authoredApr 24, 2019
add mac/development README
so we can archive homebrew-qgisdev
·
ltr-3_40final-3_8_0
1 parent 8879744 commit a8e05f0

File tree

1 file changed

+743
-0
lines changed

1 file changed

+743
-0
lines changed
 

‎mac/development.md

Lines changed: 743 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,743 @@
1+
2+
# (THIS DOCUMENT IS NOT UP TO DATE)
3+
4+
# Developing QGIS using Homebrew dependencies
5+
6+
In addition to using this tap to install [QGIS development formulae](../Formula), you can also use it to fully set up a development environment for an externally built QGIS from a clone of the current [development (master) branch](https://github.com/qgis/QGIS) of the source code tree.
7+
8+
> Note: This setup, though heavily tested, is currently _experimental_ and may change.
9+
10+
For the terminally lazy, who are already comfortable with Homebrew, [jump to sample Terminal session](#terminal).
11+
12+
## Development Tools
13+
14+
This tutorial is based upon the following software:
15+
* [Qt Creator](http://qt-project.org/downloads) for CMake/C++ development of ([core source](https://github.com/qgis/QGIS/tree/master/src) and [plugins](https://github.com/qgis/QGIS/tree/master/src/plugins))
16+
* [PyCharm Community Edition](http://www.jetbrains.com/pycharm/download/) for Python development of ([PyQGIS plugins/apps](http://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/), [Python unit tests](https://github.com/qgis/QGIS/tree/master/tests/src/python), [reStructuredText for documentation](https://github.com/qgis/QGIS-Documentation)).
17+
* macOS XCode (download via Mac App Store and _launch at least once_) and Xcode Command Line Tools (run `xcode-select --install` after installing Xcode), for Homebrew and building QGIS source. QGIS's [CMake](http://www.cmake.org) build process uses generated build files for building QGIS source directly with the `clang` compiler, _not via Xcode project files_.
18+
19+
## Homebrew
20+
21+
See http://brew.sh and [Homebrew docs](https://github.com/Homebrew/brew/tree/master/docs) for info on installing Homebrew.
22+
23+
After Homebrew is installed run the following and fix everything that it mentions, if you can:
24+
```sh
25+
brew doctor
26+
```
27+
28+
### Homebrew configuration
29+
30+
Homebrew now defaults to _auto-updating_ itself (runs `brew update`) upon *every* `brew install` invocation. While this can be handy for keeping up with the latest changes, it can also quickly break an existing build's linked-to libraries. Consider setting the `HOMEBREW_NO_AUTO_UPDATE` environment variable to turn this off, thereby forcing manual running of `brew update`:
31+
32+
```sh
33+
export HOMEBREW_NO_AUTO_UPDATE=1
34+
```
35+
36+
See end of `man brew` for other environment variables.
37+
38+
### Homebrew prefix
39+
40+
While all of the formulae and scripts support building QGIS using Homebrew installed to a non-standard prefix, e.g. `/opt/homebrew`, **do yourself a favor** (especially if you are new to Homebrew) and [install in the default directory of `/usr/local`](https://github.com/Homebrew/brew/blob/master/docs/Installation.md). QGIS has many dependencies which are available as ["bottles"](https://github.com/Homebrew/brew/blob/master/docs/Bottles.md) (pre-built binary installs) from the Homebrew project. Installing Homebrew to a non-standard prefix will force many of the bottled formulae to be built from source, since many of the available bottles are built specific to `/usr/local`. Such unnecessary building from source can comparatively take hours and hours more, depending upon your available CPU cores.
41+
42+
If desired, this setup supports QGIS builds where the dependencies are in a non-standard Homebrew location, e.g. `/opt/homebrew`, instead of `/usr/local`. This allows for multiple build scenarios, though often requires a more meticulous CMake configuration of QGIS.
43+
44+
You can programmatically find the prefix with `brew --prefix`. In formulae code, it is denoted with the HOMEBREW_PREFIX environment variable.
45+
46+
### Homebrew formula install prefixes
47+
48+
By default, Homebrew installs to a versioned prefix in the 'Cellar', e.g. `/usr/local/Cellar/gdal2/2.1.2/`. Using the versioned path for dependencies _might_ lead to it being hardcoded into the linking phase of your builds. This is an issue because the version can change often with formula changes that are unrelated to the actual dependency's version, e.g. `2.1.2_1`. When defining paths for CMake, always try the formula's 'opt prefix' first, e.g. `/usr/local/opt/gdal2`, which is a symbolic link that _always_ points to the latest versioned install prefix of the formula. This often avoids the issue, though some CMake find modules _may_ resolve the symbolic link back to the versioned install prefix.
49+
50+
### Install some basic formulae
51+
52+
Always read the 'Caveats' section output at the end of `brew info <formula>` or `brew install <formula>`.
53+
54+
```sh
55+
brew install bash-completion
56+
brew install git
57+
```
58+
59+
## Python Dependencies
60+
61+
### Select an interpreter
62+
63+
The first important decision to make is regarding whether to use Homebrew's or another Python 3.x. Currently macOS does not ship with Python 3, and QGIS 3 should be built against Python 3.x.
64+
65+
> Note: The more Homebrew formulae you install from bottles, the higher likelihood you will end up running into a formulae that requires installing Homebrew's Python 3, since bottles are always built against that Python.
66+
67+
If using Homebrew Python 3.x, install with:
68+
69+
```sh
70+
# review options
71+
brew info python3
72+
brew install python3 [--with-option ...]
73+
```
74+
75+
Regardless of which Python interpreter you use, always ensure it is the first found `python3` on PATH in your Terminal session where you run `brew` commands, i.e. `which python3` points to the correct Python 3 you wish to use when building formulae.
76+
77+
### Install required Python packages
78+
79+
Use [pip3](https://pypi.python.org/pypi/pip/) that was installed against the same Python 3 you are using when installing formulae. You can also tap [homebrew/python](https://github.com/Homebrew/homebrew-python) for some more complex package installs.
80+
81+
Reference `pip3 --help` for info on usage (usually just `pip install <package>`).
82+
83+
* [future](https://pypi.python.org/pypi/future)
84+
* [numpy](https://pypi.python.org/pypi/numpy)
85+
* [psycopg2](https://pypi.python.org/pypi/psycopg2)
86+
* [matplotlib](https://pypi.python.org/pypi/matplotlib)
87+
* [pyparsing](https://pypi.python.org/pypi/pyparsing)
88+
* [requests](https://pypi.python.org/pypi/requests)
89+
* [mock](https://pypi.python.org/pypi/mock)
90+
* [pyyaml](https://pypi.python.org/pypi/PyYAML)
91+
* [nose2](https://pypi.python.org/pypi/nose2)
92+
93+
Other Python packages **automatically installed** by Homebrew from QGIS dependencies:
94+
95+
* [sip](https://github.com/Homebrew/homebrew-core/blob/master/Formula/sip.rb)
96+
* [PyQt5](https://github.com/Homebrew/homebrew-core/blob/master/Formula/pyqt5.rb)
97+
* [QScintilla2](https://github.com/Homebrew/homebrew-core/blob/master/Formula/qscintilla2.rb)
98+
* [pyspatialite](https://github.com/OSGeo/homebrew-osgeo4mac/blob/master/Formula/pyspatialite.rb) (deprecated)
99+
* [`osgeo.gdal` and `osgeo.ogr`, etc.](https://github.com/OSGeo/homebrew-osgeo4mac/blob/master/Formula/gdal2-python.rb)
100+
101+
## Install Build and Linked Library Dependencies
102+
103+
### Install dependencies from QGIS formulae
104+
105+
> Note: substitute **`qgis3-xx`** for whatever QGIS formula you are using for dependencies, e.g. `qgis3-dev`.
106+
107+
```sh
108+
# add this tap
109+
brew tap qgis/qgisdev
110+
# review options
111+
brew info qgis3-xx
112+
# see what dependencies will be included
113+
brew deps --tree qgis3-xx [--with[out]-some-option ...]
114+
# install dependencies, but not QGIS
115+
brew install qgis3-xx --only-dependencies [--with[out]-some-option ...]
116+
```
117+
118+
You do not have to actually do `brew install qgis3-xx` unless you also want that version installed. If you do have QGIS 3 formulae installed, and are planning on _installing_ your development build (not just running from the build directory), you should unlink the formulae installs, e.g.:
119+
120+
```sh
121+
brew unlink qgis3-xx
122+
```
123+
124+
This will ensure the `qgis.core`, etc. Python modules of the formula(e) installs are not overwritten by the development build upon `make install`. All `qgis-xx` formulae QGIS applications will run just fine from their Cellar keg install directory. _Careful_, though, as multiple QGIS installs will probably all share the same application preference files; so, don't run them concurrently.
125+
126+
### Optional External Dependencies
127+
128+
The [Processing framework](http://docs.qgis.org/testing/en/docs/user_manual/processing/index.html) of QGIS can leverage many external geospatial applications and utilities, which _do not_ need to be built as dependencies prior to building QGIS:
129+
130+
* [`grass7`](https://github.com/OSGeo/homebrew-osgeo4mac/blob/master/Formula/grass7.rb) (`--with-grass` option) - [GRASS 7](http://grass.osgeo.org), which is also used by the GRASS core plugin in QGIS
131+
* [`orfeo5`](https://github.com/OSGeo/homebrew-osgeo4mac/blob/master/Formula/orfeo5.rb) (`--with-orfeo5` option) - [Orfeo Toolbox](http://orfeo-toolbox.org/otb/)
132+
* [`r`](http://www.r-project.org/) (`--with-r` option) - [R Project](http://www.r-project.org/)
133+
* [`saga-gis`](https://github.com/OSGeo/homebrew-osgeo4mac/blob/master/Formula/saga-gis.rb) (`--with-saga-gis` option) - [System for Automated Geoscientific Analyses](http://www.saga-gis.org)
134+
* [`taudem`](https://github.com/OSGeo/homebrew-osgeo4mac/blob/master/Formula/taudem.rb) - [Terrain Analysis Using Digital Elevation Models](http://hydrology.usu.edu/taudem/taudem5/index.html).
135+
136+
The `gpsbabel` formula can be installed as a dependency, though you may have to define the path to its binary when using QGIS's [GPS Tools](http://docs.qgis.org/testing/en/docs/user_manual/working_with_gps/plugins_gps.html).
137+
138+
> Note: if you install Processing external utilities _after_ installing a QGIS formula or building your own QGIS, you may need to configure the individual utility's paths in Processing's options dialog.
139+
140+
## Clone QGIS Source
141+
142+
See the QGIS [INSTALL](https://github.com/qgis/QGIS/blob/master/INSTALL) document for information on using git to clone the source tree.
143+
144+
QGIS's build setup uses CMake, which supports 'out-of-source' build directories. It is recommended to create a separate build directory, either within the source tree, or outside of it. Since the (re)build process can generate _many_ files, consider creating a separate partition on which to place the build directory. Such a setup can significantly reduce fragmentation on your main startup drive. Use of Solid State Disks is recommended.
145+
146+
## Customize Build Scripts
147+
148+
This tap offers several convenience scripts for use in Qt Creator, or wrapper build scripts, to aid in building/installing QGIS, located at:
149+
150+
```sh
151+
$(brew --repository qgis/qgisdev)/scripts
152+
```
153+
154+
> Note: **Copy the directory elsewhere** and use it from there. It's important to not edit the scripts where they are located, in the tap, because it is a git repository. You should keep that working tree clean so that `brew update` always works.
155+
156+
The scripts will be used when configuring/building/installing the QGIS project in Qt Creator, or can be used independent of Qt Creator.
157+
158+
### Open and review scripts
159+
160+
**Note:** scripts expect the HOMEBREW_PREFIX environment variable to be set, e.g. in your `.bash_profile`:
161+
162+
```sh
163+
# after prepending `brew --prefix` to PATH (not needed for default /usr/local Homebrew)
164+
export HOMEBREW_PREFIX=$(brew --prefix)
165+
```
166+
167+
* [qgis-cmake-setup.sh](../scripts/qgis-cmake-setup.sh) - For generating CMake option string for use in Qt Creator (or build scripts) when built off dependencies from this and other taps. Edit CMake options to suit your build needs. Note, the current script usually has CMake options for building QGIS with *most* core options that the current `qgis3-xx` Homebrew formula supports, which may not include things like Oracle support, etc. You will probably want to edit it and (un)comment out such lines for an initial build.
168+
169+
* [qgis-set-app-env.py](../scripts/qgis-set-app-env.py) - For setting env vars in dev build and installed QGIS.app, to ensure they are available on double-click run. _Needs to stay in the same directory as the next scripts._ Generally, you will not need to edit this script.
170+
171+
* [qgis-dev-build.sh](../scripts/qgis-dev-build.sh) - Sets up the build environ and ensures the QGIS.app in the build directory can find resources, so it can run from there.
172+
173+
* [qgis-dev-install.sh](../scripts/qgis-dev-install.sh) - Installs the app and ensures QGIS.app has proper environment variables, so it can be moved around on the filesystem. Currently, QGIS.app bundling beyond [QGIS_MACAPP_BUNDLE=0](https://github.com/qgis/QGIS/tree/master/mac) is not supported. Since all dependencies are in your `HOMEBREW_PREFIX`, _no complex bundling is necessary_, unless you intend to relocate the built app to another Mac (which is a planned feature).
174+
175+
## <a name="terminal"></a>Configure/build/install QGIS in a Terminal.app session
176+
177+
**Example** Terminal.app session for cloning and building QGIS from scratch, based off of `qgis-3-dev` formula dependencies and assuming Xcode.app, Xcode Command Line Tools, and Homebrew are _already installed_. BASH used here.
178+
179+
```sh
180+
# Setup environment variables
181+
export HOMEBREW_PREFIX=$(brew --prefix)
182+
export HOMEBREW_NO_AUTO_UPDATE=1
183+
184+
# Optionally update Homebrew (recommended)
185+
brew update
186+
187+
# Install some handy base formulae
188+
brew install bash-completion
189+
brew install git
190+
brew install cmake
191+
192+
# Decide to use recommended Homebrew's Python3
193+
# (could use Anaconda's Python 3, etc. instead, though bottles may not work)
194+
brew install python3
195+
196+
# Install some Python dependencies
197+
# NOTE: may require `sudo` if Python 3 is installed in a root-owned location
198+
pip3 install future numpy psycopg2 matplotlib pyparsing requests pyyaml mock nose2
199+
200+
# Add some useful Homebrew taps
201+
# NOTE: try to avoid tapping homebrew/boneyard
202+
brew tap homebrew/science
203+
brew tap homebrew/python
204+
brew tap qgis/qgisdev
205+
brew tap osgeo/osgeo4mac
206+
207+
# Make sure deprecated Qt4 formulae are not linked
208+
brew unlink qt
209+
brew unlink pyqt
210+
211+
# Older txt2tags generator for INSTALL doc breakes build and chokes on Python 3
212+
brew unlink txt2tags
213+
214+
# Install and verify GDAL/OGR with decent driver support
215+
# Do NOT install `gdal` (1.11.x) formula, unless you truely need it otherwise
216+
# NOTE: keg-only, e.g. only available from HOMEBREW_PREFIX/opt/gdal2 prefix
217+
brew install osgeo/osgeo4mac/gdal2 --with-complete --with-libkml
218+
brew test osgeo/osgeo4mac/gdal2
219+
220+
# If failure, review any .dylib errors when loading drivers (scroll to top of output)
221+
$HOMEBREW_PREFIX/opt/gdal2/bin/gdalinfo --formats
222+
$HOMEBREW_PREFIX/opt/gdal2/bin/ogrinfo --formats
223+
224+
# Add the Python 3 bindings for GDAL/OGR
225+
brew install osgeo/osgeo4mac/gdal2-python --with-python3
226+
brew test osgeo/osgeo4mac/gdal2-python
227+
228+
# Optionally add and verify Processing framework extra utilities
229+
brew install osgeo/osgeo4mac/grass7
230+
brew install osgeo/osgeo4mac/gdal2-grass7
231+
brew test osgeo/osgeo4mac/grass7
232+
brew test osgeo/osgeo4mac/gdal2-grass7
233+
234+
brew install osgeo/osgeo4mac/saga-gis --with-app
235+
brew test osgeo/osgeo4mac/saga-gis
236+
237+
# This one's huge, bringing in large dependencies
238+
brew install orfeo5
239+
brew test orfeo5
240+
241+
# Install remaining dependencies for qgis3-dev formula, but not QGIS
242+
# This may take a loooong time if there are missing bottles, which need built
243+
brew install qgis3-dev --only-dependencies [--with-other-options]
244+
245+
# Base directory path of src, install and build directories
246+
BASE_DIR=$HOME/src
247+
mkdir -p $BASE_DIR
248+
cd $BASE_DIR
249+
250+
# Create and save a directory to install a final QGIS.app
251+
QGIS_INSTALL=$BASE_DIR/QGIS_install
252+
mkdir -p $QGIS_INSTALL
253+
254+
# Clone QGIS source tree
255+
QGIS_SRC=$BASE_DIR/QGIS
256+
# This may take a looong time, depending upon connection speed
257+
git clone https://github.com/qgis/QGIS.git $QGIS_SRC
258+
cd $QGIS_SRC
259+
260+
# Setup out-of-source build directory, inside of QGIS tree
261+
BUILD_DIR=$BASE_DIR/QGIS/build
262+
mkdir -p $BUILD_DIR
263+
cd $BUILD_DIR
264+
265+
# Where you have copied the build scripts (here using the defaults, as is)
266+
BUILD_SCRIPTS=$(brew --repository qgis/qgisdev)/scripts
267+
268+
# Configure CMake and generate build files
269+
# usage: qgis-cmake-setup.sh 'source directory' 'build directory' 'install directory'
270+
# (directories need to absolute paths)
271+
$BUILD_SCRIPTS/qgis-cmake-setup.sh $QGIS_SRC $BUILD_DIR $QGIS_INSTALL
272+
273+
# Review or edit what was configured (almost all dependencies should be from Homebrew)
274+
ccmake $BUILD_DIR
275+
276+
# Build QGIS
277+
# usage: qgis-dev-build.sh 'absolute path to build directory'
278+
$BUILD_SCRIPTS/qgis-dev-build.sh $BUILD_DIR
279+
280+
# Run QGIS test suite from build directory
281+
# source environment and run tests inside of a bash subshell,
282+
# so your shell environment is not polluted
283+
( source $BUILD_SCRIPTS/qgis-dev.env $BUILD_DIR && ctest )
284+
285+
# Install QGIS.app
286+
# note: app bundle is moveable about the filesystem, but not to another Mac
287+
$BUILD_SCRIPTS/qgis-dev-install.sh $BUILD_DIR
288+
```
289+
290+
## Configure/build/install QGIS in Qt Creator.app
291+
292+
These steps assume you are starting from a QGIS source tree clone, having done none of the above in Terminal.app. However, using an existing Terminal-based build is possible, if you assign the existing build directory upon loading your QGIS project.
293+
294+
**Important:** This configuration uses ``/usr/local`` as the HOMEBREW_PREFIX, which is the default. Substitute if yours is different.
295+
296+
### Install QtCreator 4.2 or better
297+
298+
It is recommended to use Qt Creator >= 4.2.0, as the CMake support much better than previous versions. Newer versions are slated to offer even more CMake integration, so update often.
299+
300+
* Grab _just_ the Qt Creator installer from https://www.qt.io/download-open-source/
301+
* Click **View All Downloads** scroll down to Qt Creator section
302+
* Open the DMG and drag **Qt Creator.app** wherever you like
303+
* Open **Qt Creator.app**
304+
305+
### Make a "Build & Run" kit for Homebrew
306+
307+
Go to ``Preferences -> Build & Run``. All further settings for building a kit are contained in tabs of that Preferences section.
308+
309+
**Note:** You can click ``Apply`` button, at any time, to apply your settings without closing the dialog.
310+
311+
#### Define a CMake executable
312+
313+
Under ``CMake`` tab, click ``Add``
314+
315+
* **Name:** Brew CMake
316+
* **Path:** /usr/local/bin/cmake
317+
318+
#### Optionally define a compiler cache
319+
320+
Generally, the default macOS `clang` compiler is very quick, but subsequent compilations can be accelerated with a compiler cache. QGIS developers often use and have heavily tested ``ccache`` for this purpose:
321+
322+
```sh
323+
brew install ccache
324+
```
325+
326+
Compiler symlinks are **not available** in ``/usr/local/bin``, but can be found in:
327+
328+
```sh
329+
/usr/local/opt/ccache/libexec
330+
```
331+
332+
Under ``Compilers`` tab...
333+
334+
* Click ``Add -> Clang -> C`` and configure:
335+
336+
* **Name:** Clang (x86 64bit) - Brew ccache
337+
* **Compiler path:** _Paste_ in ``/usr/local/opt/ccache/libexec/clang``
338+
* **ABI:** x86, darwin, generic, mach_o, 64bit
339+
340+
* Click ``Add -> Clang -> C++`` and configure:
341+
342+
* **Name:** Clang (x86 64bit) - Brew ccache
343+
* **Compiler path:** _Paste_ in ``/usr/local/opt/ccache/libexec/clang++``
344+
* **ABI:** x86, darwin, generic, mach_o, 64bit
345+
346+
**Note:** If you browse to one of the symlinked compiler paths, you will end up with an unwanted "Cellar"-based path.
347+
348+
#### Define a Qt Version
349+
Under ``Qt Versions``, click ``Add``.
350+
351+
* **Version name:** Brew Qt5
352+
* **qmake location:** Browse to the executable ``/usr/local/opt/qt5/bin/qmake``
353+
354+
**Note:** Homebrew's Qt5 `qmake` is not currently linked into `HOMEBREW_PREFIX/bin`, though this may change. To check, see if `/usr/local/bin/qmake` exists and is from Homebrew's Qt5. If so, use that path instead; otherwise, continue with next step.
355+
356+
The **qmake** location for `/usr/local/opt/qt5/bin/qmake` will be saved as a versioned "Cellar" path. We need to adjust this to its "opt prefix" alternate path, the one we originally browsed. This keeps incremental Homebrew upgrades of Qt5 packages from breaking our kit in the future.
357+
358+
##### Fix qmake location
359+
360+
* Click ``OK`` for Preferences dialog and **quit** Qt Creator
361+
* Open this file in a text editor:
362+
363+
``~/.config/QtProject/qtcreator/qtversion.xml``
364+
365+
* Find the same versioned "Cellar" ``qmake`` path (associated with the element whose attribute is ``key="QMakePath"``) and change it to:
366+
367+
``/usr/local/opt/qt5/bin/qmake``
368+
369+
* Save file and relaunch Qt Creator, then go to:
370+
371+
``Preferences -> Build & Run -> Qt Versions``
372+
373+
When you select the ``Brew Qt5`` version, it should now show the "opt prefix" path.
374+
375+
#### Define a kit
376+
377+
Under ``Kits`` tab, click ``Add``, then configure with:
378+
379+
* **Name:** QGIS Build Kit - Qt5
380+
* **File system name:** _blank_
381+
* **Device type:** Desktop
382+
* **Device:** Local PC (default for Desktop)
383+
* **Sysroot:** _blank_
384+
* **Compiler:** (if using ccache, substitute the compilers you defined)
385+
* **C:** Clang (x86_64bin in /usr/bin)
386+
* **C++:** Clang (x86_64bin in /usr/bin)
387+
* **Environment:** click ``Change...`` and add the following variables:
388+
389+
```
390+
HOMEBREW_PREFIX=/usr/local
391+
PATH=/usr/local/opt/ccache/libexec:/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin
392+
```
393+
394+
**Notes:**
395+
* The kit's Qt5 `bin` dir is always prepended to PATH: `/usr/local/opt/qt5/bin`, but it will be resolved to it's "Cellar" path, e.g. `/usr/local/Cellar/qt5/5.7.1_1/bin`, which is not an issue since it is dynamically prepended.
396+
* `HOMEBREW_PREFIX` is used by the custom build and install scripts.
397+
398+
* **Debugger:** System LLDB at `/Applications/Xcode.app/Contents/Developer/usr/bin/lldb` (or `/usr/bin/lldb`, if using the Command Line Tools)
399+
* **Qt Version:** Brew Qt5 (which you previously created)
400+
* **Qt mkspec:** leave blank
401+
* **CMake Tool:** Brew CMake (which you previously created)
402+
* **CMake Generator:** CodeBlocks - Unix Makefiles
403+
* **CMake Configuration:** Press the `Change...` button and paste this into the box provided:
404+
405+
```
406+
CMAKE_CXX_COMPILER:STRING=%{Compiler:Executable}
407+
CMAKE_C_COMPILER:STRING=%{Compiler:Executable:C}
408+
QT_QMAKE_EXECUTABLE:STRING=%{Qt:qmakeExecutable}
409+
CMAKE_BUILD_TYPE:STRING=RelWithDebInfo
410+
CMAKE_FIND_FRAMEWORK:STRING=LAST
411+
CMAKE_PREFIX_PATH:STRING='/usr/local/opt/qt5;/usr/local/opt/qt5-webkit;/usr/local/opt/qscintilla2;/usr/local/opt/qwt;/usr/local/opt/qwtpolar;/usr/local/opt/qca;/usr/local/opt/gdal2;/usr/local/opt/gsl;/usr/local/opt/geos;/usr/local/opt/proj;/usr/local/opt/libspatialite;/usr/local/opt/spatialindex;/usr/local/opt/fcgi;/usr/local/opt/expat;/usr/local/opt/sqlite;/usr/local/opt/flex;/usr/local/opt/bison'
412+
```
413+
414+
**Notes:**
415+
* If using `ccache`, you must also define `CMAKE_C_COMPILER` (as above), or Apple's default C compiler will be used.
416+
* `CMAKE_PREFIX_PATH` is **critical** as it tells CMake to search _first_ in Homebrew install prefixes that are not linked into the HOMEBREW_PREFIX, e.g. `/usr/local`. Otherwise, CMake can not find them. Often, these packages are important to building QGIS or are newer versions overriding packages already installed on the base macOS.
417+
* The `CMAKE_PREFIX_PATH` value can be taken from `$(brew --repository qgis/qgisdev)/scripts/qgis-cmake-setup.sh`. You can comment out the last `eval` line of the aforementioned script to get the equivalent value above.
418+
* Do not place QGIS-specific CMake options here. Those should be defined in the CMake section of a specific QGIS source tree when loaded into Qt Creator as a project.
419+
420+
Optionally, once you have your kit defined, you can make it the default by selecting it and clicking the `Make Default` button.
421+
422+
### Load QGIS project
423+
424+
**Note:** This describes loading a CMake project in Qt Creator 4.2 (recommended minimum version). Other versions may vary.
425+
426+
When opening a project, the build directory needs defined. You can set a default build directory templated path in the `General` tab's `Default build directory:` option. If you wish to have the build directory default to _inside_ your project source tree directory, you can use the following template path:
427+
428+
```
429+
%{CurrentProject:Path}/build_%{CurrentBuild:Type}
430+
```
431+
432+
The generated build paths based upon this template can still be overridden in the next step.
433+
434+
Load QGIS project and configure/generate its build files:
435+
436+
* Select `File -> Open File or Project...` menu action
437+
* Open the `CMakeLists.txt` in the root of your cloned QGIS source tree directory
438+
* In the resulting `Configure Project` panel:
439+
440+
* Check only the `QGIS Build Kit - Qt5` you previously created, and uncheck **all** other kits
441+
* Click `Details` of your kit to reveal build directory options
442+
* Uncheck all options except "Release with Debug Information" (recommended - you can always add other types later as additional build configurations)
443+
* If you wish to use the templated directory path, and want to create it now, the easiest way is to copy the path and run `mkdir <path>` in Terminal.app.
444+
* If you wish to override the templated build directory path, click `Choose...` (create an empty build folder and select it)
445+
* Click `Configure Project`
446+
447+
**Note:** If you did not create the build directory, CMake will _configure_ the project, but not _create_ the build directory or _generate_ the build files until you choose to build the project.
448+
449+
### Configuring QGIS CMake options
450+
451+
**Tip:** You can choose the `Build -> Run CMake` menu action to reconfigure and generate build files for your project at any time. This is helpful for when Qt Creator does not update its GUI and give you the option to do so.
452+
453+
You can configure CMake options for your project in the `Projects` section of the main window, under `Active Project -> Your project` then under `Build & Run -> Your kit -> Build`.
454+
455+
* **Note:** When you `Add` or `Edit` options here, they are stored in `CMakeLists.txt.user` in the root of your QGIS source tree, under the this XML element:
456+
457+
```
458+
<valuelist type="QVariantList" key="CMake.Configuration">
459+
```
460+
If you have problems with Qt Creator picking up automatic configuration changes, check the child elements of that `valuelist` to see if there are stored option elements that need deleted (if so, quit Creator first). This is necessary until Qt adds a `Delete` action for CMake options to Creator. Optionally, you can also delete `CMakeLists.txt.user`, though you lose considerably more project configurations.
461+
462+
#### Configure for running from build directory
463+
464+
This will stage the core Python plugins so they are available at runtime from the build directory:
465+
466+
```
467+
WITH_STAGED_PLUGINS=TRUE (Add as Boolean)
468+
```
469+
470+
#### Configure QwtPolar
471+
472+
To avoid building the internal QwtPolar, and use Homebrew's:
473+
474+
```
475+
WITH_QWTPOLAR=TRUE (Add as Boolean)
476+
WITH_INTERNAL_QWTPOLAR=FALSE (Add as Boolean)
477+
```
478+
479+
#### Configure for code styling
480+
481+
To ensure the `astyle` binary is built for checking your code with `prepare-commit.sh` script before committing to PR, etc.
482+
483+
```
484+
WITH_ASTYLE=TRUE (Add as Boolean)
485+
```
486+
487+
#### Configure for install
488+
489+
If you intend to install QGIS.app, and not just run it from the build directory:
490+
491+
```
492+
CMAKE_INSTALL_PREFIX=<directory-path>
493+
```
494+
495+
This defaults to `/usr/local`, which is probably not what you want. Suggested:
496+
497+
```
498+
CMAKE_INSTALL_PREFIX=$HOME/Applications/QGIS (Add as Directory)
499+
```
500+
501+
Unless you intend to install a fully bundled, standalone `QGIS.app` (not yet supported), then you will want to set:
502+
503+
```
504+
QGIS_MACAPP_BUNDLE=0 (Add as String)
505+
```
506+
507+
#### Configure GRASS
508+
509+
If using `osgeo/osgeo4mac/grass7`:
510+
511+
```
512+
WITH_GRASS7=TRUE (Add as Boolean)
513+
GRASS_PREFIX7=/usr/local/opt/grass7/grass-base" (Add as Directory)
514+
```
515+
516+
#### Fix some CMake module search results
517+
518+
To ensure your build is isolated as much as possible from incidental Homebrew updates, prefer package "opt prefix" paths for CMake modules that find versioned prefix by default:
519+
520+
```
521+
GDAL_LIBRARY=/usr/local/opt/gdal2/lib/libgdal.dylib (Add as File)
522+
GEOS_LIBRARY=/usr/local/opt/geos/lib/libgeos_c.dylib (Add as File)
523+
GSL_CONFIG=/usr/local/opt/gsl/bin/gsl-config (Add as File)
524+
GSL_INCLUDE_DIR=/usr/local/opt/gsl/include (Add as Directory)
525+
GSL_LIBRARIES='-L/usr/local/opt/gsl/lib -lgsl -lgslcblas' (Add as String)
526+
```
527+
528+
# TODO: WIP from here to end
529+
530+
### Building QGIS
531+
532+
TODO: notes on `qgis-set-app-env.py` and `qgis-dev-build.sh`
533+
534+
### Cleaning the build
535+
536+
If you want to start with a clean setup in Qt Creator you should:
537+
538+
* Quit Qt Creator
539+
* Remove the `CMakeLists.txt.user` file at the root of the QGIS source tree
540+
* Optionally, remove the _contents_ of any existing build directory or just its `CMakeCache.txt` file
541+
* Restart Qt Creator
542+
* Load project as noted above
543+
544+
### Running/debugging QGIS.app from build directory
545+
546+
You may need to do this:
547+
548+
• add /usr/local/opt/gdal2/bin/ to the raster/gdal tool settings in qgis
549+
• add gdal to your path : export PATH=/usr/local/opt/gdal2/bin/:$PATH
550+
551+
When debugging / running from Qt-Creator, ensure that GDAL python packages are in your path by adding this to your run environment:
552+
553+
```
554+
PYTHONPATH set to $PYTHONPATH:/usr/local/opt/gdal2-python/lib/python3.5/site-packages
555+
```
556+
557+
Alternatively, add the gdal2 packages to your environment directly in QGIS like this:
558+
559+
![screen shot 2017-03-19 at 8 37 54 pm](https://cloud.githubusercontent.com/assets/178003/24084521/6d5345ec-0cf4-11e7-9d86-e8af713a5b76.png)
560+
561+
562+
563+
### Installing QGIS.app
564+
565+
### Qt Creator tweaks
566+
567+
* Import QGIS code style rules
568+
* Under `Preferences -> C++`, click `Import`
569+
* Import `qtcreator_code_style.xml` from `QGIS/doc` folder in QGIS source tree
570+
* A "QGIS" code style is imported, which you can assign as the code style for your loaded project (or import just for your project, under `Project Settings` for your project in the `Projects` section of the main window)
571+
572+
### Useful Qt Creator shortcuts
573+
574+
* **Ctrl-K** - pops up quick search for a class
575+
* **:spacebar** in the search popup will search for symbols
576+
* **Ctrl-K** - then type 'git blame' and it will give git blame for currently open file
577+
* **F2** - jump to symbol / definition under cursor
578+
* **Alt-Enter** - refactoring you can automatically implement stubs for a method in a header
579+
* **Alt-Enter** - refactoring you can generate getter and setter for a private member in a header
580+
* **Alt-Enter** - general refactoring
581+
* **Cmd-shift R** - refactor symbol name under the cursor
582+
* **Cmd-B** - Build
583+
* **Cmd-R** - Run w/o debugger
584+
* **F5** - debug
585+
586+
### Troubleshooting
587+
588+
**Problem:**
589+
/usr/local/Cellar/cmake/3.5.2/share/cmake/Modules/CMakeTestCCompiler.cmake:61: error: The C compiler "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/cc" is not able to compile a simple test program. It fails with the following output: Change Dir: /Users/timlinux/dev/cpp/QGIS/build/CMakeFiles/CMakeTmp
590+
591+
**Resolution:**
592+
593+
Close Qt Creator, remove CMakeLists.txt.user from your source tree and start again, see if that helps.
594+
595+
**Problem:**
596+
597+
CMAKE CODEBLOCKS GENERATOR not found
598+
599+
**Resolution:**
600+
601+
Manually set this to 'make' (or try ninja)
602+
603+
## Configure/build/install QGIS in CLion
604+
605+
[CLion](https://www.jetbrains.com/clion/) is a cross platform C++ IDE developed by JetBrains. Usage generally requires purchasing a commercial license, though they do provide free licenses for Open Source projects (subject to some criteria).
606+
607+
![screen shot 2017-03-19 at 10 39 28 pm](https://cloud.githubusercontent.com/assets/178003/24084554/f67a9b40-0cf4-11e7-8351-49324dc154ab.png)
608+
Image above: An example session running CLion.
609+
610+
CLion is much simpler to set up as a build environment for QGIS compared to QtCreator and my be a good alternative for those used to developing with PyCharm for their Python Work (see PyCharm section below), since both PyCharm and CLion are build on the same 'engine' and have constencies in features, key bindings etc.
611+
612+
* Open project
613+
* Open the CMakeLists.txt in QGIS Source tree
614+
* Open CLion preferences
615+
* Go to Build, execution, deployment
616+
* Go to Toolchain
617+
* CMake Executable: Custom: /usr/local/Cellar/cmake/3.6.1/bin/cmake
618+
* CMake:
619+
* Generation group box
620+
* Configuration: RelWithDebInfo
621+
* CMake options:
622+
623+
```
624+
-DWITH_BINDINGS=ON
625+
-G
626+
"Ninja"
627+
-DCMAKE_CODEBLOCKS_EXECUTABLE:PATH='/usr/local/bin/ninja'
628+
-DCMAKE_INSTALL_PREFIX:PATH='/Users/timlinux/Applications/'
629+
-DCMAKE_BUILD_TYPE:STRING=RelWithDebInfo
630+
-DCMAKE_FIND_FRAMEWORK:STRING=LAST
631+
-DCMAKE_PREFIX_PATH:STRING='/usr/local/opt/qt5;/usr/local/opt/qt5-webkit-qt@5.7;/usr/local/opt/qscintilla2;/usr/local/opt/qwt;/usr/local/opt/qwtpolar;/usr/local/opt/qca-qt@5.7;/usr/local/opt/gdal2;/usr/local/opt/gsl;/usr/local/opt/geos;/usr/local/opt/proj;/usr/local/opt/libspatialite;/usr/local/opt/spatialindex;/usr/local/opt/fcgi;/usr/local/opt/expat;/usr/local/opt/sqlite;/usr/local/opt/flex;/usr/local/opt/bison;'
632+
-DENABLE_MODELTEST:BOOL=FALSE
633+
-DENABLE_TESTS:BOOL=TRUE
634+
-DGDAL_LIBRARY:FILEPATH=/usr/local/opt/gdal2/lib/libgdal.dylib
635+
-DGEOS_LIBRARY:FILEPATH=/usr/local/opt/geos/lib/libgeos_c.dylib
636+
-DGSL_CONFIG:FILEPATH=/usr/local/opt/gsl/bin/gsl-config
637+
-DGSL_INCLUDE_DIR:PATH=/usr/local/opt/gsl/include
638+
-DGSL_LIBRARIES="-L/usr/local/opt/gsl/lib -lgsl -lgslcblas"
639+
-DWITH_QWTPOLAR:BOOL=TRUE
640+
-DWITH_INTERNAL_QWTPOLAR:BOOL=FALSE
641+
-DWITH_GRASS:BOOL=FALSE
642+
-DWITH_GRASS7:BOOL=TRUE
643+
-DGRASS_PREFIX7:PATH=/usr/local/opt/grass7/grass-base
644+
-DWITH_APIDOC:BOOL=FALSE
645+
-DWITH_ASTYLE:BOOL=TRUE
646+
-DWITH_CUSTOM_WIDGETS:BOOL=TRUE
647+
-DWITH_GLOBE:BOOL=FALSE
648+
-DWITH_ORACLE:BOOL=FALSE
649+
-DWITH_QSCIAPI:BOOL=FALSE
650+
-DWITH_QSPATIALITE:BOOL=FALSE
651+
-DWITH_QTWEBKIT:BOOL=TRUE
652+
-DWITH_SERVER:BOOL=TRUE
653+
-DWITH_STAGED_PLUGINS:BOOL=TRUE
654+
-DQGIS_MACAPP_DEV_PREFIX:PATH=/Users/timlinux/Applications/qgis-dev
655+
-DQGIS_MACAPP_INSTALL_DEV:BOOL=TRUE
656+
-DQGIS_MACAPP_BUNDLE:STRING=0
657+
'/Users/timlinux/dev/cpp/QGIS'
658+
-DCMAKE_CXX_COMPILER=/usr/local/opt/ccache/libexec/clang++
659+
-DCMAKE_C_COMPILER=/usr/local/opt/ccache/libexec/clang
660+
```
661+
662+
In our testing we found that with the above options, QGIS will compile but crash at runtime just after the splash screen. Adding the options below will resolve this issue - we will update this list to remove redundant entries in the near future.
663+
664+
```
665+
-DCMAKE_AR:FILEPATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/ar
666+
-DCMAKE_CXX_COMPILER:FILEPATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/c++
667+
-DCMAKE_C_COMPILER:FILEPATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/cc
668+
-DCMAKE_LINKER:FILEPATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/ld
669+
-DCMAKE_PREFIX_PATH:STRING=/usr/local/opt/qt5;/usr/local/opt/qt5-webkit-qt@5.7;/usr/local/opt/qscintilla2;/usr/local/opt/qwt;/usr/local/opt/qwtpolar;/usr/local/opt/qca-qt@5.7;/usr/local/opt/gdal2;/usr/local/opt/gsl;/usr/local/opt/geos;/usr/local/opt/proj;/usr/local/opt/libspatialite;/usr/local/opt/spatialindex;/usr/local/opt/fcgi;/usr/local/opt/expat;/usr/local/opt/sqlite;/usr/local/opt/flex;/usr/local/opt/bison;
670+
-DCMAKE_RANLIB:FILEPATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/ranlib
671+
-DCMAKE_STRIP:FILEPATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/strip
672+
-DQCA_INCLUDE_DIR:PATH=/usr/local/opt/qca/lib/qca-qt5.framework/Headers
673+
-DQCA_LIBRARY:FILEPATH=/usr/local/opt/qca/lib/qca-qt5.framework
674+
-DQGIS_MACAPP_INSTALL_DEV:BOOL=FALSE
675+
-DQt5WebKitWidgets_DIR:PATH=/usr/local/opt/qt5-webkit/lib/cmake/Qt5WebKitWidgets
676+
-DQt5WebKit_DIR:PATH=/usr/local/opt/qt5-webkit/lib/cmake/Qt5WebKit
677+
-DCMAKE_EXTRA_GENERATOR:INTERNAL=
678+
```
679+
680+
Make sure to review the options - espectially paths near the bottom of the list to ensure
681+
they are correct for your home directory.
682+
683+
For the most part these options were generated by calling the
684+
685+
```
686+
$(brew --repository qgis/qgisdev)/scripts/qgis-cmake-setup.sh
687+
```
688+
689+
utility script provided with homebrew.
690+
691+
692+
Generation path: Set to your home applications dir e.g.:
693+
```
694+
/Users/timlinux/dev/cpp/QGIS-CLion-Build
695+
```
696+
697+
When debugging / running from CLion, ensure that GDAL python packages are in your path by adding this to your run environment:
698+
699+
```
700+
PYTHONPATH set to $PYTHONPATH:/usr/local/opt/gdal2-python/lib/python3.5/site-packages
701+
```
702+
703+
Alternatively, add the gdal2 packages to your environment directly in QGIS like this:
704+
705+
![screen shot 2017-03-19 at 8 37 54 pm](https://cloud.githubusercontent.com/assets/178003/24084521/6d5345ec-0cf4-11e7-9d86-e8af713a5b76.png)
706+
707+
708+
709+
## PyCharm
710+
711+
* Using paths in PyCharm and PyCharm test defaults:
712+
* Using hand built QGIS:
713+
714+
Set your interpreter so add these python paths:
715+
716+
```
717+
/usr/local/lib/python3.5/site-packages/
718+
/Users/timlinux/Applications/QGIS.app/Contents/Resources/python/
719+
/Users/timlinux/Applications/QGIS.app/Contents/Resources/python/plugins
720+
```
721+

722+
723+
(Adjust these paths if you used a different install dir)
724+
725+
```
726+
QGIS_PREFIX_PATH=/Users/timlinux/dev/cpp/QGIS/build/output/bin/QGIS.app/contents/MacOS;
727+
728+
PYTHONPATH=$PYTHONPATH:/Users/timlinux/Applications/QGIS.app/contents/Resources/python:/Users/timlinux/Applications/QGIS.app/contents/Resources/python/plugins/:/usr/local/lib/python3.5/site-packages/
729+
```
730+
731+
### For tests in PyCharm:
732+
733+
```
734+
$PYTHONPATH:/Users/timlinux/Applications/QGIS.app/contents/Resources/python:/Users/timlinux//Applications/QGIS.app/Contents/Resources/python/plugins/
735+
```
736+
737+
### Commit some changes to QGIS
738+
739+
Before committing your changes to QGIS, you need to run `scripts/prepare-commit.sh`. You need to install some tools first:
740+
```
741+
brew install gnu-sed
742+
pip3 install autopep8
743+
```

0 commit comments

Comments
 (0)
Please sign in to comment.