API ใช้ภารกิจ Ant

วัตถุประสงค์

งานนี้จะรันการค้นหาที่สมบูรณ์ของข้อมูลพื้นฐานที่กำหนดเพื่อสร้างรายงานของการใช้ API

การวิเคราะห์ไม่ได้สอดแทรกบันเดิลที่ไม่มีเครื่องมือแทน

การใช้งาน

คำอธิบาย

ชื่อของภารกิจ Ant คือ: apitooling.apiuse. เมื่อต้องการใช้ ไฟล์ jar apitooling-ant.jar ต้องอยู่บน Ant classpath

<apitooling.apiuse
	location="..."
	scopepattern="..."
	referencepattern="..."
	report="..."
	considerinternal="..."
	considerapi="..."
	considerillegaluse="..."
	apipatterns="..."
	internalpatterns="..."
	archivepatterns="..."
	excludelist="..."
	includelist="..."	
	debug="..."
/>

พารามิเตอร์

แอ็ตทริบิวต์ รายละเอียด จำเป็นต้องมี
location แอ็ตทริบิวต์นี้ระบุตำแหน่งของผลิตภัณฑ์ปัจจุบันที่คุณต้องการค้นหาการใช้งาน API

ซึ่งสามารถเป็นไฟล์ .zip, .jar, .tgz, .tar.gz หรือไดเร็กทอรีที่มีผลิตภัณฑ์หรือชุดของบันเดิล

ตำแหน่งที่ระบุโดยใช้พาธสัมบูรณ์+
ใช่
scopepattern แอ็ตทริบิวต์นี้จะระบุรูปแบบของนิพจน์ทั่วไปที่ใช้เพื่อเลือกว่าบันเดิลใดตำแหน่งที่จะถูกค้นหา

ตัวอย่างเช่น ต่อไปนี้จะสแกนหาเฉพาะการใช้งาน API ในบันเดิล Eclipse:
org.eclipse.*
รูปแบบต้องอยู่ในนิพจน์ปกติที่จัดรูปแบบแล้วตามที่กำหนดไว้ ที่นี่
ไม่ใช่
referencepattern แอ็ตทริบิวต์นี้จะระบุรูปแบบนิพจน์ทั่วไปที่ใช้เพื่อกรองผลลัพธ์ของการค้นหา เฉพาะการใช้งาน API ที่อ้างถึงบันเดิลที่ตรงกับตัวกรองจะถูกรายงาน

ตัวอย่างเช่น ต่อไปนี้จะรายงานเฉพาะการใช้งานที่อ้างถึงโค้ดใน JDT:
org.eclipse.jdt.*
รูปแบบต้องอยู่ในนิพจน์ปกติที่จัดรูปแบบแล้วตามที่กำหนดไว้ ที่นี่
ไม่ใช่
report ตั้งค่าตำแหน่งเอาต์พุตที่รายงานถูกสร้างขึ้น

เมื่อภารกิจเสร็จสิ้นแล้ว รายงานจะพร้อมใช้งานในไดเร็กทอรีนี้โดยใช้โครงสร้างเชิงลำดับชั้น โฟลเดอร์ย่อยถูกสร้างขึ้น สำหรับคอมโพเนนต์ที่มีบันเดิลอื่นๆ ที่อ้างถึง แต่ละโฟลเดอร์ย่อยมีไฟล์ที่เรียกว่า "[bundlename].xml" ภายในโฟลเดอร์นี้ มีโฟลเดอร์ย่อยอื่น (ที่ชื่อ "[referencing bundle name].xml") สำหรับแต่ละบันเดิลที่อ้างถึงบันเดิลที่มีโฟลเดอร์ ภายในการอ้างถึงโฟลเดอร์บันเดิลมีหนึ่งในสามโฟลเดอร์ย่อย (API, PRIVATE หรือ OTHER) ซึ่งมีชนิด เมธอด หรือการอ้างถึงฟิลด์ที่มีชนิดนั้น

