Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MicrosoftDocs/cpp-docs/llms.txt

Use this file to discover all available pages before exploring further.

Visual Studio supports writing C++ code that targets Android and iOS mobile platforms from a single Windows development environment. The Mobile development with C++ workload installs the Android NDK, the Android SDK, Apache Ant, and Clang toolsets so you can create, build, debug, and deploy Android Native Activity apps and shared libraries directly from the Visual Studio IDE. For iOS, the workload includes tools to connect to a Mac build host running Xcode.
Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android is deprecated and will be removed in a future update. The Android NDKs bundled with the workload remain supported. For new cross-platform mobile projects, consider .NET MAUI or React Native with NDK-backed C++ libraries.

Installing the Mobile Development with C++ Workload

1

Open Visual Studio Installer

Run the Visual Studio Installer from the Start menu. Click Modify next to your Visual Studio installation.
2

Select the workload

On the Workloads tab, find and select Mobile development with C++. The workload automatically includes:
  • Android Native Development Kit (NDK)
  • Android SDK with platform tools
  • Apache Ant (build system for legacy Android projects)
  • GCC and Clang toolsets for Android ABIs
  • C++ Android development templates
  • C++ iOS development tools (for connecting to a Mac)
3

Select optional components

In the Installation details pane, expand Mobile development with C++Optional to add:
  • Additional Android NDK versions
  • Google Android Emulator
  • Intel Hardware Accelerated Execution Manager (HAXM) — for fast x86 emulation on Intel CPUs
  • IncrediBuild for parallel builds
4

Finish installation

Click Modify and wait for installation to complete. Restart your computer when prompted — some third-party components (NDK, SDK) require a reboot to register correctly.

Android NDK and SDK Setup

After installation, Visual Studio manages the NDK and SDK paths automatically. To verify or change them:
  1. Go to ToolsOptionsCross PlatformC++Android.
  2. The dialog shows the detected paths for:
    • Android NDK — the toolchain directory (e.g., C:\Microsoft\AndroidNDK\android-ndk-r25c)
    • Android SDK — the SDK root (e.g., C:\Program Files (x86)\Android\android-sdk)
    • Java SE Development Kit — required for the Android build process
To use a different NDK version, install it via the SDK Manager or the Individual components tab in the Visual Studio Installer, then update the path in the Options dialog.
Some Android NDK tools do not support Unicode characters in file paths. Ensure your project directory and source file names use only ASCII characters to avoid build failures.

Creating an Android Native Activity App

The Native Activity Application (Android) template generates a fully functional Android app written in C++ using the Android NativeActivity API. NativeActivity allows the majority of your app to be pure C/C++ code, with only a thin Java glue layer.
1

Create the project

Go to FileNewProject. In the Create a new project dialog, search for Native-Activity Application (Android) and select it. Click Next, give your project a name (e.g., MyAndroidApp), and click Create.
2

Explore the solution

Visual Studio creates two projects:
  • MyAndroidApp.NativeActivity — contains main.cpp with the C++ entry point (android_main), precompiled headers, and NDK glue code. This project compiles to a shared library (.so file).
  • MyAndroidApp.Packaging — contains AndroidManifest.xml, resources, and the Ant build.xml. This is the startup project that creates the .apk for deployment.
3

Select a target platform

From the Solution Platforms dropdown, choose x86 (for emulator) or ARM / ARM64 (for physical devices).
4

Build and deploy

Press F5 to build the solution and launch the app in the Android Emulator. Visual Studio starts the emulator if it isn’t already running, deploys the .apk, and attaches the debugger.

Android Native Activity Code Structure

The generated main.cpp follows the Android NativeActivity pattern:
// main.cpp — Android Native Activity entry point
#include <android_native_app_glue.h>
#include <EGL/egl.h>
#include <GLES/gl.h>

struct AppState {
    ANativeWindow* window = nullptr;
    EGLDisplay    display = EGL_NO_DISPLAY;
    EGLSurface    surface = EGL_NO_SURFACE;
    EGLContext    context = EGL_NO_CONTEXT;
    bool          running = false;
};

