Install and set up

ArcGIS Runtime SDK for Qt has APIs for developing desktop apps for Windows, Linux, and macOS, and mobile apps for iOS and Android. You can install the API on Windows, macOS, or Linux.

Before installing ArcGIS Runtime for Qt, make sure your development machine meets the system requirements.

Install on Windows

You will install the following components on your Windows development machine:

• Microsoft Visual Studio C++ compiler
• A Qt Framework for Windows: this framework is available from The Qt Company for developing cross-platform apps. This is not an Esri product.
• A Qt Framework for Android: (for Android developers) this framework is available from The Qt Company for developing Android apps. This is not an Esri product.
• Qt Creator: the IDE for Qt app development available from The Qt Company automatically included when you download Qt Framework for Windows. This is not an Esri product.
• ArcGIS Runtime API for Qt for Windows

Install Visual Studio

The Microsoft Visual Studio compiler is used to build apps with ArcGIS Runtime API for Qt. It is recommended that you uninstall previous versions of Visual Studio and any previous Visual Studio redistributables before installing Visual Studio, or conflicts can occur during installation. Be sure to install the C++ compiler. One way to do this is to select the Visual Studio installation option to use the C++ programming language as your default development environment.

Download the Qt Framework for Windows and Qt Creator

To build an app using the ArcGIS Runtime SDK for Qt, you need the Qt Framework designed to work with your compiler. You can install Qt Frameworks for multiple target platforms on your development machine, side-by-side.

1. Click Get Qt to download and install the appropriate Qt Framework for Windows. This download includes Qt Creator.
2. Open SSL support is required. Open SSL allows access to secure services that require user credentials. It is not delivered with the Qt Framework. For more information, see the Qt documentation about adding SSL support to your Qt app.
3. Install a debugger. See the Qt documentation for Setting Up Debugger.

Install prerequisites for Android app development

Install the prerequisite software for Android app development, including the Java SE Development Kit, Android SDK Tools, Android Platform Tools, the Android NDK, and a USB driver to communicate with a mobile device. See Qt for Android for more information on developing for Android with Qt. Also, be sure to install software versions that conform to the system requirements.

1. Browse to Getting Started with Qt for Android. Follow the instructions to download and install the prerequisite software. It is suggested that you create a new staging folder to store the prerequisite software, such as C:\Android. This folder is referred to in the download and install instructions as a <staging folder>.
2. Access the settings for Environment variables on your development machine. You can find this in the Control Panel > Advanced System Settings. If the following system environment variables were not previously established, define them as follows:
   1. Create a system environment variable called JAVA_HOME, and set its location to the Java\JDK folder, for example C:\Program Files\Java\jdk<version>.
   2. Create a system environment variable called ANDROID_NDK_ROOT, and put it in your NDK folder <staging folder>\android-ndk-<version>.
3. Click Get Qt to locate and download the Qt Framework for Android (on Windows).
4. Run the Qt for Android installer, accepting all installer defaults.
5. Set up your environment to use OpenSSL. For more information, see the OpenSSL section in the system requirements topic.
6. In Qt Creator, click Tools > Options > Devices > Android and fill in the paths. Paths should be similar to the following:
   • JDK Location: C:\Program Files\Java\jdk<version>
   • Android SDK Location: <staging folder>\adt-bundle-windows-<platform>-<date>\sdk
   • Android NDK Location: <staging folder>\android-ndk-<version>

Tell Qt Creator where to find your Qt Framework(s)

It is typical to use one Qt Creator IDE with multiple Qt Frameworks, such as one Framework for desktop development and another to build and deploy to a mobile device. Qt Creator needs to know where to find the Qt Frameworks you want to use. By default, it looks for Qt Frameworks on your development machine, but might not detect all the Qt Frameworks you want to use if you have multiple Qt Frameworks on your development machine or if you later install another Qt Framework.

Follow these steps to tell Qt Creator about additional Qt Frameworks:

1. Click Tools > Options > Build & Run > Qt Versions, and then click Add.
2. Browse to the qmake.exe file in the installation folder.
3. Provide a suitable name for this Qt Framework.
4. Click Apply.

After completing these steps, the Qt Framework you specified will be shown under the heading Manual. You can now use this Qt Framework to configure kits and projects.

Install ArcGIS Runtime SDK for Qt