ไฟล์พิเศษอื่นสามไฟล์จะถูกเขียนไปยังไดเร็กทอรีรายงาน ซึ่งได้แก่ "counts.xml", "not_searched.xml" และ "no_apidescription.xml" และไฟล์เหล่านี้มีข้อมูลเกี่ยวกับจำนวนของการอ้างถึงที่พบ บันเดิลจากข้อมูลพื้นฐานที่ไม่ค้นหาเพื่อหาข้อมูลการใช้งาน และที่ไม่มีไฟล์ .api_description อยู่ภายใน ตามลำดับ

ตำแหน่งถูกระบุไว้โดยใช้พาธสัมบูรณ์

ตัวอย่างเช่น:
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- bundle name with usage
   		|
   		+--referencing bundle name
   			|
   			+-- [API or PRIVATE or OTHER]
   				|
   				+--[type_ or method_ or field_]references.xml
ใช่
considerinternal หากการอ้างถึงภายในควรถูกพิจารณาในระหว่างการค้นหา

ค่าดีฟอลต์คือ false
ไม่ใช่
considerapi หากการอ้างถึง API ควรถูกพิจารณาในระหว่างการค้นหา

ค่าดีฟอลต์คือ false
ไม่ใช่
considerillegaluse หาก API ที่ผิดกฎเกณฑ์ที่ใช้การอ้างถึงควรถูกพิจารณาในระหว่างการค้นหา

ค่าดีฟอลต์คือ false
ไม่ใช่
apipatterns รายการที่คั่นด้วยเครื่องหมายคอมมาของรูปแบบชื่อแพ็กเกจ (นิพจน์ปกติ) เพื่อพิจารณาเป็นแพ็กเกจ API

ตามค่าดีฟอลต์ของคำอธิบาย API ดีฟอลต์ถูกใช้ในบันเดิลที่สแกนแล้ว แต่สามารถใช้เพื่อ override หรือเพิ่มแพ็กเกจ API
ไม่ใช่
internalpatterns รายการที่คั่นด้วยเครื่องหมายคอมมาของรูปแบบชื่อแพ็กเกจ (นิพจน์ปกติ) เพื่อพิจารณาเป็นแพ็กเกจแบบไพรเวต

ตามค่าดีฟอลต์แล้ว คำอธิบาย API ที่เป็นค่าดีฟอลต์ถูกใช้ในบันเดิลที่สแกนแล้ว แต่สามารถใช้ เพื่อ override หรือเพิ่มแพ็กเกจแบบไพรเวต
ไม่ใช่
archivepatterns รายการที่คั่นด้วยเครื่องหมายคอมมาของตัวระบุไฟล์เก็บถาวรที่ต้องการละเว้นในระหว่างการสแกน

ตัวระบุไฟล์เก็บถาวรมีรูปแบบ: [bundle id]:[path to archive]
ไม่ใช่
excludelist ตั้งค่าการแยกตำแหน่งรายการ

การแยกตำแหน่งรายการจะระบุไฟล์ข้อความที่แสดงรายการบันเดิลที่จะถูกแยกออกจากการวิเคราะห์ โดยดีฟอลต์บันเดิลทั้งหมดในโปรไฟล์จะถูกวิเคราะห์ แอ็ตทริบิวต์รายการที่ถูกรวมและถูกแยกสามารถถูกใช้เพื่อเลือกบันเดิลที่จะรวมหรือแยก รายการที่รวมจะ seed ชุดของบันเดิลที่จะถูกวิเคราะห์ (เมื่อปล่อยไว้บันเดิลทั้งหมดจะถูกรวม) และจากนั้นรายการที่แยกออกจะถูกนำมาใช้ แต่ละบรรทัดของไฟล์จะระบุสิ่งต่อไปนี้:
  • ชื่อบันเดิลที่ระบุ
  • นิพจน์ทั่วไปเพื่อเปรียบเทียบกับชื่อบันเดิล (บรรทัดที่มี "R:")
  • หมายเหตุ (บรรทัดที่มี '#')

ตำแหน่งที่ระบุโดยใช้พาธสัมบูรณ์
ต่อไปนี้เป็นตัวอย่างของรายการที่ถูกแยกออก:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
ไม่ใช่
includelist ตั้งตำแหน่งรานการที่รวม

