跳到主要內容

貢獻套件

貢獻流程可以分為三個步驟

  • 步驟 1. 暫存流程（新增配方和許可證）。

    借助暫存流程，將套件的配方和許可證新增至 staged-recipes 儲存庫 並建立 PR。

  • 步驟 2. 暫存後流程。

    一旦您的 PR 合併後，請查看我們的暫存後流程，以了解後續步驟。

  • 步驟 3. 維護套件。

    將套件貢獻給 conda-forge 會使您成為該套件的維護者。 深入了解維護者的角色。

以下章節將更詳細地介紹每個步驟。

暫存流程​

暫存流程，即新增套件的配方，包含三個步驟

  1. 產生配方
  2. 檢查清單
  3. 回饋和修訂

產生配方​

目前有三種產生配方的方法

  1. 如果是來自 CRAN 的 R 套件，請先使用 conda-forge 輔助腳本，用於 R 配方。 然後，如有必要，您可以手動編輯配方。

  2. 如果是 Python 套件，您可以使用 grayskull 產生配方作為起點。

    注意

    Grayskull 是一個自動 conda 配方產生器。 這個專案的目標是為 conda-forge 產生簡潔的配方，並最終取代 conda skeleton。 目前，Grayskull 可以為 PyPI 上可用的 Python 套件產生配方，也可以為那些未在 PyPI 上發布且僅作為 GitHub 儲存庫提供的套件產生配方。

    grayskull 的安裝和使用

    • 使用以下指令建立新的環境： conda create --name MY_ENV。 將 MY_ENV 替換為環境名稱。
    • 啟動這個新環境： conda activate MY_ENV。
    • 執行 conda install -c conda-forge grayskull 以安裝 grayskull。
    • 接著執行 grayskull pypi --strict-conda-forge YOUR_PACKAGE_NAME 以產生配方。 將 YOUR_PACKAGE_NAME 替換為套件名稱。

    您不一定必須使用 grayskull，而且 grayskull 產生的配方可能需要審查和編輯。 閱讀更多關於 grayskull 以及如何使用它的資訊 這裡。

  3. 如果都不是以上情況，請借助 範例配方 在 staged-recipes 儲存庫 中產生配方，並根據需要修改它。

您的最終配方應該沒有註解（除非它們實際上與配方相關，而不是通用的指示註解），並遵循範例中的順序。

注意

如果您對任何細節不確定，請無論如何建立一個 pull request。 conda-forge 團隊將審查它並協助您進行修改。

如果您是第一次使用 conda-forge 建立配方，以下提供逐步說明和檢查清單，以協助您成功建置。

逐步說明​

  1. 確保您的原始碼可以作為單一檔案下載。 原始碼應可作為封存檔 (.tar.gz、.zip、.tar.bz2、.tar.xz) 下載或在 GitHub 上標記，以確保可以驗證。（如需更多詳細資訊，請參閱 從 tarball 建置，而非儲存庫）。
  2. Fork 並 clone GitHub 上的 staged-recipes 儲存庫。
  3. 從 staged-recipes main 分支 checkout 新的分支。
  4. 透過 CLI，cd 進入 ‘staged-recipes/recipes' 目錄。
  5. 在您的 fork 副本中，在 recipes 資料夾中為您的套件建立一個新資料夾（即，...staged-recipes/recipes/<package-name>）
  6. 從 example 目錄複製 meta.yaml。 以下步驟中的所有變更都將在複製的 meta.yaml 中進行（即，...staged-recipes/recipes/<package-name>/meta.yaml）。 請保持 example 目錄不變！
  7. 根據需要修改複製的配方 (meta.yml)。 若要查看如何修改 meta.yaml，請查看 配方 meta.yaml。
  8. 使用 openssl 工具產生原始碼封存檔的 SHA256 金鑰，如範例配方中所述。 作為替代方案，您也可以前往 PyPi 上的套件說明，您可以從那裡直接複製 SHA256。
  9. 請務必填寫 test 區段。 最簡單的測試將僅測試模組是否可以匯入，如範例中所述。
  10. 移除 meta.yaml 檔案中所有不相關的註解。
提示

請務必不要對重新導向頁面進行校驗和。 因此，例如使用，

curl -sL https://github.com/username/reponame/archive/vX.X.X.tar.gz | openssl sha256

