Latest revision as of 11:43, 14 July 2014

[edit] Tutorial

In this tutorial, we will show how to create documents under PolyTraceAid. In the Zip file you just downloaded, there is a directory called BST (Binary Search Tree). Please start the project by clicking BST.sln. We will use this simple example to explain how to create documents and replay documents by PolyTraceAid.

Once the Addin is properly installed, under Visual Studio/Tools You should see a new features called PolyTraceAid. PolyTraceAid is used to create, manage and replay a trace case.

[edit] Create and Manage Trace case

Here we use the BST project to show how to Create Trace case. Please follow the steps bellow.

1. Open the BST project (BST.sln) by Visual Studio.
2. Startup PolyTraceAid from the tools.
   
3. When we first time startup PolyTraceAid for a project, we have to set the Real root Directory of the project.
   
   
   
   Select the BST directory and click OK.
   
   
   
4. There are no Tracecase for now. Let's create a new trace case called "Inorder Traversal". Press the “new” button and enter “Inorder Traversal” to create
   
   
   
   Type "Inorder Traversal" and Press "OK".
   


5. You can see that a new tracecase “Inorder Traversal” has been created.
   Now, suppose you want to give a brief explanation on the BST example in the beginning of main(). Open the main.cpp of BST project. Click at left of line 11 of main.cpp to create a Tracepoint( breakpoint ), new program comment “<@PTA...>” is added for Tracecase Manager to identify the place of the breakpoint. So, in the future, even your source code is changed, when the trace case is reloaded, the correct break point will always be set to the right position.
   


6. In the Tracecase Manager Window, a new tracepoint “line 11” has been added. A trace point actually functions as a break point during replay. However, a trace point can be attached to a multimedia document later.


7. Now, suppose you want to explain what is an inorder traversal. Let's open BinarySearchTree.cpp and Click at left of line 165 to create another Tracepoint( breakpoint )
   
   


8. So far so good. Now, the inorder traversal trace case has two trace points. It is expected that main.cpp:11 will be hit first and then BinarySearchTree.cpp:165 will be hit next when bst.print_inorder() is called. Now, let's attach/create documents for these trace points. In the Tracecase Manager window, Right Click on line 11 of the tree structure and choose Multimedia->Add File to add Building A Simple BST.pptx
   
   



9. Actually, at this moment, we can also choose to create a new document for the trace point. If the PtaExePaths.xml is set well, PolyTraceAid kindly pops up a tool bar which contains the three recommended file types for you to select. If you want to create a new power point file, simply click the power point icon, click create, and an empty power point slide will be invoked. However, in most of the time, an author does not necessarily follow such procedure and sequence to create documents. Instead, he/she may create documents separately and then attach the documents to the trace points in the last moment. So in this example, we use two power point slides created for this example in PTAFiles.zip.
   
   
10. After clicking on Add File and using a file Selector to select "Building A Simple BST.pptx". It will look like:
    
    


11. Following the similar steps, right Click on Tracepoint "line 165", and then add "Tree Traversal.pptx" to the Tracepoint.


12. Save it.
    
    


13. Now A simple Tracecase has been Created. A trace case folder is created under your BST folder
    
14. Right now, if you want to deactivate PolyTraceAid, you can close Visual Studio or make sure that no Tracecase is selected( --Select a tracecase-- should be in the combo box. )


15. Note: the three buttons to create new documents, WORD, POWERPOINT and SOUND RECODER are currently disabled.However, we can Enable these buttons.
    For example, if we want to enable the "WORD" button, open the file PtaExePaths.xml( contained in the .zip file ) with text editor and edit the Path Attribute with the real path of .exe file of Microsoft Word.
    For example, Change it from
    <PATH Name="DOC" Path="" > </PATH>
    to
    <PATH Name="DOC" Path="C:\Program Files\Microsoft Office\Office14\winword.exe" > </PATH>.
    Save it and copy it to C:\Windows\ and its path will be C:\Windows\PtaExePaths.xml
    Then restart visual studio. The WORD button will be enabled.

[edit] Play Tracecase

We can used PolyTraceAid to replay a trace case. In most of the time, a trace case is supposed to be executed by an example. So the documents should also include the instructions to operate the program between trace points. However, in this simple case, no input to the program is needed. Now let's replay the trace case saved in the previous section.

1. Open the BST project which has been modified in Create and Manage Trace case.


2. Startup PolyTraceAid and Select the tracecase “Inorder Traversal”( created by us). Then click Play Button to play.
   
   
   
   


3. Then we can use Go To Next Tracepoint, Step Over or Step Into to control the debugger.
   
   
   




4. Once the yellow arrow of Debugger hit the Tracepoint( breakpoint ), Tracecase Player will open the mapping document of the Tracepoint
   
   
   


5. Note: We can not click on Option window until the opend document is closed by us.