Jump to content
  • Advertisement
  • 12/21/17 08:09 AM
    Sign in to follow this  

    Android Debugging with Visual Studio Code

    General and Gameplay Programming


    This article discusses how to debug native Android applications using Microsoft Visual Studio Code, which can be useful for game developers implementing background services, prototyping, or other native processes on the Android platform.

    Of course, Android Studio and Visual Studio 2017/2015 also offer Android debugging capabilities, but they're more restrictive with the configuration environment and only allow debugging of applications packaged in an APK - so we are unable to debug any native processes we might be using to prototype, develop services, or other native processes on Android.

    Speaking of APKs, note that VSCode also supports debugging APKs via the Android extension.



    The following components are required to enable debugging:

    1. Visual Studio Code with the C/C++ extension installed.

    2. GNU Debugger (GDB) from the Android NDK.

      Windows <NDK_ROOT>\prebuilt\windows-x86_64\bin
      Linux <NDK_ROOT>\prebuilt\linux-x86_64\bin
      macOS <NDK_ROOT>\prebuilt\darwin-x86_64\bin


    3. A build of the target project with debugging enabled. This can be achieved by passing NDK_DEBUG=1 on the ndk-build command line, or by adding it to the project's Application.mk file. Enabling NDK_DEBUG also causes ndk-build to copy the correct version of gdbserver to the project's output directory. This will need to be copied to the target device to enable the debugger connection.
      1. Also, if the project's Application.mk file specifies the APP_OPTIM setting, it must be set to debug to disable compiler optimizations. While debugging optimized code it possible, it will be a more limited and difficult debugging experience. Optimization can be disabled by passing APP_OPTIM=debug on the ndk-build command line, or by modifying it in the project's Application.mk file.

      2. If the project does not specify the APP_OPTIM setting, setting NDK_DEBUG as described above will automatically disable optimizations.

    Debugging Setup

    Before debugging the first time, open the project workspace in VSCode and perform the following steps:

    1. Open the Debug menu and click Add Configuration...
    2. Choose C/C++ (gdb) Launch as the configuration type. If this option is not available the C/C++ extension is not installed and none of this is going to work.

    3. Configure the debugger settings for the project. The required attributes are described below.

      name The name of the debugging task. This is the name that will be displayed in the UI.
      type Should be set to cppdebug.
      request Should be set to launch.
      program The program to debug. This should point to the local version of the executable with debug symbols (the non-stripped version), which is normally in obj/local/armeabi-v7a under the project's build directory (or obj/local/arm64-v8a for 64 bit builds).
      cwd Doesn't really have any effect, but is required. Can just be set to ${workspaceFolder}.
      MIMode Should be set to gdb.
      miDebuggerPath The path to the gdb executable. This should point to the directory in the Android NDK as indicated above.
      miDebuggerServerAddress The target address to connect to. Since the device is connected via USB, this should be set to localhost:<port>, where <port> is the TCP port chosen for the debugger connection. This same port must be used when starting gdbserver on the device.
      additionalSOLibSearchPath Any additional local paths to search for debug symbols. The directory specified for the program attribute will automatically be searched first. This should point to the directories of the non-stripped versions of any additional shared libraries to be debugged (if they are not in the same directory as the main executable). Separate multiple paths with a colon.
      setupCommands An array of additional gdb commands to be executed during setup of the debugger. This needs to be used to execute the set solib-absolute-prefix command to set the local path to the stripped version of all binaries being debugged.
      preLaunchTask A task to execute before starting the debugger. See the section below about defining tasks in VSCode.

    The other attributes created for the default configuration can be deleted.

    Example launch.json file

        "version": "0.2.0",
        "configurations": [
                "name": "Remote GDB",
                "type": "cppdbg",
                "request": "launch",
                "preLaunchTask": "Forward debug port",
                "cwd": "${workspaceRoot}",
                "program": "${workspaceRoot}/app/Intermediate/android/myapp/local/armeabi-v7a/myapp",
                "additionalSOLibSearchPath": "${workspaceRoot}/app/Intermediate/android/mylib/local/armeabi-v7a",
                "miDebuggerServerAddress": "localhost:5039",
                "setupCommands": [
                        "text": "set solib-absolute-prefix ${workspaceRoot}/app/path/android",
                        "ignoreFailures": false
                "windows": {
                    "miDebuggerPath": "C:/Tools/android-ndk-r13b/prebuilt/windows-x86_64/bin/gdb.exe",
                    "MIMode": "gdb"

    Refer to the C/C++ debugging documentation for additional information. In particular, the logging attribute can be used to enable additional logging output, which can be useful for troubleshooting if the debugger is not working as expected.

    Preparing to Debug

    With the debugger configuration set, there are some additional steps required to debug the project:

    1. Copy the target binaries to the target device.
    2. Copy gdbserver to the target device.

    Starting the Debugger

    With all preparations complete, it's time to start debugging. Use the same port number in these steps as was used in the debugger configuration above.

    1. Execute gdbserver on the target device (execute permissions may need to be enabled). The server can be run in two modes: execute or attach.
      1. Execute mode will load the target executable and then wait for a client to attach. When the client attaches it will begin execution of the program. This mode is necessary to debug an application's initialization.
      2. Attach mode will attach to an already running process. It will not interrupt the process.

        Run mode gdbserver :<port> <exe>
        Attach mode gdbserver :<port> --attach <pid>
    2. Forward the debugger port from the device with ADB: adb forward tcp:<port> tcp:<port>

    3. Start the debugger in VSCode.

      1. Enable the Debug panel by clicking the bug icon on the left side of the VSCode window.
      2. Select the debug configuration from the list at the top of the panel.
      3. Click the go button to launch the debugger.
    Once the debugger starts to connect, the VSCode debug console will display messages from the debugger and allow manual debugger commands to be executed if necessary (the program must be stopped to execute debug commands). The debug panels will display debugging information (variable watches, callstacks, breakpoints, etc.), and a debugger toolbar will provide access to common debug commands. Mouse cursor based display of variables is also supported.


    VSCode also supports the definition of tasks, which can be used to execute any command line process, typcially as part of building and/or testing code. These tasks can also be used to support debugging. For instance, a task could be defined to forward the debugger port. This could then be incorporated in the debugger configuration using the preLaunchTask attribute to ensure the port is forwarded before attempting to connect the debugger. Tasks can be configured by selecting Configure Tasks... from the Tasks menu. See the VSCode documentation for more information about task configuration.

    Example tasks.json file

        "version": "2.0.0",
        "tasks": [
                "label": "Forward debug port",
                "type": "shell",
                "command": "adb",
                "args": [
                "presentation": {
                    "reveal": "never"
                "problemMatcher": []

      Report Article
    Sign in to follow this  

    User Feedback

    Create an account or sign in to comment

    You need to be a member in order to leave a comment

    Create an account

    Sign up for a new account in our community. It's easy!

    Register a new account

    Sign in

    Already have an account? Sign in here.

    Sign In Now

  • Advertisement
  • Advertisement
  • Latest Featured Articles

  • Featured Blogs

  • Popular Now

  • Similar Content

    • By EmmersionStudios
      We're currently looking to recruit a programmer to help us build out the remainder of our game, MATCHINO, for Android and iOS. Matchino is a match-3 game, utilizing elements of poker and casino gaming, in real life cities and towns throughout America. Our team is serious about putting out a polished, professional game. While we learn about the development process (it's been an eye-opener thus far), we also receive a portion of the profit share from in-game purchases and ads (using strategies designed to maximize revenue).
      Programming-wise we have the following set up: Facebook to accept player logins and store player save data, working game board mechanics, end-game process, startup screen, loading, menu UIs, and first 20 levels complete. We're gearing up to complete a demo for experience testing and for release within the next 2-3 months.
      We want to move on from this project to develop earth-shattering games, but we knew we needed to start small and gradually work up to that. Everything legal is in order, we're an LLC, we have a website/Facebook presence, contracts, etc. We just need some more help.
      If you're interested please PM or email me at sam.azzarano@emmersionstudios.com (or visit our website at www.emmersionstudios.com)
      Thank you!

    • By leekeechild
      Tile remover is the mix of classic bubble shooter and falling down block puzzle. Try to remove
      all tiles from the playground. Colored tiles are falling down one by one in a round and you
      must place them how the same colors should be alongside. If you make a group of tiles [by at
      least 3 tiles] from same color then them will be removed. When you skip more than 1 or 2 rounds
      without making a group then a new line with tiles will appear of the bottom side of playground.
      Have fun!
    • By Zippy1970
      I've created a HTML5 2D canvas game and I'm now ready to take the step and convert it to a native Android (and iOS) app. The game works perfectly fine in any desktop or mobile browser. Animations are fast and smooth.
      After some research, I decided Cordova was the way to go to create native apps for Android and iOS. My first priority is Android, simply because I have an Android phone myself and I don't have a Mac (which apparently is required to build iOS apps).
      I have looked at Cocoon.io and although that might be an even better option than Cordova (since it's actually build on top of Cordova), the thing that made me run from it is the fact that it costs $500 just to remove the "build with Cocoon" splash screen...
      After installing all prerequisites (cordova, Android Studio, nodes.js) building my first APK was easy.
      When I ran my game in the Android emulator, the game was abysmally slow... Testing it on my device yielded the same slow results. After searching the internet, I figured it was because on some devices, an old and slow WebView is used by native apps to display HTML5 content. Still strange since my phone uses Android 7.0.0 and the emulator uses Android 8.0.0...
      I quickly found FastCanvas, a PhoneGap/Cordova plugin that adds a very fast canvas "compatible" rendering surface. But it was last updated in 2013 and after trying to get it to work for almost 16 hours straight, I came to the conclusion there's no way to get this to work with the current version of Cordova.
      I then found CrossWalk-WebView. This too was pretty old and a pain to get it to work with the current version of Cordova. And when I did get it to work, I quickly found out it created a few new problems making my game unplayable (noticeably a strange lag when touching the screen. Not the famous 300ms input lag, but after touching the screen, the entire game would freeze for 200ms-300ms). So I had to give up on Crosswalk as well.
      So now I am at a loss. Can anyone offer me suggestions on how to speed up canvas rendering in Cordova? It's pretty darn frustrating that my HTML5 game is finished and I'm ready for publication, only to find out that's not as easy everyone says it is...
      (BTW, I've posted the same question on a few other forums to reach as many game developers as possible.)
    • By janek29
      Hi, I want to present my game called "Stick Bunny" – arrcade game in which you have to help Bunny to go from one platform to another.   Download from here: https://play.google.com/store/apps/details?id=com.threemgames.stickbunny   Youtube video gameplay:             Funny Bunny wants to go from one platform to another. Use stick and help Bunny. Stick can increase the length. Be careful, if the stick is too long Bunny will be knocked and if it is too short Bunny will fall down.   Try to go as far as you can.   Collect carrots and exchane them for new characters of Bunny. Tap the screen to change size of the stick.   Are you ready to reach 100 platforms or mayby you want to go even farther?   So tap the screen, join platforms with sticks, and collect carrots.   It is FREE!   I am waiting for your comments.   Please, give me feedback. If you notice any bugs please tell me.   Thanks !
    • By OfficePassenger
      Dear frends, I would like to try myself as a composer for games, I make unusual music with an unusual mood and atmosphere, I like to work on sounds and details in music, below I attach examples of my works, [deleted by moderator]
  • Advertisement

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!