Baklavalar

Bir komut satırının bir kısmını veya tamamını oluşturmak için gereken verileri bellek açısından verimli bir şekilde kapsülleyen bir nesne.

Bir işlem genellikle geçişli bağımlılıklardan toplanan değerleri içeren büyük bir komut satırı gerektirir. Örneğin, bir bağlayıcı komut satırında, bağlı olan tüm kitaplıkların ihtiyaç duyduğu her nesne dosyası listelenebilir. En iyi uygulama, bu tür geçişli verilerin birden fazla hedef tarafından paylaşılabilmesi için depset içinde depolanmasıdır. Ancak, kuralı oluşturan kişinin bir işlem komut satırı oluşturmak için bu depistleri dize listelerine dönüştürmesi gerekmesi halinde, bu bellek paylaşımı optimizasyonunu geçersiz kılar.

Bu nedenle, işlem oluşturma işlevleri dizelere ek olarak Args nesnelerini de kabul eder. Her Args nesnesi, verileri değiştirmek için isteğe bağlı dönüşümlerle birlikte dizelerin ve alt kümelerin birleştirilmesini temsil eder. Args nesneleri, komut satırını hesaplama zamanı geldiğinde, yürütme aşamasına kadar, içerdikleri alt öğeleri işlemez. Bu sayede, pahalı kopyalama işlemlerini analiz aşaması tamamlanana kadar erteleyebilirsiniz. Daha fazla bilgi için Performansı Optimize Etme sayfasına bakın.

Args, ctx.actions.args() çağrısı yapılarak oluşturulur. Bunlar, ctx.actions.run() veya ctx.actions.run_shell() için arguments parametresi olarak iletilebilir. Args nesnesinin her mutasyonu, nihai komut satırına değer ekler.

map_each özelliği, öğelerin dizelere dönüştürülme şeklini özelleştirmenize olanak tanır. map_each işlevi sağlamazsanız standart dönüşüm aşağıdaki gibi olur:

  • Zaten dize olan değerler olduğu gibi kalır.
  • File nesneleri File.path değerlerine dönüştürülür.
  • Diğer tüm türler, belirtilmemiş bir şekilde dizelere dönüştürülür. Bu nedenle, dize veya File türünde olmayan değerleri add() öğesine geçirmekten kaçınmanız ve bunları add_all() veya add_joined() öğesine iletiyorsanız map_each işlevi sağlamanız gerekir.

Dize biçimlendirmesi kullanılırken (add*() yöntemlerinin format, format_each ve format_joined parametreleri) biçim şablonu, dizelerde %-değiştirme işlemiyle aynı şekilde yorumlanır. Tek fark, şablonun tam olarak bir değiştirme yer tutucusu içermesi ve %s olması gerekir. Değişmez yüzdeler, %% olarak çıkış yapılabilir. Biçimlendirme, değer yukarıdaki yönteme göre bir dizeye dönüştürüldükten sonra uygulanır.

add*() yöntemlerinin her biri, ekstra konumsal parametreyi kabul eden alternatif bir biçime ve diğer bağımsız değişkenlerden önce eklenecek bir "bağımsız değişken adı" dizesine sahiptir. add_all ve add_joined için dizi boş olursa ekstra dize eklenmez. Örneğin, aynı kullanımla birlikte, belirtilen dizinin val1..val3 içerip içermediğine veya boş olmasına bağlı olarak komut satırına --foo val1 val2 val3 --bar veya yalnızca --bar eklenebilir.

Komut satırının boyutu sistemin izin verdiği maksimum boyuttan daha fazla büyüyebilirse bağımsız değişkenler parametre dosyalarına taşabilir. Daha fazla bilgi için use_param_file() ve set_param_file_format() başlıklı makaleleri inceleyin.

Örnek: Komut satırını oluşturmak istediğimizi varsayalım: 

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
Şu Args nesnesini kullanabiliriz: 
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)

Üyeler

add

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

Bu komut satırına bağımsız değişken ekler.

Parametreler