// Called by the OS when the app receives system events
static void HandleAppCmd(android_app* app, int32_t cmd) {
    AppState* state = static_cast<AppState*>(app->userData);
    switch (cmd) {
    case APP_CMD_INIT_WINDOW:
        if (app->window != nullptr) {
            state->window = app->window;
            state->running = true;
        }
        break;
    case APP_CMD_TERM_WINDOW:
        state->running = false;
        break;
    }
}

// Main entry point — called by the NativeActivity glue
void android_main(android_app* app) {
    AppState state{};
    app->userData = &state;
    app->onAppCmd = HandleAppCmd;

    while (true) {
        int events = 0;
        android_poll_source* source = nullptr;
        ALooper_pollAll(state.running ? 0 : -1, nullptr, &events,
                        reinterpret_cast<void**>(&source));
        if (source) source->process(app, source);
        if (app->destroyRequested) break;

        if (state.running) {
            // Render a frame — your OpenGL ES code goes here
            glClearColor(0.2f, 0.4f, 0.8f, 1.0f);
            glClear(GL_COLOR_BUFFER_BIT);
        }
    }
}
The AndroidManifest.xml declares the NativeActivity:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myandroidapp">

  <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="34" />

  <application android:label="MyAndroidApp" android:hasCode="false">
    <activity android:name="android.app.NativeActivity"
              android:label="MyAndroidApp"
              android:configChanges="orientation|keyboardHidden">
      <meta-data android:name="android.app.lib_name"
                 android:value="MyAndroidApp" />
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
    </activity>
  </application>
</manifest>

Debugging Android C++ in Visual Studio

When you press F5 with an Android project, Visual Studio:
  1. Compiles the C++ code with the NDK’s clang++ for the selected ABI.
  2. Packages the .so into an .apk using the Android SDK tools.
  3. Deploys the .apk to the emulator or connected device via ADB.
  4. Attaches LLDB (on newer NDK versions) or GDB as the native debugger.
You can set breakpoints in your C++ source, inspect local variables, and step through code exactly as you would for a Windows or Linux project.
For hardware-accelerated x86 emulation, ensure that Intel HAXM is installed and that Intel Virtualization Technology (VT-x) is enabled in your BIOS/UEFI settings. AMD processors use AMD Hypervisor (AEHD) instead.

Building for iOS with Clang on a Mac

Building for iOS requires a Mac running Xcode (version 10.2 or later) because Apple’s build tools and code signing infrastructure run only on macOS. Visual Studio connects to the Mac over the network to perform the actual compilation.
1

Set up vcremote on the Mac

On your Mac, install the vcremote agent via npm (do not use sudo — see the vcremote prerequisites):
npm install -g --unsafe-perm vcremote
vcremote
Note the host name, port, and security PIN displayed — you will need them in Visual Studio.
2

Configure the remote connection in Visual Studio

In Visual Studio, go to ToolsOptionsCross PlatformC++iOS. Enter:
  • Host name: IP address or hostname of the Mac
  • Port: 3030 (default vcremote port)
  • PIN: The PIN shown when you started vcremote
3

Build an iOS target

Create or open an iOS C++ project. Select iOS as the platform in the Solution Platforms dropdown. When you build, Visual Studio sends source files to the Mac, where Clang compiles them and returns the output.

Supported Android ABIs and API Levels

The NDK supports multiple CPU architectures. Configure the target ABI in Project PropertiesGeneralTarget Architecture:
ABITarget DevicesNotes
x86Android emulator (Intel)Fast emulation via HAXM/AEHD
x86_64Android emulator (Intel)64-bit emulation
armeabi-v7a32-bit ARM devicesMinimum API level 16
arm64-v8a64-bit ARM devicesRequired for 64-bit APKs (Play Store policy)
The Google Play Store requires that APKs targeting API level 26 and above include a 64-bit (arm64-v8a) native library. Build a multi-ABI APK by specifying multiple architectures in your project configuration.

Build docs developers (and LLMs) love