Kod Deposu Kuralları

Sorun bildir Kaynağı görüntüle Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bu sayfada, depo kurallarının nasıl tanımlanacağı açıklanmakta ve daha fazla ayrıntı için örnekler verilmektedir.

Harici depo, ilgili repo kuralı çalıştırılarak isteğe bağlı olarak oluşturulan ve Bazel derlemesinde kullanılabilen kaynak dosyaları içeren bir dizin ağacıdır. Depolar çeşitli şekillerde tanımlanabilir ancak nihayetinde her depo, derleme hedeflerinin derleme kuralları çağrılarak tanımlanması gibi, depo kuralları çağrılarak tanımlanır. Bunlar, üçüncü taraf kitaplıklarına (ör. Maven paketli kitaplıklar) bağlı olmak için kullanılabileceği gibi, Bazel'in üzerinde çalıştığı ana makineye özel BUILD dosyaları oluşturmak için de kullanılabilir.

Depo kuralı tanımı

Bir .bzl dosyasında, yeni bir depo kuralı tanımlamak ve bunu global bir değişkende depolamak için repository_rule işlevini kullanın. Bir depo kuralı tanımlandıktan sonra, depoları tanımlamak için işlev olarak çağrılabilir. Bu çağırma işlemi genellikle bir modül uzantısı uygulama işlevinin içinden gerçekleştirilir.

Depo kuralı tanımının iki temel bileşeni, öznitelik şeması ve uygulama işlevidir. Özellik şeması, bir depo kuralı çağırmaya iletilen özelliklerin adlarını ve türlerini belirler. Deponun getirilmesi gerektiğinde uygulama işlevi çalıştırılır.

Özellikler

Özellikler, depo kuralı çağırmaya aktarılan bağımsız değişkenlerdir. Bir depo kuralı tarafından kabul edilen özelliklerin şeması, depo kuralı repository_rule çağrısıyla tanımlandığında attrs bağımsız değişkeni kullanılarak belirtilir. url ve sha256 özelliklerini dize olarak tanımlayan bir örnek:

http_archive = repository_rule(
    implementation=_impl,
    attrs={
        "url": attr.string(mandatory=True),
        "sha256": attr.string(mandatory=True),
    }
)

Uygulama işlevindeki bir özelliğe erişmek için repository_ctx.attr.<attribute_name> kullanın:

def _impl(repository_ctx):
    url = repository_ctx.attr.url
    checksum = repository_ctx.attr.sha256

Tüm repository_rule öğelerinde, dolaylı olarak tanımlanmış name özelliği bulunur. Bu, biraz sihirli bir şekilde davranan bir dize özelliğidir: Bir depo kuralı çağrısına giriş olarak belirtildiğinde, görünür bir depo adı alır; ancak repository_ctx.attr.name kullanılarak depo kuralının uygulama işlevinden okunduğunda, kurallı depo adını döndürür.

Uygulama işlevi

Her depo kuralı için bir implementation işlevi gerekir. Kuralın gerçek mantığını içerir ve kesinlikle yükleme aşamasında yürütülür.

İşlevin tam olarak bir giriş parametresi vardır: repository_ctx. İşlev, belirtilen parametreler göz önüne alındığında kuralın yeniden üretilebilir olduğunu belirtmek için None değerini veya bu kuralı aynı depoyu oluşturacak şekilde yeniden üretilebilir bir kurala dönüştürecek bir dizi parametre içeren bir sözlük döndürür. Örneğin, bir Git deposunu izleyen bir kural için bu, başlangıçta belirtilen kayan bir dal yerine belirli bir commit tanımlayıcısının döndürülmesi anlamına gelir.

Giriş parametresi repository_ctx, özellik değerlerine erişmek ve hermetik olmayan işlevler (ikili dosya bulma, ikili dosya yürütme, depoda dosya oluşturma veya internetten dosya indirme) için kullanılabilir. Daha fazla bilgi için API dokümanlarına göz atın. Örnek:

