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 download, install, and configure the following components on your Windows development machine:

• Install Visual Studio
• Download the Qt Framework for Windows and Qt Creator
• Install prerequisites for Android app development on Windows
• Tell Qt Creator where to find the Qt Frameworks
• Download and Install ArcGIS Maps SDK for Qt on Windows
• Configure Qt Creator kits on Windows
• Install CMake on Windows
• Configure a Qt Creator project on 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

The Qt Framework for Windows is available from The Qt Group for developing cross-platform apps. This is not an Esri product.

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 on Windows

The Qt Framework for Android (for Android developers) is available from The Qt Group for developing Android apps. This is not an Esri product.

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 the Qt Frameworks

Qt Creator is the IDE for Qt app development available from The Qt Group. It is automatically included when you download Qt Framework for Windows. This is not an Esri product.

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.

Download and Install ArcGIS Maps SDK for Qt on Windows

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 the ArcGIS Maps SDK for Qt. From the downloads page, you can download older versions as well as other development platforms.

3. Use an un-zip extraction utility, and choose an extraction location. You may want to give some thought as to where the extraction location will be, for example: %UserProfile%\ArcGIS_Maps_SDKs. This way you can have multiple versions of the ArcGIS Maps SDK for Qt in a single parent directory.

4. Nested in the ArcGIS Maps SDK for Qt un-zip location directory, you will find a README.txt file that contains details on how to configure the ArcGIS Maps SDK for Qt on your machine. For most developers on a Windows machine, you simply need to start Windows PowerShell as an Administrator, navigate to the directory where the README.txt exists, and execute the following command: .\configure.ps1

   When prompted with the question "Do you accept the terms of the Master License Agreement? (yes/no)", enter then text yes and hit enter to complete the configuration. If you enter no the configuration will not complete.

   If you are prompted with the question "Do you want to run software from this untrusted publisher?" enter with the response of either R (run once) of A (always run) for the signed PowerShell script.

   As part of this default option of the Windows PowerShell script, the ArcGIS Maps SDK for Qt is integrated with your installation of Qt Creator. The Windows PowerShell script will need read/write access to the User Profile's %AppData% folder.

Configure Qt Creator kits on Windows

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 on Windows

CMake is only required if building with CMake instead of qmake. This is not an Esri product.

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 on Windows

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 download, install, and configure the following components on your macOS development machine:

• Install Xcode
• Download the Qt Framework for macOS and Qt Creator
• Install prerequisites for iOS development
• Install prerequisites for Android development on macOS
• Install ArcGIS Maps SDK for Qt on macOS
• Configure Qt Creator kits on macOS
• Install CMake on macOS
• Configure a Qt Creator project on 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

The Qt Framework for macOS this framework is available from The Qt Group for developing cross-platform applications. This is not an Esri product.

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

The Qt Framework for iOS (for iOS developers) is available from The Qt Group for developing iOS applications. This is not an Esri product.

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 on macOS

The Qt Framework for Android (for Android developers) is available from The Qt Group for developing Android applications. This is not an Esri product.

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 on macOS

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. From the downloads page, you can download older versions as well as other development platforms.

3. Use an un-zip extraction utility, and choose an extraction location. You may want to give some thought as to where the extraction location will be, for example: $HOME/ArcGIS_SDKs. This way you can have multiple versions of the ArcGIS Maps SDK for Qt in a single parent directory.

4. Nested in the ArcGIS Maps SDK for Qt un-zip location directory, you will find a README.txt file that contains details on how to configure the ArcGIS Maps SDK for Qt on your machine. For most developers on a macOS machine, you simply need to start Terminal, navigate to the directory where the README.txt exists, and execute the following command: ./configure.sh

   When prompted with the question "Do you accept the terms of the Master License Agreement? (yes/no)", enter then text yes and hit enter to complete the configuration. If you enter no the configuration will not complete.

   As part of this default option of the Bash script, the ArcGIS Maps SDK for Qt is integrated with your installation of Qt Creator. Note that the Bash script needs read/write access to ~/.config.

Configure Qt Creator kits on macOS

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 on macOS

CMake is only required if building with CMake instead of qmake. This is not an Esri product.

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 on macOS

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 download, install, and configure the following components on your Linux development machine:

• Download the Qt Framework for Linux and Qt Creator
• Install prerequisites for Android development on Linux
• Install ArcGIS Maps SDK for Qt on Linux
• Configure Qt Creator kits on Linux
• Install CMake on Linux
• Configure a Qt Creator project on Linux

Download the Qt Framework for Linux and Qt Creator

The Qt Framework for Linux is available from The Qt Group for developing cross-platform applications. This is not an Esri product.

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 on Linux

The Qt Framework for Android (for Android developers) is available from The Qt Group for developing Android applications. This is not an Esri product.

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 on Linux

1. Make sure you have read/write access to your desired download and extraction location.

2. Go to the downloads page, and select the Linux download for the most recent version of the ArcGIS Maps SDK for Qt. From the downloads page, you can download older versions as well as other development platforms.

3. Use an un-zip extraction utility, and choose an extraction location. You may want to give some thought as to where the extraction location will be, for example: $HOME/maps_sdks. This way you can have multiple versions of the ArcGIS Maps SDK for Qt in a single parent directory.

4. Nested in the ArcGIS Maps SDK for Qt un-zip location directory, you will find a README.txt file that contains details on how to configure the ArcGIS Maps SDK for Qt on your machine. For most developers on a Linux machine, you simply need to start Terminal, navigate to the directory where the README.txt exists, and execute the following command: ./configure.sh

   When prompted with the question "Do you accept the terms of the Master License Agreement? (yes/no)", enter then text yes and hit enter to complete the configuration. If you enter no the configuration will not complete.

   As part of this default option of the Bash script, the ArcGIS Maps SDK for Qt is integrated with your installation of Qt Creator. Note that the Bash script needs read/write access to ~/.config.

Configure Qt Creator kits on Linux

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 on Linux

CMake is only required if building with CMake instead of qmake. This is not an Esri product.

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 on Linux

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

The following additional resources are available to enhance your development projects:

• Sample code
• ArcGIS Maps SDK for Qt Toolkit
• Local Server
• Supplemental data
• Enable the display of ENC data
• 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.

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.

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.

Enable the display of ENC data

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.

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.

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.