1. Make sure you have read/write access to your desired download and extraction location and that your account has administrative privileges, as installing ArcGIS Runtime SDK for Qt on Windows requires administrative privileges.
2. Go to the downloads and select the Windows download for the most recent version of ArcGIS Runtime SDK for Qt. Note that you can download older versions as well as other development platforms.
3. Run the extraction wizard, which asks you to choose an extraction location.
4. Run setup.exe from your chosen extraction location.
5. After the setup program finishes, the post-installer starts. This integrates ArcGIS Runtime SDK for Qt with your installation of the Qt Framework and Qt Creator. Choose the Qt components you want to configure, selecting only those components that are installed on your development machine. For each component you choose, you must provide the path to that component. Please note that the post-installer needs read / write access to the User Profile's AppData folder.
   • For Qt Creator, use the path to the Qt Creator app.
   • For Qt Frameworks, use the path to qmake.exe in the Framework's install location.

Configure Qt Creator kits

In Qt Creator, a kit defines how to build an app for a target device. Set up a kit for each target device to which you will deploy your app so that you can develop and test for that device. Each kit must include references to the compiler, the Qt Framework, and the debugger. At minimum, you should set up a desktop kit.

1. Run Qt Creator.
2. Click Tools > Options > Build & Run > Kits.
3. Examine the existing kits. If no existing kit has the settings you want, click Add to create a new kit.
4. Give the kit an appropriate name.
5. Set the Device type to to match your target device, such as Desktop.
6. Choose the appropriate compiler to match the target device.
7. Choose the Qt Version.
8. Click OK or Apply to finish creating the kit.

Repeat these steps to add an Android kit if you installed the Qt Framework for Android.

Configure a Qt Creator project

1. Create a project in Qt Creator for your ArcGIS Runtime API for Qt app. You can use a provided project template to create a new project.
2. Complete the Display a map tutorial to verify your development environment is properly configured.
3. When you open a Qt Creator project file for the first time, Qt Creator prompts you to configure the project, which requires choosing the kits to use with the project. Choose the kit(s) you created in the previous step, and then click Configure Project.

You can now build your project in Qt Creator on Windows.

Install on macOS

You will install the following components on your macOS development machine:

• Apple Xcode
• The Qt Framework for macOS: this framework is available from The Qt Company for developing cross-platform applications. This is not an Esri product.
• The Qt Framework for iOS: (for iOS developers) this framework is available from The Qt Company for developing iOS applications. This is not an Esri product.
• The Qt Framework for Android: (for Android developers) this framework is available from The Qt Company for developing Android applications. This is not an Esri product.
• Qt Creator: the IDE for Qt application development available from The Qt Company bundled with Qt Framework for macOS. This is not an Esri product.
• ArcGIS Runtime SDK for Qt for macOS

Install Xcode

Install Xcode and the Xcode command line tools from the App Store or Apple's developer web site. An Apple developer account is required to log in. Follow the documentation at Apple's accounts web site.

Download the Qt Framework for macOS and Qt Creator

To build an application using ArcGIS Runtime API for Qt, you need the Qt Framework designed to work with your compiler. You can install Qt Frameworks for multiple target platforms on your development machine, side-by-side.

Download and install the Qt Framework for macOS from The Qt Company. Make sure that you also install Qt Creator along with the Qt Framework.

Install prerequisites for iOS development

If you plan to develop applications for the iOS platform, you must install Xcode for iOS. See Qt for iOS for more information on Qt for iOS.

1. Start Xcode.
2. Click Xcode > Preferences.
3. On the Downloads tab, click Component, and download the iOS simulator.
4. Configure your Xcode for Distribution by following the documentation at Apple's web site.
5. Download and install the Qt Framework for iOS (on Mac) from The Qt Company.

Install prerequisites for Android development

Install the prerequisite software for Android app development, including the Java SE Development Kit, Android SDK Tools, Android Platform Tools, and the Android NDK. See Qt for Android for more details on developing for Android with Qt. Be sure to install software versions that conform to the system requirements.

1. Browse to Getting Started with Qt for Android. Follow the instructions there to download and install the prerequisite software. It is suggested that you create a new staging folder to store all the prerequisite software, such as ~/Android. This folder is referred to in the download and install instructions as a <staging folder>.
2. Download the Qt Framework for Android (on Mac) from The Qt Company.
3. Run the Qt Framework for Android installer, accepting all installer defaults.
4. Set up your environment to use OpenSSL. For more information, see the OpenSSL section of the system requirements.
5. In Qt Creator, click Qt Creator > Preferences > Devices > Android, and fill in the paths. Paths should be similar to the following:
   • JDK Location: <staging folder>/CurrentJDK/Home
   • Android SDK Location: <staging folder>/adt-bundle-mac-x86_64-<date>/sdk
   • Android NDK Location: <staging folder>/android-ndk-<version>

