儲存區字元

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6
存放區規則的內容，包含輔助函式和屬性相關資訊。建立存放區規則時，您會取得 repository_ctx 物件做為 implementation 函式的引數。

成員

attr

struct repository_ctx.attr

用來存取屬性值的結構體。這些值由使用者提供 (如未提供，則會使用預設值)。

delete

bool repository_ctx.delete(path)

刪除檔案或目錄。傳回布林值，指出檔案或目錄是否確實已透過這個呼叫刪除。

參數

參數 說明
path string 或 path；必要
要刪除的檔案路徑，相對於儲存庫目錄或絕對路徑。可以是路徑或字串。

下載

unknown repository_ctx.download(url, output='', sha256='', executable=False, allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', block=True)

將檔案下載至提供的網址輸出路徑，並傳回包含 success 的結構體，如果下載成功，則為 true 標記，如果成功，則為檔案的雜湊，其中包含 sha256 和 integrity 欄位。如果使用者指定 sha256 或 integrity，強烈建議您設定明確的 canonical_id，例如 get_default_canonical_id。

參數

參數 說明
url string；或 string 的可迭代項目；必要
列出參照相同檔案的鏡像網址。
output string；或 Label；或 path；預設為 ''
輸出檔案的路徑，相對於存放區目錄。
sha256 string；預設值為 ''
下載檔案的預期 SHA-256 雜湊值。這必須與下載的檔案的 SHA-256 雜湊相符。由於遠端檔案可能會變更，因此省略 SHA-256 會造成安全性風險。即使您省略這個欄位，建構作業仍會變得不完整。您可以選擇是否要設定這個值，以利開發作業，但應在發布前設定。如果提供，系統會先檢查儲存庫快取是否有指定雜湊的檔案；如果在快取中找不到檔案，系統才會嘗試下載。下載成功後，檔案就會加入快取。
executable bool；預設為 False
在建立的檔案上設定可執行旗標，預設為 false。
allow_fail bool；預設值為 False
如果已設定，請在傳回值中指出錯誤，而非針對下載失敗提出錯誤。
canonical_id string；預設為 ''
如果設定此屬性，快取命中就會限制在檔案以相同的標準 ID 新增至快取的情況。根據預設，快取會使用總和檢查碼 (sha256 或 integrity)。
auth dict；預設為 {}
可選的 dict，可指定部分網址的驗證資訊。
headers dict；預設為 {}
可選的 dict，指定所有網址的 HTTP 標頭。
integrity string；預設值為 ''
下載檔案的預期總和檢查碼，以子資源完整性格式表示。此值必須與下載的檔案檢查和總和相符。由於遠端檔案可能會變更，因此省略總和檢查碼會造成安全風險。即使您省略這個欄位，建構作業仍會變得不完整。您可以選擇是否要設定這個值，以利開發作業，但應在發布前設定。如果提供，系統會先檢查存放區快取是否有指定總和檢查碼的檔案；如果在快取中找不到檔案，系統才會嘗試下載。下載成功後，檔案就會加入快取。
block bool；預設為 True
如果設為 false，呼叫會立即傳回，並傳回一個代碼，其中包含單一方法 wait()，會在下載完成後阻斷，並傳回一般傳回值或擲回。

download_and_extract

struct repository_ctx.download_and_extract(url, output='', sha256='', type='', strip_prefix='', allow_fail=False, canonical_id='', auth={}, headers={}, *, integrity='', rename_files={})

將檔案下載至提供的網址輸出路徑，並擷取該檔案，然後傳回包含 success 的結構體，如果下載成功，則會傳回 true 標記，如果成功，則會傳回檔案的雜湊，其中包含 sha256 和 integrity 欄位。如果使用者指定 sha256 或 integrity，強烈建議您設定明確的 canonical_id，例如 get_default_canonical_id

參數

參數 說明
url string；或 string 的可迭代項目；必要
列出參照相同檔案的鏡像網址
output string；或 Label；或 path；預設為 ''
相對於存放區目錄的封存檔案解開目錄路徑。
sha256 string；預設值為 ''
下載檔案的預期 SHA-256 雜湊值。這必須與下載的檔案的 SHA-256 雜湊相符。由於遠端檔案可能會變更，因此省略 SHA-256 會造成安全性風險。即使您省略這個欄位，建構作業仍會變得不完整。您可以選擇是否要設定這個值，以利開發作業，但應在發布前設定。如果提供，系統會先檢查儲存庫快取是否有指定雜湊的檔案；如果在快取中找不到檔案，系統才會嘗試下載。下載成功後，檔案就會加入快取。
type string；預設為 ''
下載檔案的封存類型。根據預設，系統會根據網址的副檔名判斷封存檔案類型。如果檔案沒有副檔名，您可以在這裡明確指定「zip」、「jar」、「war」、「aar」、「nupkg」、「whl」、「tar」、「tar.gz」、「tgz」、「tar.xz」、「txz」、「.tar.zst」、「.tzst」、「tar.bz2」、「.tbz」、「.ar」或「.deb」。
strip_prefix string；預設為 ''
從解壓縮的檔案中移除的目錄前置字串。許多封存檔都包含頂層目錄，內含封存檔中的所有檔案。您不必在 build_file 中不斷指定這個前置字串，而是可以使用這個欄位從擷取的檔案中移除前置字串。

為求相容性，這個參數也可能以已淘汰的名稱 stripPrefix 使用。

allow_fail bool；預設值為 False
如果已設定，請在傳回值中指出錯誤，而非針對下載失敗提出錯誤。
canonical_id string；預設為 ''
如果設定此屬性，快取命中就會限制在檔案以相同的標準 ID 新增至快取的情況。根據預設，快取會使用總和檢查碼 (sha256 或 integrity)。
auth dict；預設為 {}
可選的 dict，可指定部分網址的驗證資訊。
headers dict；預設為 {}
可選的 dict，指定所有網址的 HTTP 標頭。
integrity string；預設值為 ''
下載檔案的預期總和檢查碼，以子資源完整性格式表示。此值必須與下載的檔案檢查和總和相符。由於遠端檔案可能會變更，因此省略總和檢查碼會造成安全風險。即使您省略這個欄位，建構作業仍會變得不完整。您可以選擇是否要設定這個值，以利開發作業，但應在發布前設定。如果提供，系統會先檢查存放區快取是否有指定總和檢查碼的檔案；如果在快取中找不到檔案，系統才會嘗試下載。下載成功後，檔案就會加入快取。
rename_files dict；預設為 {}
可選的 dict，指定在擷取期間要重新命名的檔案。在任何目錄前置字串調整之前，名稱與鍵完全相符的封存項目會改為該值。這可用於解壓縮包含非 Unicode 檔案名稱的封存檔，或在大小寫不敏感的檔案系統中，將檔案解壓縮至相同路徑。

execute

exec_result repository_ctx.execute(arguments, timeout=600, environment={}, quiet=True, working_directory="")

執行引數清單指定的指令。指令的執行時間受 timeout 限制 (以秒為單位，預設為 600 秒)。這個方法會傳回包含指令輸出的 exec_result 結構。environment 對應項目可用於覆寫要傳遞至程序的部分環境變數。

參數

參數 說明
arguments sequence；必要
引數清單，第一個元素應為要執行的程式路徑。
timeout int；預設值為 600
指令的最大時間長度 (以秒為單位)，預設為 600 秒。
environment dict；預設為 {}
強制設定部分環境變數，以便傳遞至程序。值可以是 None，用於移除環境變數。
quiet bool；預設值為 True
如果要將 stdout 和 stderr 列印到終端機。
working_directory string；預設值為 ""
指令執行作業目錄。可以是相對於存放區根目錄的相對路徑，也可以是絕對路徑。預設為存放區根目錄。

extract

None repository_ctx.extract(archive, output='', strip_prefix='', *, rename_files={}, watch_archive='auto')

將封存檔解壓縮至存放區目錄。

參數

參數 說明
archive string；或 Label；或 path；必要
相對於存放區目錄的封存檔案路徑。
output string；或 Label；或 path；預設為 ''
相對於存放區目錄的路徑，指向封存檔案解壓縮的目錄。
strip_prefix string；預設為 ''
從解壓縮的檔案中移除的目錄前置字串。許多封存檔都包含頂層目錄，內含封存檔中的所有檔案。您不必在 build_file 中不斷指定這個前置字串，而是可以使用這個欄位從擷取的檔案中移除前置字串。

為求相容性，這個參數也可能以已淘汰的名稱 stripPrefix 使用。

rename_files dict；預設為 {}
可選的 dict，指定在擷取期間要重新命名的檔案。在任何目錄前置字串調整之前，名稱與鍵完全相符的封存項目會改為該值。這可用於解壓縮包含非 Unicode 檔案名稱的封存檔，或在大小寫不敏感的檔案系統中，將檔案解壓縮至相同路徑。
watch_archive string；預設值為 'auto'
表示是否要監控封存檔案。可以是 'yes'、'no' 或 'auto' 字串。傳遞 'yes' 等同於立即叫用 watch() 方法；傳遞 'no' 則不會嘗試監控檔案；傳遞 'auto' 只會在合法情況下嘗試監控檔案 (詳情請參閱 watch() 文件)。

file

None repository_ctx.file(path, content='', executable=True, legacy_utf8=False)

在存放區目錄中產生含有指定內容的檔案。

參數

參數 說明
path string；或 Label；或 path；必要
相對於存放區目錄的要建立的檔案路徑。
content string；預設為 ''
要建立的檔案內容，預設為空白。
executable bool；預設為 True
在建立的檔案上設定可執行的標記，預設為 true。
legacy_utf8 bool；預設值為 False
無操作。此參數已淘汰，並會在日後的 Bazel 版本中移除。

getenv

string repository_ctx.getenv(name, default=None)

如果環境變數 name 存在，則以字串形式傳回該變數的值；如果不存在，則傳回 default。

以累加方式建構時，如果變數 name 的值有任何變更，系統就會重新擷取這個存放區。

參數

參數 說明
name string；必要
所需環境變數的名稱。
default string 或 None；預設值為 None
如果找不到 name，則傳回預設值。
可能會傳回 None。

name

string repository_ctx.name

這項規則建立的外部存放區標準名稱。這個名稱保證在所有外部存放區中都是唯一的，但確切格式未指定。請改用 original_name 取得最初指定為 name 的名稱，因為這個存放區規則已例項化。

original_name

string repository_ctx.original_name

這個存放區規則例項化時，原始指定為 name 屬性的名稱。這個名稱在外部存放區中不一定會是唯一的。請改用 name 取得外部存放區的正規名稱。

os

repository_os repository_ctx.os

用來存取系統資訊的結構體。

patch

None repository_ctx.patch(patch_file, strip=0, *, watch_patch='auto')

將修補檔案套用至外部存放區的根目錄。修補檔案應為標準的 unified diff format 檔案。Bazel 原生修補程式實作項目不支援模糊比對和二進位修補程式，這類功能可透過修補指令列工具執行。

參數

參數 說明
patch_file string；或 Label；或 path；必要
要套用的修補檔案，可以是標籤、相對路徑或絕對路徑。如果是相對路徑，則會解析為存放區目錄。
strip int；預設值為 0
從檔案名稱中移除指定數量的前置元件。
watch_patch string；預設值為 'auto'
表示是否要監控修補檔案。可以是 'yes'、'no' 或 'auto' 字串。傳遞 'yes' 等同於立即叫用 watch() 方法；傳遞 'no' 則不會嘗試監控檔案；傳遞 'auto' 只會在合法情況下嘗試監控檔案 (詳情請參閱 watch() 文件)。

path

path repository_ctx.path(path)

傳回字串、標籤或路徑的路徑。如果路徑為相對路徑，則會相對於存放區目錄解析。如果路徑是標籤，則會解析為對應檔案的路徑。請注意，遠端存放區會在分析階段執行，因此無法依賴目標結果 (標籤應指向未產生的檔案)。如果路徑是路徑，則會原封不動地傳回該路徑。

參數

參數 說明
path string；或 Label；或 path；必要
string、Label 或 path，用於建立路徑。

讀取

string repository_ctx.read(path, *, watch='auto')

Reads the content of a file on the filesystem.

參數

參數 說明
path string；或 Label；或 path；必要
要讀取的檔案路徑。
watch string；預設值為 'auto'
表示是否要監控檔案。可以是 'yes'、'no' 或 'auto' 字串。傳遞 'yes' 等同於立即叫用 watch() 方法；傳遞 'no' 則不會嘗試監控檔案；傳遞 'auto' 只會在合法情況下嘗試監控檔案 (詳情請參閱 watch() 文件)。

rename

None repository_ctx.rename(src, dst)

將檔案或目錄從 src 重新命名為 dst。系統會視需要建立父項目錄。如果目的地路徑已存在，就會失敗。兩個路徑都必須位於存放區內。

參數

參數 說明
src string；或 Label；或 path；必要
要重新命名的現有檔案或目錄路徑，相對於存放區目錄。
dst string；或 Label；或 path；必要
相對於存放區目錄，檔案或目錄的新名稱。

repo_metadata

repo_metadata repository_ctx.repo_metadata(reproducible=False, attrs_for_reproducibility={})

建構可從 repo 規則的實作函式傳回的不透明物件，以提供有關其可重現性的中繼資料。

參數

參數 說明
reproducible bool; default is False
States that this repo can be reproducibly refetched; that is, if it were fetched another time with exactly the same input attributes, repo rule definition, watched files and environment variables, etc., then exactly the same output would be produced. 即使其他未追蹤的條件發生變化，例如網際網路資訊、工作區根目錄路徑、執行任意可執行檔的輸出內容等，這項屬性仍須成立。如果設為 True，系統就能在工作區之間快取擷取的存放區內容。

請注意，將此值設為 True 並不保證會在存放區內容快取中快取；舉例來說，系統一律不會快取本機存放區規則。

attrs_for_reproducibility dict；預設為 {}
如果 reproducible 為 False，則可指定此屬性，告知 Bazel 要變更原始 repo 規則的哪些屬性，才能重現。

report_progress

None repository_ctx.report_progress(status='')

更新擷取這個存放區或模組擴充功能的進度狀態。

參數

參數 說明
status string；預設值為 ''
string 會描述擷取進度的目前狀態。		 

None repository_ctx.symlink(target, link_name)

在檔案系統上建立符號連結。

參數

參數 說明
target string；或 Label；或 path；必要
符號連結應指向的路徑。
string；或 Label；或 path；必要
要建立的符號連結路徑。

template

None repository_ctx.template(path, template, substitutions={}, executable=True, *, watch_template='auto')

使用 template 生成新檔案。template 中出現的每個 substitutions 鍵都會替換為對應的值。結果會寫入 path。您可以設定選用的 executable 引數 (預設為 true)，開啟或關閉可執行位元。

參數

參數 說明
path string；或 Label；或 path；必要
相對於存放區目錄的要建立的檔案路徑。
template string；或 Label；或 path；必要
範本檔案的路徑。
substitutions dict；預設為 {}
展開範本時要進行的替換作業。
executable bool；預設為 True
在建立的檔案上設定可執行的標記，預設為 true。
watch_template string；預設值為 'auto'
表示是否要監控範本檔案。可以是 'yes'、'no' 或 'auto' 字串。傳遞 'yes' 等同於立即叫用 watch() 方法；傳遞 'no' 則不會嘗試監控檔案；傳遞 'auto' 只會在合法情況下嘗試監控檔案 (詳情請參閱 watch() 文件)。

watch

None repository_ctx.watch(path)

告知 Bazel 監控指定路徑的變更，無論該路徑是否存在，或是檔案或目錄。如果檔案或目錄有任何變更，這個存放區或模組擴充功能就會失效，下次系統會重新擷取或評估。

「變更」包括檔案內容的變更 (如果路徑是檔案)；如果路徑原本是檔案但現在是目錄，或反之；以及路徑是否開始或停止存在。值得注意的是，如果路徑為目錄，則系統「不會」納入目錄下任何檔案的變更。請改用 path.readdir()。

請注意，嘗試監看目前正在擷取的存放區內路徑，或目前模組擴充功能的運作目錄內路徑，都會導致錯誤。如果模組擴充功能嘗試監看目前 Bazel 工作區以外的路徑，也會導致錯誤。

參數

參數 說明
path string；或 Label；或 path；必要
要監控的檔案路徑。

watch_tree

None repository_ctx.watch_tree(path)

指示 Bazel 監控指定路徑下任何檔案或目錄的變更。如果檔案內容、檔案或目錄是否存在、檔案名稱或目錄名稱有任何變更，系統就會重新擷取這個存放區。

請注意，如果嘗試監看目前正在擷取的存放區內的路徑，系統會傳回錯誤。

參數

參數 說明
path string；或 Label；或 path；必要
要監控的目錄樹狀結構路徑。

which

path repository_ctx.which(program)

傳回對應程式的 path，如果路徑中沒有這類程式，則傳回 None。

參數

參數 說明
program string；必要
要在路徑中尋找的程式。
可能會傳回 None。

workspace_root

path repository_ctx.workspace_root

Bazel 叫用根工作區的路徑。