Jump to content
  • Advertisement
  • Remove ads and support GameDev.net for only $3. Learn more: The New GDNet+: No Ads!

  • 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 MobilityWins
      Game Title: "Time To Marble"
      Hi everyone.
      I'm looking to get together a team to conduct a collaborative project on Unity. I have the ideas and I will be studying the game code, design of levels in every bit of my spare time to get this completed by the end of 2019.
      However if There is an experienced Blender 3d level designer or texture designer I would very much like to have you on the team and discuss the ideas I have come up with so far while also listening to yours.
      If anyone has played the regular Nintendo game called "Marble Madness" That is the original inspiration of my game. 
      The intention is to release this game free, with ads, while providing and ad free version for a small price.
      I am open to speak with anyone on the side just let me know. 
    • By NostalgiaForge
      Hello, I recently release Idle Portal Defense to open beta and am looking for feedback and suggestions before I move toward completing and releasing it.

      Idle Portal Defense is an idle clicker game where the objective is to stop enemies from entering the portal. Purchase upgrades with gold dropped from enemies, gambled, or passive income while offline. Prestige to unlock permanent upgrades. Artifacts can be gambled, mined, rewarded for achievements or acquired by other means and give permanent upgrades as well.
      android beta opt in url:

      or if you would rather try the desktop version (it might be a bit buggier and lacking certain features so I suggest the android one above):
      Warning, progress will probably be cleared when it is released.
    • By Ewe Tek Min
      Shiba's Adventure
      If you are a dog lovers, you must not miss this epic RPG roguelike game that you've never seen. In this turn-based roguelike RPG game, you have to pick your cute favorite dog and dive into the perilous dungeons. Simply move by swiping on your screen when you are exploring the dungeon.
      • You have to avoid all the bad people whom trying to catch you to be their pet because of your cuteness! When you go into deeper dungeon, more bad people will try to catch you, just stay away from them!
      • Besides avoiding those bad people, you also need to keep your stomach full in order to survive through the deep dungeon. Don't forget to ingest some foods while you are crawling the dungeon, otherwise you will be starved to death.
      • Plan your move carefully as every move will cause you energy and you will be perish once your run out your energy.
      • More than 15 kind of adorable and cute dogs to unlock and play! Many more are coming soon!
      • Turn-based gameplay
      • Simply swipe to move your dog 
      • Randomly generated levels provide a different game experience every time!
      • Compete with your friends and see who can survive the dungeon longest!
      Leave your review or feedback to us if you can't find your favorite dogs in the game and we will create for you!
      Download now from App Store: Coming soon
      Download now from Google Play: Coming soon
    • By Alexander Orefkov
      Hi All!
      I present my new game - “Brick Break”. There is old classic puzzle game, moved to 3D, in graphics and gameplay.
      Link to Play Market
      Gameplay video
      Game was created by Urho3D engine.
    • By blapblapdiddlydoodah
      Hey everyone, I'm one of the two developers that makes Meme Exchange, the #1 Meme Stock market app on the Google Play Store and the iOS App Store. We've just set up our project on GameDev.net and thought we'd make a post over here to get some feedback.
      Download Links:
      Google Play Store
      iOS App Store
      Here's what the game is all about:
      Like dank memes? Want to learn how the stockmarket works? Meme Exchange is the #1 meme stock market app on the Play Store.

      Browse all the best dank memes and funny pics on Reddit while you learn to invest.

      Features include:
      - Browse the funniest memes from the most lit subreddits available.
      - Share the best funny pics and meme templates with your friends.
      - Buy and sell shares in a meme for profit.
      - Fund startups for a high risk investing experience
      - Compete on the leaderboard to earn free rewards and badges
      - Earn and buy crypto kek and use it to spice up your profile page and flex on your friends with dank profile icons, borders, customizable text colors and more!
      - Multi-language support: English, Spanish, Portuguese, Italian, German, Swedish, Malaysian.

      This stock market simulator will keep you and your friends entertained for hours, and have you laughing and sharing, all while improving your portfolio and knowledge of markets. Start trading today!

      Thanks for taking the time to check out this thread everyone, and we look forward to hearing your feedback!
      Here's our gamedev.net project page 
        Here's a few screenshots:

  • 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!