Install and set up

ArcGIS Maps 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 the API, 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
• The Qt Framework for Windows: this framework is available from The Qt Group for developing cross-platform apps. This is not an Esri product.
• The Qt Framework for Android: (for Android developers) this framework is available from The Qt Group for developing Android apps. This is not an Esri product.
• Qt Creator: the IDE for Qt app development available from The Qt Group automatically included when you download Qt Framework for Windows. This is not an Esri product.
• CMake: only required if building with CMake instead of qmake. This is not an Esri product.
• ArcGIS Maps SDK for Qt for Windows

Install Visual Studio

The Microsoft Visual Studio compiler is used to build apps with ArcGIS Maps SDK 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 Maps 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. 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 Development Kit (JDK), 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. 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 Maps 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 Maps SDK for Qt on Windows requires administrative privileges.
2. Go to the downloads page, and select the Windows download for the most recent version of ArcGIS Maps 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 script runs. This integrates ArcGIS Maps SDK for Qt with your installation of the Qt Framework and Qt Creator. Please note that the post-installer script needs read/write access to the User Profile's AppData folder.

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.

Install CMake

ArcGIS Maps SDK for Qt applications can be built with qmake or CMake. Qmake is installed by default with the Qt Framework. CMake must be installed separately from the CMake website. See the Qt CMake Manual for more information.

Configure a Qt Creator project

1. Create a project in Qt Creator for your ArcGIS Maps SDK 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 Group 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 Group 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 Group for developing Android applications. This is not an Esri product.
• Qt Creator: the IDE for Qt application development available from The Qt Group bundled with Qt Framework for macOS. This is not an Esri product.
• CMake: only required if building with CMake instead of qmake. This is not an Esri product.
• ArcGIS Maps 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 Maps 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.

Download and install the Qt Framework for macOS from The Qt Group. 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 Group.

Install prerequisites for Android development

Install the prerequisite software for Android app development, including the Java Development Kit (JDK), 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 Group.
3. Run the Qt Framework for Android installer, accepting all installer defaults.
4. 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>

Install ArcGIS Maps 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 Maps 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 script runs. This integrates ArcGIS Maps SDK for Qt with your installation of the Qt Framework and Qt Creator. Note that the post-installer script needs read/write access to ~/.config.

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.

Install CMake

ArcGIS Maps SDK for Qt applications can be built with qmake or CMake. Qmake is installed by default with the Qt Framework. CMake must be installed separately from the CMake website. See the Qt CMake Manual for more information.

Configure a Qt Creator project

1. Create a project in Qt Creator for your ArcGIS Maps SDK 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 Group 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 Group for developing Android applications. This is not an Esri product.
• Qt Creator: the IDE for Qt application development available from The Qt Group bundled with The Qt Framework for Linux. This is not an Esri product.
• CMake: only required if building with CMake instead of qmake. This is not an Esri product.
• ArcGIS Maps SDK for Qt for Linux

Download the Qt Framework for Linux and Qt Creator

To build an application using the ArcGIS Maps 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 Group. Make sure that you also install Qt Creator along with the Qt Framework.

Install prerequisites for Android development

Install the prerequisite software for Android app development, including the Java Development Kit (JDK), 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. Consider creating 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 Group.

3. Run the Qt Framework for Android installer, accepting all the installer defaults.

4. 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>

Install ArcGIS Maps SDK 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 Maps 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 Maps SDK 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 script runs. The post-installer integrates the ArcGIS Maps SDK for Qt with your installation of the Qt Framework and Qt Creator. Please note that the post-installer script needs read / write access to ~/.config.

8. Add the path to the ArcGIS Maps SDK for Qt library files to the environment variable LD_LIBRARY_PATH. The path is <install location>/arcgis/maps_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.

Install CMake

ArcGIS Maps SDK for Qt applications can be built with qmake or CMake. Qmake is installed by default with the Qt Framework. CMake must be installed separately from the CMake website. See the Qt CMake Manual for more information.

Configure a Qt Creator project

1. Create a project in Qt Creator for your ArcGIS Maps SDK 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 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 Maps SDK for Qt Toolkit

The open source ArcGIS Maps SDK for Qt Toolkit 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 as an archive from the downloads page. 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 SDK 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 delivers a high-quality, multiscale cartographic map display with enriched street data. In addition, it provides accurate geocoding, optimized routing, easy to follow directions, and powerful network analysis. StreetMap Premium maps can simultaneously fulfill the need for an address locator, street network dataset, and basemap in your apps. They are consistent across all regions of the world and are available for both online, connected scenarios and for use in offline, disconnected scenarios in the form of mobile map packages.

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. This SDK 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 Maps SDK for Qt developer community. Visit the support page for other ways to ask for help.

Next steps

• Overview

  Learn about the API and developer resources.

• Key features

  Discover the capabilities of the API.

• Get started

  Get started using the API.