Tell Qt Creator where to find the Qt Framework

It is typical to use one Qt Creator IDE with multiple Qt Frameworks, such as one Framework for desktop development and another to build and deploy to a mobile device. Qt Creator needs to know where to find the Qt Frameworks you want to use. By default, it looks for Qt Frameworks on your development machine, but might not detect all the Qt Frameworks you want to use if you have multiple Qt Frameworks on your development machine or if you later install another Qt Framework.

Follow these steps to tell Qt Creator about additional Qt Frameworks:

1. Start Qt Creator.
2. Click Qt Creator > Preferences > Build & Run > Qt Versions, and then click Add.
3. Browse to the qmake file in the installation location.
4. Provide a suitable name for this Qt Framework.
5. Click Apply.

After completing these steps, the Qt Framework you specified will be shown under the heading Manual. You can now use this Qt Framework to configure kits and projects.

Repeat these steps for any Qt Frameworks for Android and iOS you previously installed.

Install ArcGIS Runtime SDK for Qt

1. Make sure you have read/write access to your desired download and extraction location.
2. Go to the downloads page and select the macOS download for the most recent version of ArcGIS Runtime SDK for Qt. Note that you can download older versions as well as other development platforms.
3. Run the installer app.
4. After the installer app finishes, the post-installer starts. This integrates ArcGIS Runtime API for Qt with your installation of the Qt Framework and Qt Creator. Choose the Qt components you want to configure. Choose only components that are installed on your development machine. For each component you choose, you must provide a path to the component. Note that the post-installer needs read/write access to ~/.config.
   • For Qt Creator, use the path to the Qt Creator app.
   • For Qt Frameworks, use the path to the qmake executable in the Framework's install location.

Configure Qt Creator kits

In Qt Creator, a kit defines how to build an app for a target device. Set up a kit for each target device on which you will deploy your app to so that you can develop and test for that device. A kit includes references to the compiler, the Qt Framework, and the debugger. At minimum, you should set up a desktop kit.

1. Run Qt Creator.
2. Click Qt Creator > Preferences > Build & Run > Kits.
3. Examine the existing kits. If no existing kit has the settings you want, click Add to create a new kit.
4. Give the kit an appropriate name.
5. Set Device type to to match your target device, such as Desktop.
6. Choose the Qt Version.
7. Click OK or Apply to finish creating the kit.

Repeat these steps to add an iOS or Android kit if you installed those Qt Frameworks.

Configure a Qt Creator project

1. Create a project in Qt Creator for your ArcGIS Runtime API for Qt app. You can use a provided project template to create a new project.
2. Complete the Display a map tutorial to verify that your development environment is properly configured.
3. When you open a Qt Creator project file for the first time, Qt Creator prompts you to configure the project, which requires choosing the kits to use with the project. Choose the kit(s) you created in the previous step, and then click Configure Project.

You can now build your project in Qt Creator on macOS.

Install on Linux

You will install the following components on your Linux development machine:

• The Qt Framework for Linux: this framework is available from The Qt Company for developing cross-platform applications. This is not an Esri product.
• The Qt Framework for Android: (for Android developers) this framework is available from The Qt Company for developing Android applications. This is not an Esri product.
• Qt Creator: the IDE for Qt application development available from The Qt Company bundled with The Qt Framework for Linux. This is not an Esri product.
• ArcGIS Runtime SDK for Qt for Linux

Download the Qt Framework for Linux and Qt Creator

To build an application using the ArcGIS Runtime SDK for Qt, you will need the Qt Framework designed to work with your compiler. You can install Qt Frameworks for multiple target platforms on your development machine, side-by-side.

• Download and install the appropriate Qt Framework for Linux from The Qt Company. Make sure that you also install Qt Creator along with the Qt Framework.
• Open SSL support is required. Open SSL allows access to secure services that need user credentials. It is not delivered with the Qt Framework. For more information, see the Qt documentation about adding SSL support to your Qt application.

Install prerequisites for Android development

Install the prerequisite software for Android app development, including the Java SE Development Kit, Android SDK Tools, Android Platform Tools, and the Android NDK. See Qt for Android for details about developing for Android with Qt. Be sure to install software versions that conform to the system requirements.

