PolyTraceAid

From OO Lab
Jump to: navigation, search
This Cartoon is cited from Tech Comic [1]


Contents

Introduction

Welcome to the homepage of PolyTraceAid !!!

PolyTraceAid is an internal program documentation tool developed at
Object-Oriented Technology Lab (OOTL)
Computer Science and Information Engineering
National Central University
ZhongLi, TAIWAN


Programmers:

  • Jhih-Hao Chen [2]
  • YuYing Yu [3](Graduated)

Supervisor: Yung-Pin Cheng [4]


PolyTraceAid is an authoring tool based on the debugging break points.
In practice, a source-level debugger is a powerful tool for program comprehension because using a debugger allows you to see the output of the program, watch the variables and their value changes during the run, and browse the source code at the same time.
We suggest that an internal program document can be composed from several trace cases in PolyTraceAid. A trace case is a sequence of break points which can capture a control flow of a program run, typically designed to run an example which can go through the components which an author wants to explain. A break point in a trace case is called a trace point. Typically, a trace point is placed at a program statement from which an author expects to explain things. At a trace point, an author may link a document of arbitrary forms. Multimedia documents such as PowerPoint slides or voice recordings are particularly recommended for this procedure.

PolyTraceAid document creation guideline

File:HOW TO PREPARE A POLYTRACEAID DOCUMENT.pptx

XYZ UML editor

File:XYZ UML editor source code and specs.rar

The following are examples how to produce low cost screen-casting video clip by Camtasia to easily explain your code.

Media:construct_cone_mesh_xvid_002.avi

How to create an "You are here map !!" easily

Media:making_you_are_here_map_2_xvid.avi

How a trace case is created

Media:PTA_democlip_xvid.avi

Download and Installation

PolyTraceAid is currently implemented as an Addins of Visual Studio. It is still a research prototype that requires a lot of polishing and bug fixes. Many well-known bugs are queued to to be resolved. Please refer to the section Known Bugs for information.


Download

Release version

If you want to use PolytraceAid Tool, please download PTAInstallFile here.

Source version

If you want to develop PolytraceAid, please download source from oolab's gitlab (Make sure you have permission) 

git clone git@140.115.53.53:oolab/polytraceaid.git


Installation

Usage

  1. Download release version
  2. Extract All in the zip file
  3. Find the Visual Studio Data Directory
    • Visual Studio usually create this directory( Named "Visual Studio (version)" ) in C:\Users\user\Documents\
      So the Path may looks like C:\User\USERNAME\Documents\Vusual Studio (version).
    • In the Visual Studio Data Directory, there should be a Directory named Addins. If not, Create The directory Manually.
  4. Copy
    • PolyTraceAid.Addin
    • PolyTraceAid.dll
    to \Visual Studio 2010\Addins\
  5. Installation Complete

Development

  1. Download source version
  2. 設定VSPlugin步驟如同Usage所述
  3. 開啟編輯器修改C:\User\USERNAME\Documents\Vusual Studio (version)\Addins\PolyTraceAid.Addin內容，將<Assembly></Assembly>中的PolyTraceAid.dll路徑改為原始碼目錄底下的Debug/PolyTraceAid.dll
    例如："C:\Users\USERNAME\Documents\Visual Studio 2010\Projects\PolyTraceAid\PolyTraceAid\bin\Debug\PolyTraceAid.dll"
    如此一來就可以除錯被編譯出的dll
  4. 編譯
    • 建置專案並執行(理論上此時應該不會有編譯錯誤的情形，若出現無法寫入dll檔案的錯誤，重開Visual Studio應能解決)此時即可開始繼續進行專案開發。


Installation Problem

If you encounter unknown error with error number 80131515 when launching Visual Studio.

Ptacrash.png

Solve this by right clicking PolyTraceAid.dll and select "property", then click "Unblock" button as below

80131515 1.png

Restart Visual Studio this problem will be solved.


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.


