WinGDB also provides a way to control it "programmatically" through Visual Studio Automation (scripting). This section explains how to configure and use this interface.
Typically you will be using VS Macros to control Visual Studio and write code in Visual Basic. This documentation assumes this kind of environment. If you want to write an add-in or use other .NET language, the procedure will be generally similar.
In order to use WinGDB API in your code, first you need to add a reference to WinGDB assembly. The assembly is located in WinGDB installation directory, for example:
C:\Program Files (x86)\SoftErg\WinGDB\wingdbAutomationAPI.dll
In order to enable Visual Studio Macros to reference this assembly, you must copy it to special directory in the Visual Studio installation. Visual Studio does not use the GAC this time, instead it looks into its own PublicAssemblies subdirectory. Example locations for various Visual Studio versions can be:
C:\Program Files (x86)\Microsoft Visual Studio 8\Common7\IDE\PublicAssemblies C:\Program Files (x86)\Microsoft Visual Studio 9.0\Common7\IDE\PublicAssemblies C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\PublicAssemblies C:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\PublicAssemblies
Copy the file specified above to one or more of these directories. Now you will see the wingdbAutomationAPI assembly in Add Reference dialog in the Macros IDE on your macro project. Add a reference to this library to the project.
It is also recommended to add an import directive to your macro code:
Imports wingdbAutomationAPI
Now you can access WinGDB functionality from your VB macro.
In order to control WinGDB from a macro, you have to obtain a WinGDBEngine object reference first:
Public Sub Main() Dim hEngine As WinGDBEngine = New WinGDBEngine ( DTE ) ' .....
The engine object takes a reference to Visual Studio API root object (DTE). Since there might occur an error condition (e.g. you do not have WinGDB installed), it is recommended to check for errors with this call:
Dim bValid As Boolean = hEngine.isValid()
Now, if bValid is true, there is no error and you can use the engine object. Otherwise, signal some error and quit.
The engine itself has many methods triggering various WinGDB actions. The list of methods for version 3.1 is included below. Names of the methods and their arguments are self-explanatory. Methods which return String, pass error message in the return value. If returned string is equal to "OK", the method call has succeeded. Otherwise, an error message will be returned.
Public Function isValid() As Boolean Public Function getPreferences() As WinGDBPreferences Public Function getSolutionProperties() As WinGDBProperties Public Function getProjectProperties ( ByVal projectName As String ) As WinGDBProperties Public Function generateProjectMakefile ( ByVal projectName As String ) As String Public Function transferSolutionToRemote() As String Public Function transferProjectToRemote ( ByVal projectName As String ) As String Public Function transferSolutionFromRemote() As String Public Function transferProjectFromRemote ( ByVal projectName As String ) As String Public Function buildSolution ( Optional bWait As Boolean = True ) As String Public Function rebuildSolution ( Optional bWait As Boolean = True ) As String Public Function cleanSolution ( Optional bWait As Boolean = True ) As String Public Function deploySolution ( Optional bWait As Boolean = True ) As String Public Function buildProject ( ByVal projectName As String, Optional bWait As Boolean = True ) As String Public Function rebuildProject ( ByVal projectName As String, Optional bWait As Boolean = True ) As String Public Function cleanProject ( ByVal projectName As String, Optional bWait As Boolean = True ) As String Public Function deployProject ( ByVal projectName As String, Optional bWait As Boolean = True ) As String Public Function isBuildRunning() As Boolean Public Function hasLastBuildSucceeded() As Boolean Public Function createSynchronizedMapping ( _ ByVal loginString As String, _ ByVal localDir As String, _ ByVal remoteDir As String ) As String Public Function createSharedMapping ( _ ByVal loginString As String, _ ByVal localDir As String, _ ByVal remoteDir As String ) As String Public Function deleteAllMappings() As String Public Function openSessionsForMappings() As String Public Function closeAllSessions() As String Public Function executeRemoteCommand ( _ ByVal loginString As String, _ ByVal command As String, _ ByVal directory As String ) As String Public Function setCurrentConfiguration ( ByVal name As String ) As String Public Function setCurrentPlatform ( ByVal name As String ) As String Public Function setCurrentSystem ( ByVal name As String ) As String
There are a few more methods than listed above, those remaining ones are the more advaced or internal ones and it is not recommended to use them directly.
You can also alter WinGDB properties for a project or the solution using WinGDBProperties object returned by getProjectProperties and getSolutionProperties methods of WinGDBEngine. The solution or specified project must be loaded in Visual Studio, otherwise an error will occur. You can open a solution with DTE.Solution.Open standard API. The methods and relevant types of WinGDBProperties are as follows:
Enum ETargetType TARGET_REMOTE_LINUX = 0 TARGET_INDIRECT_LINUX = 1 TARGET_LOCAL_WINDOWS = 2 TARGET_EMBEDDED_LINUX = 3 TARGET_EMBEDDED_DEVICE = 4 End Enum Public Function setTargetType ( value As ETargetType ) As String Public Function setDebugHostLogin ( value As String ) As String Public Function setBuildHostLogin ( value As String ) As String Public Function setDebugTargetLogin ( value As String ) As String Public Function setDebuggerPath ( value As String ) As String Public Function setToolchainPaths ( value As String ) As String Public Function setLaunchArguments ( value As String ) As String Public Function setLaunchEnvironment ( value As String ) As String Public Function setTarget ( value As String ) As String Public Function setAdditionalDebuggerOptions ( value As String ) As String Public Function setSourceDirectories ( value As String ) As String Public Function setDebugInfoDirectory ( value As String ) As String Public Function setSysrootOnHost ( value As String ) As String Public Function setSysrootOnTarget ( value As String ) As String Public Function setSharedLibraryDirectories ( value As String ) As String Public Function setExecutable ( value As String ) As String Public Function setWorkingDirectory ( value As String ) As String Public Function setCore ( value As String ) As String Public Function setMainFunctionName ( value As String ) As String Public Function setVisualizerProfile ( value As String ) As String Enum EByteOrder BIG_ENDIAN = 0 LITTLE_ENDIAN = 1 End Enum Public Function setPropertyByteOrder ( value As EByteOrder ) As String Public Function setStopInMain ( value As Boolean ) As String Public Function setSourceSession ( value As Boolean ) As String Public Function setDisableHangReporter ( value As Boolean ) As String Public Function setForwardX11ForDebugging ( value As Boolean ) As String Public Function setLaunchDebuggerInSudo ( value As Boolean ) As String Public Function setPid ( value As Integer ) As String Public Function setSyncCommandTimeout ( value As Integer ) As String Public Function setRemoteBuildCommand ( value As String ) As String Public Function setRemoteSolutionBuildCommand ( value As String ) As String Public Function setRemoteRebuildCommand ( value As String ) As String Public Function setRemoteSolutionRebuildCommand ( value As String ) As String Public Function setRemoteCleanCommand ( value As String ) As String Public Function setRemoteSolutionCleanCommand ( value As String ) As String Public Function setRemoteDeployCommand ( value As String ) As String Public Function setRemoteSolutionDeployCommand ( value As String ) As String Public Function setRemoteBuildDirectory ( value As String ) As String Public Function setRemoteBuildVariables ( value As String ) As String Public Function setRemoteSolutionBuildDirectory ( value As String ) As String Public Function setRemoteSolutionBuildVariables ( value As String ) As String Public Function setReuseStandardBuildCommand ( value As Boolean ) As String Public Function setDeployBeforeStartDebugging ( value As Boolean ) As String Enum EBuildBeforeStartDebugging BUILD_PROJECT = 0 BUILD_SOLUTION = 1 BUILD_NONE = 2 End Enum Public Function setBuildBeforeStartDebugging ( value As EBuildBeforeStartDebugging ) As String Enum EProjectBuildAction RUN_BUILD_COMMANDS = 0 RUN_STANDARD_VS_BUILD = 1 End Enum Public Function setProjectBuildAction ( value As EProjectBuildAction ) As String Enum ERemoteSolutionBuildMode BUILD_ALL_PROJECTS = 0 INVOKE_SOLUTION_BUILD_COMMAND = 1 End Enum Public Function setRemoteSolutionBuildMode ( value As ERemoteSolutionBuildMode ) As String Public Function setCustomPreLoadInitScript ( value As String ) As String Public Function setCustomPostLoadInitScript ( value As String ) As String Public Function setCustomCondPreLoadInitScript ( value As String ) As String Public Function setCustomCondPostLoadInitScript ( value As String ) As String Public Function setServerAutoLaunch ( value As Boolean ) As String Public Function setServerUseSysroot ( value As Boolean ) As String Public Function setServerPortIsForwarded ( value As Boolean ) As String Public Function setDynamicLinker ( value As String ) As String Public Function setServerLibraryPaths ( value As String ) As String Public Function setServerPath ( value As String ) As String Public Function setExecutableOnTarget ( value As String ) As String Public Function setLoadProgramPath ( value As String ) As String Public Function setServerPort ( value As Integer ) As String Public Function setForwardedServerPort ( value As Integer ) As String Public Function setPidOnTarget ( value As Integer ) As String Enum EServerMode GDBSERVER_LAUNCH = 0 GDBSERVER_ATTACH = 1 GDBSERVER_MULTI = 2 End Enum Public Function setServerMode ( value As EServerMode ) As String Enum ELoadProgram LOAD_NEVER = 0 LOAD_ALWAYS = 1 LOAD_IF_CHANGED = 2 End Enum Public Function setLoadProgram ( value As ELoadProgram ) As String Enum EDeployAction DEPLOY_RUN_COMMAND = 0 DEPLOY_TRANSFER_FILE = 1 End Enum Public Function setDeployAction ( value As EDeployAction ) As String Public Function setSolutionDeployAction ( value As EDeployAction ) As String Public Function setDeployOnlyIfFileChanged ( value As Boolean ) As String Public Function setSolutionDeployOnlyIfFileChanged ( value As Boolean ) As String Public Function setDeployFile ( value As String ) As String Public Function setDeployTargetDirectory ( value As String ) As String Public Function setSolutionDeployFile ( value As String ) As String Public Function setSolutionDeployTargetDirectory ( value As String ) As String Enum EMakefileGeneratorMode MAKEFILE_GENERATE = 0 MAKEFILE_UPDATE = 1 End Enum Public Function setMakefileGeneratorMode ( value As EMakefileGeneratorMode ) As String Public Function setMakefileName ( value As String ) As String Public Function setMakefileCompilerC ( value As String ) As String Public Function setMakefileCompilerCXX ( value As String ) As String Public Function setMakefileAR ( value As String ) As String Public Function setMakefileRM ( value As String ) As String Public Function setMakefileMKDIR ( value As String ) As String Public Function setMakefileCFLAGS ( value As String ) As String Public Function setMakefileCXXFLAGS ( value As String ) As String Public Function setMakefileLDFLAGS ( value As String ) As String Public Function setMakefileIntDir ( value As String ) As String Public Function setMakefileDestDir ( value As String ) As String Public Function exportProperties ( ByVal filePath As String ) As String Public Function exportPersistentProperties ( ByVal filePath As String ) As String Public Function importProperties ( ByVal filePath As String ) As String Public Function importPersistentProperties ( ByVal filePath As String ) As String
You can also set properties with a set of raw methods. You need to know an internal property name, however. These names can be seen in XML files generated by the Export properties option. They are internal and can be subject to change in subsequent releases. Therefore it is not recommended to use them, unless there is some property not covered by the specific API described above.
Public Sub setStringProperty ( _ ByVal propertyName As String, _ ByVal propertyValue As String ) Public Sub setIntProperty ( _ ByVal propertyName As String, _ ByVal propertyValue As Integer ) Public Sub setBooleanProperty ( _ ByVal propertyName As String, _ ByVal propertyValue As Boolean )
You can also set some global preferences using the automation API. To access the preferences object, call the followng method:
Dim prefs As WinGDBPreferences = hEngine.getPreferences()
The preferences container has several methods corresponding to most commonly used settings.
Public Sub setDefaultDebuggerPath ( ByVal path As String ) Public Sub setDefaultToolchainPath ( ByVal path As String ) Public Sub setCygwinRootPath ( ByVal path As String ) Public Sub setXmingInstallPath ( ByVal path As String ) Public Sub setUseCygwin ( ByVal value As Boolean ) Public Sub setEnableSessionLogging ( ByVal value As Boolean ) Public Sub setSessionLogFilePath ( ByVal path As String ) Public Sub setAlwaysUseSSHAgent ( ByVal value As Boolean ) Public Sub setAlwaysUseSCP ( ByVal value As Boolean ) Public Sub setLimitSCPPacketSize ( ByVal value As Boolean ) Public Sub setTCPKeepAlivePeriod ( ByVal value As Integer )