Kod Deposu Kuralları

Sorun bildir Kaynağı göster

Bu sayfada kod deposu kurallarının nasıl oluşturulacağı ele alınmakta ve daha fazla ayrıntı için örnekler sağlanmaktadır.

Harici depo, yalnızca WORKSPACE dosyasında kullanılabilen ve Bazel'in yükleme aşamasında hermetik olmayan işlemleri etkinleştiren bir kuraldır. Her harici depo kuralı, kendi BUILD dosyaları ve yapılarıyla kendi çalışma alanı oluşturur. Üçüncü taraf kitaplıklara (ör. Maven paketlenmiş kitaplıkları) bağlı kalmanın yanı sıra Bazel'in çalıştığı ana makineye özel BUILD dosyaları oluşturmak için de kullanılabilirler.

Kod deposu kuralı oluşturma

Bir .bzl dosyasında yeni bir depo kuralı oluşturmak ve bu kuralı genel değişkende depolamak için repository_rule işlevini kullanın.

Özel depo kuralları, yerel depo kuralları gibi kullanılabilir. Zorunlu bir name özelliğine sahiptir ve derleme dosyalarında bulunan her hedef @<name>//package:target olarak kabul edilebilir. Burada <name>, name özelliğinin değeridir.

Kural, açık bir şekilde derlediğinizde veya derlemenin bir bağımlılığıysa yüklenir. Bu durumda, Bazel implementation işlevini yürütür. Bu işlevde deponun, içeriğinin ve BUILD dosyalarının nasıl oluşturulacağını açıklanmaktadır.

Özellikler

Özellik, attrs kuralı bağımsız değişkenine dikte olarak iletilen kural bağımsız değişkenleridir. Bir depo kuralı tanımladığınızda özellikler ve türleri tanımlanır. url ve sha256 özelliklerinin dize olarak tanımlandığı bir örnek:

local_repository = 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'ler, dolaylı olarak tanımlanmış özelliklere sahiptir (derleme kuralları gibi). İki örtülü özellik, name (oluşturma kurallarında olduğu gibi) ve repo_mapping'dir. Depo kuralının adına repository_ctx.name ile erişilebilir. repo_mapping öğesinin anlamı, yerel depo kuralları local_repository ve new_local_repository ile aynıdır.

Özellik adı _ ile başlıyorsa gizlidir ve kullanıcılar bu özelliği ayarlayamaz.

Uygulama işlevi

Her kod deposu 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 kuralı, aynı depoyu oluşturan tekrarlanabilir bir kurala dönüştürecek bir dizi parametre içeren dikte 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 bağlam için kitaplığa 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 deponun 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 yol açacak bir değişiklik olduğunda depolar yeniden 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ğıdaki durumlardan biri değişirse yeniden getirilir:

  • WORKSPACE dosyasındaki depo bildirimine iletilen parametreler.
  • Deponun uygulanmasını sağlayan Starlark kodu.
  • repository_rule öğesinin environ özelliğiyle tanımlanan herhangi bir ortam değişkeninin değeri. Bu ortam değişkenlerinin değerleri, komut satırına --action_env işaretiyle sabitlenebilir (ancak bu işaret, derlemenin her işlemini geçersiz kılar).
  • 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 sync 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 sync tarihinde yeniden getirilir (özellik ayarlanmazsa bu komut yeniden getirme işlemine neden olmaz)

  • local işareti ayarlanırsa yukarıdaki durumlara ek olarak, değişikliklerin depo veya kodunun beyanında bir değişikliğe yol açıp açmadığından bağımsız olarak, Bazel sunucusu yeniden başlatıldığında veya deponun beyanını etkileyen herhangi bir dosya değiştiğinde (ör. WORKSPACE dosyası veya yüklenen bir dosya) depo da yeniden getirilir.

    Bu durumlarda yerel olmayan depolar yeniden getirilmez. Bunun nedeni, bu depoların ağ ile iletişim kuracağı veya başka şekilde pahalı olduğu varsayılmasıdır.

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 bu dalda yeni kaydetme işlemleri kullanılabilir. Bu durumda, bazel sync çağrısı yaparak bazel'dan tüm harici depoları koşulsuz olarak yeniden getirmesini isteyebilirsiniz.

Ayrıca, bazı 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ğinin ayarlı olduğu harici depoları yeniden getirmesini isteyebilirsiniz. bazel sync --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.