Parametre Açıklama
arg_name_or_value gerekli
İki konum parametresi iletilirse bu, bağımsız değişken adı olarak yorumlanır. Bağımsız değişken adı, herhangi bir işlem yapılmadan değerin önüne eklenir. Yalnızca tek bir konum parametresi aktarılırsa value olarak yorumlanır (aşağıya bakın).
value default = unbound
Eklenecek nesne. Bu değer, yukarıda bahsedilen standart dönüşüm kullanılarak bir dizeye dönüştürülür. Bu işlevde map_each parametresi olmadığından, value bir dize veya File olmalıdır. Liste, tuple, depset veya dizin File, bu yöntem yerine add_all() veya add_joined() yöntemine iletilmelidir.
format string; or None; varsayılan = Yok
value öğesinin dizeleştirilmiş sürümüne uygulanacak bir biçim dizesi kalıbı.

add_all

Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)

Bu komut satırına birden çok bağımsız değişken ekler. Öğeler, yürütme aşamasında geç işlenir.

İşlemin büyük kısmı, aşağıdaki adımlara göre eklenecek bağımsız değişkenlerin listesi üzerinden gerçekleştirilir:

  1. Her dizin File öğesi, yinelemeli olarak o dizinde yer alan tüm File öğeleriyle değiştirilir.
  2. map_each sağlanırsa her öğeye uygulanır ve sonuçta ortaya çıkan dize listeleri, ilk bağımsız değişken listesi oluşturmak için birleştirilir. Aksi takdirde, ilk bağımsız değişken listesi her bir öğeye standart dönüşümün uygulanmasından kaynaklanır.
  3. Listedeki her bağımsız değişken varsa format_each ile biçimlendirilir.
  4. uniquify doğruysa yinelenen bağımsız değişkenler kaldırılır. Geriye yalnızca ilk kez kalır.
  5. before_each dizesi verilirse bu dize, listedeki her bağımsız değişkenin önüne yeni bir bağımsız değişken olarak eklenir. Bu işlem, bu noktanın sonuna eklenecek bağımsız değişkenlerin sayısını etkili bir şekilde iki katına çıkarır.
  6. Listenin boş ve omit_if_empty değerinin doğru (varsayılan) olduğu durumlar dışında, bağımsız değişken adı ve terminate_with bağımsız değişken verilmişse ilk ve son bağımsız değişken olarak eklenir.
Boş dizelerin, tüm bu işleme adımlarına tabi olan geçerli bağımsız değişkenler olduğunu unutmayın.

Parametreler

Parametre Açıklama
arg_name_or_values gerekli
İki konum parametresi iletilirse bu, bağımsız değişken adı olarak yorumlanır. Bağımsız değişken adı, herhangi bir işlem yapılmadan values öğesinin önüne eklenir. omit_if_empty doğru değerine ayarlanırsa (varsayılan) ve başka öğe eklenmezse (values boş olduğunda veya tüm öğeleri filtrelendiğinde olduğu gibi) bu bağımsız değişken adı eklenmez. Yalnızca tek bir konum parametresi aktarılırsa values olarak yorumlanır (aşağıya bakın).
values sequence; or depset; default = unbound
Öğeleri eklenecek liste, unsur veya depset.
map_each callable; or None; varsayılan = Yok
Her öğeyi sıfır veya daha fazla dizeye dönüştüren ve bu işlem, eklemeden önce daha fazla işlenebilen bir işlev. Bu parametre sağlanmazsa standart dönüştürme kullanılır.

İşleve bir veya iki konumsal bağımsız değişken aktarılır: dönüştürülecek öğe ve ardından isteğe bağlı bir DirectoryExpander. İkinci bağımsız değişken yalnızca sağlanan işlev kullanıcı tanımlıysa (yerleşik değil) ve birden fazla parametre bildiriyorsa iletilir.

Döndürülen değerin türü, öğe için kaç bağımsız değişken oluşturulacak olduğuna bağlıdır:

  • Her öğenin bir dizeye dönüştüğü yaygın durumda, işlev söz konusu dizeyi döndürmelidir.
  • Öğe tamamen filtrelenecekse işlev None değerini döndürecektir.
  • Öğe birden çok dizeye dönüşürse işlev, bu dizelerin bir listesini döndürür.
