Kod Deposu Kuralları

Sorun bildirme Kaynağı görüntüleme Nightly · 7.4 .

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 hedefleri derleme kuralları çağrılarak tanımlandığı gibi bir depo kuralı çağrılarak 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. Uygulama işlevi, reponun getirilmesi gerektiğinde ç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> kullanın:

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

Tüm repository_rule'ler, dolaylı olarak tanımlanmış name özelliğine sahiptir. Bu, sihirli davranan bir dize özelliğidir: Bir depo kuralı çağrısına girdi olarak belirtildiğinde görünür bir depo adı alır; ancak repository_ctx.attr.name kullanarak depo kuralının uygulama işlevinden okunduğunda standart 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, kuralın belirtilen parametrelere göre tekrarlanabilir olduğunu belirtmek için None veya bu kural için bir dizi parametre içeren ve kuralı, aynı depoyu oluşturan tekrarlanabilir bir dikte 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 program yürütme, depoda 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, depoların farklı olmasına neden olacak bir değişiklik olduğunda depolar yeniden getirilmeyebilir. 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 öğesinin 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, --repo_env işaretiyle komut satırına sabitlenebilir.
  • Depo kuralının uygulama işlevinde watched olan 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.