qt creator原始碼全方面分析(2-10-3)
目錄
- Plugin Meta Data
- 主鍵
- 外掛描述鍵
- 依賴
- 可選依賴項
- 測試依賴項
- 命令列引數
- Test.json示例
- 外掛版本說明
Plugin Meta Data
外掛的元資料檔案是一個JSON檔案,包含載入外掛庫所需的所有資訊,決定要載入哪些外掛,以及載入順序(取決於依賴關係)。此外,它包含外掛的作者,外掛的用途,以及在何處可以找到有關外掛的更多資訊。 編譯外掛時,該檔案必須位於include搜尋路徑中,並且必須具有.json副檔名。 JSON檔案將作為元資料編譯到外掛中,然後在載入外掛時由Qt Creator讀取。
主鍵
主鍵用於標識外掛,定義預設載入行為,包括強制鍵Name和Version,和可選鍵CompatVersion,Experimental,DisabledByDefault,Required和Platform。
鍵 | 值型別 | 含義 |
---|---|---|
Name | String | 用作外掛的識別符號,例如在其他外掛的依賴項中進行引用。 |
Version | String | x.y.z_n形式的版本字串,用於標識外掛。 另請參閱本章的"外掛版本說明"小節。 |
CompatVersion | String | 可選項。 如果未給出,則隱式設定為與Version相同的值。 相容性版本說明當前版本能二進位制後向相容的外掛的版本,並用於解決此外掛的依賴關係。 即 Version2.1.1和CompatVersion 2.0.0,意味著外掛的2.1.1版本是二進位制後向相容該外掛的2.1.1~2.0.0的所有版本(含2.0.0)。 |
Experimental | Boolean | 可選項。預設為false。 實驗性外掛預設情況下不會被載入,而必須由使用者顯式使能。應該為可能會對使用者體驗產生負面影響的新外掛使能此屬性。 |
DisabledByDefault | Boolean | 可選項。預設為false。 如果設定了,相應的外掛預設情況下不會被載入,而必須由使用者顯式使能。 應該為預計不會被太多人使用的外掛進行設定,以減少附加資源消耗。 |
HiddenByDefault | Boolean | 可選項。 預設為false。如果設定了,則外掛不會顯示在"關於外掛..."對話方塊的預設檢視中,只有在使用者要求檢視所有外掛時才顯示。 如果有-version命令列引數一起時,它也顯示。 |
Required | Boolean | 可選項。 預設為false。 作為"關於外掛..."對話方塊的提示,提示使用者可能無法手動禁用此外掛。 僅用於Core外掛。 |
Platform | String | 可選項。 正則表示式,匹配執行外掛的平臺名稱。 省略標籤,意味著該外掛可載入在所有平臺上。 |
外掛描述鍵
這些鍵僅用於更詳細(以使用者為中心)的外掛描述。 所有這些都是可選項。
鍵 | 值型別 | 含義 |
---|---|---|
Category | String | 預設為Utilities 。用於在"關於外掛..."對話方塊的外掛概述中,將相關聯的外掛放在同一樹節點下。 |
Vendor | String | 字串,描述外掛建立者/供應商,例如MyCompany。 |
Copyright | String | 簡短的版權宣告,例如(C) 2016 MyCompany 。 |
License | String or array of strings | 關於外掛的可能多行的許可資訊。 由於UI並非為長文字而設計,因此應保持相對簡短。 |
Description | String or array of strings | 對外掛應該提供的內容進行可能多行的描述。 由於UI並非為長文字而設計,因此應保持相對簡短。 |
Url | String | 連結到有關該外掛的更多資訊,例如http://www.mycompany-online.com/products/greatplugin 。 |
依賴
一個外掛可以依賴於其他外掛。 這些是在外掛元資料中指定的,以確保將這些其他外掛在此外掛之前被載入。
依賴項通過Dependency
鍵進行宣告,鍵由JSON物件陣列組成,包含強制鍵Name和Version,以及可選鍵Type。
以下公式說明了依賴項資訊是如何匹配的。 在公式中,被依賴外掛的名稱(與被依賴物件元資料中定義的Name相同)表示為DependencyName
,而被依賴外掛的版本表示為DependencyVersion
。 一個外掛,具有在外掛元資料定義的給定的Name,Version和CompatVersion,具備如下描述,則可成功匹配為依賴項,供其他外掛依賴:
- 它的
Name
匹配DependencyName
, 並且 CompatVersion <= DependencyVersion <= Version
.
例如一個外掛的依賴項為
{
"Name" : "SomeOtherPlugin",
"Version" : "2.3.0_2"
}
則將與如下外掛匹配,可作為上述外掛的依賴
{
"Name" : "SomeOtherPlugin",
"Version" : "3.1.0",
"CompatVersion" : "2.2.0",
...
}
因為名稱匹配,並且依賴項標籤中提供的版本2.3.0_2,是在2.2.0~3.1.0的範圍內。
鍵 | 值型別 | 含義 |
---|---|---|
Dependencies | 依賴物件陣列 | 描述對其他外掛的依賴 |
依賴物件是具有以下鍵的JSON物件:
鍵 | 值型別 | 含義 |
---|---|---|
Name | String | 該外掛所依賴的外掛的名稱。 |
Version | String | 必須相容的用來填充依賴項的被依賴外掛的版本,格式為x.y.z_n。 如果版本無關緊要,則可以為空。 |
Type | String | 可選項。 值為Required , Optional , 或 Test 。 如果依賴項是硬性要求,或者有執行外掛測試的要求,則定義之。 預設為Required 。 |
可選依賴項
外掛可以指定對另一個外掛的依賴關係是可選的,通過向依賴物件新增"Type" : "Optional":
- 如果依賴關係可以被解決,則外掛和它的依賴外掛,將按照Required依賴關係進行載入和初始化。
- 如果依賴關係無法被解決,則只有外掛被載入並初始化,就好像根本沒有宣告依賴關係一樣。
外掛不會以任何方式被通知,是否存在可選依賴外掛。因為依賴外掛可能會被載入,也可能不會,外掛也可能不會連結到該依賴外掛。從可選依賴外掛訪問物件的一種常見方法,是通過ExtensionSystem::PluginManager::getObjectByName() 或ExtensionSystem::PluginManager::getObjectByClassName()從全域性物件池中獲取物件,並在獲取的物件上,呼叫QMetaObject函式。
測試依賴項
當用戶使用-test命令列引數執行應用程式時,僅載入指定的外掛及其依賴外掛。這樣做是為了避免載入不需要的外掛,從而加快測試的執行速度。
通過使用"Type" : "Test"宣告依賴關係,外掛可以指定,要求執行測試功能,而不是執行正常功能的依賴外掛。測試依賴項是強制載入的,並且不影響載入順序。
這種依賴性不傳遞。
命令列引數
外掛可以註冊命令列引數,使用者可以在啟動應用程式時提供的。當用戶使用-help命令列引數執行應用程式時,這些命令列引數將以單行說明的形式顯示,並且外掛管理器會基於該資訊進行命令列解析和完整性檢查。如果外掛管理器為外掛找到匹配的命令列引數,會傳遞給給外掛的initialize()函式。
命令列引數是通過Arguments鍵定義的,該鍵包含一個引數物件陣列。每個單獨的引數物件,都具有強制鍵Name,以及可選鍵Parameter和Description。
鍵 | 值型別 | 含義 |
---|---|---|
Arguments | 引數物件陣列 | 描述外掛想要處理的命令列引數 |
引數物件是具有以下鍵的JSON物件:
鍵 | 值型別 | 含義 |
---|---|---|
Name | String | 命令列引數本身,包含字首符號'-',例如-my-parameter |
Parameter | String | 可選項。 如果指定了此引數,則命令列引數需要一個附加值,例如-my-parameter somevalue。 此屬性的值作為簡短描述,提供給使用者。 |
Description | String | 可選項。引數的(單行)描述,用於命令列引數幫助。 |
Test.json示例
{
"Name" : "Test",
"Version" : "1.0.1",
"CompatVersion" : "1.0.0",
"Vendor" : "My Company",
"Copyright" : "(C) 2016 MyCompany",
"License" : [
"This is a default license bla",
"blubbblubb",
"end of terms"
],
"Category" : "My Company Additions",
"Description" : [
"This plugin is just a test.",
"It demonstrates the great use of the plugin meta data."
],
"Url" : "http://www.mycompany-online.com/products/greatplugin",
"Arguments" : [
{
"Name" : "-variant",
"Parameter" : "fancy|boring",
"Description" : "Brings up the fancy or boring user interface"
}
],
"Dependencies" : [
{ "Name" : "SomeOtherPlugin", "Version" : "2.3.0_2" },
{ "Name" : "EvenOther", "Version" : "1.0.0" }
]
}
外掛版本說明
外掛版本的格式為x.y.z_n,其中x,y,z和n是非負整數。 您不必以完整格式指定版本 - 任何遺漏的部分都將隱式設定為零。 因此,2.10_2等於2.10.0_2,並且1與1.0.0_0相