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 oluşturulacağı açıklanmakta ve daha fazla bilgi için örnekler verilmektedir.

Harici depo, yalnızca WORKSPACE dosyasında kullanılabilen ve Bazel'in yükleme aşamasında hermetik olmayan işleme olanak tanıyan bir kuraldır. Her harici depo kuralı, kendi BUILD dosyaları ve yapıtlarıyla kendi çalışma alanını oluşturur. Üçüncü taraf kitaplıklara (ör. Maven paketli kitaplıklar) bağımlı olmak için ve Bazel'in üzerinde çalıştığı ana makineye özel BUILD dosyaları oluşturmak için kullanılabilirler.

Depo kuralı oluşturma

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

Özel depo kuralı, yerel depo kuralı gibi kullanılabilir. Zorunlu bir name özelliği vardır ve derleme dosyalarında bulunan her hedef, @<name>//package:target olarak adlandırılabilir. Burada <name>, name özelliğinin değeridir.

Kural, açıkça oluşturduğunuzda veya derlemenin bağımlılığı olduğunda yüklenir. Bu durumda Bazel, implementation işlevini yürütür. Bu işlev, depoyu, içeriğini ve BUILD dosyalarını nasıl oluşturacağınızı açıklar.

Özellikler

Özellikler, attrs kural bağımsız değişkenine sözlük olarak aktarılan kural bağımsız değişkenleridir. Bir depo kuralı tanımladığınızda, tanımlanan özellikler ve türleri listelenir. url ve sha256 özelliklerini dize olarak tanımlayan 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> kullanın:

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

Tüm repository_rule'lerin örtülü olarak tanımlanmış özellikleri vardır (tıpkı derleme kurallarında olduğu gibi). İki örtülü özellik vardır: name (derleme kurallarında olduğu gibi) ve repo_mapping. Depo kuralının adına repository_ctx.name ile erişilebilir. repo_mapping, yerel depo kuralları local_repository ve new_local_repository ile aynı anlama gelir.

Bir özellik adı _ ile başlıyorsa bu özellik özeldir ve kullanıcılar tarafından ayarlanamaz.

Uygulama işlevi

Her depo kuralı için 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 bağlam bilgisi 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'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 depoyu oluşturması beklenir. Buna, depoyu "getirme" adı verilir.

Normal hedeflerin aksine, depoda farklılığa neden olacak bir değişiklik olduğunda depolar yeniden getirilmez. Bunun nedeni, Bazel'in değişiklikleri algılayamadığı veya her derlemede çok fazla ek yük oluşturacağı (ör. ağdan getirilen öğeler) öğelerin olmasıdır. Bu nedenle, depolar yalnızca aşağıdaki durumlardan biri değiştiğinde yeniden getirilir:

  • WORKSPACE dosyasında deponun bildirimi için aktarılan parametreler.
  • Deponun 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.
  • read(), execute() ve benzeri repository_ctx yöntemlerine iletilen ve bir etiketle (ör. //mypkg:label.txt ancak mypkg/label.txt değil) belirtilen tüm dosyaların içeriği
  • bazel sync 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 yalnızca --configure parametresi iletildiğinde bazel sync üzerinde yeniden getirilir (özellik ayarlanmamışsa bu komut yeniden getirme işlemine neden olmaz).

  • local işareti ayarlanırsa yukarıdaki durumlara ek olarak, değişikliklerin deponun bildiriminde veya kodunda değişikliğe neden olup olmadığına bakılmaksızın, Bazel sunucusu yeniden başlatıldığında ya da deponun bildirimini etkileyen herhangi bir dosya (ör. WORKSPACE dosyası veya yüklediği bir dosya) değiştiğinde de depo yeniden getirilir.

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

Uygulama işlevini yeniden başlatma

İstenen bir bağımlılık eksikse, bir depo getirilmeye devam ederken uygulama işlevi 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şlatmaları (ağ erişiminin tekrarlanması gerekebileceğinden maliyetli olabilir) önlemek için, tüm etiket bağımsız değişkenleri mevcut bir dosyaya çözümlenebiliyorsa etiket bağımsız değişkenleri önceden getirilir. Yalnızca işlev yürütülürken oluşturulan bir dizeden veya etiketten yolu çözmenin yine de yeniden başlatmaya neden olabileceğini unutmayın.

Harici depoların yeniden getirilmesini zorlama

Bazen, tanımında veya bağımlılıklarında herhangi bir değişiklik yapılmadan harici bir depo eski hale gelebilir. Örneğin, kaynakları getiren bir depo, üçüncü taraf deposunun belirli bir dalını takip edebilir ve bu dalda yeni işlemeler kullanılabilir. Bu durumda, bazel sync işlevini çağırarak Bazel'den 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, yalnızca repository_rule tanımında configure özelliği ayarlanmış olan harici depoları yeniden getirmesini isteyebilirsiniz. Bunun için bazel sync --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.