Bazel modülleri

Bazel modülü, birden fazla sürümü olabilecek bir Bazel projesidir. Her sürüm, bağlı olduğu diğer modüller hakkında meta veriler yayınlar. Bu, Maven öğesi, npm paketi, Go modülü veya Cargo kutusu gibi diğer bağımlılık yönetimi sistemlerindeki bilinen kavramlara benzer.

Bir modülün kod deposu kökünde bir MODULE.bazel dosyası olmalıdır. Bu dosya, modülün adını, sürümünü, doğrudan bağımlılıklarının listesini ve diğer bilgileri açıklayan manifest dosyasıdır. Temel bir örnek için:

module(name = "my-module", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

MODULE.bazel dosyalarında kullanılabilen yönergelerin tam listesine bakın.

Bazel, modül çözümlemeyi gerçekleştirmek için kök modülün MODULE.bazel dosyasını okuyarak başlar ve ardından bağımlılık grafiğinin tamamını keşfedene kadar Bazel kayıt otoritesinden tüm bağımlılıkların MODULE.bazel dosyasını tekrar tekrar ister.

Ardından Bazel, varsayılan olarak her modülün kullanılacak bir sürümünü seçer. Bazel, her modülü bir depoyla temsil eder ve depoların her birinin nasıl tanımlanacağını öğrenmek için kayıt defterine tekrar başvurur.

Sürüm biçimi

Bazel'in çeşitli bir ekosistemi vardır ve projelerde çeşitli sürümlendirme şemaları kullanılır. Şu ana kadar en popüler olan SemVer olsa da farklı şemaların kullanıldığı önemli projeler de vardır. Örneğin 20210324.2 gibi versiyonları tarih tabanlı olan Abseil).

Bu nedenle Bzlmod, SemVer spesifikasyonunun daha esnek bir sürümünü kullanır. Farklılıklar şunlardır:

  • SemVer, sürümün "yayın" bölümünün 3 segmentten oluşması gerektiğini belirtir: MAJOR.MINOR.PATCH. Bazel'de bu şart, herhangi bir sayıda segmente izin verecek şekilde gevşetilmiştir.
  • SemVer'de, "sürüm" bölümündeki segmentlerin her biri yalnızca rakamlardan oluşmalıdır. Bazel'de bu değer harflere izin verecek şekilde gevşetilir ve karşılaştırma anlamı, "yayın öncesi" bölümündeki "tanımlayıcılar" ile eşleşir.
  • Ayrıca, ana, alt ve yama sürümü artışlarının semantikleri zorunlu kılınmaz. Ancak geriye dönük uyumluluğu nasıl belirttiğimizle ilgili ayrıntılar için uyumluluk düzeyi bölümüne bakın.

Geçerli herhangi bir SemVer sürümü, geçerli bir Bazel modülü sürümüdür. Ayrıca, iki SemVer sürümü a ve b, Bazel modülü sürümleri olarak karşılaştırıldığında aynı sonucu verirse ve yalnızca bu durumda a < b ile karşılaştırılır.

Sürüm seçimi

Sürümlü bağımlılık yönetimi alanının vazgeçilmez bir parçası olan elmas bağımlılık problemini düşünün. Aşağıdaki gibi bir bağımlılık grafiğiniz olduğunu varsayalım:

       A 1.0
      /     \
   B 1.0    C 1.1
     |        |
   D 1.0    D 1.1

Hangi D sürümü kullanılmalıdır? Bzlmod, bu soruyu yanıtlamak için Go modül sisteminde sunulan Minimal Sürüm Seçimi (MVS) algoritmasını kullanıyor. MVS, bir modülün tüm yeni sürümlerinin geriye dönük uyumlu olduğunu varsayar ve bu nedenle bağımlı öğeler tarafından belirtilen en yüksek sürümü seçer (örneğimizde D 1.1). D 1.1, gereksinimlerimizi karşılayabilecek en eski sürüm olduğu için "minimum" olarak adlandırılır. D 1.2 veya daha yeni sürümler olsa bile bunları seçmeyiz. MVS kullanılması, yüksek kaliteli ve tekrarlanabilir bir sürüm seçme süreci oluşturur.

Yanklanan sürümler

Kayıt defteri, belirli sürümlerin kullanılmasından kaçınılması gerekiyorsa (ör. güvenlik açıkları nedeniyle) bu sürümleri geri çekilmiş olarak tanımlayabilir. Bazel bir modülün yankılı sürümünü seçerken hata verir. Bu hatayı düzeltmek için yayından kaldırılmamış, daha yeni bir sürüme geçin veya yayından kaldırılmış sürüme açıkça izin vermek için --allow_yanked_versions işaretini kullanın.

Uyumluluk seviyesi

Go'da MVS'nin geriye dönük uyumlulukla ilgili varsayımı, bir modülün geriye dönük uyumlu olmayan sürümlerini ayrı bir modül olarak ele aldığı için işe yarar. SemVer açısından bu, A 1.x ve A 2.x'ün farklı modüller olarak kabul edildiği ve çözülmüş bağımlılık grafiğinde birlikte bulunabileceği anlamına gelir. Bu da Go'da paket yolunda ana sürümün kodlanmasıyla mümkün olur. Böylece, herhangi bir derleme zamanı veya bağlantı zamanı çakışması olmaz.

Ancak Bazel bu tür garantiler sağlayamaz. Bu nedenle, geriye dönük uyumlu olmayan sürümleri algılamak için "büyük sürüm" numarasına ihtiyacı vardır. Bu sayıya uyumluluk düzeyi denir ve her modül sürümü tarafından module() yönergesinde belirtilir. Bazel, bu bilgilerle, çözülmüş bağımlılık grafiğinde aynı modülün farklı uyumluluk düzeylerine sahip sürümlerinin bulunduğunu tespit ettiğinde hata verebilir.

Geçersiz kılar:

Bazel modül çözümlemesinin davranışını değiştirmek için MODULE.bazel dosyasında geçersiz kılma işlemlerini belirtin. Yalnızca kök modülün geçersiz kılma işlemleri geçerli olur. Bir modül bağımlılık olarak kullanılırsa geçersiz kılma işlemleri dikkate alınmaz.

Her geçersiz kılma, bağımlılık grafiğindeki tüm sürümlerini etkileyen belirli bir modül adı için belirtilir. Yalnızca kök modülün geçersiz kılma işlemleri geçerli olsa da bu geçersiz kılma işlemleri, kök modülün doğrudan bağlı olmadığı geçişli bağımlılar için olabilir.

Tek sürümü geçersiz kılma

single_version_override, birden çok amaca hizmet eder:

  • version özelliğiyle, bağımlılığın hangi sürümlerinin bağımlılığı grafiğinde istendiğine bakılmaksızın bir bağımlılığı belirli bir sürüme sabitleyebilirsiniz.
  • registry özelliğiyle, normal kayıt defteri seçim sürecini izlemek yerine bu bağımlılığın belirli bir kayıt defteri tarafından sağlanmasını zorunlu kılabilirsiniz.
  • patch* özellikleriyle, indirilen modüle uygulanacak bir dizi yamayı belirtebilirsiniz.

Bu özelliklerin tümü isteğe bağlıdır ve birbirleriyle karıştırılabilir ve eşleştirilebilir.

Birden çok sürümü geçersiz kılma

Çözüme ulaştırılan bağımlılık grafiğinde aynı modülün birden fazla sürümünün birlikte var olmasına izin vermek için bir multiple_version_override belirtilebilir.

Modül için izin verilen sürümlerin açık bir listesini belirtebilirsiniz. Bu sürümlerin tümü, çözümden önce bağımlılık grafiğinde bulunmalıdır. İzin verilen her sürüme bağlı olarak bir geçişli bağımlılık bulunmalıdır. Çözümün ardından, modülün yalnızca izin verilen sürümleri kalır. Bazel ise modülün diğer sürümlerini aynı uyumluluk düzeyinde izin verilen en yakın üst sürüme yükseltir. Aynı uyumluluk düzeyinde izin verilen daha yüksek bir sürüm yoksa Bazel hata verir.

Örneğin, çözümden önce bağımlılık grafiğinde 1.1, 1.3, 1.5, 1.7 ve 2.0 sürümleri mevcutsa ve ana sürüm uyumluluk düzeyiyse:

  • 1.3, 1.7 ve 2.0'ye izin veren birden fazla sürümün geçersiz kılınması, 1.1'in 1.3, 1.5'in 1.7 sürümüne yükseltilmesine ve diğer sürümlerin aynı kalmasına neden olur.
  • 1.7 için aynı uyumluluk düzeyinde yükseltme yapılabilecek daha yüksek bir sürüm olmadığından, 1.5 ve 2.0 özelliklerine izin veren birden çok sürümün geçersiz kılınması hatayla sonuçlanır.
  • Çözümden önce bağımlılık grafiğinde 1.9 bulunmadığı için 1.9 ve 2.0'e izin veren birden fazla sürüm geçersiz kılma işlemi hata verir.

Ayrıca kullanıcılar, tek sürüm geçersiz kılma işlemlerine benzer şekilde registry özelliğini kullanarak kayıt defterini geçersiz kılabilir.

Kayıt otoritesi dışı geçersiz kılma işlemleri

Kayıt dışı geçersiz kılma işlemleri, bir modülü sürüm çözünürlüğünden tamamen kaldırır. Bazel, bu MODULE.bazel dosyalarını bir kayıt defterinden değil, deponun kendisinden ister.

Bazel, aşağıdaki kayıt defteri dışı geçersiz kılma işlemlerini destekler:

Bazel modüllerini temsil etmeyen depoları tanımlama

bazel_dep ile diğer Bazel modüllerini temsil eden depolar tanımlayabilirsiniz. Bazen Bazel modülü olmayan bir depo tanımlamanız gerekir. Örneğin, veri olarak okunacak düz bir JSON dosyası içeren bir depo.

Bu durumda, depo kuralı çağırarak depoyu doğrudan tanımlamak için use_repo_rule yönergesini kullanabilirsiniz. Bu depo yalnızca tanımlandığı modül tarafından görülebilir.

Bu özellik, modül uzantılarıyla aynı mekanizma kullanılarak uygulanır. Bu sayede, depoları daha fazla esneklikle tanımlayabilirsiniz.

Depo adları ve katı bağımlılar

Bir modülü doğrudan bağımlılarına destekleyen bir deponun görünür adı, bazel_dep yönergesinin repo_name özelliği aksini belirtmediği sürece varsayılan olarak modül adıdır. Bu, bir modülün yalnızca doğrudan bağımlılarını bulabileceği anlamına gelir. Bu, geçişli bağımlılıklardaki değişiklikler nedeniyle yanlışlıkla oluşabilecek kesintileri önlemeye yardımcı olur.

Bir modülü destekleyen deponun standart adı, bağımlılık grafiğinde modülün birden fazla sürümü olup olmamasına bağlı olarak module_name~version (örneğin, bazel_skylib~1.0.3) veya module_name~ (örneğin bazel_features~) şeklindedir (bkz. multiple_version_override). Standart ad biçiminin kullanmanız gereken bir API olmadığını ve her zaman değişebileceğini unutmayın. Kanonik adı sabit kodlamak yerine, doğrudan Bazel'den almak için desteklenen bir yöntem kullanın: * BUILD ve .bzl dosyalarında, Label.repo_name değerini, deponun görünen adı tarafından verilen bir etiket dizesinden oluşturulan bir Label örneğinde kullanın. Örneğin: Label("@bazel_skylib").repo_name. * Çalıştırma dosyalarını ararken $(rlocationpath ...) ya da @bazel_tools//tools/{bash,cpp,java}/runfiles hizmetindeki veya bir kural kümesi rules_foo olan @rules_foo//foo/runfiles içindeki çalıştırma dosyaları kitaplıklarından birini kullanın. * IDE veya dil sunucusu gibi harici bir araçtan Bazel ile etkileşim kurarken belirli bir depo grubu için görünen adlardan standart adlara eşlemeyi almak için bazel mod dump_repo_mapping komutunu kullanın.

Modül uzantıları, bir modülün görünür kapsamına ek depolar da sağlayabilir.