檢查清單​

  • 確保許可證和許可證系列描述符（可選）的大小寫正確，並且許可證是正確的。 請注意，需要區分大小寫的輸入（例如 Apache-2.0 而不是 APACHE 2.0）。 建議對許可證欄位使用 SPDX 識別碼。（請參閱 SPDX 識別碼和表達式）
  • 確保您已包含許可證檔案，如果您的許可證需要一個 – 大部分都需要。（請參閱 這裡）
  • 如果您的專案包含測試，您需要決定在建置 conda-forge feedstock 時是否應執行這些測試。
  • 確保所有測試至少在您的開發機器上成功通過。
  • 建議：在您的原始碼上本地執行測試，以確保配方在本地運作（請參閱 在本地執行暫存配方的測試）。
  • 確保您的變更不會干擾 recipes 資料夾中的其他配方（例如 example 配方）。

回饋和修訂​

完成您的 PR 後，您所要做的就是等待我們審查團隊的回饋。

審查團隊將通過指出改進之處和回答問題來協助您。 一旦套件準備就緒，審查人員將批准並合併您的 pull request。

在合併 PR 後，我們的 CI 基礎架構將建置套件，並使其在 conda 頻道中可用。

注意

如果您有問題或一陣子沒有收到回覆，您可以通過在您的 GitHub 訊息中包含 @conda-forge/staged-recipes 來通知我們。

暫存後流程​

  • 在 PR 合併後，我們的 CI 服務將自動建立一個新的 git 儲存庫。 例如，名為 pydstool 的套件配方將被移動到一個新的儲存庫 https://github.com/conda-forge/pydstool-feedstock。 這個流程是通過 conda-forge/staged-recipes 儲存庫上的 CI 作業自動化的。 有時會因為 API 速率限制而失敗，並將自動重試。 如果您的 feedstock 在一天左右後仍未建立，請聯繫 conda-forge/core 團隊尋求協助。
  • CI 服務將自動啟用，並且將自動觸發建置，這將建置 conda 套件並上傳到 https://anaconda.org/conda-forge
  • 如果這是您的第一次貢獻，您將被添加到 conda-forge 團隊，並獲得 CI 服務的存取權，以便您可以停止和重新啟動建置。 您也將被授予對新 git 儲存庫的提交權。
  • 如果您想對配方進行變更，請從 fork 向 git 儲存庫發送 PR。 主要儲存庫的分支僅用於維護不同的版本。

Feedstock 儲存庫結構​

一旦包含套件配方的 PR 在 staged-recipes 儲存庫中合併，就會自動建立一個名為 <package-name>-feedstock 的新儲存庫。 feedstock 由 conda 配方（關於要建置什麼套件以及如何建置的指示）和必要的設定檔組成，用於使用免費提供的持續整合 (CI) 服務進行自動建置。

每個 feedstock 都包含各種檔案，這些檔案是使用我們的自動配置工具 conda-smithy 自動產生的。 廣泛而言，每個 feedstock 都有以下檔案

配方​

此資料夾包含 meta.yaml 檔案和任何其他建置套件所需的檔案/腳本。

LICENSE.txt​

此檔案是配方本身的許可證。 此許可證與套件許可證不同，套件許可證是您在使用 meta.yaml 檔案中的 license_file 提交套件配方時定義的。

CI 檔案​

這些是用於 Azure 和 TravisCI 等服務提供者的 CI 設定檔。

conda-forge.yml​

此檔案用於設定 feedstock 的設定和建置方式。 在此檔案中進行任何變更通常需要重新渲染 feedstock。

維護者角色​

維護者的工作是

  • 通過合併 conda-forge 機器人的最終維護 PR 來保持 feedstock 的更新。
  • 通過以下方式使 feedstock 與來源套件的新版本保持一致
    • 更新版本號和校驗和。
    • 確保 feedstock 的需求保持準確。
    • 確保測試需求與更新後的套件的需求相符。
  • 回答關於 feedstock 問題追蹤器上關於套件的最終問題。

一次新增多個套件​

