Kod Deposu Kuralları

Sorun bildir Kaynağı görüntüleyin Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

Harici depo, Bazel derlemesinde kullanılabilen kaynak dosyaları içeren bir dizin ağacıdır. İlgili depo kuralını çalıştırarak istendiğinde oluşturulur. Depolar birçok şekilde tanımlanabilir ancak sonuçta her depo, derleme kurallarının çağrılmasıyla tanımlandığı gibi bir depo kuralı çağrılmasıyla tanımlanır. Bunlar, üçüncü taraf kitaplıklardan (Maven paketlenmiş kitaplıkları gibi) yararlanmak için kullanılabilir ancak Bazel'in çalıştığı ana makineye özel BUILD dosyaları oluşturmak için de kullanılabilir.

Depo kuralı tanımı

Yeni bir depo kuralı tanımlamak ve bunu global bir değişkende depolamak için .bzl dosyasında 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ğrı genellikle bir modül uzantısı uygulama işlevi içinden gerçekleştirilir.

Bir depo kuralı tanımının iki ana bileşeni, öznitelik şeması ve uygulama işlevidir. Özellik şeması, bir depo kuralı çağrısına iletilen özelliklerin adlarını ve türlerini belirler. Ayrıca, deponun getirilmesi gerektiğinde uygulama işlevi çalıştırılır.

Özellikler

Özellikler, depo kuralı çağrısına iletilen bağımsız değişkenlerdir. Bir depo kuralı repository_rule çağrısıyla tanımlandığında, depo kuralı tarafından kabul edilen özelliklerin şeması attrs bağımsız değişkeni kullanılarak belirtilir. url ve sha256 özelliklerini dize olarak tanımlayan ö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> öğesini kullanın:

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

Tüm repository_rule öğelerinde name özelliği varsayılan olarak tanımlanır. Bu, biraz sihirli davranan bir dize özelliğidir: Bir depo kuralı çağrısı için 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 repo kuralı için bir implementation işlevi gerekir. Kuralın gerçek mantığını içerir ve yalnızca Yükleme Aşamasında yürütülür.

İşlevin tam olarak bir giriş parametresi (repository_ctx) vardır. İşlev, belirtilen parametreler göz önüne alındığında kuralın yeniden üretilebilir olduğunu belirtmek için None değerini veya söz konusu kural için aynı repoyu oluşturan, kuralın yeniden üretilebilir hale gelmesini sağlayacak bir parametre grubu 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 değişken dal yerine belirli bir taahhüt tanımlayıcısı döndürülmesi anlamına gelir.

repository_ctx giriş parametresi, özellik değerlerine ve hermetik olmayan işlevlere (ikili dosya bulma, ikili dosya yürütme, depolama alanında dosya oluşturma veya internetten dosya indirme) erişmek 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 söz konusu depodan bir hedefe ihtiyacı olduğunda (ör. başka bir depodaki başka bir hedef bu hedefe bağlı olduğunda veya komut satırında bu hedeften bahsedildiğinde) yürütülür. Ardından, uygulama işlevinin dosya sisteminde deposu oluşturması beklenir. Buna depoyu "getirme" denir.

Normal hedeflerin aksine, depo farklı olması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 olduğu şeyler (ör. ağdan getirilen öğeler) olmasıdır. Bu nedenle, depolar yalnızca aşağıdakilerden biri değişirse yeniden getirilir:

  • Depo kuralı çağrısına iletilen özellikler.
  • Depo kuralının uygulanmasını içeren Starlark kodu.
  • repository_ctx'nin getenv() yöntemine iletilen veya repository_rule öğesinin environ özelliğiyle tanımlanan herhangi bir ortam değişkeninin değeri. Bu ortam değişkenlerinin değerleri, --repo_env işaretiyle komut satırına sabitlenebilir.
  • Depo kuralının uygulama işlevinde watched tüm yolların varlığı, içeriği ve türü.
    • watch parametresi içeren diğer bazı repository_ctx yöntemleri (ö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.

Depoların ne zaman yeniden getirileceğini kontrol eden iki repository_rule parametresi vardır:

  • configure işareti ayarlanmışsa depo, bazel fetch --force --configure'te yeniden getirilir (configure olmayan depolar yeniden getirilmez).
  • local işareti ayarlanmışsa Bazel sunucusu yeniden başlatılırken yukarıdaki durumlara ek olarak depo da yeniden getirilir.

Harici depoların yeniden getirilmesini zorlama

Bazen harici bir depo, tanımında veya bağımlılıklarında herhangi bir değişiklik olmadan güncelliğini yitirebilir. Örneğin, kaynak getiren bir depo, üçüncü taraf deposunun belirli bir dalını takip edebilir ve bu dalda yeni taahhütler kullanılabilir. Bu durumda, bazel fetch --force --all çağrısını yaparak bazel'den tüm harici depoları koşulsuz olarak yeniden getirmesini isteyebilirsiniz.

Ayrıca, bazı repo kuralları yerel makineyi inceler ve yerel makine yükseltilirse güncelliğini yitirebilir. Burada Bazel'den yalnızca repository_rule tanımında configure özelliğinin ayarlandığı harici depoları yeniden getirmesini isteyebilirsiniz. bazel fetch --force --configure değerini kullanın.

Örnekler

  • Otomatik olarak yapılandırılmış C++ araç seti: Yerel C++ derleyiciyi, ortamı ve C++ derleyicinin desteklediği işaretçileri 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ı harici bir depo oluşturur. Bu depo, geçişli bağımlılık ağacındaki her Maven yapısını derleme hedefleri oluşturur.