Table of Contents
Current version of WinGDB for Mobile Systems supports SDK and NDK-build projects. You can either create a new project, or import an existing one.
In order to create or import a project, choose File/New/Project option from Visual Studio main menu. The following dialog will appear:
You can create a new project in an usual way. Currently the following options are available:
You can also import an existing project. Most Android projects contain a file named AndroidManifest.xml. Projects having native part also contain files named usually Application.mk and Android.mk. WinGDB operates on existing files of these types. No conversion is needed.
However, WinGDB also needs to store small amount of its own metadata, hence it creates a file with .wgaproj extension in addition to files mentioned above. The import step is needed to create this file. It must be performed only once. The resulting WinGDB project file is added to solution. From that time, the project can be used just as any Visual Studio project. The wgaproj file is also serving as a root project file with an unique name and GUID. It is needed by Visual Studio to distinguish between projects in a solution.
There are several options regarding Android project types which can be imported:
When you choose one of the create options and click OK, another dialog will appear asking you for some additional project options.
Here you can select your target platform, enter the Java namespace for your package, the name for APK file and the name of the native module. For example, if you enter "main", the module will be named "libmain.so". For Empty project, you must also set the activity name (defaulting to "NativeActivity" in case of native activity projects). When you click OK, there should be displayed additional window listing all the files that were created. After that, your project is ready for development.
When you choose one of the import options and click OK, a file selection dialog will appear asking you for location of AndroidManifest.xml file or Android.mk file, depending on project type.
In order to debug imported Android projects, You have to manually ensure that Debuggable attribute (Properties/Common/Application page) is enabled. Many projects do not enable this by default.
WinGDB works with manifest and NDK-build project formats directly. That means you can import an AndroidManifest.xml and Android.mk files from any existing project which conforms to rules described in NDK-build documentation. Since *.mk files are in fact makefile snippets, there are many constructs possible which originate in makefile syntax. WinGDB does not support all of them, just those described in NDK-build docs and a few more. Supporting the whole GNU make feature set would be at least very hard (if possible at all) in Visual Studio UI model, hence WinGDB does not even attempt that. It is recommended to use only features allowed by NDK-build documentation. WinGDB always writes files conforming to these rules.
Besides Android.mk, WinGDB also automatically reads any other *.mk file it founds, treating them as descriptions for defined configurations. You can have e.g. one configuration for debug builds, and another for release ones.
In case if your project files are auto-generated by some external tool, editing them in Visual Studio would be undesirable, as the files would be overwritten. Same applies to cases when your files use constructs not supported by WinGDB, but you still want to use its build and debugging services.
For such cases, there is a special write protection feature which allows to mark some or all essential project files (AndroidManifest.xml, Android.mk, Aplication.mk) as read-only. These files will not be overwritten by WinGDB. On the other hand, you will not be able to edit properties from these files in Visual Studio.
You can mark these files at import stage. When the following dialog appears, select one or more files. You can also leave all unselected, which means typical case when entire project is editable in Visual Studio. Files which are not selected here will be under control of Visual Studio and WinGDB.
You can also change it later, using the options on Common/Write protection page of the project properties.
The goal is to support all standard constructs, as described in NDK-build documentation. In current version, most of them are implemented, except:
WinGDB supports project build from Visual Studio. You can view build messages directly in the console, as well as jump into the code in case of compiler errors.
WinGDB uses standard Android build system shipped with SDK and NDK.
The build can consist of the following steps (some may be optional).
When you change the target platform setting (or it differs from the one set in project.properties file), WinGDB executes the update step. This is required by Android build system when the target platform has to be changed.
This step builds native part (if applicable) by means of running Cygwin make on appropriate *.mk file.
WinGDB invokes Ant to build an installable package, including Java classes. This is the last step
The project structure visible in Solution Explorer follows the project model described in the SDK/NDK documentation, with some WinGDB-specific extensions.
On the top level are several kinds of items:
Inside native module you can define folders. They are used pretty much like in standard Visual Studio projects. This is WinGDB extension to NDK project model, implemented on special variables added to Android.mk file. These variables do not affect the build process. WinGDB also defines a default folder for project source files.
To add a new folder, right-click on a module in Solution Explorer and choose Add/New folder option. New folder will be created with default name. You can then rename the folder.
To add a file to a folder, right-click on the folder in Solution Explorer and choose either Add/New item or Add/Existing item.
In the "New item" case, the following dialog will appear allowing you to choose the file type and enter the name of the file:
In the "Existing item" case, standard dialog will appear allowing you to choose an existing file to add. You can add any file to any folder. Only files with extensions *.c, *.cc, *.cxx, *.cpp, *.S and *.s are compiled.
You can also add new Java files to Java folders. As these folders reflect the file system, existing files are added automatically.
You can edit various properties for the entire project, modules and individual files. Right-click on desired item in Solution Explorer and choose the Properties option. A dialog will appear, allowing you to edit the properties.
There are three kinds of properties in NDK project model:
Currently viewed property group can be selected from the list located on the left-hand side of the dialog. Not all groups are available for all items.
WinGDB supports multiple configurations by means of Application.mk files. Each such file is treated as a description of separate configuration. All files with *.mk extension except Android.mk are considered. The name of the file (without extension) becomes the name of the configuration.
You can add an remove configurations using buttons in the Properties dialog. In current beta, the Remove operation is not implemented yet.
This chapter describes how to perform typical development actions on Android projects.
First of all, you should choose the target platform (determining Android system and API versions). Right-click on the project node in Solution Explorer and select the Common tab and General page. There is a setting named Project target. Here you can enter the platform name as defined by the SDK (e.g. "android-12"). Subsequent WinGDB versions will allow to select the platform from the list.
Typically you will debug your application on Android emulator. In such case, you have to set armeabi as one of target ABIs (you can define multiple ones). The setting is located also in the project node properties, in Configuration tab. Other ABIs are intended to be used on physical devices. They might allow faster code execution.
In order to build native and Java modules in the project, choose the Build option. This builds installable package in case of Java and Java+Native projects.
Building release packages is not completely functional in current version. These packages require signing and this step is not implemented.
In case of compilation errors, you can double click in the build console to jump to the error, just as with standard Visual Studio projects.
As WinGDB supports the Prebuilt modules feature of NDK-build, you can add external libraries to package. A prebuilt module is really some kind of link to a library file residing somewhere on disk. You can specify path to that file (relatively to your Android.mk file) setting the Prebuilt module path option in module common properties. The file will be properly added to your package by NDK-build system.
You add a prebuilt module using Add/New item option in context menu of the project. Select either Prebuilt static module or Prebuilt shared module module type from the list.
One of possible applications of that feature is importing libraries built by external build system, like vs-android. You can mix WinGDB and vs-android projects in single solution. There can be single WinGDB project serving as a root of the package (and hosting Java files) and multiple native libraries built by vs-android and imported into the root via prebuilt modules.
You can also use this to import libraries built by Native library project type in WinGDB. This is NDK-build project which does not build any application, only native libraries. Because destination directories contain the target ABI name, TARGET_ARCH_ABI variable is very helpful here to specify the library path, e.g:
Prebuilt modules are not automatically linked to normal modules. If they are supposed to be not loaded dynamically but linked, you can specify them setting Linked shared libraries and Linked static libraries properties.
The Deploy option deploys the package to the device selected on Debug property page on the project node.
Table of Contents