如果您想新增多個相關套件，它們可以以單一 pull request（在不同的目錄中）新增到 staged-recipes。 如果套件是相互依賴的（即，正在新增的一個套件將正在新增的其他一個或多個套件列為需求），只要建置以依賴順序完成，建置腳本就能夠找到僅存在於 staged-recipes 中的依賴項。 使用單一 pull request 允許您快速設定套件，而無需等待依賴鏈中的每個套件都被審查、建置並添加到 conda-forge 頻道，然後才使用鏈中的下一個配方重新開始流程。

注意

當合併包含多個相互依賴配方的 PR 時，如果建置在其依賴項建置完成之前完成，則可能會發生錯誤。 如果發生這種情況，您可以通過推送一個空的 commit 來觸發新的建置。

git commit --amend --no-edit && git push --force

同步 fork 以供未來使用​

如果您想在未來新增其他套件，您將需要在 fork 上建立新分支之前重置您的 staged-recipes fork，新增新的套件目錄/配方，並建立 pull request。 此步驟確保您擁有 staged-recipes 儲存庫中包含的工具和設定檔的最新版本，並使 pull request 更容易審查。 以下步驟將重置您的 staged-recipes fork，並且應從您的 fork staged-recipes 目錄的 clone 中執行。

  1. Checkout 您的 main 分支
    git checkout main
  2. 將 conda-forge/staged-recipes 儲存庫定義為 upstream（如果您尚未這樣做）。
    git remote add upstream https://github.com/conda-forge/staged-recipes.git
  3. 從 upstream main 分支 pull 所有 upstream 的 commits。
    git pull --rebase upstream main
  4. 將所有變更 push 到您在 GitHub 上的 fork（確保 GitHub 上沒有您需要的任何變更，因為它們將被覆寫）。
    git push origin main --force

完成這些步驟後，您可以繼續 逐步說明 中的步驟，以使用您現有的 staged-recipes fork 暫存您的新套件配方。

配方 meta.yaml​

配方目錄中的 meta.yaml 檔案是每個 conda 套件的核心。 它定義了建置和使用套件所需的一切。

meta.yaml 採用 yaml 格式，並使用 Jinja 範本。

meta.yaml 檔案的結構和欄位的完整參考可以在 conda-build 文件中的 定義元數據 (meta.yaml) 章節中找到。

在下面，我們重點介紹特別重要且特定於 conda-forge 的資訊和指南，按 meta.yaml 中的章節排序。

來源​

從 tarball 建置，而非儲存庫​

套件應使用 url 金鑰從 tarball 建置，而不是直接使用例如 git_url 從儲存庫建置。

此規則背後有幾個原因

  • 儲存庫通常比 tarball 大，會消耗共享的 CI 時間和頻寬
  • 儲存庫未進行校驗和。 因此，使用 tarball 可以更強烈地保證獲得的下載是實際要從中建置的套件。
  • 在某些系統上，可能沒有權限刪除已建立的儲存庫。

填寫 hash 欄位​

如果您的套件在 PyPi 上，您可以從 PyPI 上套件的頁面取得 sha256 hash； 在套件檔案頁面上尋找下載連結旁邊的 SHA256 連結，例如 https://pypi.org/project/<your-project>/#files。

您也可以從 Linux 上的命令列產生 hash（如果您安裝了必要的工具，也可以在 Mac 上產生）。

若要產生 sha256 hash： openssl sha256 your_sdist.tar.gz

您可能需要 openssl 套件，可在 conda-forge 上取得 conda install openssl -c conda-forge。

提示

請務必不要對重新導向頁面進行校驗和。 因此，例如使用，

curl -sL https://github.com/username/reponame/archive/vX.X.X.tar.gz | openssl sha256

下載額外的來源和資料檔案​

conda-build 3 支援每個配方多個來源。 範例可在 conda-build 文件中 找到。

建置​

跳過建置​

在 build 區段中使用 skip 金鑰以及選擇器

您可以例如指定不建置 …

  • 在特定架構上
    build:
        skip: true  # [win]
  • 針對特定的 python 版本
    build:
        skip: true  # [py<35]

選擇器的完整描述在 conda 文件中。

可選：bld.bat 和/或 build.sh​

在許多情況下，不需要 bld.bat 和/或 build.sh 檔案。 純 Python 套件幾乎永遠不需要它們。

