Bzlmod, WORKSPACE'in eksiklikleri nedeniyle eski WORKSPACE sisteminin yerini alıyor. WORKSPACE dosyası Bazel 8'de (2024'ün sonlarında) devre dışı bırakıldı ve Bazel 9'da (2025'in sonlarında) kaldırılacak. Bu kılavuz, projenizi Bzlmod'a taşımanıza ve harici bağımlılıkları yönetmek için WORKSPACE'i bırakmanıza yardımcı olur.
Neden Bzlmod'a geçmelisiniz?
Eski WORKSPACE sistemine kıyasla birçok avantajı vardır. Bu avantajlar, Bazel ekosisteminin sağlıklı büyümesini sağlar.
Projeniz diğer projelerin bağımlılığıysa Bzlmod'a geçiş, bu projelerin geçişini engellemeyi kaldırır ve projenize bağımlı olmalarını kolaylaştırır.
Gelecekteki Bazel sürümlerini kullanmak için Bzlmod'a geçiş yapılması gerekir (Bazel 9'da zorunludur).
WORKSPACE ve Bzlmod karşılaştırması
Bazel'in WORKSPACE ve Bzlmod'u, farklı söz dizimleriyle benzer özellikler sunar. Bu bölümde, belirli WORKSPACE işlevlerinden Bzlmod'a nasıl geçiş yapılacağı açıklanmaktadır.
Bazel çalışma alanının kökünü tanımlama
WORKSPACE dosyası, Bazel projesinin kaynak kökünü işaretler. Bu sorumluluk, Bazel 6.3 ve sonraki sürümlerde MODULE.bazel ile değiştirilir. 6.3'ten önceki Bazel sürümlerinde, çalışma alanınızın kök dizininde WORKSPACE
veya WORKSPACE.bazel
dosyası bulunmalıdır. Bu dosyada aşağıdaki gibi yorumlar olabilir:
WORKSPACE
# This file marks the root of the Bazel workspace. # See MODULE.bazel for external dependencies setup.
bazelrc dosyanızda Bzlmod'u etkinleştirin.
.bazelrc
, Bazel'i her çalıştırdığınızda geçerli olacak işaretler ayarlamanıza olanak tanır. Bzlmod'u etkinleştirmek için --enable_bzlmod
işaretini kullanın ve her komuta uygulanması için common
komutuna uygulayın:
.bazelrc
# Enable Bzlmod for every Bazel command common --enable_bzlmod
Çalışma alanınız için depo adını belirtin
WORKSPACE
workspace
işlevi, çalışma alanınız için bir depo adı belirtmek üzere kullanılır. Bu, çalışma alanındaki bir hedef//foo:bar
öğesinin@<workspace name>//foo:bar
olarak referans verilmesine olanak tanır. Belirtilmezse çalışma alanınızın varsayılan depo adı__main__
olur.## WORKSPACE workspace(name = "com_foo_bar")
Bzlmod
@<repo name>
olmadan//foo:bar
söz dizimiyle aynı çalışma alanındaki hedeflere referans verilmesi önerilir. Ancak eski söz dizimine ihtiyacınız varsamodule
işlevi tarafından belirtilen modül adını depo adı olarak kullanabilirsiniz. Modül adı, gerekli depo adından farklıysa depo adını geçersiz kılmak içinmodule
işlevininrepo_name
özelliğini kullanabilirsiniz.## MODULE.bazel module( name = "bar", repo_name = "com_foo_bar", )
Harici bağımlılıkları Bazel modülleri olarak getirme
Bağımlılığınız bir Bazel projesiyse Bzlmod'u da kullandığında Bazel modülü olarak bağımlı olabilirsiniz.
WORKSPACE
WORKSPACE ile Bazel projesinin kaynaklarını indirmek için
http_archive
veyagit_repository
depo kurallarını kullanmak yaygındır.## WORKSPACE load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "bazel_skylib", urls = ["https://github.com/bazelbuild/bazel-skylib/releases/download/1.4.2/bazel-skylib-1.4.2.tar.gz"], sha256 = "66ffd9315665bfaafc96b52278f57c7e2dd09f5ede279ea6d39b2be471e7e3aa", ) load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() http_archive( name = "rules_java", urls = ["https://github.com/bazelbuild/rules_java/releases/download/6.1.1/rules_java-6.1.1.tar.gz"], sha256 = "76402a50ae6859d50bd7aed8c1b8ef09dae5c1035bb3ca7d276f7f3ce659818a", ) load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains") rules_java_dependencies() rules_java_toolchains()
Gördüğünüz gibi, kullanıcıların bağımlılığın makrosundan geçişli bağımlılıkları yüklemesi yaygın bir durumdur. Hem
bazel_skylib
hem derules_java
öğesininplatform
öğesine bağlı olduğunu varsayarsakplatform
bağımlılığının tam sürümü makroların sırasına göre belirlenir.Bzlmod
Bzlmod ile bağımlılığınız Bazel Central Registry'de veya özel Bazel kayıt defterinizde olduğu sürece
bazel_dep
yönergesiyle bağımlılığınızı kullanabilirsiniz.## MODULE.bazel bazel_dep(name = "bazel_skylib", version = "1.4.2") bazel_dep(name = "rules_java", version = "6.1.1")
Bzlmod, Bazel modülü bağımlılıklarını MVS algoritmasını kullanarak geçişli olarak çözer. Bu nedenle,
platform
için gereken maksimum sürüm otomatik olarak seçilir.
Bağımlılığı Bazel modülü olarak geçersiz kılma
Kök modül olarak, Bazel modülü bağımlılıklarını farklı şekillerde geçersiz kılabilirsiniz.
Daha fazla bilgi için lütfen geçersiz kılmalar bölümünü okuyun.
Bazı örnek kullanımları örnekler deposunda bulabilirsiniz.
Modül uzantılarıyla harici bağımlılıkları getirme
Bağımlılığınız bir Bazel projesi değilse veya henüz herhangi bir Bazel kayıt defterinde mevcut değilse use_repo_rule
veya modül uzantılarını kullanarak bağımlılığınızı tanıtabilirsiniz.
WORKSPACE
http_file
depo kuralını kullanarak dosya indirme## WORKSPACE load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") http_file( name = "data_file", url = "http://example.com/file", sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", )
Bzlmod
Bzlmod ile, depoları doğrudan oluşturmak için MODULE.bazel dosyanızda
use_repo_rule
yönergesini kullanabilirsiniz:## MODULE.bazel http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") http_file( name = "data_file", url = "http://example.com/file", sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", )
Bu özellik, arka planda bir modül uzantısı kullanılarak uygulanır. Yalnızca bir depo kuralını çağırmaktan daha karmaşık bir mantık uygulamanız gerekiyorsa modül uzantısını kendiniz de uygulayabilirsiniz. Tanımı
.bzl
dosyasına taşımanız gerekir. Bu dosya, taşıma döneminde tanımı WORKSPACE ve Bzlmod arasında paylaşmanıza da olanak tanır.## repositories.bzl load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") def my_data_dependency(): http_file( name = "data_file", url = "http://example.com/file", sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", )
Bağımlılıklar makrosunu yüklemek için bir modül uzantısı uygulayın. Makronun
.bzl
dosyası içinde tanımlayabilirsiniz ancak eski Bazel sürümleriyle uyumluluğu korumak için ayrı bir.bzl
dosyasında tanımlamanız daha iyi olur.## extensions.bzl load("//:repositories.bzl", "my_data_dependency") def _non_module_dependencies_impl(_ctx): my_data_dependency() non_module_dependencies = module_extension( implementation = _non_module_dependencies_impl, )
Deponun kök projede görünür olması için MODULE.bazel dosyasında modül uzantısının ve deponun kullanımlarını bildirmeniz gerekir.
## MODULE.bazel non_module_dependencies = use_extension("//:extensions.bzl", "non_module_dependencies") use_repo(non_module_dependencies, "data_file")
Modül uzantısıyla harici bağımlılık çakışmalarını çözme
Bir proje, arayanlardan gelen girişlere göre harici depoları tanıtan bir makro sağlayabilir. Ancak bağımlılık grafiğinde birden fazla arayan varsa ve bunlar çakışmaya neden oluyorsa ne olur?
foo
projesinin, version
değerini bağımsız değişken olarak alan aşağıdaki makroyu sağladığını varsayalım.
## repositories.bzl in foo {:#repositories.bzl-foo}
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def data_deps(version = "1.0"):
http_file(
name = "data_file",
url = "http://example.com/file-%s" % version,
# Omitting the "sha256" attribute for simplicity
)
WORKSPACE
WORKSPACE ile makroyu
@foo
konumundan yükleyebilir ve ihtiyacınız olan veri bağımlılığı sürümünü belirtebilirsiniz.@foo
öğesine bağlı olan ancak farklı bir veri bağımlılığı sürümü gerektiren başka bir bağımlılığınız@bar
olduğunu varsayalım.## WORKSPACE # Introduce @foo and @bar. ... load("@foo//:repositories.bzl", "data_deps") data_deps(version = "2.0") load("@bar//:repositories.bzl", "bar_deps") bar_deps() # -> which calls data_deps(version = "3.0")
Bu durumda, son kullanıcının ihtiyacı olan sürümü elde etmek için WORKSPACE'teki makroların sırasını dikkatli bir şekilde ayarlaması gerekir. WORKSPACE'in bağımlılıkları çözmek için mantıklı bir yol sunmaması, en büyük sorunlarından biridir.
Bzlmod
Bzlmod ile
foo
projesinin yazarı, çakışmaları çözmek için modül uzantısını kullanabilir. Örneğin, tüm Bazel modülleri arasında her zaman veri bağımlılığının gereken maksimum sürümünü seçmenin mantıklı olduğunu varsayalım.## extensions.bzl in foo load("//:repositories.bzl", "data_deps") data = tag_class(attrs={"version": attr.string()}) def _data_deps_extension_impl(module_ctx): # Select the maximal required version in the dependency graph. version = "1.0" for mod in module_ctx.modules: for data in mod.tags.data: version = max(version, data.version) data_deps(version) data_deps_extension = module_extension( implementation = _data_deps_extension_impl, tag_classes = {"data": data}, )
## MODULE.bazel in bar bazel_dep(name = "foo", version = "1.0") foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension") foo_data_deps.data(version = "3.0") use_repo(foo_data_deps, "data_file")
## MODULE.bazel in root module bazel_dep(name = "foo", version = "1.0") bazel_dep(name = "bar", version = "1.0") foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension") foo_data_deps.data(version = "2.0") use_repo(foo_data_deps, "data_file")
Bu durumda, kök modülün
2.0
veri sürümü gerekirken bağımlılığıbar
için3.0
sürümü gerekir.foo
içindeki modül uzantısı bu çakışmayı doğru şekilde çözebilir ve veri bağımlılığı için3.0
sürümünü otomatik olarak seçebilir.
Üçüncü taraf paket yöneticisini entegre etme
Son bölümün ardından, modül uzantısı bağımlılık grafiğinden bilgi toplama yolu sağladığından, bağımlılıkları çözmek için özel mantık yürütün ve harici depoları tanıtmak için depo kurallarını çağırın. Bu, kural yazarlarının belirli diller için paket yöneticilerini entegre eden kural kümelerini geliştirmeleri için harika bir yol sağlar.
Modül uzantılarını kullanma hakkında daha fazla bilgi edinmek için lütfen modül uzantıları sayfasını okuyun.
Bağımlılıkları farklı paket yöneticilerinden getirmek için Bzlmod'u zaten kullanan kural kümelerinin listesini aşağıda bulabilirsiniz:
Sözde paket yöneticisi entegre eden en basit örneği examples deposunda bulabilirsiniz.
Ana makinede araç zincirlerini algılama
Bazel derleme kurallarının, ana makinenizde hangi araç zincirlerinin bulunduğunu tespit etmesi gerektiğinde ana makineyi incelemek ve araç zinciri bilgilerini harici depolar olarak oluşturmak için depo kurallarını kullanır.
WORKSPACE
Bir kabuk araç zincirini algılamak için aşağıdaki depo kuralı verilmiştir.
## local_config_sh.bzl def _sh_config_rule_impl(repository_ctx): sh_path = get_sh_path_from_env("SH_BIN_PATH") if not sh_path: sh_path = detect_sh_from_path() if not sh_path: sh_path = "/shell/binary/not/found" repository_ctx.file("BUILD", """ load("@bazel_tools//tools/sh:sh_toolchain.bzl", "sh_toolchain") sh_toolchain( name = "local_sh", path = "{sh_path}", visibility = ["//visibility:public"], ) toolchain( name = "local_sh_toolchain", toolchain = ":local_sh", toolchain_type = "@bazel_tools//tools/sh:toolchain_type", ) """.format(sh_path = sh_path)) sh_config_rule = repository_rule( environ = ["SH_BIN_PATH"], local = True, implementation = _sh_config_rule_impl, )
Depo kuralını WORKSPACE'e yükleyebilirsiniz.
## WORKSPACE load("//:local_config_sh.bzl", "sh_config_rule") sh_config_rule(name = "local_config_sh")
Bzlmod
Bzlmod ile, son bölümde
@data_file
deposunu kullanmaya benzer şekilde, modül uzantısı kullanarak aynı depoyu kullanabilirsiniz.## local_config_sh_extension.bzl load("//:local_config_sh.bzl", "sh_config_rule") sh_config_extension = module_extension( implementation = lambda ctx: sh_config_rule(name = "local_config_sh"), )
Ardından, uzantıyı MODULE.bazel dosyasında kullanın.
## MODULE.bazel sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension") use_repo(sh_config_ext, "local_config_sh")
Araç zincirlerini ve yürütme platformlarını kaydetme
Son bölümün ardından, bir depo barındırma araç zinciri bilgisi (ör. local_config_sh
) sunduktan sonra araç zincirini kaydetmek isteyebilirsiniz.
WORKSPACE
WORKSPACE ile araç zincirini aşağıdaki şekillerde kaydedebilirsiniz.
Araç zincirini
.bzl
dosyasıyla kaydedebilir ve makroyu WORKSPACE dosyasına yükleyebilirsiniz.## local_config_sh.bzl def sh_configure(): sh_config_rule(name = "local_config_sh") native.register_toolchains("@local_config_sh//:local_sh_toolchain")
## WORKSPACE load("//:local_config_sh.bzl", "sh_configure") sh_configure()
Alternatif olarak, araç zincirini doğrudan WORKSPACE dosyasında kaydedebilirsiniz.
## WORKSPACE load("//:local_config_sh.bzl", "sh_config_rule") sh_config_rule(name = "local_config_sh") register_toolchains("@local_config_sh//:local_sh_toolchain")
Bzlmod
Bzlmod ile
register_toolchains
veregister_execution_platforms
API'leri yalnızca MODULE.bazel dosyasında kullanılabilir. Bir modül uzantısındanative.register_toolchains
işlevini çağıramazsınız.## MODULE.bazel sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension") use_repo(sh_config_ext, "local_config_sh") register_toolchains("@local_config_sh//:local_sh_toolchain")
WORKSPACE
,
WORKSPACE.bzlmod
içinde kaydedilen araç zincirleri ve yürütme platformları ile her Bazel modülünün MODULE.bazel
dosyası, araç zinciri seçimi sırasında aşağıdaki öncelik sırasını (en yüksekten en düşüğe) izler:
- Kök modülün
MODULE.bazel
dosyasında kayıtlı araç zincirleri ve yürütme platformları. WORKSPACE
veyaWORKSPACE.bzlmod
dosyasına kaydedilen araç zincirleri ve yürütme platformları.- Kök modülün (geçişli) bağımlılıkları olan modüller tarafından kaydedilen araç zincirleri ve yürütme platformları.
WORKSPACE.bzlmod
kullanılmadığında:WORKSPACE.bzlmod
sonekiyle kaydedilen araç zincirleri.WORKSPACE
Yerel depoları tanıtma
Hata ayıklama için bağımlılığın yerel bir sürümüne ihtiyacınız olduğunda veya çalışma alanınızdaki bir dizini harici depo olarak dahil etmek istediğinizde bağımlılığı yerel depo olarak tanıtmanız gerekebilir.
WORKSPACE
WORKSPACE'te bu, iki yerel depo kuralı olan
local_repository
venew_local_repository
ile sağlanır.## WORKSPACE local_repository( name = "rules_java", path = "/Users/bazel_user/workspace/rules_java", )
Bzlmod
Bzlmod ile
local_path_override
kullanarak bir modülü yerel yolla geçersiz kılabilirsiniz.## MODULE.bazel bazel_dep(name = "rules_java") local_path_override( module_name = "rules_java", path = "/Users/bazel_user/workspace/rules_java", )
Modül uzantılı yerel bir depo da kullanabilirsiniz. Ancak modül uzantısında
native.local_repository
işlevini çağıramazsınız. Tüm yerel depo kurallarını Starlark'a dönüştürme çalışmaları devam etmektedir (ilerleme durumu için #18285 numaralı sorunu inceleyin). Ardından, bir modül uzantısında ilgili starlarklocal_repository
işlevini çağırabilirsiniz. Bu durum sizin için engelleyici bir sorunsalocal_repository
deposu kuralının özel bir sürümünü uygulamak da kolaydır.
Bağlama hedefleri
WORKSPACE'teki bind
kuralı kullanımdan kaldırıldı ve Bzlmod'da desteklenmiyor. Bu özellik, özel //external
paketinde bir hedefe takma ad vermek için kullanıma sunulmuştur. Buna bağlı olan tüm kullanıcılar geçiş yapmalıdır.
Örneğin, abone sayınız
## WORKSPACE
bind(
name = "openssl",
actual = "@my-ssl//src:openssl-lib",
)
Bu, diğer hedeflerin //external:openssl
'ya bağlı olmasına olanak tanır. Aşağıdaki yöntemleri kullanarak bu durumdan kurtulabilirsiniz:
//external:openssl
ifadesinin tüm kullanımlarını@my-ssl//src:openssl-lib
ile değiştirin.- İpucu: Hedefle ilgili alakalı bilgileri bulmak için
bazel query --output=build --noenable_bzlmod --enable_workspace [target]
komutunu kullanın.
- İpucu: Hedefle ilgili alakalı bilgileri bulmak için
Veya
alias
kural oluşturma özelliğini kullanın.Pakette aşağıdaki hedefi tanımlayın (ör.
//third_party
).## third_party/BUILD alias( name = "openssl", actual = "@my-ssl//src:openssl-lib", )
//external:openssl
ifadesinin tüm kullanımlarını//third_party:openssl
ile değiştirin.
Getirme ve senkronizasyon arasındaki fark
Harici depoları yerel olarak indirip güncel tutmak için getirme ve senkronize etme komutları kullanılır. Bazen de derleme için gereken tüm depolar getirildikten sonra --nofetch
işaretini kullanarak çevrimdışı derlemeye izin vermek için kullanılır.
WORKSPACE
Senkronizasyon, tüm depolar veya belirli bir yapılandırılmış depo grubu için zorunlu getirme işlemi gerçekleştirirken getirme işlemi yalnızca belirli bir hedef için getirme işlemi yapmak üzere kullanılır.
Bzlmod
Senkronizasyon komutu artık geçerli değil ancak getirme işlemi çeşitli seçenekler sunar. Bir hedefi, depoyu, yapılandırılmış bir dizi depoyu veya bağımlılık çözümlemenize ve modül uzantılarınıza dahil olan tüm depoları getirebilirsiniz. Getirme sonucu önbelleğe alınır ve getirme işlemini zorlamak için getirme işlemi sırasında
--force
seçeneğini eklemeniz gerekir.
Taşıma
Bu bölümde, Bzlmod'a geçiş sürecinizle ilgili faydalı bilgiler ve rehberlik sağlanmaktadır.
WORKSPACE'teki bağımlılıklarınızı öğrenme
Taşıma işleminin ilk adımı, sahip olduğunuz bağımlılıkları anlamaktır. Geçişli bağımlılıklar genellikle *_deps
makrolarıyla yüklendiğinden WORKSPACE dosyasında hangi bağımlılıkların kullanıldığını belirlemek zor olabilir.
Çalışma alanında çözümlenen dosyayla harici bağımlılığı inceleme
Neyse ki --experimental_repository_resolved_file
işareti bu konuda yardımcı olabilir. Bu işaret, son Bazel komutunuzda getirilen tüm harici bağımlılıkların bir "kilit dosyasını" oluşturur. Daha fazla bilgiyi bu blog yayınında bulabilirsiniz.
İki şekilde kullanılabilir:
Belirli hedeflerin oluşturulması için gereken harici bağımlılıkların bilgilerini getirmek için kullanılır.
bazel clean --expunge bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
WORKSPACE dosyasında tanımlanan tüm harici bağımlılıkların bilgilerini getirmek için.
bazel clean --expunge bazel sync --experimental_repository_resolved_file=resolved.bzl
bazel sync
komutuyla, WORKSPACE dosyasında tanımlanan tüm bağımlılıkları (aşağıdakiler dahil) getirebilirsiniz:bind
kullanımlarıregister_toolchains
veregister_execution_platforms
kullanım
Ancak projeniz platformlar arasıysa bazı depo kuralları yalnızca desteklenen platformlarda doğru şekilde çalışabileceğinden Bazel senkronizasyonu belirli platformlarda bozulabilir.
Komutu çalıştırdıktan sonra, resolved.bzl
dosyasında harici bağımlılıklarınızla ilgili bilgiler yer alır.
bazel query
ile harici bağımlılığı inceleyin
bazel query
ile depo kurallarını incelemek için de kullanılabileceğini biliyor olabilirsiniz.
bazel query --output=build //external:<repo name>
Daha rahat ve çok daha hızlı olsa da bazel query, harici bağımlılık sürümü hakkında yalan söyleyebilir. Bu nedenle, kullanırken dikkatli olun. Bzlmod ile harici bağımlılıkları sorgulama ve inceleme işlemi yeni bir alt komut aracılığıyla gerçekleştirilecek.
Yerleşik varsayılan bağımlılıklar
--experimental_repository_resolved_file
tarafından oluşturulan dosyayı kontrol ederseniz WORKSPACE'inizde tanımlanmamış birçok bağımlılık bulursunuz.
Bunun nedeni, Bazel'in bazı varsayılan bağımlılıkları eklemek için kullanıcının WORKSPACE dosya içeriğine aslında önekler ve sonekler eklemesidir.Bu bağımlılıklar genellikle yerel kurallar (ör. @bazel_tools
, @platforms
ve @remote_java_tools
) tarafından gereklidir. Bzlmod ile bu bağımlılıklar, diğer tüm Bazel modülleri için varsayılan bağımlılık olan yerleşik bir modül bazel_tools
ile tanıtılır.
Kademeli geçiş için karma mod
Bzlmod ve WORKSPACE yan yana çalışabilir. Bu sayede, bağımlılıkların WORKSPACE dosyasından Bzlmod'a taşınması kademeli bir süreç olabilir.
WORKSPACE.bzlmod
Taşıma işlemi sırasında Bazel kullanıcılarının Bzlmod'un etkin olduğu ve olmadığı derlemeler arasında geçiş yapması gerekebilir. WORKSPACE.bzlmod desteği, süreci kolaylaştırmak için uygulanır.
WORKSPACE.bzlmod, WORKSPACE ile aynı söz dizimine sahiptir. Bzlmod etkinleştirildiğinde, çalışma alanı kökünde WORKSPACE.bzlmod dosyası da varsa:
WORKSPACE.bzlmod
geçerli olur veWORKSPACE
içeriği yok sayılır.- WORKSPACE.bzlmod dosyasına önek veya sonek eklenmez.
WORKSPACE.bzlmod dosyasını kullanmak, aşağıdaki nedenlerden dolayı taşımayı kolaylaştırabilir:
- Bzlmod devre dışı bırakıldığında, bağımlılıkları orijinal WORKSPACE dosyasından getirmeye geri dönersiniz.
- Bzlmod etkinleştirildiğinde, WORKSPACE.bzlmod ile hangi bağımlılıkların taşınması gerektiğini daha iyi takip edebilirsiniz.
Depo görünürlüğü
Bzlmod, belirli bir depodan hangi diğer depoların görülebileceğini kontrol edebilir. Daha fazla bilgi için depo adları ve strict_deps bölümüne bakın.
Aşağıda, WORKSPACE de dikkate alındığında farklı türlerdeki depolardaki depo görünürlüklerinin özeti verilmiştir.
Ana depodan | Bazel modülü depolarından | Modül uzantısı depolarından | WORKSPACE depolarından | |
---|---|---|---|---|
Ana depo | Gösteriliyor | Kök modül doğrudan bağımlıysa | Kök modül, modül uzantısını barındıran modülün doğrudan bağımlısıysa | Gösteriliyor |
Bazel modülü depoları | Doğrudan mevduatlar | Doğrudan mevduatlar | Modül uzantısını barındıran modülün doğrudan bağımlılıkları | Kök modülün doğrudan bağımlılıkları |
Modül uzantısı depoları | Doğrudan mevduatlar | Doğrudan mevduatlar | Modül uzantısını barındıran modülün doğrudan bağımlılıkları + aynı modül uzantısı tarafından oluşturulan tüm depolar | Kök modülün doğrudan bağımlılıkları |
WORKSPACE Repos | Tümü görünür | Görünmez | Görünmez | Tümü görünür |
Taşıma süreci
Standart bir Bzlmod taşıma süreci şu şekilde olabilir:
- WORKSPACE'te hangi bağımlılıklarınız olduğunu anlayın.
- Projenizin kök dizinine boş bir MODULE.bazel dosyası ekleyin.
- WORKSPACE dosyasının içeriğini geçersiz kılmak için boş bir WORKSPACE.bzlmod dosyası ekleyin.
- Bzlmod etkinleştirilmiş şekilde hedeflerinizi oluşturun ve hangi deponun eksik olduğunu kontrol edin.
- Çözümlenen bağımlılık dosyasında eksik deponun tanımını kontrol edin.
- Eksik bağımlılığı bir modül uzantısı aracılığıyla Bazel modülü olarak ekleyin veya daha sonra taşımak üzere WORKSPACE.bzlmod dosyasında bırakın.
- 4. adıma geri dönün ve tüm bağımlılıklar kullanılabilir olana kadar tekrarlayın.
Taşıma aracı
Başlamanıza yardımcı olabilecek etkileşimli bir Bzlmod taşıma yardımcı komut dosyası vardır.
Komut dosyası aşağıdaki işlemleri yapar:
- WORKSPACE çözümlenmiş dosyasını oluşturun ve ayrıştırın.
- Çözümlenen dosyadan depo bilgilerini okunabilir şekilde yazdırın.
- Bazel build komutunu çalıştırın, tanınan hata mesajlarını tespit edin ve taşıma için bir yöntem önerin.
- Bir bağımlılığın BCR'de zaten mevcut olup olmadığını kontrol edin.
- MODULE.bazel dosyasına bağımlılık ekleyin.
- Modül uzantısı aracılığıyla bağımlılık ekleyin.
- WORKSPACE.bzlmod dosyasına bağımlılık ekleyin.
Bu özelliği kullanmak için en son Bazel sürümünün yüklü olduğundan emin olun ve aşağıdaki komutu çalıştırın:
git clone https://github.com/bazelbuild/bazel-central-registry.git
cd bazel-central-registry
bazel build //tools:migrate_to_bzlmod
alias migrate2bzlmod=$(realpath ./bazel-bin/tools/migrate_to_bzlmod)
cd <your workspace root>
migrate2bzlmod -t <your build targets>
Bazel modüllerini yayınlama
Bazel projeniz diğer projeler için bağımlılık oluşturuyorsa projenizi Bazel Central Registry'de yayınlayabilirsiniz.
Projenizi BCR'ye ekleyebilmek için projenin kaynak arşiv URL'sine ihtiyacınız vardır. Kaynak arşivi oluştururken dikkat etmeniz gereken birkaç nokta:
Arşivin belirli bir sürümü işaret ettiğinden emin olun.
Bzlmod, bağımlılık çözümleme sırasında sürüm karşılaştırması yapması gerektiğinden BCR yalnızca sürüm oluşturulmuş kaynak arşivlerini kabul edebilir.
Arşiv URL'sinin sabit olduğundan emin olun.
Bazel, arşivin içeriğini karma değeriyle doğrular. Bu nedenle, indirilen dosyanın sağlama toplamının hiçbir zaman değişmediğinden emin olmanız gerekir. URL GitHub'dan geliyorsa lütfen sürüm sayfasında bir sürüm arşivi oluşturup yükleyin. GitHub, isteğe bağlı olarak oluşturulan kaynak arşivlerin sağlama toplamını garanti etmez. Kısacası,
https://github.com/<org>/<repo>/releases/download/...
biçimindeki URL'ler kararlı,https://github.com/<org>/<repo>/archive/...
biçimindeki URL'ler ise kararsız olarak kabul edilir. Daha fazla bilgi için GitHub Archive Checksum Outage'a göz atın.Kaynak ağacın, orijinal deponun düzenine uygun olduğundan emin olun.
Deponuz çok büyükse ve gereksiz kaynakları kaldırarak boyutu küçültülmüş bir dağıtım arşivi oluşturmak istiyorsanız lütfen kaldırılan kaynak ağacının orijinal kaynak ağacının bir alt kümesi olduğundan emin olun. Bu, son kullanıcıların
archive_override
vegit_override
ile modülü yayınlanmamış bir sürümle geçersiz kılmasını kolaylaştırır.En yaygın API'lerinizi test eden bir alt dizinde test modülü bulundurun.
Test modülü, yayınlanacak gerçek modüle bağlı olan kaynak arşivinin bir alt dizininde bulunan kendi WORKSPACE ve MODULE.bazel dosyasına sahip bir Bazel projesidir. En yaygın API'lerinizi kapsayan örnekler veya bazı entegrasyon testleri içermelidir. Nasıl ayarlayacağınızı öğrenmek için test modülüne göz atın.
Kaynak arşivinizin URL'si hazır olduğunda, modülünüzü GitHub çekme isteğiyle BCR'ye göndermek için BCR katkı yönergelerini uygulayın.
Modülünüzü BCR'ye gönderme sürecini otomatikleştirmek için deponuzda Publish to BCR GitHub uygulamasını ayarlamanız şiddetle tavsiye edilir.
En iyi uygulamalar
Bu bölümde, harici bağımlılıklarınızı daha iyi yönetmek için uygulamanız gereken birkaç en iyi uygulama açıklanmaktadır.
Gereksiz bağımlılıkların getirilmesini önlemek için hedefleri farklı paketlere ayırın.
Testler için geliştirme bağımlılıklarının, bunlara ihtiyaç duymayan hedef oluşturma işlemleri için gereksiz yere getirilmeye zorlandığı #12835'i kontrol edin. Bu aslında Bzlmod'a özgü değildir ancak bu uygulamaları izlemek geliştirme bağımlılıklarını doğru şekilde belirtmeyi kolaylaştırır.
Geliştirme bağımlılıklarını belirtme
bazel_dep
ve use_extension
yönergeleri için dev_dependency
özelliğini true olarak ayarlayabilirsiniz. Böylece bu yönergeler bağımlı projelere yayılmaz. Kök modül olarak, hedeflerinizin geliştirme bağımlılıkları ve geçersiz kılmalar olmadan hâlâ oluşturulup oluşturulmadığını doğrulamak için --ignore_dev_dependency
işaretini kullanabilirsiniz.
Topluluk taşıma işleminin ilerleme durumu
Bağımlılıklarınızın kullanıma sunulup sunulmadığını öğrenmek için Bazel Central Registry'yi kontrol edebilirsiniz. Aksi takdirde, geçişinizi engelleyen bağımlılıkları oylamak veya yayınlamak için bu GitHub tartışmasına katılabilirsiniz.
Sorun bildirme
Bilinen Bzlmod sorunları için lütfen Bazel GitHub sorun listesini kontrol edin. Taşıma işleminizin engellenmesini önlemeye yardımcı olabilecek yeni sorunlar veya özellik istekleri gönderebilirsiniz.