1.png


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.

    2.png

    Select the BST directory and click OK.
    3.png

  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

    4.png

    Type "Inorder Traversal" and Press "OK".
    5.png

  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.png

  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 )

    5.5.png

  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

    7.png


  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:

    8.png

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

  12. Save it.

    10.png

  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.

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.

    11.png
    12.png

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


    10options.png



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


    11hit.png

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


Program Structure

Structure

專案元件簡介

  • Connect - VS Plugin的程式進入點，由此設定與開始啟動VS Plugin。
  • BreakpointListener - 在進入新增修改trace case模式時，會開啟BreakpointListener thread來監督使用者插入break point的事件。
  • Core - 提供PolytraceAid核心功能之API，像是CreateTracecase、SetCurrentTracecase、SaveCurrentTracecase...等等。
  • Player - 啟動播放trace case的功能。
  • Tracecase - 與trace case介面有關的功能。
  • VsEditor - PolytraceAid透過在原始碼中加入特殊註解來記錄該段程式碼的trace case文件路徑，來達成錄製與播放document的功能。利用VsEditor來幫忙插入這些特殊註解或刪除註解。
  • MultimediaFileType - 定義多媒體檔案型態的介面
  • Controller - 內涵 PolyTraceAidController 來控制Core與View的互動
  • View - 內涵PolyTraceAid有關的UI介面

Documents

  1. [PolyTraceAid_trace1.pptx] (SVN連結，請確認有下載權限)
  2. [PolyTraceAid_trace2.pptx] (SVN連結，請確認有下載權限)
  3. [PolyTraceAid_trace3.pptx] (SVN連結，請確認有下載權限)
  4. [PolyTraceAid_trace4.pptx] (SVN連結，請確認有下載權限)


How to create VS Plugin Project

以Visual Studio 2010為例

  1. 開啟Visual Studio 2010
  2. New Project...
  3. 左欄：Other Project Types -> Extensibility，右欄：Visual Studio Add-in，下方名稱欄(Name)填入：PolyTraceAid
  4. Next
  5. Create an Add-in using Visual C# -> Next
  6. Next
  7. What is the name of your Add-in以及What is the description of your Add-in這兩欄可以略過。然後Next
  8. 勾選Yes, create a 'Tools' menu item....
  9. 勾選I would like my Add-in to ....
  10. Next
  11. Would you like to generate settings...可忽略
  12. Next
  13. Finish


Reference

PolytraceAid is a kind of Visual Studio Add-In. And following description is retrieved from from MSDN.

You can extend Visual Studio by using add-ins, VSPackages, and Managed Extensibility Framework (MEF) extensions.
You can use add-ins in Visual Studio without installing the Visual Studio Software Development Kit (SDK).

If want to quick understanding how Add-In work, you can reference website as follow:




We always use the information in EnvDTE namespace to reach our goal in PolytraceAid.

EnvDTE contain a lot of useful information such as we can retrieve and control breakpoints.

See more detail about EnvDTE


Improvements and Problems

Improvements

  • Static point
    • 直接在編輯器上移動滑鼠即可開啟檔案，難度高。
  • Visual Studio SDK
    • 採用visual studio sdk實做PTA
  • Trace Case classification
    • 將trace case 分類
      • 使用手動
      • 使用dissimilarity
  • Trace case Editor setup
    • 在config介面可以設定editor，紀錄trace case 甚至是trace point是哪位editor所寫的
  • Trace Case location change
    • 可以詢問是否要搬動原本位置的trace case，如果要整個搬過去或是複製的話，要進一步處理。

Problems

  • Multimedia file in same folder
    • 一個trace case中相同的檔案不能被加入兩次，因為多媒體檔案放在同一個資料夾，會判斷為已經存在
    • 理想狀況下一個trace case的確不會關聯相同檔案兩次以上
Retrieved from "http://140.115.59.186/wiki/index.php?title=PolyTraceAid&oldid=47107"
Personal tools