如果可以使用一行程式碼執行建置，您可以將此行程式碼放在 meta.yaml 檔案的 build 區段的 script 條目中，如下所示： script: "{{ PYTHON }} -m pip install . -vv"。

請記住始終將 pip 添加到 host 需求中。

使用 pip​

通常 Python 套件應使用此行

build:
  script: "{{ PYTHON }} -m pip install . -vv"

作為 meta.yml 檔案或 bld.bat/build.sh 腳本檔案中的安裝腳本，同時將 pip 添加到 host 需求中

requirements:
  host:
    - pip

應使用這些選項來確保套件的乾淨安裝，而無需其依賴項。 這有助於確保我們僅包含此套件，而不是意外地將任何依賴項帶入 conda 套件中。

通常純 Python 套件只需要 python、setuptools 和 pip 作為 host 需求； 真正的套件依賴項僅是 run 需求。

需求​

建置、host 和 run​

Conda-build 區分三種不同的依賴項。 在以下段落中，我們簡要概述了哪些套件屬於哪裡。 如需詳細說明，請參閱 conda-build 文件。

建置​

建置依賴項在建置環境中是必需的，並且包含 host 套件上不需要的所有工具。

以下套件是典型的 build 依賴項範例

Host​

Host 依賴項在建置階段是必需的，但與建置套件相反，它們必須存在於 host 上。

以下套件是 host 依賴項的典型範例

  • 共享函式庫 (c/c++)
  • 連結到 c 函式庫的 python/r 函式庫（請參閱例如 針對 NumPy 建置）
  • python, r-base
  • setuptools, pip（請參閱 使用 pip）

Run​

Run 依賴項僅在套件執行時才需要。 Run 依賴項通常包括

  • 大多數 python/r 函式庫

避免外部依賴項​

作為一般規則：所有依賴項也必須由 conda-forge 打包。 這是確保我們所有套件的 ABI 相容性所必需的。

此規則只有少數例外

  1. 某些依賴項必須使用 CDT 套件來滿足（請參閱 核心依賴樹套件 (CDT)）。
  2. 某些套件需要 root 存取權限（例如裝置驅動程式），conda-forge 無法發布這些套件。 應盡可能避免這些依賴項。

釘選​

連結共享 c/c++ 函式庫會建立對在套件建置時使用的函式庫的 ABI 的依賴性。 當較新版本中刪除或修改先前存在的公開符號時，公開的介面會發生變化。

因此，至關重要的是要確保在連結後僅使用具有相容 ABI 的函式庫版本。

在最佳情況下，您依賴的共享函式庫

在這些情況下，您不必擔心版本需求

requirements:
  # [...]
  host:
    - readline
    - libpng

在其他情況下，您必須手動指定 ABI 相容版本。

requirements:
  # [...]
  host:
    - libawesome 1.1.*

有關釘選的更多資訊，請參閱 釘選的依賴項。

在執行時限制套件​

run_constrained 區段允許在執行時定義對套件的限制，而無需依賴該套件。 它可以用於限制可選依賴項的允許版本和定義不相容的套件。

定義非依賴項限制​

想像一下，一個套件可以與 awesome-software 的版本 1 一起使用（如果存在），但並不嚴格依賴它。 因此，您希望讓使用者選擇是否要將套件與 awesome-software 一起使用。 讓我們進一步假設該套件與 awesome-software 的版本 2 不相容。

在這種情況下，如果使用者選擇安裝 awesome-software，則可以使用 run_constrained 將 awesome-software 限制為版本 1.*

requirements:
  # [...]
  run_constrained:
    - awesome-software 1.*

在這裡，run_constrained 充當一種保護使用者免受不相容版本影響的方法，而不會引入不必要的依賴項。

定義衝突​

有時套件會互相干擾，因此任何時候只能安裝其中一個。 與無法滿足的版本結合使用時，run_constrained 可以定義封鎖器

package:
name: awesome-db

requirements:
  # [...]
  run_constrained:
    - amazing-db ==9999999999

在此範例中，awesome-db 無法與 amazing-db 一起安裝，因為沒有 amazing-db-9999999999 套件。

測試​

所有配方都需要測試。 以下是一些提示、技巧和理由。 您應該如何測試取決於套件的類型（python、c-lib、命令列工具、…），以及該套件可用的測試。 但每個 conda 套件都必須至少有一些測試。

