ภารกิจ Ant สำหรับการวิเคราะห์ API

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

ภารกิจนี้รันการวิเคราะห์ API ที่สมบูรณ์แล้วของโปรไฟล์ API ที่เกี่ยวข้องกับข้อมูลพื้นฐาน - ซึ่งรวมถึงการใช้ API ความเข้ากันได้แบบไบนารี และการตรวจสอบความถูกต้องของเวอร์ชันบันเดิล โปรไฟล์คือสถานะปัจจุบันของผลิตภัณฑ์ภายใต้การพัฒนา โปรไฟล์ถูกเปรียบเทียบกับ API พื้นฐานสำหรับความเข้ากันได้แบบไบนารี (โดยปกติคือรีลีสก่อนหน้านี้ของผลิตภัณฑ์)

การวิเคราะห์ไม่ได้สอดแทรกการตรวจสอบความถูกต้องของแท็ก @since เช่นเดียวกับการตรวจสอบความถูกต้องทั้งหมดที่ดำเนินการบนไฟล์คลาสแบบไบนารี (ซอร์สไม่ได้ถูกวิเคราะห์)

การใช้งาน

คำอธิบาย

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

<apitooling.analysis
	baseline="..."
	profile="..."
	report="..."
	filters="..."
	excludelist="..."
	includelist="..."
	preferences="..."
	debug="..."
	eefile="..."
/>

พารามิเตอร์

แอ็ตทริบิวต์ รายละเอียด จำเป็นต้องมี
baseline แอ็ตทริบิวต์นี้ระบุตำแหน่งของการอ้างอิงพื้นฐาน

ซึ่งสามารถเป็นไฟล์ .zip, .jar, .tgz, .tar.gz หรือไดเร็กทอรีที่สอดคล้องกับโฟลเดอร์การติดตั้ง Eclipse นี่คือไดเร็กทอรี ที่คุณสามารถค้นหาโปรแกรมเรียกทำงาน Eclipse

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

ซึ่งสามารถเป็นไฟล์ .zip, .jar, .tgz, .tar.gz หรือไดเร็กทอรีที่สอดคล้องกับโฟลเดอร์การติดตั้ง Eclipse นี่คือไดเร็กทอรี ที่คุณสามารถค้นหาโปรแกรมเรียกทำงาน Eclipse

ตำแหน่งที่ระบุโดยใช้พาธสัมบูรณ์
ใช่
report ตั้งค่าตำแหน่งเอาต์พุตที่รายงานถูกสร้างขึ้น

เมื่อภารกิจเสร็จสิ้นแล้ว รายงานจะพร้อมใช้งานอยู่ในไดเร็กทอรีโดยใช้โครงสร้างเดียวกับ root ของตัวกรอง โฟลเดอร์ย่อยถูกสร้างขึ้น สำหรับคอมโพเนนต์แต่ละตัวที่มีปัญหาที่ต้องรายงาน แต่ละโฟลเดอร์ย่อยมีไฟล์ที่เรียกว่า "report.xml"

โฟลเดอร์พิเศษเรียกว่า "allNonApiBundles" ยังถูกสร้างขึ้นในโฟลเดอร์ที่มีไฟล์ที่เรียกว่า "report.xml" ไฟล์นี้จะแสดงรายการบันเดิลทั้งหมดที่ไม่ใช้ลักษณะของเครื่องมือ API

ยังมีไฟล์ "counts.xml" ที่ถูกสร้างในไดเร็กทอรีการรายงานที่มีการสรุปของปัญหาที่พบ

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

อาร์กิวเมนต์เป็นไดเร็กทอรี root ของไฟล์ .api_filters ที่ควรใช้เพื่อกรองปัญหาที่อาจถูกสร้างขึ้นโดยการวิเคราะห์เครื่องมือ API
root ถูกระบุไว้โดยใช้พาธสัมบูรณ์
root ต้องมีโครงสร้างต่อไปนี้:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
ไม่ใช่
excludelist ตั้งค่าการแยกตำแหน่งรายการ

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