1. Browse to Getting Started with Qt for Android. Follow the instructions there to download and install the prerequisite software. It is suggested that you create a new staging folder to store all the prerequisite software, such as ~/Android. This folder is referred to in the download and install instructions as a <staging folder>.
2. Download the Qt Framework for Android (on Linux) from The Qt Company.
3. Run the Qt Framework for Android installer, accepting all the installer defaults.
4. Set up your environment to use OpenSSL. For more information, see the OpenSSL section of the system requirements topic.
5. In Qt Creator, click Tools > Options > Devices > Android, and fill in the paths. Paths should be similar to the following:
   • JDK Location: <staging folder>/jdkl.<version>
   • Android SDK Location: <staging folder>/android-sdk-linux
   • Android NDK Location: <staging folder>/android-ndk-<version>

Tell Qt Creator where to find the Qt Framework

It is typical to use one Qt Creator IDE with multiple Qt Frameworks, such as one framework for desktop development and another to build and deploy to a mobile device. Qt Creator needs to know where to find the Qt Frameworks you want to use. By default, it looks for Qt Frameworks on your development machine but might not detect all the Qt Frameworks you want to use if you have multiple Qt Frameworks on your development machine or if you later install another Qt Framework.

Follow these steps to tell Qt Creator about additional Qt Frameworks:

1. Start Qt Creator.
2. Click Tools > Options > Build & Run > Qt Versions, and then click Add.
3. Browse to the qmake file in the installation location.
4. Provide a suitable name for this Qt Framework.
5. Click Apply.

After completing these steps, the Qt Framework you specified will be shown under the heading Manual. You can now use this Qt Framework to configure kits and projects.

Repeat these steps for any Qt Frameworks for Android you previously installed.

Install ArcGIS Runtime API for Qt

1. Make sure you have read-write-execute access to your desired ArcGIS installation location.
2. Go to the downloads page and select the Linux download for the most recent version of ArcGIS Runtime SDK for Qt. Note that you can download older versions as well as other development platforms.
3. Save the file to an installation location large enough to hold the extracted content from the gzip and tar files.
4. Unzip the ArcGIS Runtime gzip file to get the tar file. At the prompt, type % gunzip .tar.gz.
5. Extract the product tar file to create the installation directory: % tar xvf .tar.
6. Run the script ./Setup from the installation location. Do not double-click on the file in the file browser and select Run in Terminal, or the post-installer will start and then exit as soon as the terminal window closes.
7. After the setup program finishes, the post-installer starts. The post-installer integrates the ArcGIS Runtime SDK for Qt with your installation of the Qt Framework and Qt Creator. Choose the Qt components to configure. Choose only those components that are installed on your computer. For each component you choose, provide a path to the component. Please note that the post-installer needs read / write access to ~/.config.
   • For Qt Creator, use the path to the Qt Creator app.
   • For Qt Framework installations, use the path to the qmake executable in the Qt Framework's install location.
8. Add the path to the ArcGIS Runtime for Qt library files to the environment variable LD_LIBRARY_PATH. The path is <install location>/arcgis/runtime_sdk/<sdk version>/sdk/linux/<platform>/lib. You can do this in your Qt Creator project settings, or by setting the LD_LIBRARY_PATH environment variable before starting Qt Creator.

Configure Qt Creator kits

In Qt Creator, a kit defines how to build an app for a target device. Set up a kit for each target device on which you will deploy your app to so that you can develop and test for that device. A kit includes references to the compiler, the Qt Framework, and the debugger. At minimum, you should set up a desktop kit.

1. Run Qt Creator.
2. Click Tools > Options > Build & Run > Kits.
3. Examine the existing kits. If no existing kit has the settings you want, click Add to create a new kit.
4. Give the kit an appropriate name.
5. Set the Device type to to match your target device, such as Desktop.
6. Choose the appropriate compiler for your development platform.
7. Choose the appropriate debugger. If there is no appropriate debugger, you will need to install one. Refer to your operating system documentation.
8. Choose the Qt Version.
9. Click OK or Apply to finish creating the kit.

Repeat these steps to add an Android kit if you installed the Qt Framework for Android.

Configure a Qt Creator project

1. Create a project in Qt Creator for your ArcGIS Runtime API for Qt app. You can use a provided project template to create a new project.
2. Complete the Display a map tutorial to verify that your development environment is properly configured.
3. When you open a Qt Creator project file for the first time, Qt Creator prompts you to configure the project. This means choosing the kits to use with the project. Choose the kit(s) you created in the previous step, and then click Configure Project.

You can now build your project in Qt Creator on Linux.