簡單的存在性測試​

有時定義測試似乎很困難，例如由於

  • 底層程式碼庫的測試可能不存在。
  • 測試套件可能需要花費太長時間才能在有限的 CI 基礎架構上執行。
  • 測試可能會佔用太多頻寬。

在這些情況下，conda-forge 可能無法執行規定的測試套件。

但是，這不是配方沒有測試的理由。 至少，我們想驗證套件是否已在所需位置安裝了所需的檔案。 這稱為存在性測試。

存在性測試可以在 meta.yaml 檔案的 test/commands 區塊中完成。

在 posix 系統上，使用 test 工具和 $PREFIX 變數。

在 Windows 上，使用 exist 命令。 請參閱下面的範例。

簡單的存在性測試範例

test:
  commands:
    - test -f $PREFIX/lib/libboost_log$SHLIB_EXT  # [unix]
    - if not exist %LIBRARY_LIB%\\boost_log-vc140-mt.lib exit 1  # [win]

測試 python 套件​

有關測試的最佳資訊，請參閱 conda build 文件 測試章節。

測試匯入​

python 套件的最小測試應確保套件可以成功匯入。 這可以使用 meta.yaml 中的以下段落完成

test:
  imports:
    - package_name

請注意，package_name 是 python 匯入的名稱； 不一定是 conda 套件的名稱（它們有時是不同的）。

測試匯入將捕獲大部分打包錯誤，通常包括依賴項的存在。 但是，它不能保證套件可以正常運作。 特別是，它沒有測試它是否與使用的依賴項版本正常運作。 在某些情況下，頂層匯入名稱不包含任何可執行程式碼（例如，具有空的 __init__.py 或沒有任何直接匯入的套件）。 此測試將始終通過！ 在這些情況下，顯式添加更多針對包含可執行程式碼的模組的匯入（例如 package_name.core）會有所幫助。

如果可能，最好運行程式碼本身的其他一些測試（測試套件）。

pip 檢查​

對於 PyPI 套件，我們強烈建議將 pip check 作為 test.commands 區段的一部分包含在內

test:
  commands:
    - pip check

此命令將檢查 Python 元數據中指定的所有依賴項是否都已滿足。

注意

pip check 有時可能會因為 PyPI 和 conda-forge 之間的元數據差異而失敗（例如，名稱不同的相同套件）。 在這些情況下，審查人員必須評估錯誤是否為假陰性。 提示：使用 pip list 來顯示 pip check「看到」的內容。

運行單元測試​

這裡的技巧是，在 Python 中有多種運行單元測試的方法，包括 nose、pytest 等。

此外，某些套件會將測試與套件一起安裝，因此它們可以就地運行，而其他套件則將測試與原始碼一起保留，因此無法直接從已安裝的套件運行。

測試需求​

有時，執行測試所需的套件並非僅使用該套件所必需。這通常是測試執行框架，例如 nose 或 pytest。您可以將其添加到 test stanza 中的 requirements，以確保包含該套件

test:
  imports:
    - package_name
...
  requires:
    - pytest

複製測試檔案​

通常，測試檔案不會與套件一起安裝。 Conda 會建立一個全新的工作副本，以執行 build recipes 的測試階段，該副本不包含來源套件的檔案。

您可以使用 source_files 區段來包含測試所需檔案

test:
  imports:
    - package_name
  requires:
    - pytest
  source_files:
    - tests
    - test_pkg_integration.py
  commands:
    - pytest tests test_pkg_integration.py

source_files 區段適用於檔案和目錄。

內建測試​

某些套件具有內建測試。在這種情況下，您可以直接在 test stanza 中放入測試命令

test:
  ...
  commands:
     python -c "import package_name; package_name.tests.runall()"

或者，您可以在 recipe 中新增一個名為 run_test.py 的檔案，該檔案將在測試時執行。這允許使用任意複雜的測試腳本。

pytest 測試​

如果測試與套件一起安裝，pytest 可以找到並為您執行它們，使用以下命令

test:
  requires:
    - pytest
  commands:
    - pytest --pyargs package_name

命令列工具​

如果 Python 套件安裝了命令列工具，您可能需要測試它們是否已正確安裝

test:
  commands:
    - util_1 --help