def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)

Uygulama işlevi ne zaman yürütülür?

Bir depo kuralının uygulama işlevi, Bazel'in bu depodan bir hedef alması gerektiğinde (ör. başka bir depodaki başka bir hedef buna bağlıysa veya komut satırında belirtilmişse) yürütülür. Uygulama işlevinin daha sonra dosya sisteminde depo oluşturması beklenir. Buna "fetching" (getirme) adı verilir.

Normal hedeflerin aksine, depo farklılaşmasına neden olacak bir değişiklik olduğunda depoların yeniden getirilmesi gerekmez. Bunun nedeni, Bazel'in değişiklikleri algılayamadığı veya her derlemede çok fazla ek yüke neden olacağı (örneğin, ağdan getirilen öğeler) şeyler olmasıdır. Bu nedenle, depolar yalnızca aşağıdaki durumlardan biri değiştiğinde yeniden getirilir:

  • Depo kuralı çağırmaya aktarılan özellikler.
  • Depo kuralının uygulanmasını içeren Starlark kodu.
  • repository_ctx'nın getenv() yöntemine iletilen veya repository_rule öğesinin environ özelliğiyle bildirilen herhangi bir ortam değişkeninin değeri. Bu ortam değişkenlerinin değerleri, komut satırında --repo_env işaretiyle sabit olarak kodlanabilir.
  • Depo kuralının uygulama işlevinde watched edilen tüm yolların varlığı, içeriği ve türü.
    • watch parametresiyle repository_ctx yöntemlerinden bazıları (ör. read(), execute() ve extract()) de yolların izlenmesine neden olabilir.
    • Benzer şekilde, repository_ctx.watch_tree ve path.readdir, yolların başka şekillerde izlenmesine neden olabilir.
  • bazel fetch --force yürütüldüğünde.

repository_rule ile ilgili iki parametre, depoların ne zaman yeniden getirileceğini kontrol eder:

  • configure işareti ayarlanırsa depo, bazel fetch --force --configure üzerinde yeniden getirilir (configure olmayan depolar yeniden getirilmez).
  • local işareti ayarlanırsa yukarıdaki durumlara ek olarak Bazel sunucusu yeniden başlatıldığında da depo yeniden getirilir.

Harici depoların yeniden getirilmesini zorlama

Bazen, tanımında veya bağımlılıklarında herhangi bir değişiklik yapılmamasına rağmen harici bir depo güncelliğini yitirebilir. Örneğin, kaynakları getiren bir depo, üçüncü taraf deposunun belirli bir dalını takip edebilir ve bu dalda yeni commit'ler kullanılabilir. Bu durumda, bazel fetch --force --all işlevini çağırarak Bazel'den tüm harici depoları koşulsuz olarak yeniden getirmesini isteyebilirsiniz.

Ayrıca, bazı depo kuralları yerel makineyi inceler ve yerel makine yükseltildiyse güncelliğini yitirebilir. Burada Bazel'den yalnızca repository_rule tanımında configure özelliği ayarlanmış olan harici depoları yeniden getirmesini isteyebilirsiniz. Bunun için bazel fetch --force --configure kullanın.

Örnekler

  • C++ otomatik yapılandırılmış araç zinciri: Yerel C++ derleyicisini, ortamı ve C++ derleyicisinin desteklediği işaretleri arayarak Bazel için C++ yapılandırma dosyalarını otomatik olarak oluşturmak üzere bir depo kuralı kullanır.

  • Go depoları, Go kurallarını kullanmak için gereken bağımlılıkların listesini tanımlamak üzere çeşitli repository_rule kullanır.

  • rules_jvm_external varsayılan olarak @maven adlı bir harici depo oluşturur. Bu depo, geçişli bağımlılık ağacındaki her Maven yapısı için derleme hedefleri oluşturur.