Tek bir dizenin veya None değerinin döndürülmesi, sırasıyla 1 veya 0 uzunluğunda bir liste döndürmekle aynı etkiye sahiptir. Ancak, gerekli olmayan bir liste oluşturmaktan kaçınmak için daha verimli ve okunabilirdir.

Normalde, expand_directories=True ayarlandığında dizin olan öğeler otomatik olarak kendi içeriklerine genişletilir. Ancak bu işlem, diğer değerlerin içinde yer alan dizinleri genişletmez (örneğin, öğeler alan olarak dizinleri olan struct'lar olduğunda). Bu durumda, belirli bir dizindeki dosyaları manuel olarak almak için DirectoryExpander bağımsız değişkeni uygulanabilir.

Büyük analiz aşaması veri yapılarının yürütme aşamasında istenmeyen şekilde saklanmasını önlemek için map_each işlevi, üst düzey bir def ifadesiyle tanımlanmalıdır. Bu, varsayılan olarak iç içe yerleştirilmiş bir işlev kapatması olmayabilir.

Uyarı: map_each çağrısı sırasında yürütülen print() ifadeleri görünür herhangi bir çıkış üretmez.

format_each string; or None; varsayılan = Yok
map_each işlevi tarafından döndürülen her dizeye uygulanan isteğe bağlı bir biçim dizesi kalıbı. Biçim dizesinde tam olarak bir tane "%s" yer tutucusu olmalıdır.
before_each string; or None; varsayılan = Yok
values parametresinden türetilen her bağımsız değişken eklenmeden önce eklenecek isteğe bağlı bir dize.
omit_if_empty varsayılan = Doğru
Doğru ise, values öğesinden türetilen ve eklenecek bağımsız değişken yoksa diğer tüm işlemler atlanır ve komut satırı değiştirilmez. Yanlış değerine ayarlanırsa başka bağımsız değişkenler olup olmamasına bakılmaksızın bağımsız değişken adı ve terminate_with (belirtilmişse) eklenir.
uniquify default = False
Doğru değerine ayarlanırsa values parametresinden türetilen yinelenen bağımsız değişkenler atlanır. Her bağımsız değişkenin yalnızca ilk geçtiği yer kalır. Bu özellik, alt konumlar zaten yinelemeleri atladığı için genellikle gerekli değildir. Ancak map_each birden çok öğe için aynı dizeyi yayınladığında yararlı olabilir.
expand_directories varsayılan = Doğru
Doğru değerine ayarlanırsa values içindeki tüm dizinler, düz bir dosya listesine genişletilir. Bu işlem, map_each uygulanmadan önce gerçekleşir.
terminate_with string; or None; varsayılan = Yok
Diğer tüm bağımsız değişkenlerden sonra eklenecek isteğe bağlı bir dize. omit_if_empty doğru değerine ayarlanırsa (varsayılan) ve başka öğe eklenmezse (values boş olduğunda veya tüm öğeleri filtrelendiğinde olduğu gibi) bu dize eklenmez.
allow_closure default = False
Doğru değerine ayarlanırsa map_each gibi işlev parametrelerinde kapatmaların kullanılmasına izin verir. Bu işlem genellikle gerekli değildir ve büyük analiz aşaması veri yapılarını yürütme aşamasında tutma riskiyle karşı karşıya kalır.

add_joined

Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)

Ayırıcı kullanarak birden çok değeri birleştirerek bu komut satırına bir bağımsız değişken ekler. Öğeler, yürütme aşamasında geç işlenir.

İşleme add_all() ile benzerdir, ancak values öğesinden türetilen bağımsız değişkenler listesi, join_with.join(...) tarafından sanki tek bir bağımsız değişkende birleştirilir ve ardından belirtilen format_joined dize şablonu kullanılarak biçimlendirilir. add_all()'den farklı olarak, öğeler tek bir bağımsız değişkende birleştirildiğinde genel olarak yararlı olmadıkları için before_each veya terminate_with parametreleri yoktur.

Filtrelemeden sonra bir bağımsız değişkene katılacak dize yoksa ve omit_if_empty doğruysa (varsayılan) işlem yapılmaz. Aksi takdirde, birleştirilecek dize yoksa ancak omit_if_empty yanlışsa birleştirilen dize boş bir dize olur.

Parametreler