如果該工具實際上具有測試模式，那就太好了。否則，只需調用 --help 或 --version 或類似命令，至少可以測試它是否已安裝並且可以運行。

R 語言套件測試​

應該測試 R 語言套件是否能成功載入函式庫。所有 CRAN 套件的 recipes 都應該從 conda_r_skeleton_helper 開始，並且會自動包含函式庫載入測試。然而，許多 R 語言套件也包含可以運行的 testthat 測試。雖然是選選的，但當套件

  • 提供其他（編譯過的）函式庫的介面 (例如，r-curl, r-xml2)
  • 擴展或整合許多其他 R 語言函式庫的功能 (例如，r-vetiver)
  • 是提供常用功能的基礎 R 語言套件 (例如，r-rmarkdown)

測試 R 語言函式庫載入​

R 語言套件的最低限度測試應確保可以成功導入交付的函式庫。這在 meta.yaml 中透過以下方式完成

test:
  commands:
    - $R -e "library('PackageName')"           # [not win]
    - "\"%R%\" -e \"library('PackageName')\""  # [win]

請注意，PackageName 是 R 語言導入的名稱；不一定是 conda 套件的名稱 (例如，r-matrix 提供 Matrix)。

運行 testthat 測試​

具有 testthat 測試的 R 語言套件的典型 test 區段看起來會像這樣

test:
  requires:
    - r-testthat
  source_files:
    - tests/
  commands:
    - $R -e "library('PackageName')"                                                  # [not win]
    - $R -e "testthat::test_file('tests/testthat.R', stop_on_failure=TRUE)"           # [not win]
    - "\"%R%\" -e \"library('PackageName')\""                                         # [win]
    - "\"%R%\" -e \"testthat::test_file('tests/testthat.R', stop_on_failure=TRUE)\""  # [win]
注意

我們建議在 testthat 測試之前包含函式庫載入檢查。

首先，需要宣告測試環境已安裝 r-testthat。這裡可能需要額外的 requirements，特別是當套件具有經過測試的選選功能時。

注意

如果任何 testthat 測試由於缺少套件而失敗，建議維護人員將此情況通知上游儲存庫。某些 R 語言套件具有選選功能，通常涉及在 DESCRIPTION 檔案的 Suggests: 區段下列出的套件。開發人員應使用 testthat::skip_if_not_installed() 函數來防止在未安裝選選套件時發生測試失敗。當未完成此操作時，發布 Issue 或 Pull Request 將有助於改進 R 生態系統中的測試實務。

其次，需要宣告從何處取得測試來源。 R 語言套件測試將在 tarball 的 tests/ 目錄中找到。這通常會包含一個 tests/testthat.R 檔案以及 tests/testthat/test_*.R 下的其他測試。輔助目錄和檔案也可能存在，並且是特定測試所需要的。

conda-forge 上的預設 R 語言建置程序不會在最終建置中包含 tests/ 目錄。雖然可以透過 --install-tests 標誌來完成此操作，但最好在 meta.yaml 中使用 tests.source_files 來僅為測試階段複製測試。

最後，使用 testthat::test_file() 函數來測試 tests/testthat.R 檔案，對於大多數套件而言，該檔案是所有其他測試的主要入口點。預設情況下，此函數在測試失敗時不會傳回錯誤值，因此需要傳遞引數 stop_on_failure=TRUE，以確保測試失敗會傳播到 conda-build。

在某些情況下，tests/testthat.R 檔案不會協調個別測試。在這種情況下，可以改為測試 tests/testthat 目錄，使用

test:
  commands:
    - $R -e "testthat::test_dir('tests/testthat/', package='PackageName', load_package='installed')"           # [not win]
    - "\"%R%\" -e \"testthat::test_dir('tests/testthat/', package='PackageName', load_package='installed')\""  # [win]

在這種情況下，預設情況下，該函數會在任何失敗時產生錯誤。同樣，此處的 PackageName 是指 R 語言函式庫名稱。

套件外部的測試​

請注意，conda-build 在安裝套件後會在隔離的環境中運行測試 – 因此，此時它無法存取原始來源 tarball。這是為了確保測試環境盡可能接近最終用戶將看到的環境。

這使得運行未與套件一起安裝的測試變得非常困難。

在本機運行 staged recipes 的測試​

