Download and build Qt5 from source

Recently I ran into a work-related task to build Geant4 on a DOE National Lab supercomputer NERSC. It was needed to do some particle-matter interaction simulations.

I would like to enable a few options for Geant4 for its full capabilities:

  • Qt5
  • GDML
  • multithread

and install all the data in a customized folder. All in all, the cmake command I need is

$ mkdir /path/to/my/project/geant4.10.06.p01/build/
$ cd /path/to/my/project/geant4.10.06.p01/build/
$ cmake -DCMAKE_INSTALL_PREFIX=/path/to/my/project/geant4.10.06.p01/install/ \
-DGEANT4_USE_GDML=ON -DGEANT4_BUILD_MULTITHREADED=ON -DGEANT4_INSTALL_DATA=ON \
-DGEANT4_INSTALL_DATADIR=/path/to/my/project/geant4.10.06.p01/data/ \
-DGEANT4_USE_QT=ON -DGEANT4_USE_SYSTEM_EXPAT=OFF -DGEANT4_USE_HDF5=OFF \
-DBUILD_SHARED_LIBS=ON ..

Now here is the issue, the CMakeLists.txt file implemented by Geant4 uses a CMake command

find_package(Qt5???? QUIET)

Although it invokes the QUIET option, if Qt5 packages are not located it falls off to finding Qt4, which basically means more trouble for most of the platforms nowadays.

NERSC has a Qt5 library, but unfortunately not complete. It was missing one of the required packages Qt5OpenGL. Therefore, I had to build my own Qt5 from source.

OK. Challenge accepted. However, it turned out it was NOT easy. Below you’ll find how I struggled and finally nailed it.

Download source code

First, download Qt5 (obviously). But, Qt has made its download site so hard to find from their official home page, so I decided to share it with you. Officially, Qt wants you to get its source code by:
Qt5 Download Source Code Instructions
Using git. After you clone the repo, you’ll need to checkout the version you want, e.g., git checkout 5.12.
That works OK, but a few people like myself still wants to download a tarball and keep the archive copy. Well the download page exists (you just can’t find it!):
Official Qt5 releases
No matter which method you use, download the source code and put it in

/path/to/my/project/qt5/

Remember /path/to/my/project is your own path.

Run init-repository

This is what a lot of other online Qt5 installation instructions are missing. If you downloaded the source code using git clone, you will first need to initiate the repository. You’ll need perl, which is installed by default on Linux/MacOS. There is a special notice, as given by the official guide: “Consider skipping the web module (Qt WebEngine), It is quite big and takes a long time to compile (and is often a source of compile errors).” If you are not running a web application (I doubt it if you are running it on a server), you should do the following:

$ cd /path/to/my/project/qt5/
$ perl init-repository --module-subset=default,-qtwebengine

Qt5 is fairly large. Wait patiently for it to finish.

Configure

Qt5 recommends you set the LLVM_INSTALL_DIR environment variable first. On most Linux systems llvm should be there already, otherwise you can use apt-get to install. On NERSC, you’ll need to load some useful modules by

$ module load cmake gcc llvm/9.0.1

Next, you need to run the configure script. There are some tricks here. The official Qt5 guidance is not optimal. I recommend you do the following:

$ ./configure -opensource -prefix /path/to/my/project/qt5/install -confirm-license

The first option gets you through the license/commercial option selections, the second option sets your installation path, the last option confirms the license agreement for you.

Warning: make sure you changed the /path/to/project/ to your own path. Don’t ask me why I would mention that and the lesson I learned in a hard way.

Make and Install

Now you are ready for the longest process: make
To speed up the process, please consider make -jN where N is the number of cores you could use on your computer/server. Usually, the login node of supercomputers does not allow too many cores to be used. So on NERSC I just did
$ make -j4
It will take a long time.
When it’s done, just do a
$ make install

If you followed the steps above, this will install subfolders of libraries, docs, binaries, header files all in /path/to/my/project/qt5/install/. Such as ./lib/, ./include/, ./examples/, ./bin/ etc.

In order to use the newly installed Qt5 in your other CMake projects, you’ll need to specify where your own Qt5 is. Specifically, where the CMake configuration file is. When you do a find_package(XXX REQUIRED), CMake tries to find a file called Config.cmake, or -config.cmake. The directories that CMake will search in are described as follows:
CMake Search Procedure

All in all, in order to let CMake find your own packages, you’ll need to let it know where it is (obviously). You can do this in two ways:

  • Specify the package location (CMake file as described above) when you run CMake;
  • Permanently add your CMake directory to your environment settings.

To use the first option, just do

$ cmake -DCMAKE_PREFIX_PATH=/path/to/my/project/qt5/install/:${CMAKE_PREFIX_PATH} \
Blabla

Notice that Blabla is not part of a valid CMake command…
To use the second option, just do

$ export CMAKE_PREFIX_PATH=/path/to/my/project/qt5/install/:${CMAKE_PREFIX_PATH}

In the login shell environment on a command line, or append that line to your ~/.bashrc or similar (If you are using bash. If not I suggest you switch to bash).

You are all set!

You are now all set to use Qt5, or build applications that rely on Qt5 using CMake. Thanks for reading. Hope it was useful.