Install From Source

Installation on Windows

Users can download and use XtalOpt pre-compiled binaries from the download page. The following notes are not "instructions"; they are just meant to give you a picture of the overall compilation process. Depending on the compiler and installation details of dependencies, you might need to adjust them or adopt another approach.

Note: these are merely general guidelines and come with no warranty whatsoever. The user is responssible in case their computer system incures any damage as a result of using, in part or in whole, the following materials.

Obtaining the source code

To obtain the source-code of the latest stable version (or previous releases) of XtalOpt see the download page.

Compiler and dependencies

A C++ compiler with C++11 support is necessary to compile the program, e.g., MSVC versions 2015 or later.

Moreover, compiling XtalOpt requires the following dependencies:

(1) git (any version),
(2) cmake (any version)
(3) Qt framework (version 5.2.1 or later of Qt5),
(4) Qwt libraries (version 6.1.3 or later, and compiled with the same version of the installed Qt),
(5) Eigen library (version 3 or later),
(6) libssh and openssh (this is not required if you disable the ssh; which is enabled by default).

The MSVC compiler can be downloaded and installed from its website. Required dependencies can be downloaded and installed from their website or existing package managers. For instance, Qt can be downloaded from its website, and the Eigen and libssh may be installed using the vcpkg.
Once the compiler and Qt are available, the Qwt can be easily built from source. As an example, on our system (with the "MSVC 2017" compiler and Qt 5.12.12 installed), we were able to build Qwt by simply running the following batch file in "Qt 5.12.12 (MSVC 2017 64-bit)" command prompt in the root of the Qwt source-code. The Qwt was then installed in its default location "C:\Qwt-6.2.0".

call "C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
set PATH="C:\Qt\Qt5.12.12\5.12.12\msvc2017_64\bin";%PATH%
nmake install

A few comments about installing dependencies:

About Eigen library: In principle the Eigen library does not need to be installed! One can simply download its source-code, unpack it at the desired location, and point the cmake to that path.
Dependencies installed using vcpkg: After installing packages with vcpkg, we needed to:
(1) Appy the user-wide integration for the installed packages,
(2) When running cmake, add the "-DCMAKE_TOOLCHAIN_FILE" with the path to the vcpkg.cmake (suggested by the package itself), and add the path to "installed" directory in the vcpkg location to the "-DCMAKE_PREFIX_PATH" flag.
For more information, especially updates on integration details, see the vcpkg website.

Configuring the build

Once all required packages are installed, the user should create a "build" directory in the root of the XtalOpt source-code directory. In the "build" directory, then one can configure the build using

cmake .. [-G <generator-name>]

If the dependencies are installed in standard locations or available through environment variables, there is a chance that cmake will find them (or at least some of them!). If the configuration fails, however, you may inspect the output of the cmake command to see what are the missing libraries/packages. You need to redo the build with providing the correct path to required dependencies using the appropriate configuration flags:

cmake .. [-G <generator-name>] [-D<flag1>=<value1> -D<flag2>=<value2> ...]

To our experience, those which are most likely to be a source of trouble (along with their corresponding cmake flags) are as follows:

Package cmake flag Value
Qt5 directory -DCMAKE_PREFIX_PATH <path to Qt5 installation>/lib/cmake/Qt5
Qwt include directory -DQWT_INCLUDE_DIR <path to Qwt installation>/lib/qwt.framework/Headers
Qwt library -DQWT_LIBRARY <path to Qwt installation>/lib/qwt.framework/qwt
Eigen include directory -DEIGEN3_INCLUDE_DIR <path to Eigen installation> OR "the parent folder of the Eigen/ subfolder"
libssh include directory -DLIBSSH_INCLUDE_DIRS <path to libssh installation>/include
libssh library -DLIBSSH_LIBRARIES <path to libssh installation>/lib/<libssh library filename>

Compiling XtalOpt

After configuring the build, you can compile the code with the "make" (or "nmake" in the case of MSVC) command.

Upon successful compilation, there should be a directory named "bin" in the build directory which contains the xtalopt.exe file. Note that this executable will run successfully only if all required ".dll" files are present in the same "bin" directory. Basically, you can manually find and copy those libraries there. However, the proper (and easy) way would be to configure the build for installation before compiling it (see the next section).

Installing XtalOpt

Installing the code will create a standalone directory in which the XtalOpt executable and required libraries are properly collected. In order to configure the code for installation, you should add the "-DBUILD_INDEPENDENT_PACKAGE=ON" and "-DCMAKE_BUILD_TYPE=Release" configuration flags to the cmake command.

Note that the default installation location is the "C:/Program Files (x86)/XtalOpt/bin" directory. Writing files to that location requires administrative privileges, i.e., the command prompt must be started with "Run as Administrator". Alternatively, you can specify another location which does not require such privileges. To do so, you can add the "-DCMAKE_INSTALL_PREFIX=<desired/path/for/installation>" flag to the cmake command.

Finally, after compiling the code with the above installation-related cmake flags, you need to run "make install" (or, "nmake install" for MSVC compiler). If everything goes well, you will find the XtalOpt executable along with required libraries collected in the "bin/" directory in the installation location.

Example of a complete build script

The details of the cmake and make/nmake setup would depend on the compiler and the installed dependencies. With that in mind, we are providing the following batch file just as an example of a possible setup to build the code on Windows operating system.

In the reference system, the "MSVC 2017 64-bit" compiler, Qt 5.12.12, and Qwt 6.2.0 were installed. Eigen and libssh dependencies were installed using vcpkg package manager. The following batch file was run inside the build directory (located in the root of the XtalOpt source-code) in the developer command prompt, i.e., "x64 Native Tools Command Prompt for VS 2017". At the end, XtalOpt was installed in "C:\xtalopt_windows" directory.

@echo off

REM Written by Patrick Avery

REM ***NOTE: This script was used in "x64 Native Tools Command Prompt for VS 2017"***
REM ***NOTE: Run this script inside the build folder in the source directory***

REM *********************************************************
REM **** Set all variables to their correct directories  ****
REM *********************************************************

set qt5dir=C:\Qt\Qt5.12.12\5.12.12\msvc2017_64
set qwtdir=C:\Qwt-6.2.0
set insdir=C:\xtalopt_windows

REM *********************************************************
REM **** Configure the build                             ****
REM *********************************************************

cmake .. -G "NMake Makefiles" ^
-DCMAKE_PREFIX_PATH="%qt5dir%;C:\Develop\vcpkg\installed\arm64-windows" ^
-DQWT_LIBRARY=%qwtdir%\lib\qwt.lib ^
-DQWT_INCLUDE_DIR=%qwtdir%\include ^
-DCMAKE_TOOLCHAIN_FILE="C:\Develop\vcpkg\scripts\buildsystems\vcpkg.cmake" ^

REM *********************************************************
REM **** Compile XtalOpt                                 ****
REM *********************************************************


REM *********************************************************
REM **** Install XtalOpt                                 ****
REM *********************************************************

nmake install

To SSH or not to SSH?!

By default, XtalOpt is ssh-enabled to facilitate a remote server access. That's, to let you running XtalOpt on your personal computer while the structure optimizations are performed on a remote server. If you don't need this option and plan to use the code only on your computer, then the ssh feature can be disabled by setting "-DENABLE_SSH=OFF" at the configuration time. In that case, all ssh-related configuration flags are irrelevant and can be removed, and XtalOpt build does not depend on libssh.

Back to Top ⇧