如果您想在本機的 staged-recipes 儲存庫中運行和建置套件，請前往根儲存庫目錄並運行 build-locally.py 腳本（您需要 Python 3）。然後您可以按照提示選擇您要建置的變體。如果您要為 Linux 建置套件，則這需要您在機器上安裝 Docker。對於 MacOS，它會提示您選擇 SDK 的位置（例如 export OSX_SDK_DIR=/opt）以下載。

$ cd ~/staged-recipes
$ python build-locally.py

如果您知道要建置哪個映像檔，您可以將其指定為腳本的引數。

$ cd ~/staged-recipes
$ python build-locally.py <VARIANT>

其中 <VARIANT> 是 .ci_support/ 目錄中的檔案名稱之一，例如 linux64、osx64 和 linux64_cuda<version>。

關於​

手動封裝授權條款​

有時，即使授權條款要求，上游維護人員也不會在他們的 tarball 中包含授權條款檔案。

如果是這種情況，您可以將授權條款新增到 recipe 目錄（此處命名為 LICENSE.txt），並在 meta.yaml 內部引用它

about:
  license_file: LICENSE.txt

在這種情況下，也請通知上游開發人員授權條款檔案遺失。

重要

只有在下載的封存檔中沒有授權條款檔案時，才應將授權條款與 recipe 一起發布。如果封存檔中有授權條款檔案，請將 license_file 設定為封存檔中授權條款檔案的路徑。

SPDX 識別碼和表達式​

對於 recipe meta.yaml 中的 about: license 條目，建議使用 SPDX 識別碼或表達式。

請參閱 SPDX 授權條款識別碼 以取得授權條款。請參閱 SPDX 授權條款例外 以取得授權條款例外。請參閱 SPDX 規範 附錄 D 以取得有關表達式的規範。以下是一些範例

Apache-2.0
Apache-2.0 WITH LLVM-exception
BSD-3-Clause
BSD-3-Clause OR MIT
GPL-2.0-or-later
LGPL-2.0-only OR GPL-2.0-only
LicenseRef-HDF5
MIT
MIT AND BSD-2-Clause
PSF-2.0
Unlicense

包含的依賴項的授權條款​

對於某些語言（Go、Rust 等），目前的政策是將所有依賴項及其依賴項包含在套件中。當封裝授權條款檔案時，這會產生問題，因為每個依賴項都需要將其授權條款檔案包含在 recipe 中。

對於某些語言，社群提供了可以自動化此過程的工具，從而可以自動包含所有需要的授權條款檔案。

Rust​

cargo-bundle-licenses 可以包含在套件的建置過程中，並將自動收集並新增套件所有依賴項的授權條款檔案。

如需詳細說明，請造訪專案頁面，但以下可以找到一個簡短範例。

首先，將授權條款的集合包含為建置過程的一個步驟。

build:
  number: 0
  script:
    - cargo-bundle-licenses --format yaml --output THIRDPARTY.yml
    - build_command_goes_here

然後，將該工具包含為建置時依賴項。

requirements:
  build:
    - cargo-bundle-licenses

最後，確保產生的檔案包含在 recipe 中。

about:
  license_file:
    - THIRDPARTY.yml
    - package_license.txt

Go​

go-licenses 可以包含在套件的建置過程中，並將自動收集並新增套件所有依賴項的授權條款檔案。

如需詳細說明，請造訪專案頁面，但以下可以找到一個簡短範例。

首先，將授權條款的集合包含為建置過程的一個步驟。

build:
  number: 0
  script:
    - go build [...]
    - go-licenses save . --save_path="./license-files/"

然後，將該工具包含為建置時依賴項。

requirements:
  build:
    - {{ compiler('go') }}
    - go-licenses

最後，確保產生的檔案包含在 recipe 中。

about:
  license_file:
    - LICENSE
    - license-files/
重要

我們不是律師，無法保證以上建議是正確的，也無法保證這些工具能夠找到所有授權條款檔案。此外，我們無法承擔任何責任或義務。您始終有責任仔細檢查是否包含所有授權條款，並驗證任何產生的輸出是否正確。

注意

依賴項授權條款的正確且自動化的封裝是一個正在進行的討論。請隨時新增您的想法。

額外​

Recipe 維護者​

