כלי לניפוי באגים

ניפוי באגים בפרויקט באמצעות הכלי לניפוי באגים ב-Visual Studio (LLDB) בזמן השימוש ברכיב תוסף פיתוח משחקים ל-Android.

הפעלה של הכלי לניפוי באגים

כדי להפעיל את הכלי לניפוי באגים, צריך להיות מסוגל ליצור, לפרוס ולהפעיל המשחק ב-Android. פרטים נוספים זמינים בקטע הפעלת הדוגמה.

אחרי שמוודאים שאפשר להפעיל את המשחק ללא הכלי לניפוי באגים, אפשר להשתמש בכלי לניפוי באגים, מקישים על F5 או בוחרים בפריט התחלת ניפוי באגים. בתפריט ניפוי באגים. תופיע תיבת דו-שיח בזמן שהכלי לניפוי באגים מצרף את הקובץ למשחק.

הפעלת הכלי לניפוי באגים נמשכת בין 10 שניות לדקה אחת או יותר בהתאם לגודל האפליקציה ולכמות הסמלים שצריך לטעינה במהלך ההפעלה. לוקח יותר זמן כשמחברים את המכשיר למכשיר חדש בפעם הראשונה שהכלי לניפוי באגים צריך להוריד כמה ספריות Android למכשיר המארח. אם לוקח יותר מדקה אחת בפעם הראשונה במספר ניסיונות במכשיר חדש, כדאי לבטל את סשן ניפוי הבאגים ולאחר מכן להפעיל אותו מחדש.

כשמריצים את הכלי לניפוי באגים בצורה הזו, המשחק מתחיל במצב בהמתנה למשך במצב ניפוי באגים והוא לא יבצע שום קוד של המשחק עד לניפוי באגים. הפעולה הזו מאפשרת גם לנפות באגים בקטע האתחול של במשחק שלך.

מידע נוסף על תכונות ספציפיות לניפוי באגים ב-Visual Studio זמין מסמכי התיעוד של Visual Studio.

צירוף לתהליך

אם רוצים לנפות באגים במשחק שכבר פועל בחנות פיזית או וירטואלית אפשר לצרף את הכלי לניפוי באגים לתהליך מ-Visual Studio.

ב-Visual Studio, מוודאים שפתרון ל-Android פתוח, וגם:

  1. עוברים לתפריט ניפוי באגים ובוחרים באפשרות צירוף לתהליך....
  2. בתפריט הנפתח Transport, בוחרים באפשרות Android Game Development Extension.
  3. מהתפריט הנפתח מזהה, בוחרים את מכשיר Android שלכם.
  4. צריך לבחור את תהליך המשחק מרשימת התהליכים הזמינים לוחצים על Attach (צירוף).

צירוף לעיבוד

ביצוע פקודות LLDB.Shell

כשיש סשן של ניפוי באגים פעיל, צריך להשתמש בחלון הפקודה של Visual Studio כדי להריץ את הסרטון פקודות LLDB.Shell.

פורמט הפקודה:

LLDB.Shell [command]

דוגמה:

>LLDB.Shell expr myIntVariable = 9
Status:  Success
Output Message:
(int) $2 = 9

התרשים להמחשת הנתונים

מגדירי פורמט

אפשר לשנות את הפורמט שבו ערך מוצג במצב אוטומטי, חלונות מסוג Local, Watch ו-DataTip עם משתנים, משתמשים במזהי פורמטים.

מציינים את הפורמט נמצאים בסוף הביטויים. הן מתחילות בפסיק ואחריה מחרוזת קצרה. לדוגמה, שמציין ,x ב-_myInt,x הביטוי יעצב את myInt כמספר הקסדצימלי קטן.

ניתן להשתמש במזהי פורמטים ישירות בחלון שעון או חלונות של מכוניות, מקומיים ו-DataTip על ידי הוספה שלהם אל Natvis הבעות פנים. למידע נוסף, ראו נטווי.