Additional downloads

Additional sources of sample code, data, and tools are available to enhance your ArcGIS Runtime development projects. You can even download this guide as stand-alone developer documentation.

Sample code

Browse the comprehensive list of samples in the documentation or download sample code from the GitHub repository. Interact with live samples using the sample viewer app, which can be downloaded from ArcGIS Online for your target platform (Windows, macOS, Linux, or Android).

ArcGIS Runtime API for Qt Toolkit

The open source ArcGIS Runtime Toolkit for Qt contains UI components and utilities that will help simplify your Qt app development.

• ArcGISArView: A scene view that integrates with ARKit/ARCore features for augmented reality on mobile devices.
• AuthenticationView Dialog: A wrapper view that will automatically display the proper authentication view for any of the supported authentication types (OAuth, Token, HTTP Basic, HTTP Digest, SAML, PKI).
• ClientCertificateView Dialog: A dialog for handling PKI authentication.
• OAuth2View Dialog: A dialog for handling OAuth authentication.
• SslHandshakeView Dialog: A dialog for allowing/blocking SSL Handshake related issues.
• UserCredentialsView Dialog: A generic dialog for handling username/password authentication.
• Callout Control: A view for displaying information at a geographic location on the map.
• PopupView Control: A view for displaying attributes and attachments for features.
• TimeSlider Control: A control for visualizing temporal data by changing the currently visible time extent.
• Compass Control: (C++ only) A compass (aka north arrow) control for indicating which direction is north.
• Coordinate Conversion Control: (C++ Only) A tool for assisting in converting coordinates from one format to another.

Local Server

Local Server enables you to run offline geoprocessing tasks to provide advanced spatial analysis and data manipulation in your applications. These tasks work in the same way as geoprocessing tasks running on ArcGIS Enterprise. If you want to run offline geoprocessing tasks in your app, install local server following the steps in Local Server.

Stand-alone developer documentation

You can download the developer documentation (for any ArcGIS Runtime API) as an archive from the downloads. The archive contains instructions to serve the documentation from a local web server so you can access it without a connection to the internet. The stand-alone documentation includes the developer guide, API reference, tutorials, and samples documentation. This documentation is designed to run on a local stand-alone computer or on an internal network and not on the public internet.

To serve the documentation locally:

• Download the documentation for the ArcGIS Runtime API(s) you want to use. The downloaded files are in a .zip archive format.
• Extract the archive to a local folder. The extracted archive has two subfolders: public and install.
• Open the README.md file in the install folder and follow the instructions for your chosen web server.

Supplemental data

StreetMap Premium

StreetMap Premium for ArcGIS Runtime provides enriched street data, which powers a high-quality cartographic maps and high-quality search, geocoding, and route analysis. StreetMap Premium maps are consistent across all regions of the world and can be taken offline for disconnected use; they can simultaneously fulfill the need for an address locator, street network dataset, and basemap in your app.

If you want to use StreetMap Premium data (the StreetMap Premium extension), download the demonstration data from the downloads page for development and testing. Please contact Esri Customer Service for access to a region of your choice for development and testing or to license StreetMap Premium data for deployment.

Projection Engine data

Datum transformations are used when geometries must be projected from one spatial reference to another when there is a difference in the datum that underlies the two spatial references. Datum transformations can be mathematically defined (equation-based transformations), or may rely on external supporting files (grid-based transformations). Certain Projection Engine data files must be present when you use a grid-based transformation in your app; attempting to use a transformation with missing Projection Engine files will cause an error. The API can detect whether the necessary files are available on the local file system.

If your app requires grid-based transformations, you can download supporting Projection Engine files from the downloads page. See the Spatial references topic for more information about working with coordinate systems, projections, and datum transformations.

Electronic Navigational Charts (ENC)

Electronic navigational charts (ENCs) are georeferenced vector datasets for the visualization and analysis of hydrographic and maritime information. ArcGIS Runtime supports ENCs that conform to the International Hydrographic Organization (IHO) S-57 standard.

If you want to work with Electronic Navigational Charts (ENC) download the hydrography directory from the downloads page.

See the Display electronic navigational charts topic for more information about working with ENC data.

Support

If you have questions or difficulty getting set up, ask for help on the ArcGIS Runtime SDK for Qt developer community. Visit the support page for other ways to ask for help.

Next steps

• Overview

  Learn about the API and its capabilities.

• Get started

  Install and setup the API and get your API key.

• Display a map

  Get started with the display a map tutorial.