維護者是指負責維護和更新一個或多個 feedstock 儲存庫和套件及其未來版本的人員。他們擁有僅限於他們維護的套件的 feedstock 儲存庫的推送權限，並且可以將 pull requests 合併到其中。

為套件貢獻 recipe 會使您自動成為該套件的 維護者。請參閱維護者角色和維護套件以了解有關維護者所做事項的更多資訊。如果您希望成為特定套件的維護者，則應聯絡目前的維護者，並使用以下命令在該套件的 feedstock 中開啟 issue

@conda-forge-admin，請新增使用者 @username

其中 username 是要新增的新維護者的 GitHub 使用者名稱。請參閱成為維護者和更新維護者列表以取得詳細說明。

Feedstock 名稱​

如果您希望 feedstock 的名稱與 staged-recipes 中的套件名稱不同，您可以使用該套件 recipe 中的 feedstock-name 指令，如下所示

extra:
  feedstock-name: <name>

此處，<name> 是您希望 feedstock 使用的名稱。如果未指定，則名稱將取自 meta.yaml 中的頂層 name 欄位。

其他​

啟動腳本​

Recipes 允許擁有啟動腳本，這些腳本將在環境啟動時被 source 或 call。通常建議在可以選擇其他選項時避免使用啟動腳本，因為人們並不總是按照預期的方式啟動環境，並且這些套件可能會因此而行為異常。

在 recipe 中使用它們時，可以隨意在 recipe 中將它們命名為 activate.bat、activate.sh、deactivate.bat 和 deactivate.sh。建議已安裝的腳本以套件名稱和分隔符號 - 作為前綴。以下是一些適用於 Unix 和 Windows 的範例程式碼，它們將使此安裝過程更容易。請隨時借用它。

在 build.sh 中

# Copy the [de]activate scripts to $PREFIX/etc/conda/[de]activate.d.
# This will allow them to be run on environment activation.
for CHANGE in "activate" "deactivate"
do
    mkdir -p "${PREFIX}/etc/conda/${CHANGE}.d"
    cp "${RECIPE_DIR}/${CHANGE}.sh" "${PREFIX}/etc/conda/${CHANGE}.d/${PKG_NAME}_${CHANGE}.sh"
done

在 build.bat 中

setlocal EnableDelayedExpansion

:: Copy the [de]activate scripts to %PREFIX%\etc\conda\[de]activate.d.
:: This will allow them to be run on environment activation.
for %%F in (activate deactivate) DO (
    if not exist %PREFIX%\etc\conda\%%F.d mkdir %PREFIX%\etc\conda\%%F.d
    copy %RECIPE_DIR%\%%F.bat %PREFIX%\etc\conda\%%F.d\%PKG_NAME%_%%F.bat
    :: Copy unix shell activation scripts, needed by Windows Bash users
    copy %RECIPE_DIR%\%%F.sh %PREFIX%\etc\conda\%%F.d\%PKG_NAME%_%%F.sh
)

Jinja 模板​

recipe meta.yaml 可以包含在建置時評估的表達式。這些表達式以 Jinja 語法編寫。

Jinja 表達式在 meta.yaml 中具有以下用途

  • 它們允許定義變數以避免程式碼重複。對 version 使用變數允許在每次更新時僅更改版本一次。

    {% set version = "3.7.3" %}

    package:
      name: python
      version: {{ version }}

    source:
      url: https://www.python.org/ftp/python/{{ version }}/Python-{{ version }}.tar.xz
      sha256: da60b54064d4cfcd9c26576f6df2690e62085123826cff2e667e72a91952d318

  • 它們可以調用 conda-build 函數以進行自動程式碼生成。範例包括編譯器、cdt 套件或 pin_compatible 函數。

    requirements:
      build:
        - {{ compiler('c') }}
        - {{ compiler('cxx') }}
        - {{ cdt('xorg-x11-proto-devel') }}  # [linux]
        - {{ cdt('libx11-devel') }}          # [linux]

    或

    requirements:
      build:
        - {{ compiler('c') }}
        - {{ compiler('cxx') }}
      host:
        - python
        - numpy
      run:
        - python
        - {{ pin_compatible('numpy') }}

如需更多資訊，請參閱 conda-build 文件中的使用 Jinja 模板區段。