רשימה של מזהי תמיכה

שם הפורמט מציינים תיאור
בוליאני B מציגים את הערך הזה כערך בוליאני נכון/לא נכון, תוך שימוש בכלל המקובל שלפיו 0 הוא לא נכון וכל השאר נכון
קובץ בינארי b הציגו את זה בתור רצף של ביטים
בינארי, אין 0b מוביל B הצגת רצף ביטים ללא קידומת 0b
בייטים y את הבייטים, אבל מנסים להציג אותם גם כתווי ASCII.
למשל (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
בייטים עם ASCII Y את הבייטים, אבל מנסים להציג אותם גם כתווי ASCII.
למשל (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
תו c מציגים את הבייטים כתווי ASCII
למשל (int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0
תו שניתן להדפסה C מציגים את הבייטים כתווי ASCII ניתנים להדפסה
לדוגמה, (int *) c.sp.x = P.._....
מספר ממשי (float) מורכב F צריך לפרש את הערך הזה בתור החלק האמיתי והדמיוני של מספר מורכב מנקודה צפה (floating-point).
למשל: (int *) c.sp.x = 2.76658e+19 + 4.59163e-41i
עשרוני d, i הצג זאת כמספר שלם חתום (הפעולה לא מבצעת העברה, אלא רק מציגה את הבייטים כמספר שלם עם סימן)
ספירה E,en מציג את הערך כספירה, ומדפיס את שם הערך אם הוא זמין או את הערך המספרי השלם, אחרת
למשל. (enum enumType) val_type = eValue2
הקסדצימלי – אותיות קטנות x, h הצגת הבייטים בסימון הקסדצימלי קטן (הפעולה לא מבצעת העברה, אלא רק מציגה את הבייטים)
הקסדצימלי – אותיות רישיות X, H הצגת הבייטים בסימון הקסדצימלי באותיות רישיות (הפעולה לא מבצעת העברה, אלא רק מציגה את הבייטים בפורמט הקסדצימלי)
הקסדצימלי – אותיות קטנות, ללא 0x בהתחלה xb, hb מציגים את הפעולה בסימון הקסדצימלי קטן ללא קידומת 0x (הפעולה לא מבצעת העברה, היא רק מציגה את הבייטים כהקסדצימליים)
הקסדצימלי – אותיות רישיות, ללא 0x בהתחלה Xb, Hb הצגת הבייטים בסימון הקסדצימלי באותיות רישיות ללא קידומת 0x (הפעולה לא מבצעת העברה, אלא רק מציגה את הבייטים בפורמט הקסדצימלי)
float f מציג זאת כמספר נקודה צפה (floating-point) (לא מבצע העברה, אלא מפרש את הבייטים כערך נקודה צפה של IEEE754)
אוקטלית o מציגים את זה בסימון אוקטלי
סוג מערכת הפעלה O מציגים את הכתובת הזאת בתור MacOS OSType
למשל, (float) x = '\n\x1f\xd7\n'
מחרוזת – C-string s להציג את המחרוזת הזו כמחרוזת C עם 0 סירוגין
למשל: "שלום עולם"
מחרוזת – מחרוזת C, ללא מירכאות sb מציגים את המחרוזת הזו כמחרוזת C עם 0 ללא מירכאות,
למשל: שלום עולם
מחרוזת – UTF-8 s8 יש להציג זאת כמחרוזת UTF-8 עם סיום 0
למשל: u8"hello עולם ☕"
מחרוזת - UTF-8, ללא מירכאות s8b מציגים את המחרוזת הזו כמחרוזת UTF-8 עם סיום 0 ללא מירכאות.
למשל: שלום עולם ☕
מחרוזת – UTF-16 סו יש להציג זאת כמחרוזת UTF-16 עם סיום 0
למשל. u"hello עולם ☕"
מחרוזת - UTF-16, ללא מירכאות משנה מציגים את המחרוזת הזו כמחרוזת UTF-16 עם סיום 0 ללא מירכאות.
למשל, שלום עולם ☕
מחרוזת - UTF-32 s32 יש להציג זאת כמחרוזת UTF-32 עם סיום 0
למשל: 'שלום עולם ☕'
מחרוזת - UTF-32, ללא מירכאות s32b מציגים את המחרוזת הזו כמחרוזת UTF-32 עם סיום 0 ללא מירכאות.
למשל: שלום עולם ☕
unicode16 U צריך להציג את התווים האלה כתווי UTF-16
למשל: (צף) x = 0xd70a 0x411f
unicode32 U32 צריך להציג את התווים האלה כתווי UTF-32
למשל: (float) x = 0x411fd70a
מספר עשרוני לא חתום u הצגת מספר שלם לא חתום (הפעולה לא מבצעת העברה, אלא רק מציגה את הבייטים כמספר שלם לא חתום)
מצביע p להציג את הכתובת הזו כמצביע נייטיב (אלא אם מדובר באמת בסמן, הכתובת שתתקבל כנראה לא תהיה חוקית)
מספר שלם מורכב I צריך לפרש את הערך הזה בתור החלק האמיתי והדמיוני של מספר שלם מרוכב.
לדוגמה, (int *) מצביע = 1048960 + 1i
מערך תווים a מופיעים כמערך תווים.
למשל (char) *c.sp.z = {X}
גולמי ! פורמט גולמי, תוך התעלמות מכל התאמה אישית של תצוגות לפי סוגי נתונים.

נטביס

מסגרת Natvis מאפשרת להתאים אישית את האופן שבו מוצג ב-Visual Studio בחלונות המשתנים של הכלי לניפוי באגים. לדוגמה, אפשר להשתמש ב-Natvis כדי להתאים אישית את התצוגות בחלונות צפייה, מקומיים וטיפים בנושא נתונים.

התכונה Natvis מופעלת כברירת מחדל, אבל אפשר להשבית אותה ב-Visual Studio באמצעות הגדרת התפריט כלים > אפשרויות > תוסף פיתוח משחקים ל-Android > נטוויס סימון למושבת.

קובצי Natvis בטעינה

Visual Studio טוען קובצי Natvis משלושת המיקומים שמפורטים בהמשך, וגם טוען אותן מחדש בכל פעם שמתחילים סשן ניפוי באגים. הקבצים חייבים להתאים ל סכימת Natvis של Visual Studio 2017.

  • .natvis קבצים שהם חלק מפרויקט שנטען או מפריט פתרון ברמה העליונה.
  • הספרייה הספציפית למשתמש (%USERPROFILE%\Documents\Visual Studio 2017\Visualizers)
  • הספרייה ברמת המערכת (%VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers)
קובצי Natvis בטעינה מחדש

לטעון מחדש קובצי Natvis במהלך סשן ניפוי באגים על ידי הערכה של .natvisreload ב חלון פקודות או חלון שעון.

קובץ Natvis לדוגמה

קובץ Natvis לדוגמה הזה כולל את כל התגים והמאפיינים בשלב זה נתמך.

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">

  <Type Name="demo::Vector&lt;*&gt;">
    <AlternativeType Name="MySimilarVectorType&lt;*&gt;"/>

    <!-- Included to show the <SmartPointer> feature is supported. -->
    <SmartPointer Optional="true" Usage="Minimal">ptr</SmartPointer>

    <!-- Included to show the <DisplayString> feature is supported. -->
    <DisplayString Condition="_size == 0" Optional="true">()</DisplayString>
    <DisplayString Condition="_size == 1">(x={_items[0]})</DisplayString>
    <DisplayString Condition="_size == 2">(x={_items[0]}, y={_items[1]})</DisplayString>
    <DisplayString Condition="_size == 3">(x={_items[0]}, y={_items[1]}, z={_items[2]})</DisplayString>
    <DisplayString>[Size={_size,x}] (x={_items[0]}, y={_items[1]}, z={_items[2]}, ...)</DisplayString>

    <!-- Included to show the <StringView> feature is supported. -->
    <StringView Condition="true" Optional="true">_stringViewText</StringView>

    <Expand HideRawView="false">
      <!-- Included to show the <Item> feature is supported. -->
      <Item Name="X" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 1" Optional="true">_items[0]</Item>
      <Item Name="Y" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 2" Optional="true">_items[1]</Item>
      <Item Name="Z" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 3" Optional="true">_items[2]</Item>

      <!-- Included to show the <ArrayItems> feature is supported. -->
      <ArrayItems Condition="_size >= 4" Optional="true">
        <Size Condition="true" Optional="true">_size</Size>
        <ValuePointer Condition="true">_items</ValuePointer>
      </ArrayItems>

      <!-- Included to show the <IndexListItems> feature is supported. -->
      <IndexListItems Condition="true" Optional="true">
        <Size Condition="true" Optional="true">_listSize</Size>
        <ValueNode Condition="true">_list[%i]</ValueNode>
      </IndexListItems>

      <!-- Included to show the <LinkedListItems> feature is supported. -->
      <LinkedListItems Condition="true" Optional="true">
        <Size Optional="true">_listSize</Size>
        <HeadPointer>_head</HeadPointer>
        <NextPointer>_next</NextPointer>
        <ValueNode>_value</ValueNode>
      </LinkedListItems>

      <!-- Included to show the <ExpandedItem> feature is supported. -->
      <ExpandedItem Condition="true" Optional="true">_childVar</ExpandedItem>

      <!-- Included to show the <Synthetic> feature is supported. -->
      <Synthetic Name="[Size]" Condition="true" Optional="true">
        <DisplayString>_size</DisplayString>
        <Expand HideRawView="true">
          <!-- Any supported <Expand> sub-tags. -->
        </Expand>
      </Synthetic>

      <!-- Included to show the <TreeItems> feature is supported. -->
      <TreeItems Condition="true" Optional="true">
        <Size>_treeSize</Size>
        <HeadPointer>_head</HeadPointer>
        <LeftPointer>_left</LeftPointer>
        <RightPointer>_right</RightPointer>
        <ValueNode>_value</ValueNode>
      </TreeItems>

      <!-- Included to show format specifiers are supported. -->
      <Item Name="[Hex Dump at {_index,x}]">myInt[_index],x</Item>
    </Expand>
  </Type>
</AutoVisualizer>

יוצר קובצי Natvis

ב-Visual Studio יש תמיכה ביצירת קובצי Natvis משלכם. אפשר לקבל מידע נוסף על התאמה אישית של חלונות המשתנים של הכלי לניפוי באגים, MSDN.

ניפוי באגים בקובצי Natvis

במקרים מסוימים, שגיאות יוצגו בתור ה-Value של המשתנה (למשל, חלונות אוטומטית, צפייה וכו'). לדוגמה: <error: use of undeclared identifier 'missingVar'>

כדי לגשת לפרטים נוספים על השגיאה, אפשר לפתוח את GoogleAndroid.log מסרגל הכלים של תוסף לפיתוח משחקים ב-Android.

מגבלות ידועות

  • אם התג או המאפיין לא מופיעים בקובץ לדוגמה שלמעלה, הם לא שיש תמיכה כרגע. מערכת Visual Studio מתעלמת מתגים ומאפיינים לא נתמכים, ולכן אפשר להשאיר אותם בקובץ Natvis קיים והקובץ יעבוד, כל עוד הוא משתמש בסכימה שלנו.

  • המאפיין Usage, גם אם נדרש על ידי הסכימה, לא נתמך עבור <SmartPointer>. עם זאת, LLDB לא מגביל את הגישה לאופרטורים מוגדר ב-C++, כך שאפשר להגדיר כל אופרטור נדרש ב-C++ במקום זאת.