Parametre Açıklama
arg_name_or_values gerekli
İki konum parametresi iletilirse bu, bağımsız değişken adı olarak yorumlanır. Bağımsız değişken adı, herhangi bir işlem yapılmadan values önüne eklenir. omit_if_empty doğru değerine sahipse (varsayılan) ve values öğesinden türetilen dize yoksa bu bağımsız değişken eklenmez (values boşsa veya tüm öğeleri filtrelendiğinde gerçekleşebilir). Yalnızca tek bir konum parametresi aktarılırsa values olarak yorumlanır (aşağıya bakın).
values sequence; or depset; default = unbound
Öğeleri birleştirilecek liste, çift veya depset.
join_with gerekli
string.join() ile aynı şekilde, map_each ve format_each uygulanmasından elde edilen dizeleri birleştirmek için kullanılan bir ayırıcı dize.
map_each callable; or None; varsayılan = Yok
add_all ile aynıdır.
format_each string; or None; varsayılan = Yok
add_all ile aynıdır.
format_joined string; or None; default = None
Birleştirilen dizeye uygulanan isteğe bağlı bir biçim dizesi kalıbı. Biçim dizesinde tam olarak bir tane "%s" yer tutucusu olmalıdır.
omit_if_empty default = True
Doğru ise birleştirilecek dize yoksa (values boş olduğu veya tüm öğeleri filtrelendiği için) diğer tüm işlemler engellenir ve komut satırı değiştirilmez. Yanlış değerine ayarlanırsa birleştirilecek dize olmasa bile iki bağımsız değişken eklenir: bağımsız değişken adı ve ardından boş bir dize (sıfır dizelerin mantıksal birleşimidir).
uniquify default = Yanlış
add_all için olanla aynıdır.
expand_directories default = Doğru
add_all ile aynıdır.
allow_closure default = Yanlış
add_all için olanla aynıdır.

set_param_file_format

Args Args.set_param_file_format(format)

parametre kullanılıyorsa param dosyasının biçimini ayarlar

Parametreler

Parametre Açıklama
format gerekli
Şunlardan biri olmalıdır:
  • "multiline" (çok satırlı): Her öğe (bağımsız değişken adı veya değeri), param dosyasına tam olarak yazılır ve ardından bir yeni satır karakteri eklenir.
  • "shell": "çok satırlı" ile aynıdır, ancak öğeler kabuk tırnaklıdır
  • "flag_per_line": "multiline" ile aynıdır ancak (1) param dosyasına yalnızca flag'ler ("--" ile başlayan) yazılır ve (2) flag'lerin değerleri (varsa) aynı satıra "=" ayırıcısıyla yazılır. Bu, Abseil işaret kitaplığının beklediği biçimdir.

Çağrılmazsa varsayılan olarak "kabuk" kullanılır.

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

Bağımsız değişkenleri bir params dosyasına dökerek bunları, param dosyasına işaret eden bir işaretçiyle değiştirir. Bağımsız değişkenleriniz sistemin komut uzunluğu sınırları için çok büyük olduğunda kullanın.

Bazel, verimlilik için yürütme sırasında parametreler dosyasını çıkış ağacına yazmayı tercih edebilir. İşlemlerde hata ayıklama gerçekleştiriyorsanız ve parametre dosyasını incelemek istiyorsanız --materialize_param_files öğesini derlemenize iletin.

Parametreler

Parametre Açıklama
param_file_arg gerekli
Tek bir "%s" içeren biçim dizesi. Bağımsız değişkenler bir params dosyasına dökülürse, params dosyasının yoluyla biçimlendirilmiş bu dizeyi içeren bir bağımsız değişken ile değiştirilir.

Örneğin, bağımsız değişkenler bir parametre dosyasına "params.txt" dökülürse, "--file=%s" değerinin belirtilmesi işlem komut satırının "--file=params.txt" içermesine neden olur.

use_always default = False
Bağımsız değişkenlerin her zaman bir params dosyasına aktarılıp aktarılmayacağı. Yanlış değerine ayarlanırsa bağımsız değişkenlerin sisteme ve bağımsız değişken uzunluğuna göre dökülmesi gerekip gerekmediğine Google karar verir.