ตำแหน่งที่ระบุโดยใช้พาธสัมบูรณ์
ต่อไปนี้เป็นตัวอย่างของรายการที่ถูกแยกออก:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 org.eclipse.platform.doc.isv
 org.eclipse.platform.doc.user
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
ไม่ใช่
includelist ตั้งตำแหน่งรานการที่รวม

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

ตำแหน่งที่ระบุโดยใช้พาธสัมบูรณ์
ต่อไปนี้เป็นตัวอย่างของรายการที่ถูกรวม:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 R:org.eclipse.platform.doc.*
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
ไม่ใช่
preferences ตั้งค่าการกำหนดค่าตามความชอบสำหรับภารกิจ

การกำหนดค่าตามความชอบถูกใช้เพื่อกำหนดระดับความรุนแรงของปัญหา ระดับความรุนแรงของปัญหามีค่าอยู่สามค่า: ละเว้น คำเตือน หรือข้อผิดพลาด ชุดของปัญหาที่ตรวจพบถูกนิยามไว้โดยคีย์การกำหนดค่าตาความชอบสำหรับปัญหาที่สอดคล้งกันในเครื่องมือ API
ตำแหน่งที่ระบุโดยใช้พาธสัมบูรณ์ หากตำแหน่งที่กำหนดไว้ไม่มีอยู่ การกำหนดค่าตามความชอบจะไม่ถูกตั้งค่าไว้
บรรทัดที่ขึ้นต้นด้วย '#' จะถูกละเว้น รูปแบบของไฟล์การกำหนดค่าตามความชอบจะดูคล้ายกับที่แสดงต่อไปนี้:
 #Thu Nov 20 17:35:06 EST 2008
 ANNOTATION_ELEMENT_TYPE_ADDED_METHOD_WITHOUT_DEFAULT_VALUE=Ignore
 ANNOTATION_ELEMENT_TYPE_CHANGED_TYPE_CONVERSION=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_FIELD=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_METHOD=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_TYPE_MEMBER=Warning
 API_COMPONENT_ELEMENT_TYPE_REMOVED_API_TYPE=Ignore
 API_COMPONENT_ELEMENT_TYPE_REMOVED_TYPE=Ignore
 CLASS_ELEMENT_TYPE_ADDED_METHOD=Error
 CLASS_ELEMENT_TYPE_ADDED_RESTRICTIONS=Ignore
 CLASS_ELEMENT_TYPE_ADDED_TYPE_PARAMETER=Ignore
 CLASS_ELEMENT_TYPE_CHANGED_CONTRACTED_SUPERINTERFACES_SET=Ignore
 ...
คีย์สามารถพบได้ใน org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes
ไม่ใช่
debug ตั้งค่าดีบัก

ค่าที่เป็นไปได้คือ: true, false
ค่าดีฟอลต์คือ false
ไม่ใช่
eefile ตั้งค่าไฟล์สภาวะแวดล้อมการเรียกใช้งานเพื่อใช้

ตามค่าดีฟอลต์ ไฟล์สภาวะแวดล้อมการเรียกใช้งานสอดคล้องกับสภาวะแวดล้อมแบบ JavaSE-1.6 ถูกนำมาใช้

รูปแบบของไฟล์ที่กล่าวถึงใน หน้าวิกินี้

ไฟล์ถูกระบุไว้โดยใช้พาธสัมบูรณ์
ไม่ใช่

ตัวอย่าง

	<apitooling.analysis
		baseline="D:\eclipse\3.4.1\eclipse"
		profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"
		report="D:\reports\xml"
		filters="D:\filters"
		excludelist="D:\exclude_list_external.txt"
		preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs"
		debug="true"
	/>

รันภารกิจการสร้างไฟล์ report.xml ภายในโฟลเดอร์ D:\reports\xml ซึ่งจะใช้รายการที่แยกออกและไฟล์ .api_filter ที่วางอยู่ใน D:\exclude_list_external.txt และ D:\filters เพื่อลดจำนวนของปัญหาที่ต้องรายงาน

ระดับความรุนแรงของปัญหาจะถูกสร้างขึ้นตามที่ระบุไว้โดย D:\tests_api\org.eclipse.pde.api.tools.prefs

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

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

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