Kod Deposu Kuralları

Sorun bildir Kaynağı göster

Bu sayfada, depo kurallarının nasıl tanımlanacağı ele alınmakta ve daha ayrıntılı bilgi için örnekler sağlanmaktadır.

Harici depo, karşılık gelen depo kuralı çalıştırılarak istek üzerine oluşturulan ve Bazel derlemesinde kullanılabilen kaynak dosyaları içeren bir dizin ağacıdır. Depolar çeşitli yollarla tanımlanabilir ancak nihayetinde, derleme hedeflerinin derleme kurallarının çağrılmasıyla tanımlanması gibi her depo, bir depo kuralı çağrılıp tanımlanır. Üçüncü taraf kitaplıklara (Maven paketli kitaplıklar gibi) bağlı olmanın yanı sıra Bazel'ın çalıştığı ana makineye özel BUILD dosyaları oluşturmak için de kullanılabilirler.

Kod deposu kuralı tanımı

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

Depo kuralı tanımının iki ana bileşeni, özellik şeması ve uygulama işlevidir. Özellik şeması, bir depo kuralı çağrısına iletilen özelliklerin adlarını ve türlerini belirler ve 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. Depo kuralının repository_rule çağrısıyla tanımlandığı durumlarda depo kuralının kabul ettiği özelliklerin şeması, 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,
    local=True,
    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 öğeleri, dolaylı olarak tanımlanmış name özelliğine sahiptir. Bu, sihirli bir şekilde davranan bir dize özelliğidir: Depo kuralı çağrısına giriş olarak belirtildiğinde belirgin bir depo adı alır. Ancak repository_ctx.attr.name kullanılarak depo kuralının uygulama işlevinden okunduğunda ise standart depo adını döndürür.

Uygulama işlevi

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

İşlev tam olarak bir giriş parametresine (repository_ctx) sahiptir. İşlev, belirtilen parametrelere göre kuralın yeniden oluşturulabilir olduğunu belirtmek için None veya söz konusu kural için, aynı depoyu oluşturan tekrarlanabilir bir kurala dönüştürecek parametre grubu içeren bir diktürü döndürür. Örneğin, git deposunu izleyen bir kural için başlangıçta belirtilen kayan dal yerine belirli bir kaydetme tanımlayıcısı döndürmeniz gerekir.

repository_ctx giriş parametresi, özellik değerlerine ve hermetik olmayan işlevlere (ikili program 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 belgelerine bakı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 bu depodan bir hedefe ihtiyaç duyduğunda yürütülür. Örneğin, başka bir hedef (başka bir depoda) bu hedefe bağımlı olduğunda veya komut satırında bu hedeften bahsedildiğinde yürütülür. Daha sonra uygulama işlevinin dosya sisteminde depoyu oluşturması beklenir. Buna depoyu "getirme" denir.

Normal hedeflerin aksine, deponun farklı olmasına neden olacak bir değişiklik olduğunda depolar tekrar getirilmez. Bunun nedeni, Bazel'ın değişiklikleri algılayamadığı veya her derlemede çok fazla ek yüke (ör. ağdan getirilen şeyler) yol açabilmesidir. 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 ürününün getenv() yöntemine iletilen veya repository_rule özelliğinin 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 doğrudan bağlanabilir.
  • Etiket tarafından başvurulan read(), execute() ve benzer repository_ctx yöntemlerine iletilen herhangi bir dosyanın içeriği (örneğin, mypkg/label.txt değil //mypkg:label.txt)
  • bazel fetch --force yürütüldüğünde.

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

  • configure işareti ayarlanırsa kod deposu, yalnızca --configure parametresi kendisine aktarıldığında bazel fetch tarihinde yeniden getirilir (özellik ayarlanmazsa bu komut yeniden getirme işlemine neden olmaz)
  • local işareti ayarlanırsa yukarıdaki durumlara ek olarak, Bazel sunucusu yeniden başlatıldığında depo da yeniden getirilir.

Uygulama işlevini yeniden başlatma

Uygulama işlevi, bir deponun istediği bir bağımlılık eksikse depo getirilirken yeniden başlatılabilir. Bu durumda, uygulama işlevinin yürütülmesi durdurulur, eksik bağımlılık çözülür ve bağımlılık çözüldükten sonra işlev yeniden yürütülür. Gereksiz yeniden başlatmalardan (ağ erişiminin tekrarlanması gerekebileceği için pahalıdır) önlemek için tüm etiket bağımsız değişkenlerinin mevcut bir dosyada çözümlenebilmesi koşuluyla etiket bağımsız değişkenleri önceden getirilir. Yalnızca işlevin yürütülmesi sırasında oluşturulan bir dizeden veya etiketten gelen bir yolun çözümlenmesinin yine de yeniden başlatmaya neden olabileceğini unutmayın.

Harici depoların yeniden getirilmesini zorunlu kılma

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, depo getirme kaynakları, üçüncü taraf deposunun belirli bir dalını izleyebilir ve yeni kaydetme işlemleri bu dalda kullanılabilir. Bu durumda, bazel fetch --force --all yöntemini çağırarak bazel'dan tüm harici depoları koşulsuz olarak yeniden getirmesini isteyebilirsiniz.

Dahası, bazı depo kuralları yerel makineyi inceler ve yerel makine yükseltilirse güncelliğini yitirebilir. Burada Bazel'dan yalnızca repository_rule tanımında configure özelliği ayarlanmış olan harici depoları yeniden getirmesini isteyebilirsiniz. bazel fetch --all --configure kullanın.

Örnekler

  • C++ otomatik yapılandırılmış araç zinciri: Yerel C++ derleyicisine, ortama ve C++ derleyicisinin desteklediği işaretlere bakarak 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 amacıyla çeşitli repository_rule kullanır.

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