ตำแหน่งของรายการที่รวมจะระบุไฟล์ข้อความที่แสดงรายการบันเดิลที่จะถูกรวมในการวิเคราะห์ โดยดีฟอลต์บันเดิลทั้งหมดในโปรไฟล์จะถูกวิเคราะห์ แอ็ตทริบิวต์รายการที่ถูกรวมและถูกแยกสามารถถูกใช้เพื่อเลือกบันเดิลที่จะรวมหรือแยก รายการที่รวมจะ seed ชุดของบันเดิลที่จะถูกวิเคราะห์ (เมื่อปล่อยไว้บันเดิลทั้งหมดจะถูกรวม) และจากนั้นรายการที่แยกออกจะถูกนำมาใช้ แต่ละบรรทัดของไฟล์จะระบุสิ่งต่อไปนี้:
  • ชื่อบันเดิลที่ระบุ
  • นิพจน์ทั่วไปเพื่อเปรียบเทียบกับชื่อบันเดิล (บรรทัดที่มี "R:")
  • หมายเหตุ (บรรทัดที่มี '#')

ตำแหน่งที่ระบุโดยใช้พาธสัมบูรณ์
ต่อไปนี้เป็นตัวอย่างของรายการที่ถูกรวม:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
ไม่ใช่
ตัวกรอง ตั้งค่าไดเร็กทอรี root ของตัวกรอง API เพื่อใช้ระหว่าง use scan

อาร์กิวเมนต์เป็นไดเร็กทอรี root ของไฟล์ .api_filters ที่ควรใช้เพื่อกรองการอ้างอิง

ไฟล์ .api_filters จะระบุปัญหาเฉพาะที่ต้องการข้ามระหว่างการวิเคราะห์ api ระหว่าง use scan ตัวกรองปัญหาจะถูกแปลงเป็นรายการของการอ้างถึงที่จะถูกกรองจากผลลัพธ์ของ use scan

root ถูกระบุไว้โดยใช้พาธสัมบูรณ์
root ต้องมีโครงสร้างต่อไปนี้:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
ไม่ใช่
debug ตั้งค่าดีบัก

ค่าที่เป็นไปได้คือ: true, false
ค่าดีฟอลต์คือ false
ไม่ใช่

ตัวอย่าง

	<apitooling.apiuse
		location="/eclipse/eclipse.tar.gz"
		scopepattern=".*"
		referencepattern="org\.eclipse.*"
		report="/eclipse/apiuse-both/XML"
		considerinternal="true"
		considerapi="true"
		considerillegaluse="true"
		archivepatterns="org.eclipse.test.bundle:/libs/contributed.jar"
		excludelist="D:\exclude_list_external.txt"
		debug="true"
	/>

รันภารกิจการสร้างไฟล์ *.xml ภายในโฟลเดอร์ /eclipse/apiuse-both/XML งานจะค้นหาบันเดิลทั้งหมดในตำแหน่งของผลิตภัณฑ์ - ระบุโดยนิพจน์ทั่วไป .* - ค้นหาการอ้างอิงทั้งหมดไปยังบันเดิลใดๆ ที่ตัวบ่งชี้เริ่มต้นด้วย org.eclipse (กำหนดโดยนิพจน์ทั่วไป org\.eclipse.*) ซึ่งจะใช้ไฟล์รายการที่แยกออกที่อยู่ใน D:\exclude_list_external.txt เพื่อลดจำนวนของปัญหาที่จะรายงาน

ขณะที่สแกน ไฟล์คลาสใดๆ ที่พบอยู่ในไฟล์เก็บถาวร /libs/contributed.jar ภายใน org.eclipse.test.bundle จะถูกละเว้น

หากเปิดใช้งานการดีบัก การติดตามการดีบักบางส่วนจะแสดงอยู่ในคอนโซล Ant

การอ้างถึงที่เกี่ยวข้อง

ภารกิจ Ant สำหรับ API Freeze
ภารกิจ Ant สำหรับการสร้างไฟล์
ภารกิจ Ant สำหรับการแปลงรายงานการวิเคราะห์
ภารกิจ Ant สำหรับการแปลงรายงาน API Freeze
ภารกิจ Ant สำหรับการไม่ยอมรับ API
ภารกิจ Ant สำหรับการแปลงรายงานการไม่ยอมรับ API
ภารกิจ Ant สำหรับการแปลงรายงานการใช้ API