Table of Contents

Using the Automation API

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.

Referencing the WinGDB Automation API library.

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.

Accessing WinGDB

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.

Accessing WinGDB properties

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 )

Setting global WinGDB preferences

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 )

Table of Contents


Copyright (C) 2008-2019 SOFT-ERG. All rights reserved.